1. General

The new API v2 was introduced in chy.stat 2.10.0. The old API v1 is still supported, but is deprecated. New clients should use the new API v2. Existing clients should be migrated to the new API v2.

You can find the API v1 Specification here: https://apidocs.chystat.com/current

API v1 is deprecated and will be removed after 01/01/2023.

1.1. API v1 to v2 migration

There are few breaking changes in the Ordo endpoint request and response format. See the Ordo migration guide for details.

All other API endpoints have the same request and response format as they had in API v1. The only change is in the URI part: /api/v1 → /api/v2

1.2. Field types

Request and response fields can be one of the following types

Type

Description

String

JSON string

Number

JSON number

Boolean

JSON boolean

Object

JSON object with nested fields

Array

JSON array

Localized String

JSON object that represents text with variations for multiple languages. This object may contain ISO 639-1 language codes as keys and a default key. E.g.:

{
    "default": "My text",
    "de": "Mein text",
    "fr": "Mon texte"
}

Localized string with a default (english in this case) text and with german and french variants.

{
    "default": "My text"
}

Localized string with only a default text.

{
    "en": "My text",
    "de": "Mein text",
    "fr": "Mon texte"
}

Localized string with only a localized variants.

String (ISO 8601 Date)

Date formatted according to ISO 8601 string. E.g., 2019-06-10T08:16:24+01:00

Varies

Data type of the field can vary depending on some circumstances

1.3. Error codes

All API endpoints returns a standard HTTP status code to indicate the result. Additional information is sent in the response body in form of JSON. This JSON message contains an error code and a message with error description.

{
  "code": 40,
  "message": "Unable to parse the 'path' request parameter"
}

Error codes from 0 to 99 are general. Each API endpoint can have its own, more detailed error codes. These are documented in each API endpoint section.

The general API error codes are:

Code HTTP status code Name Description

0

500

General error

General error where no specific code can’t be used.

20

401

Authentication error

Authentication failed. Missing or invalid JWT / API token.

21

403

Authorization error

Authorization failed. API Token doesn’t have required permissions.

30

400

Missing request param

Any of the required request parameters is missing.

40

400

Invalid request param

Any of the request parameters is invalid or can’t be processed.

1.4. Application status

Sometimes it is advisable to check the status of an application, whether it is running and ready to process requests. Status of chystat application can be checked by performing simple HTTP GET request to \status\health endpoint with no query parameters. Various status codes can be returned, depending on current application state.

Server should respond by returning status code 200 indicating application seems to work properly.

When problem is encountered status code 503 may be returned instead, signalizing unspecified problem on the server side.

Similarly, obtaining no response at all indicates the application is completely out of service.

1.5. Authentication

All API endpoints are secured and requests to them has to be authenticated and authorized. Request can be authenticated using generated API token, sent in the request header.

To see existing tokens or to create one:

  1. Login to a chy.stat application with admin rights

  2. Go to section System settings → General → API

  3. Open detail of existing or create a new API token

API token key and Token secret are confidential. Appropriate measures must be taken when handling this information. If you suspect that the Token secret was compromised, you should immediately delete the API token and issue a new one. If the API token key might have been compromised, you can only regenerate the API token key.

1.5.1. API token key authentication

To authenticate the request with private API token key, it must be presented in the Authorization header of the request.

Private API token key is shown to the user only once and can’t be shown again later. If the user lost the private API token key, it is possible to regenerate the key under the token detail tab.

With this type of authentication, we use Bearer Authorization schema

Authorization: Bearer <API token key>

This type of authentication is only possible when using secured connection (HTTPS).

1.5.2. JWT authentication (HMAC)

JWT authentication is deprecated. You should use API token key authentication over TLS connection instead.

We can also use virtual JWT tokens, created with the Token ID and Token secret, to authenticate inbound requests.

This authentication method is known as HMAC authentication.

Virtual authentication tokens are sent in form of JWT (JSON Web Tokens)

The client is responsible for generating and sending the JWT token.

There are a lot of libraries that can be used to simplify the creation of JWTs.

The token has to be sent in the Authorization header using the same Bearer schema

Authorization: Bearer <JWT token>

Getting the API token details

To create JWT token, you must use Token ID and Token secret of an existing API token. To get this information, navigate to existing API tokens, choose a token and copy its details.

JWT Header

Header is a standard JWT header where the token type and an algorithm used to create its signature is defined.

{
  "alg": "HS256",
  "typ": "JWT"
}
JWT Payload

Payload must contain these claims:

  • iat - Issued At. It’s a UNIX time (in seconds) representing time when the token was created. It will be used for validation of the token age. By default, we reject tokens older than 10 minutes.

  • sub - Subject. It should contain the Token ID received from chy.stat (see Getting the API token for the details)

{
  "iat": 1504783221,
  "sub": "VXFE78JLQ9OHrvAKKg5vSw"
}
JWT Signature

The token has to be signed by the Token secret (see Getting the API token for the details). Only the HS256 algorithm is supported for signing the token.

1.6. Pagination

Requests that return multiple items will be paginated to 50 items by default. You can specify further pages with the pageNumber parameter. You can change the default page size using pageSize parameter. Maximum is 100 items.

Note that page numbering is 1-based and that omitting the pageNumber parameter will return the first page.

1.7. WebSockets

Endpoints that are designed using publisher-subscriber pattern use STOMP sub-protocol over WebSocket protocol. WebSocket protocol doesn’t define message semantics. This is the reason why we use STOMP messaging protocol. It allows you to subscribe to a topic and receive messages published to this topic.

1.7.1. Connection

WebSocket API is published at /api/v2/ws endpoint. There is only one WebSocket endpoint for the whole API. WebSocket API is separated in multiple topics to which you can subscribe after connection.

1.7.2. Authentication

STOMP protocol allows you to send custom headers in CONNECT message. We expect X-Authorization header in CONNECT message that contains private API token key or JWT token.

Semantics of the X-Authorization header is the same as of the HTTP Authorization header:

X-Authorization: Bearer <API token key> for API token key, or

X-Authorization: Bearer <JWT token> for JWT token

Similar to API endpoints authentication, providing API token key will only work as long as the connection is secure. When establishing secured WebSocket connection, replace the initial ws: in the request URL with wss: as seen in the example below.

1.7.3. Sample

This is sample code that shows how to use chy.stat WebSocket API. It is written in JavaScript.

We will use STOMP.js library

npm i @stomp/stompjs

index.js

import {Client} from '@stomp/stompjs';

// API Token key authentication
const apiTokenKey = "your API token key";

// JWT authentication
const jwt = createJwt();

const clientOptions = {
	brokerURL: "wss://your.chystat.url/api/v2/ws",
	reconnectDelay: 5000,
	heartbeatIncoming: 10000,
	heartbeatOutgoing: 10000,
	connectHeaders: {
		"X-Authorization": "Bearer " + apiTokenKey
		// or "X-Authorization": "Bearer " + jwt
	}
};
const client = new Client(clientOptions);

const onMessage = (message) => {
	console.log(`Received message: ${message.body}`);
};

client.onConnect = () => {
	console.log("Successfully connected to the server");

	const headers = {
	    ...
	};

	client.subscribe("/user/topic/measurements", onMessage, headers);
};

client.activate();

2. Core

2.1. Measured values

2.1.1. K-key Query

Comparison operators
Operator Description

