RazGazOrder Ingest API

1Overview

The cashier system sends RazGaz one HTTP request per delivery order. RazGaz prices the delivery, broadcasts it to nearby carriers, and manages the carrier from assignment through hand-over to the customer.

There is no status back-channel on this integration. RazGaz does not call the cashier system back, and there is no endpoint to poll for the state of a delivery or for carrier details. If the cashier system needs delivery status, say so before integrating — it is a separate contract, not a parameter of this one.

2What RazGaz issues you

Two things, both from RazGaz, before the first order:

The API key is shown once, at creation, and is not recoverable afterwards. Store it as a secret. Any key can be revoked by RazGaz at any time, after which every request presenting it is rejected with 401.

3Authentication

Present the key on every request, either way:

If both are present, the header is used. A request with no key, an unknown key or a revoked key is answered 401 and nothing is recorded — no order is created, and RazGaz raises no internal alert. A 401 in production means the integration is silently delivering nothing, so treat it as a hard failure and escalate rather than retry indefinitely.

4Call: Add Order

POST /ingestOrder

4.1Request — required fields

Every field below must be present, and the four coordinate values must be JSON numbers, not strings. A request failing any of these is rejected with 400 and no order is created.

Coordinates are mandatory and are never derived. This endpoint does not geocode: it does not convert a text address into coordinates, and it does not substitute the branch's stored position for a missing pickupLocation. A cashier system that cannot produce coordinates for both ends cannot use this integration.

4.2Request — optional fields

4.3Reserved fields — do not send

The endpoint accepts several further fields that belong to RazGaz's own operations. Sending them from a cashier system is not supported: they change what the carrier is paid and how the delivery is dispatched, and RazGaz does not validate them against the delivery.

estimatedPayout, broadcastRadius, platformOrderRef, regionId, restaurantId.

scheduledFor is likewise not part of this integration: it is stored on the first POST and has no effect, so an order sent with a future time is dispatched immediately, and a different time on a later POST of the same order is not stored. An order for later must not be sent until it is due.

restaurantName is accepted as a fallback for identifying the branch when externalId matches nothing, and it must then match RazGaz's own spelling of the name character for character. Do not rely on it: send externalId.

4.4Response

Both answer with the same body:

Treat any 2xx as accepted. created: false is a normal, successful answer, not a duplicate error.

4.5Errors

A network timeout with no response is indistinguishable from a 500 and should be handled the same way: retry. Retrying is always safe — see §6.

5Identifying the restaurant

Send externalId on every order. RazGaz holds your code for each branch against that branch, keyed to your API key, so:

• your codes need no relation to RazGaz's own identifiers or naming;
• two cashier systems may use different codes for the same branch without interfering;
• a branch you have not been issued a code for is not integrated yet. An order carrying an unknown code is still accepted with 201 — it simply arrives attached to no restaurant, and RazGaz raises no alert. This is the failure mode to watch for on the first order from each new branch: the request looks entirely successful.

If your API key is ever rotated, the branch codes must be re-registered against the new key before it is used. Coordinate a rotation with RazGaz; do not switch keys unilaterally.

6Idempotency and retries

The orderId you send is the order's identity on the RazGaz side. A second request carrying an orderId already known is an update, never a second delivery.

An update rewrites the order details you own — both addresses and both coordinate pairs, customer name and phone, line items, amount, payment method, notes, prep time, placed-at time — and leaves the delivery itself alone: assignment to a carrier, the state of the delivery, and every timestamp of its progress are never touched by an incoming request. A prep time the kitchen has already answered for itself is also preserved.

Consequences for the cashier system:

• Retrying is always safe, at any interval, for as long as needed. No retry can create a second delivery or disturb one in progress.
• A correction is sent the same way: re-send the whole order with the same orderId and the corrected values. Partial payloads are not supported — a field left out of the retry is written as empty, not left as it was.
• A correction is applied to the order whatever state it is in, but a delivery already under way is being driven by a person. Phone RazGaz as well, rather than assuming the carrier has seen the change.

Cancellation is not part of this integration. To cancel an order already sent, contact RazGaz.

7Prep time

estimatedReadyMinutes tells RazGaz when the food will be ready, and it is the single most useful optional field: it is what lets RazGaz time the carrier's arrival to the kitchen rather than send them to stand at a counter.

When it is absent, RazGaz falls back to what it knows about the branch:

• a branch with an average prep time recorded uses that average;
• a branch with no average dispatches with no ready time at all;
• a branch configured to give a time per order holds the delivery, undispatched, until a person in that kitchen answers. Nothing releases it automatically.

That last case is why a cashier system that knows its own kitchen should always send the field: it removes a manual step that otherwise delays every order.

8Before going live

1. RazGaz has issued the API key and one restaurant code per branch.
2. Every branch's coordinates are correct in the cashier system, and every order carries them as numbers.
3. One real order per branch has been sent and confirmed — with RazGaz — to have arrived attached to the right restaurant. §5 explains why the HTTP response alone does not confirm this.
4. estimatedReadyMinutes is being sent if the cashier system can produce it.
5. Retries on 500 and on timeout are implemented; 400 and 401 are not retried blindly but surfaced to whoever can act on them.