Requirements
Transport-level expectations that apply to both the Product API and the Transaction API.
Transport
- HTTPS with a valid certificate. Plain HTTP and self-signed or expired certificates are rejected.
- Reasonable response times, even for large lists. If you cannot keep the full catalogue within a sensible response time, offer pagination.
- Concurrent requests must be tolerated. Several venues may be synchronised at the same time, and a manual sync from the CMS can overlap a scheduled run.
Behaviour
- Requests must be idempotent and side-effect free. Cheers only reads. A fetch must never create, modify, consume or lock anything on your side.
- Identifiers must be stable and permanent -- for products, variants, modifiers and transactions alike. A reused or regenerated identifier silently breaks product matching or causes transactions to be dropped as duplicates.
- Always return the full current product list, never a delta. Products missing from a response are flagged as "disappeared from the POS". See Processing rules.
HTTP Status Codes
Use ordinary HTTP semantics:
| Status | When |
|---|---|
200 | Success -- and only success. |
401 | Missing or invalid credentials. |
4xx | Client-side problem (bad parameter, unknown venue identifier). |
5xx | Server-side problem. |
Never return an error inside a 200 response
A 200 OK whose body contains an error object is read as a successful sync with the payload it
happens to describe. In the product case that means an empty or partial list -- and every
product absent from it gets flagged as disappeared.
On a non-2xx response Cheers marks the sync run as failed, leaves the existing data untouched,
and shows the error message to the partner in the CMS. That is the behaviour you want when
something goes wrong.
Checklist Before Go-Live
- HTTPS endpoint with a valid certificate
- Authentication scheme documented, credentials handed to the partner
- Venue scoping available if one credential serves several venues
- Product endpoint returns the full catalogue with identifier, name, gross price and VAT
- Variants and modifiers carry their own identifier, name and price
- Pagination -- if used -- signals the last page and sorts deterministically
- Transaction endpoint returns an identifier and an ISO-8601 creation timestamp with offset
- Start-time filter supported on transactions
- Errors returned as
4xx/5xx, never as200