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": {…}}.

codeHTTPMeaning
VALIDATION422A field is missing or wrong; errors names each one.
UNAUTHORIZED401No token, or it was revoked.
FORBIDDEN403The token lacks the ability, the subscription is not active, or the company switched the API off.
NOT_FOUND404No such record in this company.
CONFLICT409Duplicate reference, a reused idempotency key with another body, or the record is not in a state for this.
RATE_LIMITED429Too many calls; wait for Retry-After seconds.
DISABLED503The platform switched the API off for maintenance.
SERVER_ERROR500Our 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"
Answer
200OK

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
200OK
401Unauthorized
403Forbidden (ability, subscription or API module off)

Items

GET /items

Items (ability read:catalog), cursor-paginated by last update

ParameterInTypeNotes
typequery string
updated_sincequery string (date-time)
limitquery integer
cursorquery stringmeta.next_cursor of the previous page
curl -X GET https://prodaksha.com/api/v1/items \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
Answer
200OK

Consignments

POST /consignments

Declare an arrival (ability write:consignments)

ParameterInTypeNotes
Idempotency-Keyheader string
Body fieldTypeNotes
reference_no requiredstringe.g. 'VA-2026-000123' (max 40)
source requiredstringWhere 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'
kindstring: coffee | value_additioncoffee = a coffee milling batch (CMB-...), value_addition = any other chain (VAB-...). Optional.
modestring: toll | purchasetoll = 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.
senderobject
item requiredobject
declared_qty requirednumbere.g. 1250.5
unit requiredstringe.g. 'kg'
bagsinteger
dispatched_atstring (date-time)
transportobject
lotsarray of object
notesstring
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
201Created: data.id (ULID), data.status = pending_intake, data.supplier_ref. The sender (external_system + society_id) becomes a supplier marked society.
403The society withdrew its consent (FORBIDDEN)
409Duplicate reference_no, or Idempotency-Key reused with another body
422Validation failed
GET /consignments/{id}

Consignment status (ability read or write:consignments)

ParameterInTypeNotes
id requiredpath string
curl -X GET https://prodaksha.com/api/v1/consignments/{id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
Answer
200OK
404Not 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.

ParameterInTypeNotes
id requiredpath string
decision requiredpath string: approve | dispute
Body fieldTypeNotes
notestringrequired 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
200OK: the consignment, status received (approve) or variance_review (dispute), variance.decision
409Not waiting for a decision

Intakes

GET /intakes

Receipts of supplier and society deliveries (ability read or write:consignments)

ParameterInTypeNotes
consignment_idquery stringULID or reference_no
supplier_refquery stringthe society id in the partner system
limitquery integer
curl -X GET https://prodaksha.com/api/v1/intakes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
Answer
200OK: 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)

ParameterInTypeNotes
scopequery string: purchase | sales
curl -X GET https://prodaksha.com/api/v1/price-lists \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
Answer
200OK

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.

ParameterInTypeNotes
id requiredpath string
curl -X GET https://prodaksha.com/api/v1/work-orders/{id}/outputs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
Answer
200OK: work_order_ref, completed_at, outputs [item, role, qty, unit, lot_no, yield_pct, yield_flag]
404Not found

Lots

GET /lots/{lot_no}/trace

One step back and one step forward from a lot (ability read or write:consignments)

ParameterInTypeNotes
lot_no requiredpath string
curl -X GET https://prodaksha.com/api/v1/lots/{lot_no}/trace \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
Answer
200OK: received_on (ticket, consignment), back, forward, deliveries
404Not found

Invoices

GET /invoices

Self-billed purchase invoices to suppliers and societies (ability read, read:statements or approve:statements); drafts are never shown

ParameterInTypeNotes
supplier_refquery string
statusquery string: issued | part_paid | paid | cancelled
curl -X GET https://prodaksha.com/api/v1/invoices \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
Answer
200OK: 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)

ParameterInTypeNotes
id requiredpath string
curl -X GET https://prodaksha.com/api/v1/invoices/{id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
Answer
200OK
404Not found

Payments

GET /payments

Payments made to suppliers and societies (ability read, read:statements or approve:statements)

ParameterInTypeNotes
supplier_refquery string
curl -X GET https://prodaksha.com/api/v1/payments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
Answer
200OK: 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

ParameterInTypeNotes
client_refquery stringthe society id the factory stored for the client
statusquery string: issued | approved | disputed | invoiced
curl -X GET https://prodaksha.com/api/v1/statements \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
Answer
200OK: 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)

ParameterInTypeNotes
id requiredpath string
curl -X GET https://prodaksha.com/api/v1/statements/{id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
Answer
200OK
404Not found
POST /statements/{id}/approve

The client approves an issued statement (ability approve:statements); it is then invoiced

ParameterInTypeNotes
id requiredpath string
Body fieldTypeNotes
notestring(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
200OK: status approved
409Not an issued statement
POST /statements/{id}/dispute

The client disputes an issued statement with a reason (ability approve:statements)

ParameterInTypeNotes
id requiredpath string
Body fieldTypeNotes
note requiredstring(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
200OK: status disputed
409Not an issued statement
422Reason 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"
Answer
200OK
POST /webhooks

Register an endpoint; the response carries the signing secret once (ability admin)

Body fieldTypeNotes
url requiredstring (uri)
events requiredarray of stringe.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"]}'
Answer
201Created
DELETE /webhooks/{id}

Deactivate an endpoint (ability admin)

ParameterInTypeNotes
id requiredpath string
curl -X DELETE https://prodaksha.com/api/v1/webhooks/{id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
Answer
200OK

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.

ParameterInTypeNotes
Idempotency-Keyheader string
Body fieldTypeNotes
location requiredstringthe store's location code e.g. 'COLD1'
reading requirednumberdegrees Celsius e.g. 3.4
recorded_atstring (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
201Recorded: data.within (in band), data.held_lots
404No such location
422Not a reading, or the store has no temperature band