eq

Matches values that are equal to a specified value.

in

Matches values that are equal to any of the values specified in an array.

gt

Matches values that are greater than a specified value.

gte

Matches values that are greater than or equal to a specified value.

lt

Matches values that are less than a specified value.

lte

Matches values that are less than or equal to a specified value.
EQ

Syntax: { "Kxxxx": { "eq": <value> } }

Implicit equal syntax: { "Kxxxx": <value> }

The eq operator performs an equality check. Selects the values where the value of a K-key is equal to the provided value. If you will not use an explicit operator, implicit equal operator will be used.

Since version 2.10.9 you can use null as the eq operator value. Such condition will match K-keys without a value. null value can be used in both explicit and implicit syntax.

Examples:

{ "K2001": { "eq": "weight" } }

This query will select all values of a "weight" characteristic

{ "K2001": "weight" }

This is the same query as above, but it uses implicit equal operator syntax

{ "K0014": { "eq": null } }

This query will select all values without identifier (since 2.10.9)

IN

Syntax: { "Kxxxx": { "in": [ <value1>, <value2>, …​, <valueN> ]} }

The in operator selects the values where the value of a K-key equals any value in the specified array.

Examples:

{ "K2001": { "in": [ "weight", "diameter", "height" ] } }

This query will select all values of a "weight", "diameter" and "height" characteristics

LT / LTE / GT / GTE

Syntax: { "Kxxxx": { "lt": <value> } }

The lt / lte / gt / gte operators compares the value of a K-key to the provided value. They all behave similarly and have the same syntax.

These comparison operators can be used only for numeric and date K-keys.

Examples:

{ "K0001": { "gte": 99.9 } }

This query will select all values greater than or equal to 99.9

Comparison operator K-keys

You can use any of the part (K1xxx), characteristic (K2xxx), or value (K0xxx) K-keys in the query. You can also use catalog K-keys (K4xxx) of the catalogs configured in the database settings.

Comparison operators values

Values used in query expressions should have the same data type as the K-key. Values of date K-keys should use ISO 8601 formatted string value.

Logical operators
Operator Description

and

Joins query clauses with a logical AND. Returns all values that match the conditions of all the clauses.

or

Joins query clauses with a logical OR. Returns all values that match the conditions of any of the clauses.

not

Negates the effect of a query expression.
AND

Syntax: { "and": [ { <expression1> }, { <expression2> } , …​ , { <expressionN> } ] }

The and operator performs a logical AND operation on an array of one or more expressions (e.g. <expression1>, <expression2>, etc.) and selects the values that satisfy all the expressions in the array.

Examples:

{
    "and": [
        { "K1001": "muffin" },
        { "K2001": "weight" }
    ]
}

This query will select all values of a "weight" characteristic of a "muffin" part

OR

Syntax: { "or": [ { <expression1> }, { <expression2> } , …​ , { <expressionN> } ] }

The or operator performs a logical OR operation on an array of two or more <expressions> and selects the values that satisfy at least one of the <expressions>.

Examples:

{
    "or": [
        { "K2001": "diameter" },
        { "K2001": "weight" }
    ]
}

This query will select all values of a "diameter" and "weight" characteristics (regardless of part)

NOT

Syntax: { "not": { <expression> } }

The not operator performs a logical NOT operation on the specified <expression> and selects the values that do not match the <expression>.

Examples:

{
    "not": { "K2001": "weight" }
}

This query will select all values of all characteristics except the "weight" characteristic

2.1.2. Output Formats

Measured values can be exported in one of the supported formats:

Format Code MIME type Description

AQDEF

aqdef

application/vnd.aqdef

AQDEF in JSON

aqdef-json

application/json

AQDEF structure written in JSON format. Normalized form of the data. Contains hierarchy of part / characteristics / values.

AQDEF in flat JSON

aqdef-json-flat

application/json

AQDEF structure written in JSON format. Denormalized form of the data with a flat structure.

CSV

csv

text/csv
AQDEF

See here and here for more information about the AQDEF format.

Catalog K-keys (K4xxx) are not supported in this format.

Example:

K0100 1
K1001/1 <part_number_1>
K2001/1 <characteristic_code_1>
K2101/1 1.5
K2110/1 1
K2111/1 2
K0001/1 1.6
K0004/1 01.01.2020/15:18:31
K0001/1 1.7
K0004/1 01.01.2020/15:19:31
AQDEF in JSON

JSON containing AQDEF data. The JSON contains normalized form of the data in similar tree-like structure as normal AQDEF.

Catalog K-keys (K4xxx) are not supported in this format.

Example:

{
  "parts": [
    {
      "K1001": "<part_number_1>",
      "characteristics": [
        {
          "K2001": "<characteristic_code_1>",
          "values": [
            {
              "K0001": 1.6,
              "K0004": "2013-01-01T15:18:31+01:00"
            },
            {
              "K0001": 1.7,
              "K0004": "2013-01-02T15:19:31+01:00"
            }
          ]
        }
      ]
    }
  ]
}
AQDEF in flat JSON

JSON containing flat AQDEF data. The JSON contains denormalized form of the data. Every value is wrapped in object that contains all the information about its part and characteristic.

Catalog K-keys (K4xxx) are supported in this format.

Example:

[
  {
    "K1001": "<part_number_1>",
    "K2001": "<characteristic_code_1>",
    "K0001": 1.6,
    "K0004": "2013-01-01T15:18:31+01:00"
  },
  {
    "K1001": "<part_number_1>",
    "K2001": "<characteristic_code_1>",
    "K0001": 1.7,
    "K0004": "2013-01-02T15:19:31+01:00"
  }
]
CSV

CSV containing the data. Each row contains single value and information about its part and characteristic.

Catalog K-keys (K4xxx) are supported in this format.

Example:

K1001,K2001,K0001,K0004
<part_number_1>,<characteristic_code_1>,1.6,2013-01-01T15:18:31+01:00
<part_number_1>,<characteristic_code_1>,1.7,2013-01-02T15:19:31+01:00

2.1.3. Find values by query

A POST request is used to find measured values using the given query

HTTP request
POST /api/v2/measurements/search HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 588

{
  "query": {
    "and": [
      {
        "K1001": "shaft"
      },
      {
        "or": [
          {
            "K2001": "length"
          },
          {
            "K2001": "diameter"
          }
        ]
      },
      {
        "K0004": {
          "gt": "2020-01-01T15:18:31+01:00"
        }
      },
      {
        "K0004": {
          "lt": "2020-01-01T16:18:31+01:00"
        }
      }
    ]
  },
  "responseOptions": {
    "format": "aqdef-json",
    "kKeys": [
      "K1001",
      "K2001",
      "K0001",
      "K0004"
    ]
  },
  "pageSize": 100,
  "pageNumber": 1
}
Request fields
Path Type Description

query

Object

See K-key Query section

responseOptions.format

String

Format in which the data will be returned. Can be any of:

  • aqdef

  • aqdef-json

  • aqdef-json-flat

  • csv

See Output Formats for more details

responseOptions.kKeys

Array

List of K-keys that should be written to the response. Can be used only with one of the JSON or CSV output formats.

pageSize

Number

Number of values to return. Maximum page size is increased to 1000 for this API endpoint.

pageNumber

Number

1-based index of the page to return
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 479

