ZigoTrace Partner API: Developer Guide

ZigoTrace Partner APIFor software vendors (ERPs, distribution and supply-chain systems) who want to give their own customers ZigoTrace: a rebuilt supply chain, the losses and gaps in it with a value on each, and a way to close them.

Base URL: https://agri-api.zigotrace.com/v1

Spec: GET /v1/openapi.json (public, no key needed). Use our client libraries, or generate your own from it.

Stability: v1 does not change in a way that breaks a caller. A breaking change would ship as /v2, and v1 would keep running.

How it fits togetheryour ERP ──records──▶ ZigoTrace ──webhooks──▶ your ERP │ rebuilds the chain, checks it │ finding.opened / finding.closed │ fix.proposed (the exact record to write) your ERP ◀── you write the record, then it comes back in the next sync ──┘ fix.confirmed + finding.closed

You hold a partner key and create one organisation per customer.

You send that customer's records: goods received, dispatches, invoices, stock movements and so on.

ZigoTrace checks the chain and tells you what it finds, as findings.

To close a finding, you send the missing values. ZigoTrace answers with a proposal: the exact record your ERP should hold. It never writes into ZigoTrace's own store for your customers, because your ERP is the system of record.

You write the record in your ERP and acknowledge the proposal. When the record arrives in your next sync and the check no longer raises the finding, you get fix.confirmed and finding.closed.

A finding closes only when the record really exists. Marking it done is not enough.AuthenticationEvery call except /v1/openapi.json needs your partner key:Authorization: Bearer zpk_...ZigoTrace issues the key. To start building, ask for a free sandbox key: it comes with test organisations already loaded with sample records. The key is shown once and stored only as a hash; if you lose it, ask for it to be rotated.Organisation keys (zgk_...) do not work on /v1. An organisation you create through the API has no key of its own; your partner key reaches it.Quick startKEY="zpk_..." API="https://agri-api.zigotrace.com/v1" # 1. Where events should go. Store the secret it returns: it signs every event. curl -X PUT "$API/partner/webhook" -H "Authorization: Bearer $KEY" \ -H "Content-Type: application/json" -d '{"url": "https://erp.example.com/zigotrace/events"}' # 2. One organisation per customer. Sending the same external_ref again returns the same organisation. curl -X POST "$API/orgs" -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \ -d '{"name": "Kilimani Foods", "external_ref": "cust-42", "templates": ["horeca_distributor"]}' # 3. Their records. Check the fields against GET /v1/schema/receipts. curl -X POST "$API/orgs/org-.../records/receipts" -H "Authorization: Bearer $KEY" \ -H "Idempotency-Key: grn-2026-09-24-001" -H "Content-Type: application/json" \ -d '{"records": [{"receipt_id": "GRN-881", "lot_id": "LOT-2026-0412", "supplier_id": "SUP-NYERI", "received_date": "2026-09-24", "quantity": 40, "unit": "kg", "location": "WH-1"}]}' # 4. What is open now. curl "$API/orgs/org-.../findings?area=receiving" -H "Authorization: Bearer $KEY"Organisations

Call

What it does

POST /orgs

Creates an organisation: name, optional external_ref (your id for the customer) and optional templates (the kind of business). Returns 201, or 200 with the existing organisation when the external_ref is already known.

GET /orgs

Lists your organisations.

GET /orgs/{org_id}

Gets one organisation.

PUT /orgs/{org_id}/module

On a Pro contract, sets which business module the organisation runs: general, horeca, wholesale, retail or freight. It can also be set at creation with module.

DELETE /orgs/{org_id}

Deactivates the organisation. Its records are kept, so a mistaken removal can be undone by ZigoTrace support. Later calls answer 410.

Templates (kinds of business): agri_exporter, horeca_distributor, fmcg_wholesaler, retailer, logistics_operator. The template decides where a lot's chain has to begin (a farm plot, or a named supplier) and which checks run. If you leave it out, ZigoTrace works it out from the data.Another partner's organisation answers 404. Its existence is not disclosed.Records in: the data contractGET /v1/schema lists every kind of record, each with its JSON Schema. GET /v1/schema/{entity} returns one. The main ones:

Entity

What it is

Identified by

receipts

Goods received from a supplier

receipt_id

dispatches

Goods delivered to a customer

dispatch_id

invoices

Purchase and sales invoices (direction: payable / receivable)

invoice_id

stock_movements

