Enterprise FeatureThis 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
/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
, 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
ADIOrderProgressDocument Data Model
See also: ADIOrderErrorDetailsDocument
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 valid80000160
- Requested IDs quantity is not allowed80000170
- Project is not found80000180
- The list of identifiers contains forbidden characters80009998
- 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 found80300010
- 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.
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
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.