{
  "parts": [
    {
      "K1001": "shaft",
      "characteristics": [
        {
          "K2001": "diameter",
          "values": [
            {
              "K0001": 0.896,
              "K0004": "2020-01-01T15:35:00+01:00"
            }
          ]
        },
        {
          "K2001": "length",
          "values": [
            {
              "K0001": 12.336,
              "K0004": "2020-01-01T15:35:00+01:00"
            }
          ]
        }
      ]
    }
  ]
}

2.1.4. Get notified about new values (WS)

WebSocket API is used to get notifications about new measurements.

Topic

/user/topic/measurements

Subscribe
const query = {
    K2001: "diameter"
};

const responseOptions = {
    format: "aqdef-json-flat",
    kKeys: ["K1001", "K2001", "K0001", "K0004", "K0053"]
};

const headers = {
    query: JSON.stringify(query),
    responseOptions: JSON.stringify(responseOptions)
};

client.subscribe("/user/topic/measurements", onMessage, headers);
Subscribe headers
Path Type Description

query

Object

Query that filters measured values you will be notified about. See K-key Query section

responseOptions.format

String

Format in which the data will be returned. Can be any of:

  • aqdef

  • aqdef-json

  • aqdef-json-flat

  • csv

See Output Formats for more details

responseOptions.kKeys

Array

List of K-keys that should be written to the message. Can be used only with one of the JSON or CSV output formats.

count

Boolean

If true only count of new measured values will be sent to client.
Message body

Messages will contain new measured values written in the response format specified in subscription header.

2.2. Upload

2.2.1. Upload Data

Using this API endpoint a client is able to post some data to a target chy.stat upload. The format of the data must be supported by the configured data source parser. We support various inputs as AQDEF, JSON, CSV, etc.

If you are not familiar with AQDEF format, you can get more information here

The upload API is designed to be asynchronous. It means that when you post a data request, there is no guaranteed time when the data will be loaded to the chy.stat system.

A POST request is used to upload the data

HTTP request
POST /api/v2/upload HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 229

{
  "dataSourceId": "4f86f6d6-6cdc-450a-af2a-8f03165232d3",
  "aqdefContent": "K0100 1\nK1001 part\nK1002 My part\nK2001/1 char1\nK2002/1 My characteristic\nK0001/1 0.0068\nK0004/1 18.6.2019/15:33:00\n",
  "path": "my-file.dfq"
}
Request fields
Path Type Description

dataSourceId

String

Id of the API datasource defined in the chy.stat upload. You can obtain this identifier in chy.stat: System settings → General → Upload → Your target upload → Data sources → Your target API datasource

aqdefContent

Array / Object / String

Data that will be loaded to the chy.stat. Format of the data depends on the selected parser in the target data source. Can be any of:

  • String

  • Json object

  • Json array

path

String

Optional. This field can contain file name or relative path to file.
HTTP response
HTTP/1.1 200 OK

Since the upload API is designed to be asynchronous, we provide only two type of response.

  • HTTP 200 OK - upload request has been accepted and the data will be uploaded as soon as possible

  • HTTP 40x/50x - upload request has been rejected

In case of rejection, the response contains a JSON body with a specific API error code and a message.

Error codes

These are Upload API specific error codes on top of the general ones.

Code HTTP status code Name Description

110

404

Unknown data source ID

The target data source does not exist.

120

503

Upload is not running

The target upload is not running right now.

2.3. Embeddables

See chystat-embeddables for more information about how to use embeddedables.

2.3.1. Find all embeddable graphics

A GET request is used to find all embeddable graphics

HTTP request
GET /api/v2/embed/graphics HTTP/1.1
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1730

[
  {
    "id": "58058e34-50ef-49b6-9fde-738eb91148bc",
    "name": {
      "cs": "Průběh hodnot",
      "default": "Value chart"
    },
    "description": {
      "default": "Value chart with 30 values in history"
    },
    "parameters": [
      {
        "key": "maxCharacteristicValues",
        "name": {
          "default": "Number of values"
        },
        "dataType": "int"
      },
      {
        "key": "dataHistory.type",
        "name": {
          "default": "History type [totalValues | historicalValues] (Required for time period history)"
        },
        "dataType": "string"
      },
      {
        "key": "dataHistory.numberOfValues",
        "name": {
          "default": "Number of historical values, max. 10 000 (Required for time period history)"
        },
        "dataType": "int"
      },
      {
        "key": "dataHistory.displayedPeriodConfig.lastPeriod",
        "name": {
          "default": "Period to search for data [lastHour | lastDay | lastWeek | lastMonth] (Data history parameters \u0027type\u0027 and \u0027numberOfValues\u0027 are REQUIRED)"
        },
        "dataType": "string"
      },
      {
        "key": "dataHistory.displayedPeriodConfig.timePeriodId",
        "name": {
          "default": "Time period settings id (Data history parameters \u0027type\u0027 and \u0027numberOfValues\u0027 are REQUIRED)"
        },
        "dataType": "string"
      },
      {
        "key": "dataHistory.displayedPeriodConfig.timePeriodCount",
        "name": {
          "default": "Time period count, defaults to 1 if not specified (Data history parameters \u0027type\u0027 and \u0027numberOfValues\u0027 are REQUIRED)"
        },
        "dataType": "int"
      }
    ]
  }
]
Response fields
Path Type Description

[].id

String

Unique id of the embeddable graphic

[].name

Localized String

Name of the embeddable graphic

[].description

Localized String

Description of the embeddable graphic

[].parameters[]

Array

Parameters of the graphic that can be used to override its default configuration

[].parameters[].key

String

Key of the parameter

[].parameters[].name

Localized String

Name of the parameter

[].parameters[].dataType

String

Data type of the parameter. Can be one of: ['int' | 'string']

3. Ordo

3.1. Orders

3.1.1. API v1 to v2 migration

The following query fields and response fields has been moved:

V1 field

V2 field

closedAt

flow.closed.date

closedBy

flow.closed.user

evaluatedAt

flow.evaluated.date

evaluatedBy

flow.evaluated.user

Field state can contain any of the configured states codes, not only open, closed and evaluated.

Field evaluation can contain any of the configured evaluation codes, not only ok, conditionally-ok and nok.

3.1.2. Find order by id

A GET request is used to find an order by id

HTTP request
GET /api/v2/orders/orders/1 HTTP/1.1
Path parameters
Table 1. /api/v2/orders/orders/{id}
Parameter Description

id

Order id
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1339

{
  "createdBy": {
    "id": 1,
    "username": "kenobi",
    "name": "Obi-Wan Kenobi",
    "email": "obi-wan@kenobi.com",
    "department": "Department 1"
  },
  "state": "evaluated",
  "evaluation": "ok",
  "metadata": {
    "reason": "First piece",
    "part": {
      "K1001": "part-number",
      "K1000": 1,
      "K1002": "My part"
    }
  },
  "flow": {
    "evaluated": {
      "date": "2019-02-02T11:00:00+01:00",
      "user": {
        "id": 1,
        "username": "kenobi",
        "name": "Obi-Wan Kenobi",
        "email": "obi-wan@kenobi.com",
        "department": "Department 1"
      }
    },
    "open": {
      "date": "2019-02-01T17:00:00+01:00",
      "user": {
        "id": 1,
        "username": "kenobi",
        "name": "Obi-Wan Kenobi",
        "email": "obi-wan@kenobi.com",
        "department": "Department 1"
      }
    }
  },
  "id": 1,
  "code": "order-001",
  "createdAt": "2019-02-01T17:00:00+01:00",
  "priority": "normal",
  "hierarchyLevel": {
    "id": 1,
    "code": "ms-lab",
    "name": {
      "cs": "Měrové centrum",
      "default": "Measurement laboratory"
    },
    "shortName": {
      "cs": "Měrové",
      "default": "MS lab"
    }
  },
  "cooling": {
    "initialTemperature": 65.3,
    "startedAt": "2019-02-01T17:00:00+01:00",
    "finishedAt": "2019-02-01T22:00:00+01:00"
  }
}
Response fields
Path Type Description

