Skip to main content

Changelog

ITS API

AfCFTA ITS API changes​

What changed in the contract an integrator builds against: the eTD API, the notification feed, the public verification and tracking routes, the reference-data reads, the signing keys, the error catalogue, and the partner contract a State Party's own systems implement. Newest first.

1.0.0 (2026-09)​

The first published version of the integrator contract.

The eTD API, version 1​
  • POST /api/v1/etd issues an electronic Transit Declaration. The request is grouped by the sections of the adopted TD form, and the serial number and commodity numbers are assigned by ITS, never sent.
  • Reads: GET /api/v1/etd/{serial_no} for the current version, or an earlier one with version or as_of; the paged list at GET /api/v1/etd with page-number, page-size and filter; the printed declaration at GET /api/v1/etd/{serial_no}/pdf; and GET /api/v1/etd/scope for the countries your credential may act for.
  • Amendment is POST /api/v1/etd/{serial_no}/versions: a whole-document new version, guarded by If-Match, with a reason and an idempotency key.
  • The lifecycle acts DEPART, EXIT, ARRIVE and DISCHARGE are stamps, at POST /api/v1/etd/{serial_no}/endorsements/{stamp_type}, by the country whose turn it is. POST /api/v1/etd/{serial_no}/cancel withdraws a declaration before any exit is stamped.
  • Supporting documents are uploaded to and downloaded from /api/v1/etd/{serial_no}/attachments.
  • Deliveries are acknowledged with POST /api/v1/etd/{serial_no}/deliveries/ack, and GET /api/v1/etd/reconciliation/digest is the backstop for anything missed.
  • GET /api/v1/notifications is the notification feed, for an organisation that reads rather than registering an endpoint to be called.
  • GET /api/public/verify/{code} answers whether a printed declaration is genuine, and GET /api/public/track/{serial_no} with the X-Party-Tin header lets the declarant or the consignee follow a consignment. Neither needs an account.
  • GET /.well-known/jwks.json publishes the public document-signing keys, retired keys included, so a declaration signed before a key rotation stays verifiable.
  • GET /api/v1/error-catalogue lists every error code the service returns, with its English message and HTTP status.
Lifecycle v5​
  • Every country performs the same three acts. The departure country registers, departs and exits; a transit country arrives, departs and exits; the destination arrives and discharges. The state machine loops once per country: REGISTERED, DEPARTED, IN_TRANSIT, ARRIVED, and the terminal DISCHARGED and CANCELLED.
  • v5 adds one step, IN_TRANSIT to DISCHARGED, which only ITS fires. It closes a transit whose destination is not on ITS once the authorised transit time has run out. That closure is recorded as SYSTEM_DESTINATION_NOT_ONBOARDED and is not evidence that the goods arrived. Attempting it yourself is BUS-ETD-085.
  • Coming from lifecycle v4: RECORD_DEPARTURE_EXIT and RECORD_ARRIVAL became DEPART, EXIT and ARRIVE, the state EXITED became DISCHARGED, and every act now fires a transition.
Retired error codes​

These numbers are never reused, so an old log holding one still means what it meant.

  • VAL-ETD-011 was an ambiguous customs stamp time. The stamp-time field is gone: ITS records when it received each stamp from its own clock.
  • VAL-ETD-031 was an unreadable list cursor. The list pages by number now, and cursor and limit are no longer read.
  • VAL-ETD-032 was more than 100 serials in one POST /api/v1/etd/batch. That endpoint is gone: filter the list with serial_no@@ instead, where more than 100 serials is VAL-ETD-034.
Partner contract v1 to v3​

The partner contract is what a State Party's systems expose for ITS to call. Its version is recorded per country, so v1, v2 and v3 peers work side by side and upgrading is one country at a time.

  • v1: GET /v1/tracking/{e_seal_id} for a cargo tracking system, and GET /v1/guarantee/{reference} for a guarantee platform.
  • v2 adds POST /v2/etd/notifications: ITS tells a national customs system that a declaration it has an interest in has a new version.
  • v3 adds two reads for cargo tracking systems, for the corridor-wide live view: POST /v3/tracking/positions for many seals at once, and GET /v3/tracking/{e_seal_id}/history for the track over a window. There is deliberately no push: ITS stores no positions, so it asks and you answer.