Factory API
Version 1.0.0 · Base URL https://prodaksha.com/api/v1
Factory API v1 (factory_system/04_API_AND_WEBHOOK_CONTRACT.md). Changes are additive; a breaking change is /api/v2.
Engine ids are ULID strings (chapter 16, decision 5). Documents carry the sender's `reference_no`, which is stored and echoed.
Times are ISO-8601 with offset. Quantities carry `unit` (a code from the company's units).
Writes accept `Idempotency-Key` (or `X-Idempotency-Key`): a retry with the same key and body returns the first response.
Getting started
Ask the factory for a token: the platform's Super Admin issues it for the factory (an FPOBox link gets its own from the factory's FPOBox page). Send it on every call:
curl -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" https://prodaksha.com/api/v1/company
A token belongs to one company and carries abilities: read, read:catalog, write:consignments, read:statements, approve:statements, write:readings, admin . admin implies all of them. Each endpoint below names the ability it needs.
Every answer is JSON: {"success": true, "data": …, "meta": …}.
Errors
A failed call answers {"success": false, "code": "…", "message": "…", "errors": {…}}.
| code | HTTP | Meaning |
VALIDATION | 422 | A field is missing or wrong; errors names each one. |
UNAUTHORIZED | 401 | No token, or it was revoked. |
FORBIDDEN | 403 | The token lacks the ability, the subscription is not active, or the company switched the API off. |
NOT_FOUND | 404 | No such record in this company. |
CONFLICT | 409 | Duplicate reference, a reused idempotency key with another body, or the record is not in a state for this. |
RATE_LIMITED | 429 | Too many calls; wait for Retry-After seconds. |
DISABLED | 503 | The platform switched the API off for maintenance. |
SERVER_ERROR | 500 | Our fault; retry later with the same idempotency key. |
Paging and limits
Lists return up to limit rows (at most 200) and meta.next_cursor; pass it back as cursor for the next page, until it is null. Use updated_since to fetch only what changed.
Each token may make 120 calls a minute.
Retrying safely
Send an Idempotency-Key header (up to 100 characters, e.g. a UUID) with every write. A retry with the same key and body returns the first answer and changes nothing; the same key with another body is refused (409). Consignments are also unique by your reference_no.
Webhooks
Register an address with POST /webhooks (admin ability); the answer carries its signing secret once. Each event is a POST with this body:
{"id": "01J…", "type": "consignment.received", "occurred_at": "2026-09-30T08:15:00+03:00", "company_id": 12, "data": {…}}
Headers: X-Event-Id, X-Timestamp (Unix seconds) and X-Signature = sha256= and the HMAC-SHA256 of the raw body with your secret. Refuse a timestamp more than 5 minutes off, compare signatures in constant time, and ignore an event id you already have. Reply 2xx within 10 seconds; failures are retried after 1, 5, 30, 120, 720 minutes, then set aside.
// PHP
$ok = hash_equals('sha256=' . hash_hmac('sha256', file_get_contents('php://input'), $secret), $_SERVER['HTTP_X_SIGNATURE'] ?? '')
&& abs(time() - (int) ($_SERVER['HTTP_X_TIMESTAMP'] ?? 0)) <= 300;
# Python
ok = hmac.compare_digest("sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest(), headers["X-Signature"])
// Node.js
const ok = crypto.timingSafeEqual(Buffer.from("sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex")), Buffer.from(req.headers["x-signature"]));
Events you may subscribe to (or "*" for all):
consignment.declared consignment.received consignment.variance_decided run.completed statement.issued invoice.issued payment.recorded lot.hold_changed company.activated company.suspended toll.dispatched sale.proceeds stock.document.posted stock.document.reversed journal.posted intake.posted run.reversed job_card.finished sales_order.confirmed delivery.posted delivery.returned sales_invoice.posted credit_note.posted einvoice.signed receipt.recorded receipt.matched approval.requested approval.decided
Health
GET /health · no token needed
Version, time and migration state
curl -X GET https://prodaksha.com/api/v1/health \
-H "Accept: application/json"
Company
GET /company
Tenant profile, country, currency, modules on (ability read or read:catalog)
curl -X GET https://prodaksha.com/api/v1/company \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
| Answer | |
200 | OK |
401 | Unauthorized |
403 | Forbidden (ability, subscription or API module off) |
Items
GET /items
Items (ability read:catalog), cursor-paginated by last update
| Parameter | In | Type | Notes |
type | query |
string | |
updated_since | query |
string (date-time) | |
limit | query |
integer | |
cursor | query |
string | meta.next_cursor of the previous page |
curl -X GET https://prodaksha.com/api/v1/items \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
Consignments
POST /consignments
Declare an arrival (ability write:consignments)
| Parameter | In | Type | Notes |
Idempotency-Key | header |
string | |
| Body field | Type | Notes |
reference_no required | string | e.g. 'VA-2026-000123' (max 40) |
source required | string | Where it comes from, e.g. society_api, supplier_api. toll_client (or mode toll) = the sender's own goods, processed for a fee. e.g. 'society_api' |
kind | string: coffee | value_addition | coffee = a coffee milling batch (CMB-...), value_addition = any other chain (VAB-...). Optional. |
mode | string: toll | purchase | toll = the sender keeps ownership and pays for processing (the sender must be a toll client of the factory); purchase or absent = the factory buys it. |
sender | object | |
item required | object | |
declared_qty required | number | e.g. 1250.5 |
unit required | string | e.g. 'kg' |
bags | integer | |
dispatched_at | string (date-time) | |
transport | object | |
lots | array of object | |
notes | string | |
curl -X POST https://prodaksha.com/api/v1/consignments \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
-d '{"reference_no":"VA-2026-000123","source":"society_api","item":{"code":"string"},"declared_qty":1250.5,"unit":"kg"}'
| Answer | |
201 | Created: data.id (ULID), data.status = pending_intake, data.supplier_ref. The sender (external_system + society_id) becomes a supplier marked society. |
403 | The society withdrew its consent (FORBIDDEN) |
409 | Duplicate reference_no, or Idempotency-Key reused with another body |
422 | Validation failed |
GET /consignments/{id}
Consignment status (ability read or write:consignments)
| Parameter | In | Type | Notes |
id required | path |
string | |
curl -X GET https://prodaksha.com/api/v1/consignments/{id} \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
| Answer | |
200 | OK |
404 | Not found (or another company's) |
POST /consignments/{id}/variance/{decision}
The society approves or disputes a weight difference outside the tolerance (ability write:consignments or approve:statements). id may be the ULID or the reference_no.
| Parameter | In | Type | Notes |
id required | path |
string | |
decision required | path |
string: approve | dispute | |
| Body field | Type | Notes |
note | string | required to dispute (max 255) |
curl -X POST https://prodaksha.com/api/v1/consignments/{id}/variance/{decision} \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
-d '{}'
| Answer | |
200 | OK: the consignment, status received (approve) or variance_review (dispute), variance.decision |
409 | Not waiting for a decision |
Intakes
GET /intakes
Receipts of supplier and society deliveries (ability read or write:consignments)
| Parameter | In | Type | Notes |
consignment_id | query |
string | ULID or reference_no |
supplier_ref | query |
string | the society id in the partner system |
limit | query |
integer | |
curl -X GET https://prodaksha.com/api/v1/intakes \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
| Answer | |
200 | OK: intake_ticket_no, reference_no, received_qty, reject_qty, accepted_qty, moisture, price, net_amount, variance, lot_no, payment_status; meta.next_cursor |
Price lists
GET /price-lists
Price lists by grade and period (ability read:catalog)
| Parameter | In | Type | Notes |
scope | query |
string: purchase | sales | |
curl -X GET https://prodaksha.com/api/v1/price-lists \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
Work orders
GET /work-orders/{id}/outputs
Results of a run (ability read or write:consignments). id may be the ULID or the run number.
| Parameter | In | Type | Notes |
id required | path |
string | |
curl -X GET https://prodaksha.com/api/v1/work-orders/{id}/outputs \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
| Answer | |
200 | OK: work_order_ref, completed_at, outputs [item, role, qty, unit, lot_no, yield_pct, yield_flag] |
404 | Not found |
Lots
GET /lots/{lot_no}/trace
One step back and one step forward from a lot (ability read or write:consignments)
| Parameter | In | Type | Notes |
lot_no required | path |
string | |
curl -X GET https://prodaksha.com/api/v1/lots/{lot_no}/trace \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
| Answer | |
200 | OK: received_on (ticket, consignment), back, forward, deliveries |
404 | Not found |
Invoices
GET /invoices
Self-billed purchase invoices to suppliers and societies (ability read, read:statements or approve:statements); drafts are never shown
| Parameter | In | Type | Notes |
supplier_ref | query |
string | |
status | query |
string: issued | part_paid | paid | cancelled | |
curl -X GET https://prodaksha.com/api/v1/invoices \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
| Answer | |
200 | OK: invoice_no, reference_no (consignment), lines [description, qty, unit, rate, amount, deductions, net], total, paid, outstanding, due_date |
GET /invoices/{id}
One purchase invoice (id or invoice_no)
| Parameter | In | Type | Notes |
id required | path |
string | |
curl -X GET https://prodaksha.com/api/v1/invoices/{id} \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
Payments
GET /payments
Payments made to suppliers and societies (ability read, read:statements or approve:statements)
| Parameter | In | Type | Notes |
supplier_ref | query |
string | |
curl -X GET https://prodaksha.com/api/v1/payments \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
| Answer | |
200 | OK: payment_no, invoice_no, amount, currency, rail, txn_ref, paid_at |
Statements
GET /statements
Toll statements issued to your clients (ability read:statements or approve:statements); drafts are never shown
| Parameter | In | Type | Notes |
client_ref | query |
string | the society id the factory stored for the client |
status | query |
string: issued | approved | disputed | invoiced | |
curl -X GET https://prodaksha.com/api/v1/statements \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
| Answer | |
200 | OK: statement_no, reference_no (consignment), lines [description, qty, unit, rate, amount], subtotal, vat, total, currency, due_date, status |
GET /statements/{id}
One toll statement (ability read:statements or approve:statements)
| Parameter | In | Type | Notes |
id required | path |
string | |
curl -X GET https://prodaksha.com/api/v1/statements/{id} \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
POST /statements/{id}/approve
The client approves an issued statement (ability approve:statements); it is then invoiced
| Parameter | In | Type | Notes |
id required | path |
string | |
| Body field | Type | Notes |
note | string | (max 255) |
curl -X POST https://prodaksha.com/api/v1/statements/{id}/approve \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
-d '{}'
| Answer | |
200 | OK: status approved |
409 | Not an issued statement |
POST /statements/{id}/dispute
The client disputes an issued statement with a reason (ability approve:statements)
| Parameter | In | Type | Notes |
id required | path |
string | |
| Body field | Type | Notes |
note required | string | (max 255) |
curl -X POST https://prodaksha.com/api/v1/statements/{id}/dispute \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
-d '{"note":"string"}'
| Answer | |
200 | OK: status disputed |
409 | Not an issued statement |
422 | Reason missing |
Webhooks
GET /webhooks
Registered endpoints (ability admin)
curl -X GET https://prodaksha.com/api/v1/webhooks \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
POST /webhooks
Register an endpoint; the response carries the signing secret once (ability admin)
| Body field | Type | Notes |
url required | string (uri) | |
events required | array of string | e.g. ["consignment.received","run.completed"] |
curl -X POST https://prodaksha.com/api/v1/webhooks \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
-d '{"url":"string","events":["consignment.received","run.completed"]}'
DELETE /webhooks/{id}
Deactivate an endpoint (ability admin)
| Parameter | In | Type | Notes |
id required | path |
string | |
curl -X DELETE https://prodaksha.com/api/v1/webhooks/{id} \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
Temperature readings
POST /temperature-readings
A cold-store probe sends a reading (ability write:readings). Outside the store's band, the chilled and frozen lots in it are put on hold.
| Parameter | In | Type | Notes |
Idempotency-Key | header |
string | |
| Body field | Type | Notes |
location required | string | the store's location code e.g. 'COLD1' |
reading required | number | degrees Celsius e.g. 3.4 |
recorded_at | string (date-time) | when the probe read it; default now |
curl -X POST https://prodaksha.com/api/v1/temperature-readings \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
-d '{"location":"COLD1","reading":3.4}'
| Answer | |
201 | Recorded: data.within (in band), data.held_lots |
404 | No such location |
422 | Not a reading, or the store has no temperature band |