id

Number

Unique order id

code

String

Unique order code

state

String

Current state of the order. Can be a code of any configured state (System settings → Ordo → States and evaluation)

evaluation

String

Contains current evaluation of the order if the order was already evaluated (state=evaluated). Can be a code of any configured evaluation (System settings → Ordo → States and evaluation)

priority

String

Current priority of the order. Can be one of the following: normal, high, very-high, critical

createdAt

String (ISO 8601 Date)

Date and time when the order was created

createdBy

Object

User that has created the order

hierarchyLevel

Object

Level of the hierarchy in which the order is created. See the hierarchy field details

cooling

Object

Information about part cooling. See the cooling field details

metadata

Object

Metadata of the order.

Keys of this object are metadata field identifiers and their value contains a content of this metadata field.

Metadata fields are configured per chy.stat instance so the content may vary depending on your system configuration.

flow

Object

Information about flow (transitions between states) of the order.

Keys of this object are codes of states and their value contains the date when the order was moved to this state for the last time and the user who did this. See the flow field details

Possible states of the order are configured per chy.stat instance so the content may vary depending on your system configuration.
Response field user

The createdBy and flow.xxx.user objects contains the following keys:

Path Type Description

id

Number

Unique id of the user

username

String

User name of the user

name

String

Display name of the user

email

String

Email address of the user

department

String

Department the user belongs to
Response field hierarchy

The hierarchyLevel object contains the following keys:

Path Type Description

id

Number

Unique id of the hierarchy level

parentId

Number

Id of the parent level. This property will be omitted for root levels.

code

String

Code of the hierarchy level

name

Localized String

Name of the hierarchy level.

shortName

Localized String

Short name of the hierarchy level
Response field cooling

The cooling object contains the following keys:

Path Type Description

initialTemperature

Number

Initial temperature that the part had when cooling started

startedAt

String (ISO 8601 Date)

Date and time when the cooling started

finishedAt

String (ISO 8601 Date)

Date and time when the cooling ended
Response field flow

The flow object contains the following keys:

Path Type Description

date

String (ISO 8601 Date)

Date and time when the order entered the given state for the last time

user

Object

User that has changed the state of the order

3.1.3. Find orders by query

A POST request is used to find multiple orders using the given query

HTTP request
POST /api/v2/orders/orders/search HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 925

{
  "code": [
    "order-001"
  ],
  "state": [
    "evaluated"
  ],
  "evaluation": [
    "ok"
  ],
  "priority": [
    "normal"
  ],
  "createdAt": {
    "from": "2019-02-01T00:00:00+01:00",
    "to": "2019-02-02T00:00:00+01:00"
  },
  "createdBy": [
    {
      "id": 1,
      "username": "kenobi"
    }
  ],
  "hierarchyLevel": [
    {
      "id": 1,
      "code": "ms-lab"
    }
  ],
  "metadata": {
    "reason": {
      "fulltext": "piece"
    },
    "part": {
      "equal": 1,
      "in": [
        1,
        2
      ],
      "fromInclusive": 1,
      "toInclusive": 1,
      "fromExclusive": 0,
      "toExclusive": 2
    }
  },
  "flow": {
    "evaluated": {
      "date": {
        "from": "2019-02-02T00:00:00+01:00",
        "to": "2019-02-03T00:00:00+01:00"
      },
      "user": [
        {
          "id": 1,
          "username": "kenobi"
        }
      ]
    }
  },
  "pageSize": 30,
  "pageNumber": 1
}
Request fields
Path Type Description

code

Array / String

Order codes to search for

state

Array / String

Indicates the state of the orders to return. Can be a code of any configured state (System settings → Ordo → States and evaluation)

evaluation

Array / String

Indicates the evaluation of the orders to return. Can be a code of any configured evaluation (System settings → Ordo → States and evaluation)

priority

Array / String

Indicates the priority of the orders to return. Can be any of normal, high, very-high, critical

createdAt

Array / Object

Orders created within this period will be returned. You can omit one of the from or to dates.

createdAt.from

String (ISO 8601 Date)

Start date of the period (inclusive)

createdAt.to

String (ISO 8601 Date)

End date of the period (exclusive)

createdBy[]

Array / Object

Orders created by this user will be returned

createdBy[].id

Number

Identifier of the user

createdBy[].username

String

Username of the user

hierarchyLevel[]

Array / Object

Orders assigned to this hierarchy level will be returned

hierarchyLevel[].id

Number

Identifier of the hierarchy level

hierarchyLevel[].code

String

Code of the hierarchy level

metadata

Object

Filters orders by their metadata field values. See the metadata field details

Metadata fields are configured per chy.stat instance so the content may vary depending on your system configuration.

flow

Object

Filters orders using data about flow (transitions between states) of the order.

Keys of this object are codes of states you want to filter by. See the flow field details

Possible states of the order are configured per chy.stat instance so the content may vary depending on your system configuration.

pageSize

Number

Number of items to return

pageNumber

Number

1-based index of the page to return

All the request fields with Array / String or Array / Object data type can contain either array or a single value.

I.e.

"state": [ "open" ]

is the same as

"state": "open"
Request field metadata

The metadata query object can contain multiple field conditions. keys in the metadata object are field identifiers and the values are conditions that can contain any combination of:

Path Type Description

fulltext

String

Content of the field has to contain this text. Comparison is case-insensitive.

equal

Varies

Content of the field has to be equal to this value. If the field content is of type String, the comparison is case-sensitive.

in

Array

Content of the field has to be one of the provided values

fromInclusive

Varies

Content of the field has to be greater than or equal to this value

toInclusive

Varies

Content of the field has to be less than or equal to this value

fromExclusive

Varies

Content of the field has to be greater than this value

toExclusive

Varies

Content of the field has to be less than this value
Request field flow

The flow query object can contain multiple conditions. keys in the flow object are codes of the states and the values are conditions that can contain any combination of:

Path Type Description

date

Array / Object

Orders that changed their status to the given status for the last time within this period will be returned. You can omit one of the from or to dates.

date.from

String (ISO 8601 Date)

Start date of the period (inclusive)

date.to

String (ISO 8601 Date)

End date of the period (exclusive)

user[]

Array / Object

Filter orders by the user that has changed the order status to the given status for the last time

user[].id

Number

Identifier of the user

user[].username

String

Username of the user
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1467

