APIBook and follow deliveries from your own systems · v0.1.0

How it works

  • Base URLhttps://api.178-62-10-216.sslip.io
  • Sign-inAn API client of your organisation (Developers in your account): OAuth client credentials with a signed key (private_key_jwt) and DPoP-bound tokens. Not Human approves the scopes it may use.
  • The same booking twiceYour externalRef makes booking idempotent: sending it again returns the same delivery.
  • Limits60 bookings and 240 quotes a minute per client. Over that: 429 RATE_LIMITED with Retry-After.
  • ErrorsJSON { error, message, details? }; error is a stable code, message is for people.
  • EventsSigned webhooks for every step (Webhooks); poll the delivery only when you need to.

Quickstart: one delivery

  1. Is it deliverable, and what does it cost? Nothing is reserved.
    curl -s https://api.178-62-10-216.sslip.io/v1/bookings/quote -H "Authorization: DPoP $TOKEN" -H "DPoP: $PROOF" \
  -H "Content-Type: application/json" -d @order.json
  2. Book it. The answer says which robot takes it, or why none can.
    curl -s https://api.178-62-10-216.sslip.io/v1/bookings -H "Authorization: DPoP $TOKEN" -H "DPoP: $PROOF" \
  -H "Content-Type: application/json" -d @order.json
    {
  "externalRef": "ORD-10042",
  "siteId": "site_…",
  "pickup":   { "pose": { "lat": 0, "lon": 0, "headingRad": 0 }, "window": { "from": "…", "to": "…" } },
  "dropoffs": [{ "pose": { "lat": -26.1306, "lon": 28.1610, "headingRad": 0 }, "window": { "from": "…", "to": "…" } }],
  "items": [{ "itemRef": "ORD-10042-1", "sizeM": [0.35, 0.25, 0.2], "massKg": 2.5, "dropoffIndex": 0, "temperature": "chilled" }],
  "recipient": { "name": "…", "phone": "+27…", "language": "en", "addressLabel": "12 Van Der Walt Road" },
  "handover": { "method": "pin", "waitSec": 600 }
}
    The store's position comes from siteId. The drop-off is the kerb point outside the address: GET /v1/partner/places?q=… finds real addresses where a robot is in service.
  3. Follow it. Stage, doors, the robot while it is coming, and the timeline.
    curl -s https://api.178-62-10-216.sslip.io/v1/bookings/$BOOKING_ID/delivery -H "Authorization: DPoP $TOKEN" -H "DPoP: $PROOF"
  4. Proof of handover once it is collected.
    curl -s https://api.178-62-10-216.sslip.io/v1/bookings/$BOOKING_ID/proof -H "Authorization: DPoP $TOKEN" -H "DPoP: $PROOF"
  5. Cancel before it leaves the store.
    curl -s -X POST https://api.178-62-10-216.sslip.io/v1/bookings/$BOOKING_ID/cancel -H "Authorization: DPoP $TOKEN" -H "DPoP: $PROOF" \
  -H "Content-Type: application/json" -d '{"reason":"Customer cancelled"}'

Endpoints

areas

  • GET/v1/partner/areasYour own areas: where your robots may not go, must stay, slow down or stay quiet, for all your jobs or some of your sites
  • POST/v1/partner/areasDraw an area for your own jobs (starts as a draft); it can only add restrictions
  • POST/v1/partner/areas/{areaId}/activateSwitch an area on
  • POST/v1/partner/areas/{areaId}/archiveSwitch an area off for good (kept for the record)
  • POST/v1/partner/areas/{areaId}/editChange a draft area
  • POST/v1/partner/areas/what-ifWhat switching an area on would change for your jobs: robots inside or outside now, your unfinished jobs, the last 30 days

Billing

  • GET/v1/partner/invoicesMonths you have an invoice for, newest first
  • GET/v1/partner/invoices/{month}Your invoice for a month (a draft until the month ends)

