ADI Orders

❗Enterprise Feature

This feature is available only to customers with an enterprise Platform subscription. Contact us to discuss enabling it on your account.

The ADI Orders API allows external systems and integrators to order bulk large amounts of ADIs (Thngs) required for serializing their goods. This is the usually the best approach to such a task, as opposed to creating each Thng individually. Each ADI order includes metadata and template information describing how each generated Thng looks.

API Status /adis/orders/ /adis/orders/:orderId /adis/orders/:orderId/events /adis/orders/:orderId/events/:orderEventId

ADIOrderDocument Data Model

Object representing an order of new ADIs, containing data about what they should look like.

You must specify either your own list of ids, or specify idGeneration so that the Platform can generate them instead.

See also: ADIOrderMetadataDocument, ADIOrderStatusDocument, ADIOrderIDGenerationDocument, ADIOrderFileMetadataDocument, ADIOrderResultsDocument

ADIOrderMetadataDocument Data Model

Object describing the data used as input for the order, such as what the output Thngs should look like.

ADIOrderIDGenerationDocument Data Model

Metadata of the set of IDs for generation.

.prefix (string)
    The prefix of every ID to be generated.

.suffix (string)
    The suffix of every ID to be generated.

.characterSet (string, one of 'GS1-64w', 'AN-47', 'UAN-28', 'GS1-36w')
    The character set to be used for ID generation. Default
    value is 'AN-47'.

.length (number, required)
    The length of ID part which is going to be generated. Does
    not include 'prefix' and 'suffix' if were set. Allowed
    values are in range 8..20

.quantity (number, required)
    The quantity of IDs to be generated. Maximal allowed value
    is 20000.

The values available for characterSet define which characters will be used in the IDs generated. These are:

• AN-47 (Unambiguous alphanumeric without vowels) - 23456789BCDFGHJKLMNPQRSTVWXZbcdfghjkmnpqrstvwxz
• GS1-64w - (Web-safe GS1 Serial AI encodable character set) -0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz
• UAN-28 - (Unambiguous AlphaNumeric) 23456789BCDFGHJKLMNPQRSTVWXZ
• GS1-36w - (Web-safe GS1 Serial AI encodable character set) 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ
• N - (Numeric) 0123456789 - note that the unique range for numeric is limited so use with caution!

ADIOrderStatusDocument Data Model

See also: ADIOrderProgressDocument

ADIOrderProgressDocument Data Model

See also: ADIOrderErrorDetailsDocument

ADIOrderErrorDetailsDocument Data Model

Error codes:

• 80000010 - The identifier has invalid format.
• 80000020 - ADI Order not found.
• 80000030 - ADI Order event not found.
• 80000040 - Product not found.
• 80000050 - Array of identifiers contains more ids than allowed.
• 80000060 - Provided list of identifiers contains duplicates.
• 80000070 - Action type doesn't exist.
• 80000080 - Identifiers doesn't belong to the specified adi-order.
• 80000090 - Account is not allowed to make request in specified target account.
• 80000100 - Short domain not specified together with default redirect URL.
• 80000110 - Provided filter is not valid.
• 80000120 - Invalid query parameter.
• 80000130 - ADI Order is in progress.
• 80000140 - Product is not unique.
• 80000150 - ADI Order request body is not valid
• 80000160 - Requested IDs quantity is not allowed
• 80000170 - Project is not found
• 80000180 - The list of identifiers contains forbidden characters
• 80009998 - Request body is missing.
• 80009999 - Internal unknown error.
• 80100010 - Thng already exists.
• 80100020 - Redirection for shortDomain and shortId already exists and points to the different resource.
• 80100030 - Product with the identifier is not found.
• 80100040 - Product with the identifier is not unique.
• 80109999 - Internal unknown error.
• 80200010 - Thng with the identifier is not found
• 80300010 - An identity with that Identifier and ADI order already exists for that same account.

ADIOrderFileMetadataDocument Data Model

Contains configuration required for file generation.

.csv (ADIOrderFileCsvMetadataDocument)
    Contains configuration parameters for txt file generation.

.txt (ADIOrderFileTxtMetadataDocument)
    Contains configuration parameters for txt file generation.

See also: ADIOrderFileCsvMetadataDocument, ADIOrderFileTxtMetadataDocument

ADIOrderFileCsvMetadataDocument Data Model

Contains configuration parameters for txt file generation.

ADIOrderFileTxtMetadataDocument Data Model

Contains configuration parameters for txt file generation.

ADIOrderResultsDocument Data Model

Object containing links to generated files.

.identifiers (ADIOrderFileIdentifiersDocument)
    Links to files with identifiers.

.errors (ADIOrderFileErrorsDocument)
    Link to file with errors happened during ADI generation.

See also: ADIOrderFileIdentifiersDocument, ADIOrderFileErrorsDocument

ADIOrderFileIdentifiersDocument Data Model

Links to files with identifiers.

.csv (string)
    Link to csv file.

.txt (string)
    Link to txt file.

.json (string)
    Link to json file.

ADIOrderFileErrorsDocument Data Model

Link to file with errors happened during ADI generation.

.json (string)
    Link to the json file with errors.

Create an ADI Order

Read all ADI Orders

Retrieve a list of ADI Orders.

operator.adiOrder().read()
  .then(console.log);

Read an ADI Order

Read a single ADI Order by its id.

Retrieve ADI Order IDs as Text, CSV and JSON files

Once the ID files have been generated, the file links will be returned within results.identifiers when you read the Order.

Please note that there will be a delay between the order status changing to Complete and the files being available.

To retrieve the IDs, select the link for the format you require and send a GET request with the following additional headers:

Your file links expire after 30 minutes. To get new links, retrieve the ADI Order again.

Retrieve ADI Order errors as JSON file

If there were errors, you can download a JSON file containing these errors from the file location referenced in results.errors.json. Send a GET request with the following additional headers:

ADI Order Events

Once an ADI Order has completed, it is also possible to create events represented by actions on the Thngs created through the order, such as encodings or other supply-chain related real-world events. This can be used to record in one request the action on all the items in the order.

If the ADI Order was created with the metadata.project property specified, any events created for this order will result in actions scoped to the same project.

ADIOrderEventDocument Data Model

Object containing action details and IDs of ADIs to create actions for.

See also: ActionDocument, ADIOrderEventStatusDocument

Create an ADI Order Event

Creates an event for actions on the ADIs (Thngs) in the specified ADI Order. This request should include the IDs to use when creating the actions.

const orderId = 'UNc6n2Bk6GPhh6waRm2mNppb';
const payload = {
  metadata: {
    type: 'encodings',
    tags: ['example']
  },
  ids: [
    'serial1',
    'serial2'
  ],
  customFields: {
    internalId: 'X7JF'
  },
  tags: ['X7JF']
};

operator.adiOrder(orderId).event()
  .create(payload)
  .then(console.log);

Read all ADI Order events

Retrieves all ADI Order events belonging to the specified ADI Order.

const orderId = 'UNc6n2Bk6GPhh6waRm2mNppb';

operator.adiOrder(orderId).event()
  .read()
  .then(console.log);

Read an ADI Order event

Retrieve a single ADI order event by its ID.

const orderId = 'UNc6n2Bk6GPhh6waRm2mNppb';
const eventId = 'UrF2qWHREAQGMHVD2kKKbtqc';

operator.adiOrder(orderId)
  .event(eventId)
  .read()
  .then(console.log);

Add the withErrors=true query parameter to see errors within the status property.