[
  {
    "createdBy": {
      "id": 1,
      "username": "kenobi",
      "name": "Obi-Wan Kenobi",
      "email": "obi-wan@kenobi.com",
      "department": "Department 1"
    },
    "state": "evaluated",
    "evaluation": "ok",
    "metadata": {
      "reason": "First piece",
      "part": {
        "K1001": "part-number",
        "K1000": 1,
        "K1002": "My part"
      }
    },
    "flow": {
      "evaluated": {
        "date": "2019-02-02T11:00:00+01:00",
        "user": {
          "id": 1,
          "username": "kenobi",
          "name": "Obi-Wan Kenobi",
          "email": "obi-wan@kenobi.com",
          "department": "Department 1"
        }
      },
      "open": {
        "date": "2019-02-01T17:00:00+01:00",
        "user": {
          "id": 1,
          "username": "kenobi",
          "name": "Obi-Wan Kenobi",
          "email": "obi-wan@kenobi.com",
          "department": "Department 1"
        }
      }
    },
    "id": 1,
    "code": "order-001",
    "createdAt": "2019-02-01T17:00:00+01:00",
    "priority": "normal",
    "hierarchyLevel": {
      "id": 1,
      "code": "ms-lab",
      "name": {
        "cs": "Měrové centrum",
        "default": "Measurement laboratory"
      },
      "shortName": {
        "cs": "Měrové",
        "default": "MS lab"
      }
    },
    "cooling": {
      "initialTemperature": 65.3,
      "startedAt": "2019-02-01T17:00:00+01:00",
      "finishedAt": "2019-02-01T22:00:00+01:00"
    }
  }
]
Response fields
Path Type Description

[]

Array

Array of orders found by the query

[].id

Number

Unique order id

[].code

String

Unique order code

[].state

String

Current state of the order. Can be a code of any configured state (System settings → Ordo → States and evaluation)

[].evaluation

String

Contains current evaluation of the order if the order was already evaluated (state=evaluated). Can be a code of any configured evaluation (System settings → Ordo → States and evaluation)

[].priority

String

Current priority of the order. Can be one of the following: normal, high, very-high, critical

[].createdAt

String (ISO 8601 Date)

Date and time when the order was created

[].createdBy

Object

User that has created the order

[].hierarchyLevel

Object

Level of the hierarchy in which the order is created. See the hierarchy field details

[].cooling

Object

Information about part cooling. See the cooling field details

[].metadata

Object

Metadata of the order.

Keys of this object are metadata field identifiers and their value contains a content of this metadata field.

Metadata fields are configured per chy.stat instance so the content may vary depending on your system configuration.

[].flow

Object

Information about flow (transitions between states) of the order.

Keys of this object are codes of states and their value contains the date when the order was moved to this state for the last time and the user who did this. See the flow field details

Possible states of the order are configured per chy.stat instance so the content may vary depending on your system configuration.
Response field user

The createdBy and flow.xxx.user objects contains the following keys:

Path Type Description

id

Number

Unique id of the user

username

String

User name of the user

name

String

Display name of the user

email

String

Email address of the user

department

String

Department the user belongs to
Response field hierarchy

The hierarchyLevel object contains the following keys:

Path Type Description

id

Number

Unique id of the hierarchy level

parentId

Number

Id of the parent level. This property will be omitted for root levels.

code

String

Code of the hierarchy level

name

Localized String

Name of the hierarchy level.

shortName

Localized String

Short name of the hierarchy level
Response field cooling

The cooling object contains the following keys:

Path Type Description

initialTemperature

Number

Initial temperature that the part had when cooling started

startedAt

String (ISO 8601 Date)

Date and time when the cooling started

finishedAt

String (ISO 8601 Date)

Date and time when the cooling ended
Response field flow

The flow object contains the following keys:

Path Type Description

date

String (ISO 8601 Date)

Date and time when the order entered the given state for the last time

user

Object

User that has changed the state of the order

4. Scrap

4.1. Production levels

Hierarchical structure of production. Can contain divisions, lines, workplaces.

4.1.1. Production level types

Type Description

structure

Any structure above the line

line

Production line, department

workplace

Production workplace

4.1.2. Find production level by id

Use a GET request to find a production level by id

HTTP request
GET /api/v2/scrap/processes/1 HTTP/1.1
Path parameters
Table 1. /api/v2/scrap/processes/{id}
Parameter Description

id

Id of the production level
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 149

{
  "shortName": {
    "default": "Division"
  },
  "type": "structure",
  "id": 1,
  "code": "division",
  "name": {
    "default": "Division"
  }
}
Response fields
Path Type Description

id

Number

Id of the production level

parentId

Number

Id of the parent production level

code

String

Unique code of the production level

shortName

Localized String

Short name of the production level

name

Localized String

Name of the production level

type

String

Type of the production level. See Production level types

4.1.3. Find production level by code

Use a GET request to find a production level by code

HTTP request
GET /api/v2/scrap/processes?code=division HTTP/1.1
Query parameters
Parameter Description

code

Code of the production level
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 149

{
  "shortName": {
    "default": "Division"
  },
  "type": "structure",
  "id": 1,
  "code": "division",
  "name": {
    "default": "Division"
  }
}
Response fields

See Production level response fields

4.1.4. Find all production levels

Use a GET request to find all production levels

HTTP request
GET /api/v2/scrap/processes HTTP/1.1
Query parameters
Parameter Description

pageNumber

1-based index of the page to return (optional)

pageSize

Number of items to return (optional)
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1137

[
  {
    "shortName": {
      "default": "Division"
    },
    "type": "structure",
    "id": 1,
    "code": "division",
    "name": {
      "default": "Division"
    }
  },
  {
    "shortName": {
      "default": "Dept 1"
    },
    "type": "line",
    "parentId": 1,
    "id": 2,
    "code": "department_1",
    "name": {
      "default": "Department 1"
    }
  },
  {
    "shortName": {
      "default": "Preparation"
    },
    "type": "workplace",
    "parentId": 2,
    "id": 3,
    "code": "preparation",
    "name": {
      "default": "Preparation"
    }
  },
  {
    "shortName": {
      "default": "Dept 2"
    },
    "type": "line",
    "parentId": 1,
    "id": 4,
    "code": "department_2",
    "name": {
      "default": "Department 2"
    }
  },
  {
    "shortName": {
      "default": "Mixing"
    },
    "type": "workplace",
    "parentId": 4,
    "id": 5,
    "code": "mixing",
    "name": {
      "default": "Mixing"
    }
  },
  {
    "shortName": {
      "default": "Packing"
    },
    "type": "workplace",
    "parentId": 4,
    "id": 6,
    "code": "packing",
    "name": {
      "default": "Packing"
    }
  }
]
Response fields

An array of Production level response fields

4.1.5. Create production level

Use a POST request to create a production level

HTTP request
POST /api/v2/scrap/processes HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 177

{
  "parentId": 1,
  "code": "department_1",
  "poradi": 0,
  "shortName": {
    "default": "Department 1"
  },
  "name": {
    "default": "Department 1"
  },
  "type": "line"
}
Request fields
Path Type Description

parentId

Number

Id of the parent production level

code

String

Unique code of the production level

shortName

Localized String

Short name of the production level

name

Localized String

Name of the production level

type

String

Type of the production level. See Production level types
HTTP response
HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Content-Length: 13

{
  "id": 7
}
Response fields
Path Type Description

id

Number

Id of the created production level

4.1.6. Replace production level

Use a PUT request to replace an existing production level

HTTP request
PUT /api/v2/scrap/processes/3 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 170

