Prodaksha Developers

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.

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 item CLEAN-AA), BP1, PF1… for tea, null for by-products and waste;
  • bags and bag_unit (60 kg bags for coffee), or packets for 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):

  1. Create the factory's processor account, set its password, copy the webhook signing secret.
  2. Give the factory: the FPOBox address, the processor login and password, and the signing secret.

In Prodaksha (factory admin):

  1. The platform switches on the API and webhooks module; the factory switches on FPOBox link.
  2. Supply → FPOBox link: address, processor account, password, signing secret → Save → Test connection.
  3. Create a token there and give it to FPOBox, if FPOBox will push.
  4. Sync now (then every 15 minutes). The societies that consented appear, with their products.
  5. Map each society product to a factory item → Save the mapping.
  6. 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.proceeds shows 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