REST with JSON
Resources are plain nouns and bodies are JSON. An error says what was wrong and where, so a person can fix it without asking us.
API and webhooks
Your own systems, on a plain API.
DigiOS has a REST API that speaks JSON, and webhooks that tell your systems when something happens on the floor. Use them for anything on this site that doesn't have a name of its own.
Where it stands
Your systems call DigiOS over REST in JSON; DigiOS calls yours with webhooks.
Two ways to work
Most connections use both: your system calls DigiOS to send work, and DigiOS calls your system when the work is done.
How it starts
Your system asks DigiOSYour system makes a call over HTTPS.
DigiOS tells your systemSomething happens on the floor, such as a shipment closing, and DigiOS sends a webhook.
What carries it
Your system asks DigiOSREST, with JSON in the body.
DigiOS tells your systemAn HTTPS post of JSON to an address you register.
How it is secured
Your system asks DigiOSOAuth client credentials, with a token scoped to one client.
DigiOS tells your systemA secret only you and DigiOS hold, which your system checks before it trusts the message.
If it fails
Your system asks DigiOSSend it again with the same idempotency header and nothing changes the second time.
DigiOS tells your systemA delivery you don't confirm is retried with growing gaps until you do, and each attempt shows in a log.
How you test
Your system asks DigiOSIn a sandbox, offered to early-access customers.
DigiOS tells your systemThe same sandbox sends test deliveries to an address you choose.
How calls work
Client credentials
Your system gets a token with OAuth client credentials. Tokens are scoped to one client, so a token for one client cannot see another's.
Safe to send again
A write carries an idempotency header. Send it twice and the second send returns the first answer. A document sent twice never opens two orders.
Pages
A long list comes in pages. Each page says how to ask for the next one, so no call has to carry everything at once.
Limits
Limits apply per token. A busy client doesn't slow another, and a call over the limit is told when to try again.
Signed webhooks
Each delivery is signed with a secret, retried until you confirm it, and listed in a log you can read. A delivery you missed can be sent again from the log.
What it carries
| Document | Direction | What it is |
|---|---|---|
| Orders | In and out | An order to ship, with its lines and ship-to details in; its status and shipment back |
| Advance ship notices | In | What a supplier or client is sending, so receiving knows what to expect |
| Receipts | Out | What arrived, in what quantity, against which notice or order |
| Shipments and tracking | Out | What shipped, in which packages, with which carrier and tracking number |
| Stock levels | Out | What is on hand, by item and location, as a snapshot or as changes |
| Adjustments | Out | A change to stock that was counted, moved or corrected |
| Items and parties | In | Items with their units and barcodes, and the customers and ship-to addresses orders name |
| Statements | Out | The charges for a client's period, as lines and a total |
Questions about the API
Do we have to build against it?
No. The systems named on this site connect without code from you. The API is for what has no name here.
Does it carry the same documents as EDI?
Yes. An order made by API and an order that arrives as an 850 are the same order to DigiOS, and a rejected document goes to the same queue.
Is every webhook delivered on time?
A webhook is delivered at least once, with no guarantee of when. The same delivery can arrive twice, so check its ID, and run a reconciliation on a schedule to catch anything missed.
Can we try it before we commit?
A sandbox is offered to early-access customers. Ask, and we tell you what a first test would look like.
What are the limits?
Limits apply per token. We state them in writing when you get access.
Tell us what you want to connect.
Say which of your systems should talk to DigiOS and what should move. A person answers in writing.