{
  "parentId": 2,
  "code": "mounting",
  "poradi": 0,
  "shortName": {
    "default": "Mounting"
  },
  "name": {
    "default": "Mounting"
  },
  "type": "workplace"
}
Path parameters
Table 1. /api/v2/scrap/processes/{id}
Parameter Description

id

Id of the production level to replace
Request fields

See Production level request fields

HTTP response
HTTP/1.1 200 OK

4.1.7. Delete production level

Use a DELETE request to delete an existing production level

HTTP request
DELETE /api/v2/scrap/processes/1 HTTP/1.1
Path parameters
Table 1. /api/v2/scrap/processes/{id}
Parameter Description

id

Id of the production level to delete
HTTP response
HTTP/1.1 200 OK

4.2. Product levels

Hierarchical structure of products. Can contain family od products, products, components.

4.2.1. Product level types

Type Description

structure

Any structure above the product

product

Concrete product

component

Product component

4.2.2. Find product level by id

Use a GET request to find a product level by id

HTTP request
GET /api/v2/scrap/products/1 HTTP/1.1
Path parameters
Table 1. /api/v2/scrap/products/{id}
Parameter Description

id

Id of the product level
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 143

{
  "shortName": {
    "default": "Muffin"
  },
  "type": "structure",
  "id": 1,
  "code": "muffin",
  "name": {
    "default": "Muffin"
  }
}
Response fields
Path Type Description

id

Number

Id of the product level

parentId

Number

Id of the parent product level

code

String

Unique code of the product level

shortName

Localized String

Short name of the product level

name

Localized String

Name of the product level

type

String

Type of the product level. See Product level types

numberOfComponents

Number

How many components are contained in the parent product

price

Number

Price of the product or component

defaultProductionSize

Number

How many products are typically produced in a single batch

4.2.3. Find product level by code

Use a GET request to find a product level by code

HTTP request
GET /api/v2/scrap/products?code=muffin HTTP/1.1
Query parameters
Parameter Description

code

Code of the product level
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 143

{
  "shortName": {
    "default": "Muffin"
  },
  "type": "structure",
  "id": 1,
  "code": "muffin",
  "name": {
    "default": "Muffin"
  }
}
Response fields

See Product level response fields

4.2.4. Find all product levels

Use a GET request to find all product levels

HTTP request
GET /api/v2/scrap/products HTTP/1.1
Query parameters
Parameter Description

pageNumber

1-based index of the page to return (optional)

pageSize

Number of items to return (optional)
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1070

[
  {
    "shortName": {
      "default": "Muffin"
    },
    "type": "structure",
    "id": 1,
    "code": "muffin",
    "name": {
      "default": "Muffin"
    }
  },
  {
    "shortName": {
      "default": "Choco muffin"
    },
    "type": "product",
    "parentId": 1,
    "id": 2,
    "code": "choco_muffin",
    "name": {
      "default": "Choco muffin"
    }
  },
  {
    "shortName": {
      "default": "Flour"
    },
    "type": "component",
    "numberOfComponents": 10,
    "price": 0.1,
    "parentId": 2,
    "id": 3,
    "code": "flour",
    "name": {
      "default": "Flour"
    }
  },
  {
    "shortName": {
      "default": "Cacao"
    },
    "type": "component",
    "numberOfComponents": 1,
    "price": 1,
    "parentId": 2,
    "id": 4,
    "code": "cacao",
    "name": {
      "default": "Cacao"
    }
  },
  {
    "shortName": {
      "default": "Chocolate"
    },
    "type": "component",
    "numberOfComponents": 2,
    "price": 2,
    "parentId": 2,
    "id": 5,
    "code": "chocolate",
    "name": {
      "default": "Chocolate"
    }
  }
]
Response fields

An array of Product level response fields

4.2.5. Create product level

Use a POST request to create a product level

HTTP request
POST /api/v2/scrap/products HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 171

{
  "shortName": {
    "default": "Vanilla muffin"
  },
  "type": "product",
  "parentId": 1,
  "code": "vanilla_muffin",
  "name": {
    "default": "Vanilla muffin"
  }
}
Request fields
Path Type Description

parentId

Number

Id of the parent product level

code

String

Unique code of the product level

shortName

Localized String

Short name of the product level

name

Localized String

Name of the product level

type

String

Type of the product level. See Product level types

numberOfComponents

Number

How many components are contained in the parent product

price

Number

Price of the product or component

defaultProductionSize

Number

How many products are typically produced in a single batch
HTTP response
HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Content-Length: 13

{
  "id": 6
}
Response fields
Path Type Description

id

Number

Id of the created product level

4.2.6. Replace product level

Use a PUT request to replace an existing product level

HTTP request
PUT /api/v2/scrap/products/3 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 190

{
  "shortName": {
    "default": "Flour"
  },
  "type": "component",
  "numberOfComponents": 10,
  "price": 0.2,
  "parentId": 2,
  "code": "flour",
  "name": {
    "default": "Flour"
  }
}
Path parameters
Table 1. /api/v2/scrap/products/{id}
Parameter Description

id

Id of the product level to replace
Request fields

See Product level request fields

HTTP response
HTTP/1.1 200 OK

4.2.7. Delete product level

Use a DELETE request to delete an existing product level

HTTP request
DELETE /api/v2/scrap/products/1 HTTP/1.1
Path parameters
Table 1. /api/v2/scrap/products/{id}
Parameter Description

id

Id of the product level to delete
HTTP response
HTTP/1.1 200 OK

4.3. Defect types

4.3.1. Types od defect types

Type Description

process

Process defect

product

Product defect

4.3.2. Find defect type by id

Use a GET request to find a defect type by id

HTTP request
GET /api/v2/scrap/defect-types/1 HTTP/1.1
Path parameters
Table 1. /api/v2/scrap/defect-types/{id}
Parameter Description

id

Id of the defect type
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 103

{
  "type": "process",
  "id": 1,
  "code": "E001",
  "name": {
    "default": "High temperature"
  }
}
Response fields
Path Type Description

id

Number

Id of the defect type

code

String

Unique code of the defect type

name

Localized String

Name of the defect type

type

String

Type of the defect type. See See Types od defect types

4.3.3. Find defect type by code

Use a GET request to find a defect type by code

HTTP request
GET /api/v2/scrap/defect-types?code=E001 HTTP/1.1
Query parameters
Parameter Description

code

Code of the defect type
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 103

{
  "type": "process",
  "id": 1,
  "code": "E001",
  "name": {
    "default": "High temperature"
  }
}
Response fields

See Defect type response fields

4.3.4. Find all defect types

Use a GET request to find all defect types

HTTP request
GET /api/v2/scrap/defect-types HTTP/1.1
Query parameters
Parameter Description

pageNumber

1-based index of the page to return (optional)

pageSize

Number of items to return (optional)
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 356

[
  {
    "type": "process",
    "id": 1,
    "code": "E001",
    "name": {
      "default": "High temperature"
    }
  },
  {
    "type": "process",
    "id": 2,
    "code": "E002",
    "name": {
      "default": "Low temperature"
    }
  },
  {
    "type": "product",
    "id": 3,
    "code": "E101",
    "name": {
      "default": "Too hard"
    }
  }
]
Response fields

An array of Defect type response fields

4.3.5. Create defect type

Use a POST request to create a defect type

HTTP request
POST /api/v2/scrap/defect-types HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 88

