# Delivahere Partner API

> Book, pay for and track Delivahere deliveries for your own customers. Create deliveries for your customers, pay for them, hand over codes and follow every delivery by webhook. JSON over HTTPS; authenticate every request with the `client_id` and `secret_key` headers Delivahere issues to you.

## Notes for coding agents

Read these before writing integration code.

- Two environments with separate keys: QA (`http://103.187.101.50:8721/request/public`) for building and testing, Live (`https://admin.delivahere.com/request/public`) for real money. Make the base URL configuration, never a constant.
- Every call sends `client_id` and `secret_key` headers. The secret is server-side only: read it from an environment variable or secrets manager, never put it in code, a mobile app, a browser bundle, logs or a repo.
- Send a unique `Idempotency-Key` (built from the partner's own order ID plus the action) on every create, accept and cancel, and reuse it on retries.
- Branch on `error.code`, not on the message. Back off on `429` and honour `Retry-After`.
- Webhooks: verify `X-Webhook-Signature` (HMAC-SHA256 of the **raw** body) with a constant-time compare, reject events older than 10 minutes, de-duplicate on `idempotencyKey`, reply exactly `200` quickly and process on a queue. Ignore unknown events and fields.
- Build delivery logic on `publicStatus`, not internal statuses.
- A new sender is created by their first `POST /createRequestWithUser` (send `fullName` and `email` with a mobile that isn't on Delivahere). There is no separate sign-up call. Use a mobile and email never used on Delivahere; an account the partner can't act for can't be given a session.
- Drop-off codes are secrets: never log them; pass them only to the receiver.
- In payloads, fields starting with `partner` or `da` describe the delivery partner agent (the courier), not the API partner.

## Docs

- [Everything in one file](https://developers.delivahere.com/llms-full.txt): all guides, every endpoint and every webhook event as markdown. Load this one.
- [OpenAPI 3.1 spec (JSON)](https://developers.delivahere.com/openapi.json): the machine-readable contract, for client generators and Postman.
- [OpenAPI 3.1 spec (YAML)](https://developers.delivahere.com/openapi.yaml)

## Guides

- [Overview](https://developers.delivahere.com/#/guide/overview)
- [Quickstart](https://developers.delivahere.com/#/guide/quickstart)
- [Authentication](https://developers.delivahere.com/#/guide/authentication)
- [Retries and idempotency](https://developers.delivahere.com/#/guide/idempotency)
- [Responses and errors](https://developers.delivahere.com/#/guide/errors)
- [Paying for deliveries](https://developers.delivahere.com/#/guide/payments)
- [Delivery lifecycle](https://developers.delivahere.com/#/guide/lifecycle)
- [Webhooks](https://developers.delivahere.com/#/guide/webhooks)
- [Go-live checklist](https://developers.delivahere.com/#/guide/go-live)

## Endpoints

- [Check whether a sender exists](https://developers.delivahere.com/#/op/lookupUser): `POST /users/lookup`
- [Open a session for a sender](https://developers.delivahere.com/#/op/createSession): `POST /session`
- [Upload a package photo](https://developers.delivahere.com/#/op/uploadMedia): `POST /media`
- [Create a delivery](https://developers.delivahere.com/#/op/createDelivery): `POST /createRequestWithUser`
- [List a sender's deliveries](https://developers.delivahere.com/#/op/listDeliveries): `GET /deliveries`
- [Get a delivery](https://developers.delivahere.com/#/op/getDelivery): `GET /deliveries/{idOrCode}`
- [Get a delivery's transit legs](https://developers.delivahere.com/#/op/getTimeline): `GET /deliveries/{idOrCode}/timeline`
- [Cancel a delivery](https://developers.delivahere.com/#/op/cancelDelivery): `POST /deliveries/{idOrCode}/cancel`
- [List bids on a delivery](https://developers.delivahere.com/#/op/listBids): `GET /deliveries/{idOrCode}/bids`
- [Accept a bid](https://developers.delivahere.com/#/op/acceptBid): `POST /deliveries/{idOrCode}/bids/{bidId}/accept`
- [Get the sender's wallet balance](https://developers.delivahere.com/#/op/getWalletBalance): `GET /wallet/balance`
- [Recommend an offer](https://developers.delivahere.com/#/op/recommendPrice): `POST /pricing/recommend`
- [Estimate a price with a breakdown](https://developers.delivahere.com/#/op/estimatePrice): `POST /pricing/estimate`
- [Public tracking](https://developers.delivahere.com/#/op/trackDelivery): `GET /track/{trackingToken}`

## Webhook events

- [`delivery.created`](https://developers.delivahere.com/#/event/delivery.created): A delivery was created.
- [`delivery.published`](https://developers.delivahere.com/#/event/delivery.published): The job is open to delivery partner agents again.
- [`delivery.bid_submitted`](https://developers.delivahere.com/#/event/delivery.bid_submitted): A delivery partner agent bid on the delivery.
- [`delivery.bid_accepted`](https://developers.delivahere.com/#/event/delivery.bid_accepted): A bid was accepted and paid for.
- [`delivery.codes_issued`](https://developers.delivahere.com/#/event/delivery.codes_issued): Drop-off code created or regenerated.
- [`delivery.pickup_verified`](https://developers.delivahere.com/#/event/delivery.pickup_verified): Pickup verified.
- [`delivery.pickup_confirmed`](https://developers.delivahere.com/#/event/delivery.pickup_confirmed): The delivery partner agent confirmed collecting the package.
- [`delivery.in_transit`](https://developers.delivahere.com/#/event/delivery.in_transit): The package is on its way.
- [`delivery.location_updated`](https://developers.delivahere.com/#/event/delivery.location_updated): The delivery partner agent's position.
- [`delivery.pickup_rejected`](https://developers.delivahere.com/#/event/delivery.pickup_rejected): The pickup failed verification.
- [`delivery.dropoff_rejected`](https://developers.delivahere.com/#/event/delivery.dropoff_rejected): The drop-off failed verification.
- [`delivery.partner_cancelled`](https://developers.delivahere.com/#/event/delivery.partner_cancelled): The delivery partner agent cancelled an accepted job.
- [`delivery.delivered`](https://developers.delivahere.com/#/event/delivery.delivered): Delivered.
- [`delivery.returned`](https://developers.delivahere.com/#/event/delivery.returned): Returned to the sender.
- [`delivery.cancelled`](https://developers.delivahere.com/#/event/delivery.cancelled): Cancelled.
- [`delivery.return_requested`](https://developers.delivahere.com/#/event/delivery.return_requested): The delivery partner agent asked to return the package to the sender.
- [`delivery.return_agreed`](https://developers.delivahere.com/#/event/delivery.return_agreed): The return to sender was agreed.
- [`payment.required`](https://developers.delivahere.com/#/event/payment.required): A payment link must be paid.
- [`payment.successful`](https://developers.delivahere.com/#/event/payment.successful): A payment went through.
- [`payment.failed`](https://developers.delivahere.com/#/event/payment.failed): A payment source couldn't pay.
- [`payment.refund_initiated`](https://developers.delivahere.com/#/event/payment.refund_initiated): A refund was started.
- [`payment.refund_completed`](https://developers.delivahere.com/#/event/payment.refund_completed): A refund finished.
- [`account.signup`](https://developers.delivahere.com/#/event/account.signup): A user you onboarded was created.
- [`account.kyc_required`](https://developers.delivahere.com/#/event/account.kyc_required): A user you onboarded must complete identity checks.
- [`account.kyc_approved`](https://developers.delivahere.com/#/event/account.kyc_approved): Identity checks passed.
- [`account.kyc_rejected`](https://developers.delivahere.com/#/event/account.kyc_rejected): Identity checks failed.