All endpoints

Being released

The money rails described here are built and tested, and are being rolled out. Until a rail is switched on for the exchange, invoices are paid by bank transfer or mobile money and recorded by Finance, as today.

Every endpoint under https://apiexchange.yeshara.network. Reads need a signed-in user; writes need the role shown (an Admin holds every role). Open needs no token. Money endpoints are described in detail on Money endpoints.

Sign-in and users

Method	Path	Role
POST	/api/v1/auth/login	Open
POST	/api/v1/auth/logout	Signed in
GET	/api/v1/auth/me	Signed in
POST	/api/v1/auth/password	Signed in
GET	/api/v1/users	Signed in
POST	/api/v1/users	Admin
PATCH	/api/v1/users/:id	Admin

Reading

Method	Path
GET	/health	Open
GET	/api/v1/catalogue	Open
GET	/api/v1/ledger	Open
GET	/api/v1/dataset	Everything the web app reads, in one document
GET	/api/v1/lots, /lots/:id/provenance
GET	/api/v1/listings, /book, /book/:listingId
GET	/api/v1/orders, /orders/:id
GET	/api/v1/buyers, /parties
GET	/api/v1/warehouses, /inspections, /releases, /receipts, /consignments
GET	/api/v1/vehicles, /trips, /moves, /gate-passes, /checkpoints, /devices
GET	/api/v1/border-posts, /clearances, /border-cash
GET	/api/v1/payments, /payouts, /escrows, /custody, /transactions
GET	/api/v1/invoices, /transfers, /rails, /rails/balances
GET	/api/v1/cards, /advances, /cardholders
GET	/api/v1/disputes, /messages, /audit

Paths after the first in a row share its /api/v1 prefix.

Warehouse and receipts

Method	Path	Role
POST	/api/v1/warehouses	Warehouse
PATCH	/api/v1/warehouses/:id	Warehouse
POST	/api/v1/inspections	Warehouse
POST	/api/v1/intakes	Warehouse
POST	/api/v1/conversions	Warehouse
POST	/api/v1/releases	Warehouse
POST	/api/v1/releases/:id/confirm	Warehouse
POST	/api/v1/releases/:id/cancel	Warehouse
POST	/api/v1/lots/:id/receipt	Warehouse
GET	/api/v1/receipts/:id	Open
POST	/api/v1/receipts/:id/void	Warehouse
POST	/api/v1/receipts/:id/payout	Finance
POST	/api/v1/payouts/:id/settle	Finance
POST	/api/v1/payouts/:id/write-off	Finance

Trade

Method	Path	Role
POST	/api/v1/orders	Desk
POST	/api/v1/orders/:id/dispatch	Desk, Warehouse
POST	/api/v1/orders/:id/settle	Finance
POST	/api/v1/disputes	Desk
POST	/api/v1/parties	Desk
PATCH	/api/v1/parties/:id	Desk

Logistics

Method	Path	Role
POST	/api/v1/vehicles	Desk, Finance
PATCH	/api/v1/vehicles/:id	Desk, Finance
POST	/api/v1/moves	Desk, Warehouse
POST	/api/v1/consignments	Desk, Warehouse
POST	/api/v1/consignments/:id/cancel	Desk, Warehouse
POST	/api/v1/gate-passes	Desk, Warehouse
POST	/api/v1/gate-passes/:id/confirm	Desk, Warehouse
POST	/api/v1/gate-passes/:id/cancel	Desk, Warehouse
POST	/api/v1/gate-passes/:id/send	Desk, Warehouse
POST	/api/v1/trips/:id/arrive	Desk, Warehouse
POST	/api/v1/checkpoints	Desk, Border
POST	/api/v1/border-posts	Desk, Border
PATCH	/api/v1/border-posts/:id	Desk, Border
POST	/api/v1/clearances	Desk, Border
POST	/api/v1/clearances/:id/documents	Desk, Border
POST	/api/v1/clearances/:id/inspection	Desk, Border
POST	/api/v1/clearances/:id/clear	Desk, Border
POST	/api/v1/border-cash	Border, Finance
POST	/api/v1/border-cash/:id/reconcile	Finance
POST	/api/v1/border-cash/:id/query	Finance
POST	/api/v1/devices	Desk
PATCH	/api/v1/devices/:id	Desk
POST	/api/v1/devices/:id/events	The device's own token

Invoices

Method	Path	Role
POST	/api/v1/orders/:id/invoice	Finance, Desk
POST	/api/v1/trips/:id/invoice	Finance, Desk
GET	/api/v1/invoices/:id	Open
POST	/api/v1/invoices/:id/issue	Finance, Desk
POST	/api/v1/invoices/:id/sign	Finance, Desk
POST	/api/v1/invoices/:id/payments	Finance, Desk
POST	/api/v1/invoices/:id/collect	Finance, Desk
POST	/api/v1/invoices/:id/pay-out	Finance, Desk
POST	/api/v1/invoices/:id/void	Admin

Escrow, transfers and rails

Method	Path	Role
POST	/api/v1/escrows	Finance
POST	/api/v1/escrows/:id/release	Finance
POST	/api/v1/escrows/:id/refund	Finance
POST	/api/v1/escrows/:id/dispute	Finance
POST	/api/v1/transfers/:id/approve	Finance
POST	/api/v1/transfers/:id/cancel	Finance
POST	/api/v1/rails/poll	Finance

Road money and driver cards

Method	Path	Role
POST	/api/v1/trips/:id/advances	Desk, Finance
POST	/api/v1/advances/:id/recover	Finance
POST	/api/v1/advances/:id/write-off	Finance
POST	/api/v1/cards	Desk, Finance
PATCH	/api/v1/cards/:id	Desk, Finance
GET	/api/v1/cards/quote, /cards/float, /cards/:id/balance	Signed in
POST	/api/v1/cards/:id/load	Desk, Finance
POST	/api/v1/cardholders	Desk, Finance
POST	/api/v1/cardholders/:id/documents	Desk, Finance
POST	/api/v1/cardholders/:id/kyc	Desk, Finance
POST	/api/v1/cardholders/:id/cards	Desk, Finance

Webhooks

Method	Path
POST	/api/v1/hooks/mamlaka/payments	Open; see Callbacks and webhooks
POST	/api/v1/hooks/mamlaka/cards	Open, signed