External Production Partner API 1.0.0 documentation

External Production Partner API 1.0.0

This AsyncAPI document specifies the message formats and communication channels between Nexus Go Cards 2.0 (NGOC) and the External Production Partner.

NGOC functions as both a message producer and consumer, depending on the operation:

SEND Operations: Messages sent by NGOC to the External Production Partner.
RECEIVE Operations: Messages received by NGOC from the External Production Partner.

The communication is handled through Azure Service Bus, with de-duplication detection enabled and configured for a 5-day window.

To kickstart your integration you can generate client code using one of the supported AsyncAPI generator templates listed here. The example below generates a nodejs application based on this AsyncAPI specification.

Download the AsyncAPI CLI

npm install -g @asyncapi/cli

Download the generator

npm install @asyncapi/generator@2.4.1

Generate client code

asyncapi generate fromTemplate https://prodpartner.cards.nxsas.com/asyncapi.yml --output ./generated-project @asyncapi/nodejs-template -p server=production

Guidelines for message handling:

Set the message type (e.g., EXTERNAL_PRODUCTION_REQUEST_SENT) as the subject/label of the Service Bus message.
For idempotency, generate a unique UUID to use as the messageId.

For additional information on publishing and subscribing to Azure Service Bus messages, refer to the official Azure Service Bus documentation.

Queue credentials will be provided during the integration setup process.

Servers

amqp://sbns-pubservicebusnamespacepub-prod-03241.servicebus.windows.net/amqpproduction
NGOC managed Azure Service Bus instance used for messaging.

Operations

SEND EXTERNAL_PRODUCTION_REQUEST_SENT
Operation IDproduction-request.publish
Available only on servers:
- production
Accepts the following message:
idempotency-uuid
Message IDidempotency-uuid
object [ExternalProductionData]
organisationId
required
string
non-empty
shipmentId
required
string
non-empty
ordered
required
string
format: date-time
object
addressOne
required
string
non-empty
addressTwo
string
postalCode
required
string
non-empty
city
required
string
non-empty
countryCode
required
string
2 characters
Country code must be in alpha-2 format

recipient
required
string
non-empty
recipientPhone
string
companyName
string
Additional properties are allowed.
object
articleId
required
string
non-empty
cardId
required
string
non-empty
object
Card elements as specified during on-boarding of article, key value pairs shown are only examples

Examples values:
{"FIRST_NAME":"Jane","LAST_NAME":"Doe","EMPLOYEE_NUMBER":"555-555"}
Additional properties:
string
array<string>
Keys expected to be present in the reportData sent as part of the EXTERNAL_PRODUCTION_CARD_PRODUCED message.

Items:
string
Currently supported values are MIFARE_UID and SERIAL_NUMBER. More values will be added over time.

Allowed values:
"MIFARE_UID"
"SERIAL_NUMBER"
Additional properties are allowed.
array<object>
object
articleId
required
string
non-empty
accessoryId
required
string
non-empty
quantity
required
integer
>= 1
Additional properties are allowed.
Additional properties are allowed.
Examples
{ "organisationId": "string", "shipmentId": "string", "ordered": "2019-08-24T14:15:22Z", "address": { "addressOne": "string", "addressTwo": "string", "postalCode": "string", "city": "string", "countryCode": "st", "recipient": "string", "recipientPhone": "string", "companyName": "string" }, "card": { "articleId": "string", "cardId": "string", "cardElements": { "FIRST_NAME": "Jane", "LAST_NAME": "Doe", "EMPLOYEE_NUMBER": "555-555" }, "expectedReportDataFields": [ "MIFARE_UID" ] }, "accessories": [ { "articleId": "string", "accessoryId": "string", "quantity": 1 } ] }

This example has been generated automatically.
RECEIVE EXTERNAL_PRODUCTION_CARD_PRODUCED
Operation IDcard-produced.subscribe
Available only on servers:
- production
Accepts the following message:
idempotency-uuid
Message IDidempotency-uuid
object [ExternalProductionCardProduced]
organisationId
required
string
non-empty
shipmentId
required
string
non-empty
cardId
required
string
non-empty
timestamp
required
string
format: date-time
object
Report data as specified during on-boarding of article, key value pairs shown are only examples

Examples values:
{"MIFARE_UID":"1234ABCD","SERIAL_NUMBER":"123456"}
Additional properties:
string
Additional properties are allowed.
Examples
{ "organisationId": "string", "shipmentId": "string", "cardId": "string", "timestamp": "2019-08-24T14:15:22Z", "reportData": { "MIFARE_UID": "1234ABCD", "SERIAL_NUMBER": "123456" } }

