Contracting API

Test Portal

Every endpoint below is exercisable from a browser, no code required. It captures a real fingerprint from a SecuGen scanner attached to your own machine, walks it through verification, and creates a contract end to end — the fastest way to see the whole flow work before writing any integration code.

Test credentials

A shared, low-privilege credential pair for exercising this API and the Test Portal above — not a production contractor account.

X-System-Identifier: H263-TEST-1
X-Auth-Key: fc2fed9edb02e57294a89ba191db50970a20930c8ac95351

{
  "username": "test@contractor.co.zw",
  "password": "#Pass12345"
}

V000000A

Authentication

Two credentials, on every contracting request: a system credential identifying which software is calling, and a Bearer token identifying which contractor. Biometric requests carry only the system credential — there's no contractor identity involved in a fingerprint match.

1. Get a system credential from TIMB A X-System-Identifier/X-Auth-Key pair, issued to your software once during onboarding — not something you request per call. Send both headers on every request to this service, biometric or contracting.
2. Request a token With the system headers attached, POST your TBGMS username (email) and password to /auth/token. No separate credential to issue for this part — it's the same login your contractor already has on the TBGMS desktop app.
3. Attach both to every contracting call Send the system headers and Authorization: Bearer <accessToken> on every other contracting request. The token already identifies your contractor — no contractor ID is passed separately.
4. Re-authenticate on expiry Tokens expire after expiresInMinutes (60 by default). There is no refresh endpoint yet — call /auth/token again to mint a new one.

If your TBGMS account is a sub-user linked to a super-user (ContractorSuperUser), authenticate with your own sub-user credentials — the API resolves your contractor identity through the super-user chain automatically, matching how the desktop app already authorizes you.

XAF setup checklist

Before a contractor can integrate, TIMB's TBGMS administrator needs to set up the following in the desktop app. This is data entry, not code — but a contract-creation call will fail with a clear error at whichever step is missing, so it's worth doing all five before a contractor starts testing.

1. Create the Contractor record

   One row per buying company. The email must exactly match (case-insensitively) the TBGMS login the contractor's system will authenticate with.

   contractor_name email contractor_code

2. Confirm the TBGMS login is active

   The contractor's PermissionPolicyUser account must be active and not locked out. If they'll use a sub-user account instead of the contractor's own login, that sub-user's super-user link must point back to this Contractor's email.

3. Price the contractor's items

   Add a ContractorItemPricing row for every item this contractor sells — an item with no pricing row can't be added to a contract line.

   Item custom_code unit_price

4. Set up the crop's season

   Every crop needs at least one CropSeason row — the most recently created one is what a new contract is written against. No season configured means contract creation fails with 422.

5. (Optional) Build pricing templates

   If the contractor's system wants to build a contract from a reusable bundle (e.g. "standard seed pack") rather than raw pricing IDs, add a ContractorItemPricingTemplate with its item mappings. Purely a convenience — contract creation only ever needs pricing IDs.

Contracting flow, end to end

Biometric verification and contract creation are two separate APIs, each requiring a system credential — this is the sequence that ties them together, and the one most integrators ask about first.

Every request carries a system credential; contracting requests carry a second credential on top of it. /api/biometric/* authenticates with only X-System-Identifier/ X-Auth-Key — there is no user identity involved, just the device making the call. /api/contracting/* requires that same header pair plus the Bearer JWT from /auth/token, which identifies the contractor. A field agent's device and your back-office contracting system are usually different pieces of software, so TIMB typically issues them separate system credentials — ask for both.

1. Check eligibility GET /growers/{growerNumber} — confirm the grower isn't already contracted by someone else before doing anything else.
2. Enroll, if this grower has never been captured before POST /api/biometric/enroll — a one-time capture per grower. Skip this if they're already enrolled.
3. Verify the grower's fingerprint at the point of contracting POST /api/biometric/verify — returns a txnReference. Hold onto it; it's what "biometrically confirms" the contract.
4. Create the contract POST /contracts, passing that txnReference as verificationReference. A matched verification completes the contract in the same call — no separate confirm step needed.
5. (Only if verification didn't match, or wasn't available) Either pass an explicit override and written reason on that same create call to complete it anyway, or omit verificationReference entirely to create it OPEN and finalize later with POST /contracts/{id}/confirm — using a fresh verification, since each one only works once.

Endpoints

Every request/response body below is the exact JSON shape the API sends and expects — field names, types, and all.

Business rules

The same rules TBGMS's desktop contracting form enforces, applied identically here.

Error format

Every non-2xx response, from every contracting endpoint, has this exact shape:

{ "message": "Grower already contracted by another contractor" }

Hosting

Hosted at tgbms.devx.ndawana.tech, alongside the Test Portal. This document is served at the site's root as a living reference — bookmark the domain itself rather than a copy of this file.