{
  "code": "E102",
  "name": {
    "default": "Medium baked"
  },
  "type": "product"
}
Request fields
Path Type Description

code

String

Unique code of the defect type

name

Localized String

Name of the defect type

type

String

Type of the defect type. See See Types od defect types
HTTP response
HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Content-Length: 13

{
  "id": 4
}
Response fields
Path Type Description

id

Number

Id of the created defect type

4.3.6. Replace defect type

Use a PUT request to replace an existing defect type

HTTP request
PUT /api/v2/scrap/defect-types/3 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 86

{
  "code": "E101",
  "name": {
    "default": "Too crispy"
  },
  "type": "product"
}
Path parameters
Table 1. /api/v2/scrap/defect-types/{id}
Parameter Description

id

Id of the defect type to replace
Request fields

See Defect type request fields

HTTP response
HTTP/1.1 200 OK

4.3.7. Delete defect type

Use a DELETE request to delete an existing defect type

HTTP request
DELETE /api/v2/scrap/defect-types/1 HTTP/1.1
Path parameters
Table 1. /api/v2/scrap/defect-types/{id}
Parameter Description

id

Id of the defect type to delete
HTTP response
HTTP/1.1 200 OK

4.4. Teams

4.4.1. Find team by id

Use a GET request to find a team by id

HTTP request
GET /api/v2/scrap/teams/1 HTTP/1.1
Path parameters
Table 1. /api/v2/scrap/teams/{id}
Parameter Description

id

Id of the team
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 72

{
  "id": 1,
  "code": "T001",
  "name": {
    "default": "Team 1"
  }
}
Response fields
Path Type Description

id

Number

Id of the team

code

String

Unique code of the team

name

Localized String

Name of the team

4.4.2. Find team by code

Use a GET request to find a team by code

HTTP request
GET /api/v2/scrap/teams?code=T001 HTTP/1.1
Query parameters
Parameter Description

code

Code of the team
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 72

{
  "id": 1,
  "code": "T001",
  "name": {
    "default": "Team 1"
  }
}
Response fields

See Team response fields

4.4.3. Find all teams

Use a GET request to find all teams

HTTP request
GET /api/v2/scrap/teams HTTP/1.1
Query parameters
Parameter Description

pageNumber

1-based index of the page to return (optional)

pageSize

Number of items to return (optional)
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 266

[
  {
    "id": 1,
    "code": "T001",
    "name": {
      "default": "Team 1"
    }
  },
  {
    "id": 2,
    "code": "T002",
    "name": {
      "default": "Team 2"
    }
  },
  {
    "id": 3,
    "code": "T003",
    "name": {
      "default": "Team 3"
    }
  }
]
Response fields

An array of Team response fields

4.4.4. Create team

Use a POST request to create a team

HTTP request
POST /api/v2/scrap/teams HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 61

{
  "code": "T004",
  "name": {
    "default": "Team 4"
  }
}
Request fields
Path Type Description

code

String

Unique code of the team

name

Localized String

Name of the team
HTTP response
HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Content-Length: 13

{
  "id": 4
}
Response fields
Path Type Description

id

Number

Id of the created team

4.4.5. Replace team

Use a PUT request to replace an existing team

HTTP request
PUT /api/v2/scrap/teams/3 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 72

{
  "code": "T003",
  "name": {
    "default": "Team 3 - trainees"
  }
}
Path parameters
Table 1. /api/v2/scrap/teams/{id}
Parameter Description

id

Id of the team to replace
Request fields

See Team request fields

HTTP response
HTTP/1.1 200 OK

4.4.6. Delete team

Use a DELETE request to delete an existing team

HTTP request
DELETE /api/v2/scrap/teams/1 HTTP/1.1
Path parameters
Table 1. /api/v2/scrap/teams/{id}
Parameter Description

id

Id of the team to delete
HTTP response
HTTP/1.1 200 OK

4.5. Shifts

4.5.1. Find shift by id

Use a GET request to find a shift by id

HTTP request
GET /api/v2/scrap/shifts/1 HTTP/1.1
Path parameters
Table 1. /api/v2/scrap/shifts/{id}
Parameter Description

id

Id of the shift
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 73

{
  "id": 1,
  "code": "S001",
  "name": {
    "default": "Shift 1"
  }
}
Response fields
Path Type Description

id

Number

Id of the shift

code

String

Unique code of the shift

name

Localized String

Name of the shift

4.5.2. Find shift by code

Use a GET request to find a shift by code

HTTP request
GET /api/v2/scrap/shifts?code=S001 HTTP/1.1
Query parameters
Parameter Description

code

Code of the shift
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 73

{
  "id": 1,
  "code": "S001",
  "name": {
    "default": "Shift 1"
  }
}
Response fields

See Shift response fields

4.5.3. Find all shifts

Use a GET request to find all shifts

HTTP request
GET /api/v2/scrap/shifts HTTP/1.1
Query parameters
Parameter Description

pageNumber

1-based index of the page to return (optional)

pageSize

Number of items to return (optional)
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 269

[
  {
    "id": 1,
    "code": "S001",
    "name": {
      "default": "Shift 1"
    }
  },
  {
    "id": 2,
    "code": "S002",
    "name": {
      "default": "Shift 2"
    }
  },
  {
    "id": 3,
    "code": "S003",
    "name": {
      "default": "Shift 3"
    }
  }
]
Response fields

An array of Shift response fields

4.5.4. Create team

Use a POST request to create a shift

HTTP request
POST /api/v2/scrap/shifts HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 62

{
  "code": "S004",
  "name": {
    "default": "Shift 4"
  }
}
Request fields
Path Type Description

code

String

Unique code of the shift

name

Localized String

Name of the shift
HTTP response
HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Content-Length: 13

{
  "id": 4
}
Response fields
Path Type Description

id

Number

Id of the created shift

4.5.5. Replace team

Use a PUT request to replace an existing shift

HTTP request
PUT /api/v2/scrap/shifts/3 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 70

{
  "code": "S003",
  "name": {
    "default": "Shift 3 - night"
  }
}
Path parameters
Table 1. /api/v2/scrap/shifts/{id}
Parameter Description

id

Id of the shift to replace
Request fields

See Shift request fields

HTTP response
HTTP/1.1 200 OK

4.5.6. Delete shift

Use a DELETE request to delete an existing shift

HTTP request
DELETE /api/v2/scrap/shifts/1 HTTP/1.1
Path parameters
Table 1. /api/v2/scrap/shifts/{id}
Parameter Description

id

Id of the shift to delete
HTTP response
HTTP/1.1 200 OK

4.6. Productions

4.6.1. Find production by id

Use a GET request to find a production by id

HTTP request
GET /api/v2/scrap/productions/1 HTTP/1.1
Path parameters
Table 1. /api/v2/scrap/productions/{id}
Parameter Description

id

Id of the production
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 878