Receipts, issues, adjustments, write-offs

movement_id

shipment_legs

Transport legs, with proof of delivery

see the schema

harvests

Harvest events for producers (plot to lot)

see the schema

suppliers, farms, batches, contacts

Reference data

see the schema

POST /orgs/{org_id}/records/{entity} with {"records": [ ... ]}:

Records are upserted by their id field, so sending the same record again updates it and does not duplicate it.

A record that can't be stored is returned in rejected with its index in your array and the reason: an unknown field, a missing required value, or a value of the wrong type. The rest are stored.

At most 5,000 records per call; page anything bigger.

By default the call then checks the chain and returns findings: {open, opened, closed, coverage}. For a large first load, pass ?check=false on each page and call POST /orgs/{org_id}/check once at the end.

Large loads: background importsPOST /orgs/{org_id}/imports with {"entity": "receipts", "records": [...]} takes up to 50,000 records. It answers 202 at once with a job; the records are stored and the chain checked in the background. POST /orgs/{org_id}/check?background=true runs a check the same way.{"job_id": "job-5c1e...", "kind": "import", "status": "queued", "result": null, "error": null}

Poll GET /orgs/{org_id}/jobs/{job_id} (statuses: queued, running, succeeded, failed), or wait for the job.done event.

On success, result has the same shape a direct records call returns. On failure, error says why.

GET /orgs/{org_id}/jobs lists recent jobs. Jobs for one organisation run in order, one at a time.

The records are not kept on the job once applied; the result says what became of them.

Findings outGET /orgs/{org_id}/findings returns what is open now, most serious first. You can filter with area, gap_type, lot and blocking, and page with limit (up to 500) and offset.{ "finding_id": "dist_purchase_unbilled|lot:LOT-2026-0412|", "gap_type": "dist_purchase_unbilled", "label": "Received with no purchase invoice", "area": "receiving", "severity": 0.6, "priority": "High", "blocking": false, "node_id": "lot:LOT-2026-0412", "lot": "LOT-2026-0412", "description": "lot LOT-2026-0412 was received from a supplier but no purchase invoice references it ...", "evidence": { "...": "..." }, "fix": { "verb": "Record the supplier's invoice", "asks": "supplier", "fields": [ {"name": "invoice_no", "label": "Invoice number", "kind": "text", "required": true}, {"name": "amount", "label": "Amount", "kind": "number", "required": true}, {"name": "issue_date", "label": "Invoice date", "kind": "date", "required": true} ], "prefill": {"issue_date": "2026-09-24"} } }

Areas: traceability, receiving, inventory, deliveries, billing, loss, wastage, cold_chain, compliance, other.

fix: the form that closes the finding, with whatever is already on file filled in. Render it in your UI as it is. It is null for findings that need a specialist tool, such as a forest check.

asks: who holds the missing fact. supplier or customer means an outside party; anything else is a department, such as finance or warehouse.

GET /orgs/{org_id}/findings/summary returns totals by area, by kind and by priority. These are the numbers behind the gaps report.

ReportsGET /orgs/{org_id}/reports lists the reports for that organisation's books:

Data Quality

Stock Loss

Wastage and Shelf Life

Food Safety and Recall Readiness

Compliance

Supply Chain Gaps Summary

Each entry has its headline and metrics. Download a report with GET /orgs/{org_id}/reports/{report_id}.pdf or .docx.Workflows and the resolve planThe same step-by-step workflows the ZigoTrace app shows are available here:

GET /orgs/{org_id}/workflows/{plugin_id}: each step's status. The plugins are general, horeca, wholesale, retail and freight.

GET /orgs/{org_id}/workflows/{plugin_id}/{step_key}/resolution: the step's findings sorted by how each one can close:

batch: every value is already on file.
ask: a named outside party holds the fact.
here: someone on the customer's own team holds it.
tool: it needs a specialist tool.

POST .../resolution/ask with {"recipient": "party:SUP-NYERI"} returns a no-login answer link covering all of that party's open items. It is not emailed unless you pass "send": true and an address is known; most partners send the link through their own channels.

Fixes: proposed, never writtenPOST /orgs/{org_id}/fixes with {"finding_id": "...", "values": {...}}. Values already on file are filled in for you, and anything you send overrides them. The response (201) is a proposal:{ "proposal_id": "prop-9f2c...", "finding_id": "dist_purchase_unbilled|lot:LOT-2026-0412|", "status": "proposed", "records": [ {"entity": "invoices", "operation": "upsert", "record": {"invoice_id": "...", "direction": "payable", "amount": 5200, "batch_id": "LOT-2026-0412", "...": "..."}} ], "values": {"invoice_no": "INV-9", "amount": 5200, "issue_date": "2026-09-24"}, "source": "api" }

