The key, the warehouse and error responses

Summary

Every API request carries two things: who is asking (the key) and, when needed, which warehouse (the warehouse code). With that the warehouse knows which customer it is and where incoming data should land. This article is for whoever will build the integration, or for whoever supervises it from the warehouse and needs to understand why something failed.

The service address

Every operation hangs off your system's address followed by /api/wms. For example, if you sign in at https://warehouse.example.com, the service is at https://warehouse.example.com/api/wms.

Method and path	What for
`POST /api/wms/asns`	Create an advance ship notice (and its receipt).
`POST /api/wms/shipments`	Create a confirmed shipment.
`GET /api/wms/shipments/{id}`	Look up a shipment.
`GET /api/wms/receipts/{id}`	Look up a receipt.
`GET /api/wms/inventory`	Look up stock, page by page.
`POST /api/wms/edi`	Send an X12 EDI file (also requires the EDI module).

The access key

The key is a long string we generate for an integration user. That user is not a person: it exists only for the API, is tied to one customer and has access to one or more warehouses. It is sent on every request in the authorization header:

Authorization: Bearer 7|U2FtcGxlIGtleSBmb3IgdGhlIGV4YW1wbGU...

If it is missing or invalid, the response is 401.
If the integration user is not tied to a customer, operations answer 403 with API token is not bound to a client. That is a setup error: write to us.
The key does not expire on its own. It keeps working until we revoke it.

Choosing the warehouse

If the key has access to a single warehouse, there is nothing to choose. If it has several, each request can say which one it works in with the X-Warehouse-Code header and the warehouse code (the one shown in the warehouse settings, not its name):

X-Warehouse-Code: DAL-01

Without the header: the key's first active warehouse is used. If tomorrow the order changes or one is deactivated, requests start landing somewhere else: that is why it is worth always sending it when there is more than one.
With a code that does not exist, or one the key has no access to: 403 with No warehouse bound to this API token.
With a warehouse that does not have the API module on: 404, with no further detail.

The headers on each request

POST /api/wms/asns HTTP/1.1
Host: warehouse.example.com
Authorization: Bearer 7|U2FtcGxlIGtleSBmb3IgdGhlIGV4YW1wbGU...
X-Warehouse-Code: DAL-01
Content-Type: application/json
Accept: application/json

Important: the Accept: application/json header is not decoration. Without it, a validation error can come back as a redirect instead of a 422 with the list of fields, and an invalid key as a redirect to the sign-in page. The customer's system would see a 302 and have no idea what happened.

Responses

Operations that create something answer 201 with the created document. Look-ups answer 200. Anything else is an error and creates nothing: the API validates every line before writing, so there are no half-created notices or shipments.

Error table

Response	What it means	What to do
401	The key is missing, incomplete or revoked.	Check the authorization header; if we revoked it, ask for a new one.
403	The key has no active warehouse, asked for a warehouse that is not its own, or is not tied to a customer.	Check the warehouse code; if it is right, write to us to review the key.
404	The API (or EDI) module is not on in that warehouse, or the receipt or shipment asked for does not exist or belongs to another customer.	Confirm the id being looked up; if it is correct, check the module with us.
422 with `unknown_sku`	A line carries a SKU that is not in that customer's catalog (or in the warehouse's general catalog). The response says which one.	Add the product or fix the SKU and send again. Nothing was created.
422 with `errors`	Required data is missing or badly formatted: a notice with no lines, a shipment with a zero quantity, a date that cannot be read, a text that is too long.	The response lists which field failed and why.
500	A server failure. The response carries a reference number.	Send us that number: with it we find the detail.

Error body examples

Unknown SKU:

HTTP/1.1 422 Unprocessable Content
{
  "error": "unknown_sku",
  "sku": "NT-9999"
}

Field validation (each message comes in the system's configured language):

HTTP/1.1 422 Unprocessable Content
{
  "message": "The lines.0.qty field must be greater than 0.",
  "errors": {
    "lines.0.qty": ["The lines.0.qty field must be greater than 0."]
  }
}

A warehouse that does not match:

HTTP/1.1 403 Forbidden
{
  "message": "No warehouse bound to this API token."
}

Changing or revoking a key

There is no screen for this: write to us. Revoking is immediate; the next request with that key already returns 401. If your customer changes integrators, the right move is to revoke the old key and hand over a new one, not to share the same one.

Tip: if you suspect a key leaked (it ended up in an email, a screenshot, a code repository), ask for the revocation first and investigate afterwards. With that key someone can create notices and shipments in your customer's name.

Troubleshooting

Everything worked and suddenly it returns 404.

The API module was turned off in the warehouse, or requests started landing in another warehouse because they do not send the code. Always send X-Warehouse-Code.

The integrator gets a sign-in page.

The Accept: application/json header is missing and the key is not valid.

A 500 with a reference number.

It is not a problem with the customer's data. Send us the reference, the time and the operation.

Frequently asked questions

Can a customer have several keys?

Yes: for example, one for their ERP and another for their online store. That way, if one leaks, it can be revoked without cutting off the other. Both see exactly the same data.

Is there a limit on requests per minute?

Today there is no fixed limit on these operations. Still, ask the integrator not to look up stock more than needed: a full stock look-up every few minutes is enough for almost any case.