{
  "id": 1,
  "date": "2020-01-01T17:00:00+01:00",
  "process": {
    "type": "line",
    "id": 1,
    "code": "baking",
    "name": {
      "default": "Baking"
    }
  },
  "product": {
    "type": "product",
    "id": 1,
    "code": "muffin",
    "name": {
      "default": "Muffin"
    }
  },
  "shift": {
    "id": 1,
    "code": "S001",
    "name": {
      "default": "Shift 1"
    }
  },
  "team": {
    "id": 1,
    "code": "T001",
    "name": {
      "default": "Team 1"
    }
  },
  "order": "order-001",
  "totalProduction": 125,
  "complete": true,
  "createdBy": {
    "id": 1,
    "username": "kenobi",
    "name": "Obi-Wan Kenobi",
    "email": "obi-wan@kenobi.com",
    "department": "Department 1"
  },
  "editedBy": {
    "id": 1,
    "username": "kenobi",
    "name": "Obi-Wan Kenobi",
    "email": "obi-wan@kenobi.com",
    "department": "Department 1"
  }
}
Response fields
Path Type Description

id

Number

Id of the production

date

String

Production date

process

Object

Production level, see Production level response fields

product

Object

Product level, see Product level response fields

shift

Object

Team, see Team response fields

team

Object

Shift, see Shift response fields

order

String

Order code

totalProduction

Number

Total production count

complete

Boolean

True if this production is complete

createdBy

Object

User that created the production

editedBy

Object

User that last modified the production

The createdBy and editedBy contains the following keys:

Response fields-user
Path Type Description

id

Number

Unique id of the user

username

String

User name of the user

name

String

Display name of the user

email

String

Email address of the user

department

String

Department the user belongs to

4.6.2. Find production by query

Use a POST request to find a production by query

HTTP request
POST /api/v2/scrap/productions/search HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 465

{
  "order": [
    "order-001"
  ],
  "process": [
    {
      "id": 1,
      "code": "baking"
    }
  ],
  "product": [
    {
      "id": 1,
      "code": "muffin"
    }
  ],
  "team": [
    {
      "id": 1,
      "code": "T001"
    }
  ],
  "shift": [
    {
      "id": 1,
      "code": "S001"
    }
  ],
  "createdAt": {
    "from": "2019-12-31T23:00:00+01:00",
    "to": "2020-01-01T23:00:00+01:00"
  },
  "complete": true,
  "pageSize": 20,
  "pageNumber": 1
}
Request fields
Path Type Description

order

Array / String

Order codes

process[]

Array / Object

Production levels

process[].id

Number

Id of the production level

process[].code

String

Unique code of the production level

product[]

Array / Object

Product levels

product[].id

Number

Id of the product level

product[].code

String

Unique code of the product level

team[]

Array / Object

Teams

team[].id

Number

Id of the team

team[].code

String

Unique code of the team

shift[]

Array / Object

Shifts

shift[].id

Number

Id of the shift

shift[].code

String

Unique code of the shift

createdAt

Object

Period of the production creation date

complete

Boolean

Complete or uncomplete production

pageSize

Number

Number of items to return

pageNumber

Number

1-based index of the page to return

The periodInclusive and periodExclusive contains the following keys.

Request fields-period
Path Type Description

from

String (ISO 8601 Date)

Start date of the period (inclusive)

to

String (ISO 8601 Date)

End date of the period (exclusive)
You can omit one of the from or to dates
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 984

[
  {
    "id": 1,
    "date": "2020-01-01T17:00:00+01:00",
    "process": {
      "type": "line",
      "id": 1,
      "code": "baking",
      "name": {
        "default": "Baking"
      }
    },
    "product": {
      "type": "product",
      "id": 1,
      "code": "muffin",
      "name": {
        "default": "Muffin"
      }
    },
    "shift": {
      "id": 1,
      "code": "S001",
      "name": {
        "default": "Shift 1"
      }
    },
    "team": {
      "id": 1,
      "code": "T001",
      "name": {
        "default": "Team 1"
      }
    },
    "order": "order-001",
    "totalProduction": 125,
    "complete": true,
    "createdBy": {
      "id": 1,
      "username": "kenobi",
      "name": "Obi-Wan Kenobi",
      "email": "obi-wan@kenobi.com",
      "department": "Department 1"
    },
    "editedBy": {
      "id": 1,
      "username": "kenobi",
      "name": "Obi-Wan Kenobi",
      "email": "obi-wan@kenobi.com",
      "department": "Department 1"
    }
  }
]
Response fields

An array of Production response fields

4.7. Defects

4.7.1. Find defects by production id

Use a GET request to find defects by production id

HTTP request
GET /api/v2/scrap/productions/1/defects HTTP/1.1
Path parameters
Table 1. /api/v2/scrap/productions/{id}/defects
Parameter Description

id

Id of the production
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2502

{
  "processDefects": [
    {
      "productDefects": [
        {
          "repairNumber": "SN124",
          "description": "Some useful description",
          "scrappedComponents": [],
          "id": 2,
          "defectType": {
            "type": "product",
            "id": 2,
            "code": "E101",
            "name": {
              "default": "Too hard"
            }
          },
          "count": 8,
          "position": "position-1"
        }
      ],
      "id": 1,
      "process": {
        "shortName": {
          "default": "Mixing"
        },
        "type": "workplace",
        "parentId": 4,
        "id": 5,
        "code": "mixing",
        "name": {
          "default": "Mixing"
        }
      },
      "defectType": {
        "type": "process",
        "id": 1,
        "code": "E001",
        "name": {
          "default": "High temperature"
        }
      },
      "count": 15,
      "position": "position-1"
    },
    {
      "productDefects": [],
      "id": 2,
      "process": {
        "shortName": {
          "default": "Mixing"
        },
        "type": "workplace",
        "parentId": 4,
        "id": 5,
        "code": "mixing",
        "name": {
          "default": "Mixing"
        }
      },
      "defectType": {
        "type": "process",
        "id": 1,
        "code": "E001",
        "name": {
          "default": "High temperature"
        }
      },
      "count": 4,
      "position": "position-2"
    }
  ],
  "productDefects": [
    {
      "repairNumber": "SN123",
      "description": "Some useful description",
      "scrappedComponents": [
        {
          "component": {
            "shortName": {
              "default": "Flour"
            },
            "type": "component",
            "numberOfComponents": 10,
            "price": 0.1,
            "parentId": 1,
            "id": 1,
            "code": "flour",
            "name": {
              "default": "Flour"
            }
          },
          "count": 2
        }
      ],
      "id": 1,
      "process": {
        "shortName": {
          "default": "Mixing"
        },
        "type": "workplace",
        "parentId": 4,
        "id": 5,
        "code": "mixing",
        "name": {
          "default": "Mixing"
        }
      },
      "defectType": {
        "type": "product",
        "id": 2,
        "code": "E101",
        "name": {
          "default": "Too hard"
        }
      },
      "count": 4,
      "position": "position-1"
    }
  ]
}
Response fields
Path Type Description

processDefects[]

Array

Array of process defects, see Process defect response fields

productDefects[]

Array

Array of product defects without process defect cause, see Product defect response fields
Process defect response fields
Path Type Description

id

Number

Id of the process defect

process

Object

Production level, see Production level response fields

defectType

Object

Defect type, see Defect type response fields

productDefects[]

Array

Array of product defects caused by this process defect, see Product defect response fields

count

Number

Pieces count

position

String

Position
Product defect response fields
Path Type Description

id

Number

Id of the process defect

process

Object

Production level, see Production level response fields

defectType

Object

Defect type, see Defect type response fields

count

Number

Pieces count

position

String

Position

repairNumber

String

Repair number

description

String

Description

scrappedComponents[]

Array

Array of scrapped components
Scrapped component response fields
Path Type Description

component

Object

Component, see Producit level response fields

count

Number

Component count