Status

Meaning

Moved by

proposed

Here is what to write.

ZigoTrace

acknowledged

Written in your ERP: POST /proposals/{id}/ack with an optional erp_reference.

You

confirmed

The record came back in a sync and the finding is gone.

ZigoTrace, with fix.confirmed

rejected

Not going to be written: POST /proposals/{id}/reject with a reason. The finding stays open.

You

Proposals are also made when your customer resolves a finding inside the ZigoTrace app, or when a supplier answers a link. source says which: resolve or respond. Each one reaches you as a fix.proposed event. There is at most one open proposal per finding; proposing again replaces the records on the one still waiting.GET /orgs/{org_id}/proposals?status=proposed lists proposals; GET /orgs/{org_id}/proposals/{id} gets one.WebhooksPUT /partner/webhook with {"url": "https://..."} sets the endpoint. The response includes webhook_secret the first time, or when you pass "rotate_secret": true. Store it; it is not shown again.Events are sent only while an endpoint is set; nothing is queued before you set one, or after you remove it. Whatever happened meanwhile is in GET /orgs/{id}/findings and GET /orgs/{id}/proposals.Event types:

Type

When

finding.opened

A check raised a finding for the first time, or again after it had closed.

finding.closed

A check no longer raises a finding.

fix.proposed

A proposal was made, with the exact records to write.

fix.confirmed

A proposed record came back in a sync and closed its finding.

job.done

A background import or check finished, whether it succeeded or failed.

ping

Sent by POST /partner/webhook/test.

Every event is sent in the same envelope:{"id": "evt-3a9...", "type": "fix.proposed", "created_at": "2026-09-24T09:12:03Z", "org_id": "org-...", "external_ref": "cust-42", "data": { ... }}Verifying a delivery. Each request carries Zigo-Signature: t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of "<t>.<raw body>" keyed with your webhook secret. Reject a request when the signature doesn't match, or when t is more than 5 minutes old.import hashlib, hmac, time def verify(secret: str, raw_body: bytes, header: str) -> bool: parts = dict(p.split("=", 1) for p in header.split(",")) t = int(parts["t"]) if abs(time.time() - t) > 300: return False expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, parts["v1"])const crypto = require("crypto"); function verify(secret, rawBody, header) { const parts = Object.fromEntries(header.split(",").map((p) => p.split("="))); if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false; const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.`).update(rawBody).digest("hex"); return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1)); }Delivery and retries.

Delivery is at least once, so de-duplicate on the event id.

Answer with any 2xx to accept an event. Anything else, or no answer within 10 seconds, is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours. After that the delivery is marked failed.

GET /partner/webhook/deliveries?status=failed shows the delivery log. POST /partner/webhook/deliveries/{id}/retry sends one again.

IdempotencyPOST /orgs, POST /orgs/{org_id}/records/{entity} and POST /orgs/{org_id}/fixes accept an Idempotency-Key header:

A retry with the same key and the same body returns the first answer, with Idempotent-Replay: true, instead of applying twice.

The same key with a different body answers 409.

Keys are remembered for 24 hours.

Embedding views in your appShow a customer their ZigoTrace views inside your own product, in an iframe, without them signing in to ZigoTrace.POST /orgs/{org_id}/embed-tokens:{"views": ["gaps", "reports", "resolve"], "plugin_id": "horeca", "step_key": "goods_receiving", "ttl_minutes": 60, "theme": {"primary": "#0B7A75", "name": "Acme ERP"}}It returns {"token", "url", "expires_at"}. Load the url in an iframe:<iframe src="https://agri.zigotrace.com/embed?t=eyJ..." style="width:100%;height:900px;border:0"></iframe>

View

What it shows

gaps

The gap charts: where the findings are, how serious they are, what's behind them, and a Word download.

reports

The report list with PDF downloads.

resolve

One workflow step's Resolve panel: Fix all, ask a party, one at a time, set aside. It needs plugin_id and step_key. Fixes made here are proposed to you with fix.proposed, exactly like fixes made through the API.

Scope. The token opens only the routes its views need, for this one organisation. It is not a sign-in and cannot reach anything else in ZigoTrace.

