JOE stands for JACOB Order Engine and describes a standardized interface to handle orders. The JOE API allows placing orders, retrieving order-related documents like invoices, and subscribing to order-related events. The main goal of JOE is to avoid long integration phases by keeping things simple.
Feel free to contact us with any issues regarding this API.
Using the JOE API requires an API key which must be appended to each request as a query parameter:
https://api.jacob.services/1.0/joe?apikey=123
Keep in mind that API keys are customer-specific and should be kept confidential.
All documents, i.e. orders, order responses, invoices and dispatch notifications, are represented as JSON or XML. The XML representations loosely follow the OpenTRANS 2.1 specification, the corresponding JSON ones are equivalent. There are examples for both formats.
The default input and output format for documents is XML. This can be changed to JSON by setting the request's Content-Type or Accept header to application/json.
| Method | URL | Description | Details |
|---|---|---|---|
| POST | https://api.jacob.services/1.0/joe | Place an order | Link |
| Method | URL | Description | Details |
|---|---|---|---|
| GET | https://api.jacob.services/1.0/joe | List all orders | Link |
| GET | https://api.jacob.services/1.0/joe/{orderId} | Get document status | Link |
| Method | URL | Description | Details |
|---|---|---|---|
| GET | https://api.jacob.services/1.0/joe/{orderId}/order | Download an order | Link |
| GET | https://api.jacob.services/1.0/joe/{orderId}/response | Download an order response | Link |
| GET | https://api.jacob.services/1.0/joe/{orderId}/invoice | Download an invoice | Link |
| GET | https://api.jacob.services/1.0/joe/{orderId}/dispatch | Download a dispatch notification | Link |
JOE generates events whenever new order response, invoice or dispatch notification documents become available. The event subscription mechanism allows getting notified about such events.
The alternative to getting notified about events is polling, i.e. checking the document status at regular intervals.
Getting notified requires an HTTP endpoint. Subscribing means specifying the desired event type and the HTTP endpoint. Once subscribed, every time an event of the desired type occurs JOE will POST the JSON representation of the event to the user's endpoint.
Endpoints may be access restricted by one of the following mechanisms:
- 'Basic' HTTP Authentication
- Authorization via custom HTTP header, e.g.
x-access-token: 3858f622 - Authorization via query parameter, e.g.
http://example.com/webhook?token=3858f622
See the description of the subscription object for details.
| Method | URL | Description | Details |
|---|---|---|---|
| POST | https://api.jacob.services/1.0/joe/events/subscriptions | Subscribe to an event | Link |
| DELETE | https://api.jacob.services/1.0/joe/events/subscriptions/{subId} | Unsubscribe from an event | Link |
| Method | URL | Description | Details |
|---|---|---|---|
| GET | https://api.jacob.services/1.0/joe/events/subscriptions/{subId} | Fetch a subscription | Link |
| PATCH | https://api.jacob.services/1.0/joe/events/subscriptions/{subId} | Change a subscription | Link |
| PUT | https://api.jacob.services/1.0/joe/events/subscriptions/{subId} | Replace a subscription | Link |
Product information, like product descriptions, available stock and prices, can be queried by using the Product API.
Unless otherwise noted using the Product API requires an API key which must be appended to each request as a query parameter:
https://api.jacob.services/1.0/products/...?apikey=123
Keep in mind that API keys are customer-specific and should be kept confidential.
| Method | URL | Description | Details |
|---|---|---|---|
| GET | https://api.jacob.services/1.0/products/{sku} | Get general product information | Link |
| GET | https://api.jacob.services/1.0/products/{sku}/price | Get price and available stock for a product | Link |