This example has been generated automatically.
SEND EXTERNAL_PRODUCTION_REPORT_OK
Operation IDreport-ok.publish
Available only on servers:
- production
Accepts the following message:
idempotency-uuid
Message IDidempotency-uuid
object [ExternalProductionReportOk]
organisationId
required
string
non-empty
shipmentId
required
string
non-empty
cardId
required
string
non-empty
timestamp
required
string
format: date-time
Additional properties are allowed.
Examples
{ "organisationId": "string", "shipmentId": "string", "cardId": "string", "timestamp": "2019-08-24T14:15:22Z" }

This example has been generated automatically.
RECEIVE EXTERNAL_PRODUCTION_SHIPPED
Operation IDshipped.subscribe
Available only on servers:
- production
Accepts the following message:
idempotency-uuid
Message IDidempotency-uuid
object [ExternalProductionShipped]
organisationId
required
string
non-empty
shipmentId
required
string
non-empty
array<string>
Items:
string
array<object>
object
accessoryId
string
non-empty
quantity
integer
>= 1
Additional properties are allowed.
object
shippingCarrier
string
trackingNumber
string
trackingUrl
string
Additional properties are allowed.
timestamp
required
string
format: date-time
Additional properties are allowed.
Examples
{ "organisationId": "string", "shipmentId": "string", "cardIds": [ "string" ], "accessories": [ { "accessoryId": "string", "quantity": 1 } ], "shippingInfo": { "shippingCarrier": "string", "trackingNumber": "string", "trackingUrl": "string" }, "timestamp": "2019-08-24T14:15:22Z" }

This example has been generated automatically.
SEND EXTERNAL_PRODUCTION_SHIPPED_OK
Operation IDshipped-ok.publish
Available only on servers:
- production
Accepts the following message:
idempotency-uuid
Message IDidempotency-uuid
object [ExternalProductionShippedOk]
organisationId
required
string
non-empty
shipmentId
required
string
non-empty
timestamp
required
string
format: date-time
Additional properties are allowed.
Examples
{ "organisationId": "string", "shipmentId": "string", "timestamp": "2019-08-24T14:15:22Z" }

This example has been generated automatically.
RECEIVE EXTERNAL_PRODUCTION_ERROR
Operation IDerror.subscribe
Available only on servers:
- production
Accepts the following message:
idempotency-uuid
Message IDidempotency-uuid
object [ExternalProductionError]
organisationId
required
string
non-empty
shipmentId
required
string
non-empty
array<string>
Items:
string
array<string>
Items:
string
required
object
errorCode
required
string
Allowed values:
"INVALID_CARD_ELEMENT"
"INVALID_SAS_LINK"
"INVALID_DELIVERY_ADDRESS"
"UNKNOWN_ARTICLE"
"INVALID_REPORT_DATA"
"INVALID_MESSAGE"
"MISSING_NOTIFICATION"
"OTHER"
details
required
string
non-empty
Additional properties are allowed.
timestamp
required
string
format: date-time
Additional properties are allowed.
Examples
{ "organisationId": "string", "shipmentId": "string", "cardIds": [ "string" ], "accessoryIds": [ "string" ], "reason": { "errorCode": "INVALID_CARD_ELEMENT", "details": "string" }, "timestamp": "2019-08-24T14:15:22Z" }

This example has been generated automatically.
SEND EXTERNAL_PRODUCTION_ERROR
Operation IDerror.publish
Available only on servers:
- production
Accepts the following message:
idempotency-uuid
Message IDidempotency-uuid
object [ExternalProductionError]
organisationId
required
string
non-empty
shipmentId
required
string
non-empty
array<string>
Items:
string
array<string>
Items:
string
required
object
errorCode
required
string
Allowed values:
"INVALID_CARD_ELEMENT"
"INVALID_SAS_LINK"
"INVALID_DELIVERY_ADDRESS"
"UNKNOWN_ARTICLE"
"INVALID_REPORT_DATA"
"INVALID_MESSAGE"
"MISSING_NOTIFICATION"
"OTHER"
details
required
string
non-empty
Additional properties are allowed.
timestamp
required
string
format: date-time
Additional properties are allowed.
Examples
{ "organisationId": "string", "shipmentId": "string", "cardIds": [ "string" ], "accessoryIds": [ "string" ], "reason": { "errorCode": "INVALID_CARD_ELEMENT", "details": "string" }, "timestamp": "2019-08-24T14:15:22Z" }

