Before you start
Before creating an order:- Create the fleet with
POST /emp/v1/fleets. - Keep the customer-provided
fleetId; you will use the same value when placing card orders. - Discover available products with
GET /emp/v1/products. - If the selected product includes
printing.schema, use that schema to understand the supported printing payload.
Flow
1. Create or identify the fleet
The order request uses thefleetId you provided when creating the fleet.
2. Discover available products
Use product discovery to see which cards can be ordered.printing.schema object. This schema describes the printing payload expected for that product.
printing field, create the order without a printing payload.
3. Create the order
Create one order for one card.quantity. One request always represents one card order.
printing is optional at the Drive API level because requirements depend on the selected product. The fulfilment system validates the submitted payload against the product configuration.
4. Track the order
The card is a physical product that has to be manufactured, so it is not available right after the order is created. Track the order until the card has been produced. The create response contains theid of the order. To track an order, provide its ID to the single-order endpoint.
status to decide when to stop polling:
- While the
statusis not final, keep polling. - Stop polling when the
statusisORDER_ASSIGNED,ORDER_CANCELLED,ORDER_REFUNDED,ORDER_PAYMENT_FAILEDorORDER_REFUND_FAILED. ORDER_ASSIGNEDmeans fulfilment is complete and no further charging keys will be added.ORDER_CANCELLEDandORDER_REFUNDEDmean fulfilment ended and no further charging keys will be added.ORDER_PAYMENT_FAILEDandORDER_REFUND_FAILEDare final from your perspective, because the Drive API offers no action to recover them. Contact your Plugsurfing support contact to resolve the order.
GET /emp/v1/orders, which lists the orders of your organizations. Prefer the single-order endpoint for tracking.
5. Retrieve the manufactured card
The response has the same fields as an item of the order list, plus an optionalchargingKeys array. Each entry in chargingKeys is the charging key of a card that has been manufactured for the order.
chargingKeysis omitted until the first card has been manufactured.- While the
statusisORDER_PROCESSING,chargingKeysmay contain only the cards manufactured so far, including for an order withquantitygreater than 1. Do not treat the order as complete until it reaches a finalstatus. - The list endpoint
GET /emp/v1/ordersnever includeschargingKeys.
validTo and contractId) are omitted above for brevity. Orders that do not exist or are not accessible to the caller return 404.
6. Enable the card
Manufactured cards are created disabled. Enable each card with itskeyIdentifier before it can be used for charging.
Error handling
Common client-facing errors:400 Bad Request: required fields are missing, the body is malformed JSON, or the printing payload does not match product requirements.404 Not Found: thefleetIddoes not exist, the fleet is not available to the calling EMP, or the decodedproductIddoes not exist.500 Internal Server Error: an unexpected server-side error occurred.