Lifetime. Tokens last ttl_minutes, which defaults to 60 and can be at most 720. Make a fresh one each time the page loads; don't store them. If the organisation is removed, its tokens stop working.

Theme. theme.primary recolours the buttons, tabs and highlights; theme.name shows as the heading. A small "Powered by ZigoTrace" line stays at the foot.

In the resolve view, findings that need a specialist tool are listed by name only, since those tools are pages of the full app.

Test organisations and the sandboxGET /samples lists a year of generated records for each kind of business: horeca_distributor, fmcg_wholesaler, retailer, logistics_operator and agri_exporter.POST /orgs/{org_id}/sample with {"template": "horeca_distributor"} loads one into a test organisation in the background. It answers 202 with a job, sets the organisation's kind of business to match, and checks the chain. The sample files are messy spreadsheets like real customers' files, read by the same sync your customers' uploads go through. Loading a sample does not count toward your usage.To build before you have a contract, ask ZigoTrace for a sandbox: a free partner key on Max, with one organisation per kind of business already loaded (external_ref sample-<template>).Client librariesGenerated from this spec and kept in step with it. Each package's version is the API version it was generated from.

Python 3.10+, standard library only: pip install zigotrace-partner

from zigotrace_partner import ZigoTracePartner, verify_webhook
zt = ZigoTracePartner("zpk_...")
org = zt.create_org({"name": "Kilimani Foods", "external_ref": "cust-42"})
zt.push_records(org["org_id"], "receipts", {"records": rows}, idempotency_key="grn-001")

TypeScript / JavaScript, using fetch (Node 20+, browsers, Deno), ES module or CommonJS, with typed request bodies: npm install @zigotrace/partner

import { ZigoTracePartner, verifyWebhook } from "@zigotrace/partner";
const zt = new ZigoTracePartner("zpk_...");
const org = await zt.createOrg({ name: "Kilimani Foods", external_ref: "cust-42" });

Both include verify_webhook / verifyWebhook. Every method returns the JSON body, or bytes for a PDF or Word file, and raises ZigoTraceError with the status and the API's explanation. Packages: zigotrace-partner on PyPI and @zigotrace/partner on npm.Your contract: plan, usage and statementGET /partner shows your terms:

The plan every one of your organisations runs on. On max, every module is open, including EUDR and Biodiversity. On pro, each organisation runs General plus the one module you set for it.

The price per active organisation per month, and any monthly minimum.

Your rate limit.

GET /partner/usage?period=YYYY-MM returns the month's statement; it defaults to the current month in UTC. For each organisation it shows records sent, checks, proposals, API calls and whether the organisation was active, then the total:The figures below are illustrative; yours are in your contract.{"period": "2026-09", "plan": "max", "currency": "USD", "price_per_org_cents": 1000, "active_orgs": 12, "subtotal_cents": 12000, "minimum_cents": 25000, "total_cents": 25000, "total": "USD 250.00", "minimum_applied": true, "orgs": [ ... ]}An organisation is active in a month when records were sent for it or its chain was checked. An organisation you created but didn't use costs nothing, and reading findings or reports alone doesn't make one active. ZigoTrace invoices you monthly from this statement.Rate limitsEach response carries X-RateLimit-Limit and X-RateLimit-Remaining. Over your limit (600 requests a minute unless your contract says otherwise), calls answer 429 with a Retry-After header in seconds. For large volumes, use one background import rather than many small calls.ErrorsErrors come back as {"detail": "..."}, written to be shown to a person.

Code

Meaning

400

The request can't be applied as sent (for example, a fix is still missing a required value).

401

The partner key is missing or invalid.

404

No such organisation for this partner, or no such entity, proposal or delivery.

409

Conflict: the finding is no longer open, the proposal has already been confirmed or rejected, or an Idempotency-Key was reused with a different body.

410

The organisation was removed.

413

More than 5,000 records in one call, or more than 50,000 in one import.

429

Over your rate limit; wait for Retry-After seconds.

422

This kind of finding has no form.

Versions

1.2.0: embedded views (POST /orgs/{org_id}/embed-tokens), sample books for test organisations (GET /samples, POST /orgs/{org_id}/sample), the generated client libraries, and operation ids that read as method names. All additive.

1.1.0: background imports and checks (job.done), usage and the monthly statement, rate limits, and a Pro module per organisation. All additive.

1.0.0: first release.