FPOBox
FPOBox is the system farmer societies and cooperatives use to record their members' deliveries and pay them. When a society sends a batch to a factory that runs Prodaksha, the two systems keep each other up to date, so the society sees what the miller received, made, charged and sold, and can pay its members.
This page is the FPOBox side of Connecting a supplier or society system. It also shows the pattern for any society system that wants the same depth of link.
How the two systems talk
| Direction | How |
|---|---|
| Factory → FPOBox (pull) | Every 15 minutes the factory logs in to FPOBox as a processor and reads consents, each society's product catalogue, dispatched batches and the society's decisions |
| FPOBox → factory (push, optional) | FPOBox can also POST /api/v1/consignments and decide variances and statements through the factory API, with the token the factory created for it |
| Factory → FPOBox (events) | Signed webhooks to {FPOBox address}/api/v2/processor/events, the same events and signature as in Webhooks |
The pull means nothing is lost when a push fails; the push makes it faster. A batch is never created twice: the factory keeps one consignment per reference_no.
Batch numbers
reference_no is always the society's batch:
CMB-26-41: a coffee milling batch ("kind": "coffee");VAB-26-7: a value-addition batch, for every other chain ("kind": "value_addition").
"mode": "toll" means the society keeps the goods and pays for milling; without it the factory buys them.
What FPOBox provides (/api/v2)
| Method and path | Purpose |
|---|---|
POST /auth/partner-login |
The factory's processor login; answers a JWT |
GET /processor/consents |
Societies that gave this factory access, with scope toll, purchase or both |
GET /processor/societies/{fpo_id}/catalog |
The society's products: {fpo_id, products: [{product_id, name, item_code, unit, value_chain, grades: []}]} |
GET /processor/societies/{fpo_id}/consignments?status=dispatched |
Batches the society dispatched, in the consignment shape of the factory API |
GET /processor/societies/{fpo_id}/decisions?since=<ISO 8601> |
The society's answers: [{decision_id, reference_no, kind: variance or statement, decision: approve or dispute, note, statement_no, decided_at}] |
POST /processor/events |
Receives the factory's events (signature checked). Answers 2xx for a batch it does not know, and ignores it |
The factory applies each decision once (by decision_id), and asks only for decisions after the latest one it recorded for that society.
Consent comes first
A society must connect to the factory in FPOBox (Coffee → Millers → Connect, or the value-addition equivalent) before anything flows:
- the factory sees the society only after the next sync;
- a pushed consignment naming an FPOBox society that has not consented is refused
403 FORBIDDEN("has not given this factory access"); - if the society withdraws consent, the next request is refused.
Product codes
A society's product code (item_code in its catalogue) does not have to match the factory's item codes. The factory lists every society product on its FPOBox link page and maps each to one of its items (a match by code or name is suggested). After that, the society's own code is accepted both in the pull and in a push.
Grades, bags and quality in the results
run.completed carries, per output:
grade:AA,AB,PB… for clean coffee (from the itemCLEAN-AA),BP1,PF1… for tea,nullfor by-products and waste;bagsandbag_unit(60 kg bags for coffee), orpacketsfor goods counted in pieces;quality: the checks recorded on the run or its main lot (moisture, screen size, cup score…).
A dry-mill run on parchment that came from a wet-mill run still reports to the society's original batch: the factory follows the lot tree back to the consignment.
Setting up a factory and its societies
In FPOBox (super admin):
- Create the factory's processor account, set its password, copy the webhook signing secret.
- Give the factory: the FPOBox address, the processor login and password, and the signing secret.
In Prodaksha (factory admin):
- The platform switches on the API and webhooks module; the factory switches on FPOBox link.
- Supply → FPOBox link: address, processor account, password, signing secret → Save → Test connection.
- Create a token there and give it to FPOBox, if FPOBox will push.
- Sync now (then every 15 minutes). The societies that consented appear, with their products.
- Map each society product to a factory item → Save the mapping.
- For toll work: Toll Processing → make each society a toll client linked to its FPOBox id, and add tariffs.
Each society, in FPOBox: Connect to the factory. Only batches dispatched after that are seen.
Money, in short
- Toll goods never become the factory's stock; the factory earns only its tariffs and charges.
- When the factory sells a society's goods on its behalf, the buyer owes the factory, and the factory owes the society the net: gross less the broker's deductions and the factory's own charges.
sale.proceedsshows each line;payment.recorded(kind: proceeds) shows the payment. - FPOBox then pays each member from the proceeds, less the society's own deductions (loans, inputs, levies).
When something does not match
| What you see | Why, and what to do |
|---|---|
| The factory's sync says "FPOBox refused the login" | Wrong processor login or password; re-enter it on the FPOBox link page and Test connection |
| "Item … is not in the factory's item list. Map it on the FPOBox screen." | Map the society's product to a factory item, then Sync now |
| "No toll client fpobox 39 is set up at this factory" | A toll batch: make society 39 a toll client linked to FPOBox |
403 "has not given this factory access" |
The society has not connected to the factory in FPOBox, or withdrew; connect, then sync |
| A decision is "skipped" | FPOBox sent a decision for a batch the factory does not have; nothing changed |
| FPOBox rejects events with a timestamp error | The two servers' clocks differ by more than 5 minutes; fix NTP |
| Events waiting or failed on the factory's FPOBox card | Wrong signing secret on one side, or FPOBox unreachable; deliveries retry for about 15 hours |
