{"openapi":"3.0.3","info":{"title":"Factory API","version":"1.0.0","description":"Factory API v1 (factory_system/04_API_AND_WEBHOOK_CONTRACT.md). Changes are additive; a breaking change is /api/v2.\nEngine ids are ULID strings (chapter 16, decision 5). Documents carry the sender's `reference_no`, which is stored and echoed.\nTimes are ISO-8601 with offset. Quantities carry `unit` (a code from the company's units).\nWrites accept `Idempotency-Key` (or `X-Idempotency-Key`): a retry with the same key and body returns the first response.\n"},"servers":[{"url":"/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Sanctum token issued per company by the platform. Abilities read, read:catalog, write:consignments, read:statements, approve:statements, write:readings, admin (admin implies all)."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":100}}},"schemas":{"Error":{"type":"object","required":["success","message","code"],"properties":{"success":{"type":"boolean","example":false},"message":{"type":"string"},"code":{"type":"string","enum":["VALIDATION","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","CONFLICT","RATE_LIMITED","DISABLED","METHOD_NOT_ALLOWED","SERVER_ERROR"]},"errors":{"type":"object","additionalProperties":{"type":"string"}}}},"Item":{"type":"object","properties":{"id":{"type":"string","description":"ULID"},"code":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["raw","pack","consumable","semi","finished","service","tooling"]},"category":{"type":"string","nullable":true},"unit":{"type":"string","description":"base unit code"},"units":{"type":"array","items":{"type":"object","properties":{"unit":{"type":"string"},"factor":{"type":"number"}}}},"tracking":{"type":"string","enum":["none","lot","serial"]},"gtin":{"type":"string","nullable":true},"hs_code":{"type":"string","nullable":true},"vat_class":{"type":"string"},"is_active":{"type":"boolean"},"updated_at":{"type":"string","format":"date-time"}}},"ConsignmentIn":{"type":"object","required":["reference_no","source","item","declared_qty","unit"],"properties":{"reference_no":{"type":"string","maxLength":40,"example":"VA-2026-000123"},"source":{"type":"string","example":"society_api","description":"Where it comes from, e.g. society_api, supplier_api. toll_client (or mode toll) = the sender's own goods, processed for a fee."},"kind":{"type":"string","enum":["coffee","value_addition"],"description":"coffee = a coffee milling batch (CMB-...), value_addition = any other chain (VAB-...). Optional."},"mode":{"type":"string","enum":["toll","purchase"],"description":"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":{"type":"object","properties":{"external_system":{"type":"string","example":"fpobox"},"society_id":{"type":"integer"},"name":{"type":"string"},"consent_ref":{"type":"string"}}},"item":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"One of the factory's item codes (GET /items), or your own product code once the factory has mapped it to one of its items."},"grade":{"type":"string"}}},"declared_qty":{"type":"number","example":1250.5},"unit":{"type":"string","example":"kg"},"bags":{"type":"integer"},"dispatched_at":{"type":"string","format":"date-time"},"transport":{"type":"object","additionalProperties":true},"lots":{"type":"array","items":{"type":"object","required":["lot_no","qty"],"properties":{"lot_no":{"type":"string"},"qty":{"type":"number"},"plot_set_ref":{"type":"string"}}}},"notes":{"type":"string"}}},"WebhookEvent":{"type":"object","description":"Body of every webhook POST. Headers: X-Event-Id (= id), X-Timestamp (unix seconds; reject if more than 5 minutes off),\nX-Signature: sha256=<hex hmac_sha256(raw body, endpoint secret)>. Reply 2xx to accept; be idempotent by X-Event-Id.\nRetries after 1m, 5m, 30m, 2h, 12h, then the delivery is dead-lettered.\n","properties":{"id":{"type":"string"},"type":{"type":"string","example":"consignment.received"},"occurred_at":{"type":"string","format":"date-time"},"company_id":{"type":"integer"},"data":{"type":"object","additionalProperties":true}}}}},"paths":{"/health":{"get":{"security":[],"summary":"Version, time and migration state","responses":{"200":{"description":"OK"}}}},"/company":{"get":{"summary":"Tenant profile, country, currency, modules on (ability read or read:catalog)","responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (ability, subscription or API module off)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/items":{"get":{"summary":"Items (ability read:catalog), cursor-paginated by last update","parameters":[{"name":"type","in":"query","schema":{"type":"string"}},{"name":"updated_since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"meta.next_cursor of the previous page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"meta":{"type":"object","properties":{"next_cursor":{"type":"string","nullable":true},"limit":{"type":"integer"}}}}}}}}}}},"/consignments":{"post":{"summary":"Declare an arrival (ability write:consignments)","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsignmentIn"}}}},"responses":{"201":{"description":"Created: data.id (ULID), data.status = pending_intake, data.supplier_ref. The sender (external_system + society_id) becomes a supplier marked society."},"403":{"description":"The society withdrew its consent (FORBIDDEN)"},"409":{"description":"Duplicate reference_no, or Idempotency-Key reused with another body"},"422":{"description":"Validation failed"}}}},"/consignments/{id}":{"get":{"summary":"Consignment status (ability read or write:consignments)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Not found (or another company's)"}}}},"/consignments/{id}/variance/{decision}":{"post":{"summary":"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.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"decision","in":"path","required":true,"schema":{"type":"string","enum":["approve","dispute"]}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":255,"description":"required to dispute"}}}}}},"responses":{"200":{"description":"OK: the consignment, status received (approve) or variance_review (dispute), variance.decision"},"409":{"description":"Not waiting for a decision"}}}},"/intakes":{"get":{"summary":"Receipts of supplier and society deliveries (ability read or write:consignments)","parameters":[{"name":"consignment_id","in":"query","required":false,"schema":{"type":"string"},"description":"ULID or reference_no"},{"name":"supplier_ref","in":"query","required":false,"schema":{"type":"string"},"description":"the society id in the partner system"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200}}],"responses":{"200":{"description":"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":{"summary":"Price lists by grade and period (ability read:catalog)","parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["purchase","sales"],"default":"purchase"}}],"responses":{"200":{"description":"OK"}}}},"/work-orders/{id}/outputs":{"get":{"summary":"Results of a run (ability read or write:consignments). id may be the ULID or the run number.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK: work_order_ref, completed_at, outputs [item, role, qty, unit, lot_no, yield_pct, yield_flag]"},"404":{"description":"Not found"}}}},"/lots/{lot_no}/trace":{"get":{"summary":"One step back and one step forward from a lot (ability read or write:consignments)","parameters":[{"name":"lot_no","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK: received_on (ticket, consignment), back, forward, deliveries"},"404":{"description":"Not found"}}}},"/invoices":{"get":{"summary":"Self-billed purchase invoices to suppliers and societies (ability read, read:statements or approve:statements); drafts are never shown","parameters":[{"name":"supplier_ref","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["issued","part_paid","paid","cancelled"]}}],"responses":{"200":{"description":"OK: invoice_no, reference_no (consignment), lines [description, qty, unit, rate, amount, deductions, net], total, paid, outstanding, due_date"}}}},"/invoices/{id}":{"get":{"summary":"One purchase invoice (id or invoice_no)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Not found"}}}},"/payments":{"get":{"summary":"Payments made to suppliers and societies (ability read, read:statements or approve:statements)","parameters":[{"name":"supplier_ref","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK: payment_no, invoice_no, amount, currency, rail, txn_ref, paid_at"}}}},"/statements":{"get":{"summary":"Toll statements issued to your clients (ability read:statements or approve:statements); drafts are never shown","parameters":[{"name":"client_ref","in":"query","required":false,"schema":{"type":"string"},"description":"the society id the factory stored for the client"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["issued","approved","disputed","invoiced"]}}],"responses":{"200":{"description":"OK: statement_no, reference_no (consignment), lines [description, qty, unit, rate, amount], subtotal, vat, total, currency, due_date, status"}}}},"/statements/{id}":{"get":{"summary":"One toll statement (ability read:statements or approve:statements)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Not found"}}}},"/statements/{id}/approve":{"post":{"summary":"The client approves an issued statement (ability approve:statements); it is then invoiced","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":255}}}}}},"responses":{"200":{"description":"OK: status approved"},"409":{"description":"Not an issued statement"}}}},"/statements/{id}/dispute":{"post":{"summary":"The client disputes an issued statement with a reason (ability approve:statements)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["note"],"properties":{"note":{"type":"string","maxLength":255}}}}}},"responses":{"200":{"description":"OK: status disputed"},"409":{"description":"Not an issued statement"},"422":{"description":"Reason missing"}}}},"/webhooks":{"get":{"summary":"Registered endpoints (ability admin)","responses":{"200":{"description":"OK"}}},"post":{"summary":"Register an endpoint; the response carries the signing secret once (ability admin)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"},"example":["consignment.received","run.completed"]}}}}}},"responses":{"201":{"description":"Created"}}}},"/webhooks/{id}":{"delete":{"summary":"Deactivate an endpoint (ability admin)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/temperature-readings":{"post":{"summary":"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.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["location","reading"],"properties":{"location":{"type":"string","description":"the store's location code","example":"COLD1"},"reading":{"type":"number","description":"degrees Celsius","example":3.4},"recorded_at":{"type":"string","format":"date-time","description":"when the probe read it; default now"}}}}}},"responses":{"201":{"description":"Recorded: data.within (in band), data.held_lots"},"404":{"description":"No such location"},"422":{"description":"Not a reading, or the store has no temperature band"}}}}}}