This example has been generated automatically.

Messages

#1production-request-msg
Message IDproduction-request-msg
object [ExternalProductionData]
organisationId
required
string
non-empty
shipmentId
required
string
non-empty
ordered
required
string
format: date-time
object
addressOne
required
string
non-empty
addressTwo
string
postalCode
required
string
non-empty
city
required
string
non-empty
countryCode
required
string
2 characters
Country code must be in alpha-2 format

recipient
required
string
non-empty
recipientPhone
string
companyName
string
Additional properties are allowed.
object
articleId
required
string
non-empty
cardId
required
string
non-empty
object
Card elements as specified during on-boarding of article, key value pairs shown are only examples

Examples values:
{"FIRST_NAME":"Jane","LAST_NAME":"Doe","EMPLOYEE_NUMBER":"555-555"}
Additional properties:
string
array<string>
Keys expected to be present in the reportData sent as part of the EXTERNAL_PRODUCTION_CARD_PRODUCED message.

Items:
string
Currently supported values are MIFARE_UID and SERIAL_NUMBER. More values will be added over time.

Allowed values:
"MIFARE_UID"
"SERIAL_NUMBER"
Additional properties are allowed.
array<object>
object
articleId
required
string
non-empty
accessoryId
required
string
non-empty
quantity
required
integer
>= 1
Additional properties are allowed.
Additional properties are allowed.
#2card-produced-msg
Message IDcard-produced-msg
object [ExternalProductionCardProduced]
organisationId
required
string
non-empty
shipmentId
required
string
non-empty
cardId
required
string
non-empty
timestamp
required
string
format: date-time
object
Report data as specified during on-boarding of article, key value pairs shown are only examples

Examples values:
{"MIFARE_UID":"1234ABCD","SERIAL_NUMBER":"123456"}
Additional properties:
string
Additional properties are allowed.
#3report-ok-msg
Message IDreport-ok-msg
object [ExternalProductionReportOk]
organisationId
required
string
non-empty
shipmentId
required
string
non-empty
cardId
required
string
non-empty
timestamp
required
string
format: date-time
Additional properties are allowed.
#4shipped-msg
Message IDshipped-msg
object [ExternalProductionShipped]
organisationId
required
string
non-empty
shipmentId
required
string
non-empty
array<string>
Items:
string
array<object>
object
accessoryId
string
non-empty
quantity
integer
>= 1
Additional properties are allowed.
object
shippingCarrier
string
trackingNumber
string
trackingUrl
string
Additional properties are allowed.
timestamp
required
string
format: date-time
Additional properties are allowed.
#5shipped-ok-msg
Message IDshipped-ok-msg
object [ExternalProductionShippedOk]
organisationId
required
string
non-empty
shipmentId
required
string
non-empty
timestamp
required
string
format: date-time
Additional properties are allowed.
#6error-msg
Message IDerror-msg
object [ExternalProductionError]
organisationId
required
string
non-empty
shipmentId
required
string
non-empty
array<string>
Items:
string
array<string>
Items:
string
required
object
errorCode
required
string
Allowed values:
"INVALID_CARD_ELEMENT"
"INVALID_SAS_LINK"
"INVALID_DELIVERY_ADDRESS"
"UNKNOWN_ARTICLE"
"INVALID_REPORT_DATA"
"INVALID_MESSAGE"
"MISSING_NOTIFICATION"
"OTHER"
details
required
string
non-empty
Additional properties are allowed.
timestamp
required
string
format: date-time
Additional properties are allowed.

External Production Partner API 1.0.0

Servers

Operations

SEND EXTERNAL_PRODUCTION_REQUEST_SENT

Examples

This example has been generated automatically.

RECEIVE EXTERNAL_PRODUCTION_CARD_PRODUCED

Examples

This example has been generated automatically.

SEND EXTERNAL_PRODUCTION_REPORT_OK

Examples

This example has been generated automatically.

RECEIVE EXTERNAL_PRODUCTION_SHIPPED

Examples

This example has been generated automatically.

SEND EXTERNAL_PRODUCTION_SHIPPED_OK

Examples

This example has been generated automatically.

RECEIVE EXTERNAL_PRODUCTION_ERROR

Examples

This example has been generated automatically.

SEND EXTERNAL_PRODUCTION_ERROR

Examples

This example has been generated automatically.

Messages