Deliveries and stores

  • GET/v1/bookingsYour deliveries with stage, lockers, vehicle position while active and timeline (recipient masked)
  • GET/v1/bookings/{bookingId}/deliveryOne delivery (custody view)
  • GET/v1/bookings/{bookingId}/photosPhotos of the order as loaded (metadata)
  • GET/v1/bookings/{bookingId}/photos/{photoId}One photo (data URL)
  • GET/v1/bookings/{bookingId}/proofDelivery proof: handover time, door, how it was opened (PIN, one-tap, remote with a hashed staff reference), door closed and empty, and the vehicle's reports at the stop, with a digest
  • POST/v1/bookings/quoteDry-run admission: can a vehicle take this now, where each stop resolves to, planned times and an indicative price (nothing is reserved)
  • GET/v1/partner/sitesYour stores (pickup sites) with their default handover rules

Bookings

  • POST/v1/bookingsBook a delivery (drop-offs by address, placeId, location or pose); admitted onto a vehicle or rejected with reasons (C2)
  • GET/v1/bookings/{bookingId}Booking and mission progress
  • POST/v1/bookings/{bookingId}/cancelCancel (partners: before departure; the vehicle ends the mission safely). On a shared trip: the order leaves the trip before it is sent; after that only operations can cancel the whole trip
  • POST/v1/bookings/{bookingId}/redeliverBook an order that was not collected again as a redelivery (same items, recipient and drop-off; a new reference and window), linked to the first; charged as a new delivery

Your organisation

  • POST/v1/bookings/bulkBook from a CSV file (one row per item, rows with the same externalRef are one order): a result per order and row; dryRun only validates; idempotent by externalRef; within the booking quota
  • GET/v1/partner/activityAudit trail of the organisation's bookings and people
  • GET/v1/partner/meThe signed-in partner: organisation, roles and what they may do
  • GET/v1/partner/placesSearch real drop-off addresses where a vehicle is in service (?q=); each names its service area
  • GET/v1/partner/quotaYour per-minute limits on this API (requests, bookings, quotes) for the calling client or person
  • GET/v1/partner/slotsRecurring slots: each with its last occurrences and the next five (recipient masked)
  • POST/v1/partner/slotsCreate a recurring slot (days, local time, store, drop-off, items): each occurrence is booked aheadMinutes before its pickup window
  • GET/v1/partner/slots/{slotId}One recurring slot
  • POST/v1/partner/slots/{slotId}/pausePause a recurring slot (books nothing until resumed)
  • POST/v1/partner/slots/{slotId}/resumeResume a paused slot

sim

  • GET/v1/bookings/{bookingId}/recipient-linkSIM only: the tracking link that would go out by SMS (no SMS provider in SIM)

support

  • GET/v1/partner/bookings/{bookingId}/communicationsEvery message about your booking: SMS to the recipient (provider, status), webhooks, notices and case messages
  • GET/v1/partner/support/casesYour support cases, latest first (?status=&bookingId=)
  • POST/v1/partner/support/casesOpen a support case, about one of your bookings or in general
  • GET/v1/partner/support/cases/{caseId}One of your cases: the conversation, credits and activity with the job's timeline
  • POST/v1/partner/support/cases/{caseId}/messagesWrite to support on one of your cases (reopens a waiting or resolved case)

Webhooks

  • POST/v1/partner/webhook-deliveries/{deliveryId}/replaySend a delivery again now (same event id)
  • GET/v1/partner/webhooksYour webhook endpoints (secrets are never shown again)
  • POST/v1/partner/webhooksRegister an endpoint for signed delivery events; the secret is in this answer only
  • GET/v1/partner/webhooks/{webhookId}/deliveriesDelivery log of an endpoint, newest first
  • POST/v1/partner/webhooks/{webhookId}/pingSend a test event now and return the attempt
  • POST/v1/partner/webhooks/{webhookId}/rotateNew signing secret and key id (the old one stops at once)
  • POST/v1/partner/webhooks/{webhookId}/statusPause or resume an endpoint

Machine-readable: https://api.178-62-10-216.sslip.io/openapi.json (OpenAPI 3.1).