Best Practices

Guidelines for building robust integrations.

Use externalCode as an Idempotency Key

Every product, document, and delivery point in the External API is identified by an externalCode that you provide. This code serves as a natural idempotency key: creating a resource with the same externalCode twice returns a 409 Conflict instead of creating a duplicate.

Use meaningful, stable identifiers from your source system (e.g., your ERP order number, SKU code, or internal ID). This ensures a direct mapping between your system and the WMS, and protects against accidental duplicate submissions caused by retries or network issues.

Create Dependencies First

The API enforces referential integrity. Resources must be created in the correct order:

1. Products — create all products referenced in document lines before creating the document
2. Delivery points — create delivery points before referencing them in expedition documents
3. Documents — create documents only after all referenced products and delivery points exist

If you attempt to create a document referencing a non-existent product, the API returns a 404 error with the key nonExistingProduct.

Pagination

All list endpoints support pagination via query parameters. Always paginate when querying resources that may return large result sets.

The response includes the X-Total-Count header with the total number of matching records. Use this header to calculate total pages and implement pagination controls.

Cache Access Tokens

Access tokens are valid for 1 hour (3600 seconds). Requesting a new token for every API call is wasteful. Cache the token and reuse it until it approaches expiration. A good practice is to refresh the token 5 minutes before it expires.

# Store token with expiration time
token_data = get_access_token()
token = token_data["access_token"]
expires_at = time.time() + token_data["expires_in"] - 300  # 5 min buffer

# Before each API call, check if refresh is needed
if time.time() >= expires_at:
    token_data = get_access_token()
    token = token_data["access_token"]
    expires_at = time.time() + token_data["expires_in"] - 300

Handle Webhooks Idempotently

Webhooks may be delivered more than once, for example when your endpoint processed a request but answered after the timeout and an operator then re-sent the document. Your webhook handler must be idempotent to avoid processing the same event multiple times.

Use the closingDocumentCode field as a deduplication key. Before processing a webhook payload, check if you have already processed a payload with the same closingDocumentCode. If so, acknowledge the webhook (return 2xx) but skip processing.

Test on Alpha First

Always develop and test your integration against the Alpha (staging) environment before connecting to production. The Alpha environment mirrors production functionality but uses isolated data.

Monitor API Usage

All API calls are logged in an audit trail. You can query audit records to monitor your integration's activity, detect errors, and troubleshoot issues. Each audit entry includes the operation type, status, timestamp, and request/response details.

Error Handling Strategy

Different error categories require different handling strategies.