Prodaksha Developers

Connecting a supplier or society system

The main integration: your system sends raw material to a factory, and needs to know what happened to it, so it can pay its farmers or members. FPOBox (farmer societies) works this way; so can a cooperative union, an estate, an aggregator or an outgrower scheme.

Before the first delivery

Step Who What
1 Factory Switches on the API and webhooks module and asks the platform for a token for your system (Quick start)
2 You Register your webhook address (POST /webhooks)
3 You Read the factory's items (GET /items?type=raw). Use its codes, or ask the factory to map your product codes to its items
4 Factory For toll work only: sets you (each society) up as a toll client linked to your id (sender.external_system + sender.society_id), with its tariffs
5 Both Agree the weight tolerance (how far the received weight may differ from what you declared before you are asked to decide)

The journey, step by step

# At the factory You call You receive
1 — POST /consignments when the goods leave 201 with the consignment id, status pending_intake
2 Weighed in at the gate: received, rejected, moisture — consignment.received
3 Weight outside the tolerance: waits for you POST /consignments/{id}/variance/approve or /dispute (with a note) consignment.variance_decided
4 Quality checks; a failed critical check holds the lot — lot.hold_changed
5 Processed (one or more runs) GET /work-orders/{id}/outputs if you want the detail run.completed: outputs by grade, bags, quality results

Then it depends on the mode you sent:

Toll ("mode": "toll", the goods stay yours):

# At the factory You call You receive
6 Charges for its work: tariffs plus charges such as gunny bags or an export fee GET /statements?client_ref=… statement.issued
7 Waits for you POST /statements/{id}/approve, or /dispute with a note —
8a Sends your products back to you — toll.dispatched
8b Or sells them on your behalf, at auction, through a broker or directly — sale.proceeds: gross per lot and grade, charges, net
9 Pays you the net proceeds GET /payments payment.recorded with kind: "proceeds"

Purchase (no mode, the factory buys):

# At the factory You call You receive
6 Self-billed invoice for what was accepted, by grade and price list, less agreed deductions GET /invoices?supplier_ref=… invoice.issued
7 Pays you, in one or more payments GET /payments?supplier_ref=… payment.recorded

Your system then settles with its own members or farmers, from these amounts and its own deductions.

The consignment you send

{
  "reference_no": "CMB-26-41",
  "source": "society_api",
  "kind": "coffee",
  "mode": "toll",
  "sender": {"external_system": "your-system", "society_id": 39, "name": "Karati Farmers Co-operative", "consent_ref": "REL-118"},
  "item": {"code": "COFFEE-PARCHMENT", "grade": "P1"},
  "declared_qty": 1250.5, "unit": "kg", "bags": 25,
  "dispatched_at": "2026-11-15T08:10:00+03:00",
  "transport": {"vehicle": "KDA 123A", "driver_phone": "+254700000000", "movement_permit": "AFA/…"},
  "lots": [{"lot_no": "KAR-2026-11-14", "qty": 1250.5, "plot_set_ref": "optional, for EUDR"}],
  "notes": ""
}
Field Required Notes
reference_no yes Your number, up to 40 characters, unique at this factory. Echoed in every event
source yes Where it comes from, for example society_api or supplier_api
kind no coffee (a coffee milling batch) or value_addition (any other chain)
mode no toll = your goods, processed for a fee; purchase or absent = the factory buys them
sender for societies external_system (your system's name) and society_id (the society in your system); name is used the first time
item.code yes A factory item code, or your own product code once the factory mapped it
item.grade no Your grade, kept with the delivery
declared_qty, unit yes What you sent; the unit is one of the factory's unit codes (kg, bag60…)
bags, dispatched_at, transport, lots, notes no Lots (up to 200) keep traceability back to your farms or collection days

What each value chain receives and makes

The raw material codes, products, grades, yields and quality checks differ by value chain. Each one has its own page with an example consignment and the run.completed you would get back: see Value chains. For example:

  • Coffee dry mill: parchment in; clean coffee by grade (AA, AB, PB, C, E, T, TT) in 60 kg bags, plus husks.
  • Tea factory: green leaf in; made tea by grade (BP1, PF1, PD, D1, FNGS, BMF) for the auction.
  • Mango pulp and juice: fresh mango in; pulp and nectar, with peel and stones as by-products.

Good practice

  • Declare before the truck arrives, so the gate clerk can receive against your consignment instead of typing it in.
  • One consignment per truck or batch. Several of your collection days can travel as lots of one consignment.
  • Keep reference_no stable. Never reuse a number for another delivery.
  • Store X-Event-Ids and process each event once.
  • Reconcile weekly with GET /intakes, /statements, /invoices and /payments, in case an event was missed while your system was down.