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.

2026-11-02 (the declaration read summarises its manifest)​

Added​
  • include=manifest on GET /api/v1/etd/{serial_no}. Under data.manifest, once the declaration is discharged: produced_at (when ITS wrote the manifest), source_version_no, discharged_at, and formats[] — code, name, media_type and file_extension for every format GET /api/v1/manifest/{serial_no}?format= accepts at that moment, the two built in and then the Secretariat's published formats by code; a format withdrawn is as absent here as it is refused there. Absent before discharge, like any include with nothing to say. Under etd:read, like the other includes; the manifest itself stays behind manifest:read on its own route. Times follow tz. VAL-ETD-059's valid set names it. Additive. Integration guide chapter 8.

2026-10-28 (exports honour the listing's narrowing)​

Changed​
  • An export is the listing it was taken from. GET /api/v1/customs-offices/export and GET /api/v1/governance/{dataset}/export take the narrowing their listings take, with the same names and the same meaning: filter, query and order-by on both, active_only on both, and maintainable_only on the customs-office register. The file holds every row the listing would answer for those parameters, in that order; page-number and page-size are not read, because a file is not a page. Before, both exports ignored every narrowing and returned the whole dataset, so a console's "what is on screen" export was not. A filter or order-by naming a column the dataset does not have is a 400, as on the listing. Additive for any caller that sends nothing: the file is still the whole dataset, now including withdrawn rows, which the export had silently dropped while the unnarrowed listing showed them; send active_only=true for only the rows that grant.

2026-10-28 (receiving endpoints: HTTPS only)​

Changed​
  • Breaking: a receiving endpoint's address must start with https://. POST /api/v1/onboarding/organisations/me/endpoints refuses a base_url that does not, http:// included, with 400 ERR-015 and a validation_errors entry on base_url reading "must start with https://: ITS calls a receiving endpoint over HTTPS only" (VAL-ETD-065 when it reaches the service). An announcement carries the signed declaration and the guarantee check carries a bearer token, so neither may cross a network in the clear. Endpoints already approved at an http:// address are not rewritten and keep receiving announcements; declaring a replacement needs an https:// address. VAL-ETD-065's message now names this reason, and its contract version is corrected to v1. The published request schema (DeclareReceivingEndpointDto) states the rule as pattern: ^https://.+ on base_url; the response still reports a stored http:// address as it is. Partner contract; integration guide §19.

2026-10-28 (cargo manifest)​

Added​
  • GET /api/v1/manifest/{serial_no}: the cargo manifest of a discharged declaration. Every DISCHARGED declaration has exactly one, produced in the same transaction as the discharge, including a transit ITS closed because the destination is not on ITS (its arrival date and time are empty). It follows the ASYCUDA AWMDS layout element for element; an element the declaration holds no value for is empty in the XML and null in JSON. format=json (the default, in the response envelope), format=asycuda-awmds (application/xml), or the code of a format the Secretariat publishes; tz for the zone of the dates and time, UTC when absent. Needs manifest:read, granted with etd:read, and opens to exactly the callers who may read the declaration. Served with an ETag; If-None-Match is answered 304. New errors: 409 BUS-ETD-134 before discharge, 400 VAL-ETD-138 for a format not served. Integration guide §8.1; eTD to Cargo Manifest Mapping 1.0.

2026-10-27 (partner contract)​

Removed​
  • Tracking is no longer part of the partner contract. GET /v1/tracking/{e_seal_id}, POST /v1/tracking/positions and GET /v1/tracking/{e_seal_id}/history are gone, with their schemas (TrackingResponse, TrackingData, TrackingBatchResponse, TrackingHistoryResponse, TrackPoint). ITS never calls a tracking path on a receiving endpoint. Nothing changes for readers: include=tracking and the public track route answer as before, from the cargo tracking system ITS's deployment is configured with, and TRACKING_UNAVAILABLE until it is connected. The guarantee check, GET /v1/guarantee/{reference}, and POST /v1/etd/notifications are unchanged. The contract also gains the 401 row ITS already applied to announcements: the token is dropped and the announcement retried with a new one, while a 403 is final. Partner contract; integration guide §13.
Changed​
  • INT-ETD-045 names no configuration key. It reads "The sign-in for a system ITS calls is not fully configured, so it could not be called. The log names the missing configuration key." It is logged, never returned; the read it belongs to answers VERIFICATION_UNAVAILABLE or TRACKING_UNAVAILABLE.

2026-10-23 (users: telephone numbers)​

Changed​
  • A telephone number is E.164 or it is refused. phone and alternative_phone on POST /api/v1/users, PUT /api/v1/users/{id} and the bulk CSV/Excel import accept only + followed by the country calling code and the national number as digits, 2–15 of them (+254700000000). A national number, a number with spaces or without its +, or a blank is a 400 on the API and a named-cell row error on the import. ITS serves a continent, and a number without its country cannot be dialled or texted from anywhere. The check is on the shape only; numbering-plan validity is the collecting client's job. Numbers stored earlier in another shape are not rewritten: they are refused the next time a client resends them, which is where the person re-enters the number; a PUT that leaves phone out keeps the stored value. Absent still means keep, so there is no way to clear a number through this API. (kairos user-management 4.5.0.)

2026-10-23 (roles)​

Changed​
  • A custom role's key is the server's to derive. POST /api/v1/authz/tenants/{tenantId}/roles no longer requires name. Left out or blank, the key is derived from display_name: accents folded, lowercased, runs of other characters a single hyphen (Regional Auditor → regional-auditor); a display name with no Latin letter or digit gets a generated role-xxxxxxxx; a derived key a built-in role or another custom role of the tenant already holds takes a numeric suffix. The created role's name is in the response and never changes. A name that is supplied is validated: ^[a-z0-9_-]+$ and not one of Keycloak's own realm roles (offline_access, uma_authorization, uma_protection, create-realm, default-roles-*) → 400; already held → 409, as before (kairos authorization SDK 4.4.0).

2026-10-22 (people)​

Added​
  • A person's e-mail address can be changed. PUT /api/v1/users/{userId}/email with {"data": {"email": "..."}} changes the address a person signs in with, for an administrator holding user:update over that person's tenant. Sign-in uses the new address from the moment the call returns; password-reset and verification mail go there. 409 DUPLICATE_USER when another person holds the address. The address is identity, not profile: it is not a field on PUT /users/{userId}. For a person whose username was their address (every onboarding contact), the username follows. The organisation onboarding records naming the person as technical contact or administrator follow in the same transaction, so a later contact reconcile or re-sent invitation still finds the same person, and the organisation is projected to the sandbox, whose own copy of the person converges to the renamed identity (kairos user-management 4.3.1). The realm does not ask the person to verify the new address at sign-in.

2026-10-22 (built-in roles)​

Changed​
  • A built-in role's permissions can be changed by an administrator. PUT /api/v1/authz/tenants/{tenantId}/roles/{roleId} with permission_ids is accepted for a built-in role (is_system_role), written through to Keycloak, and kept across restarts and the directory sync; is_editable says so on the role. system-admin is protected (is_protected): it refuses every change, deactivation and deletion with 400. A built-in role that is edited keeps its key. Deployments: the catalogue now only seeds a realm; a future catalogue grant change reaches an existing realm through one boot with AUTHZ_REALM_PROVISIONING_RECONCILE_PERMISSION_POLICIES=true, which resets every built-in role's grants to the catalogue. Live only: an edited built-in role applies to Live Core; the sandbox keeps the catalogue's grants, which is what a State Party certifies against.

2026-10-22​

Changed — breaking​
  • The permission catalogue is grouped and labelled for the role editor, and authz-permission is gone. Every permission on GET /api/v1/authz/permissions now carries a resource_category (one of Transit, Onboarding, Reference data, Reports, Administration, Audit & ledger — or Platform for the SDK's own tenant, member and sync resources, which a role editor hides) and a short resource_display_name ("Transit declarations", "Customs offices", "Roles"). The resource authz-permission and its one scope are retired, as in kairos 4.0.0: listing the catalogue is part of reading roles (authz-role:read). A role that held authz-permission:read loses nothing it could use.
  • Roles are the Secretariat's to administer too. secretariat-admin holds every authz-role scope (read, create, update, delete, activate, deactivate), as system-admin does. The platform resources stay the operator's.
Added​
  • A role says whether it may be edited. GET /api/v1/authz/tenants/{tenantId}/roles and the single-role reads carry is_editable (a custom role always; a built-in role only where this deployment allows it) and is_protected (a built-in role closed to every change, including activation and deletion). A role editor reads these rather than guessing from is_system_role.
  • GET /api/v1/authz/me/tenant answers the signed-in person's own tenant with no permission required, and 204 when they act in none. The portal resolves its tenant header from it instead of listing tenants.

2026-10-21​

Changed — breaking​
  • The consortium ledger anchors ITS's records; it no longer delivers announcements or records country attestations. ITS anchors its records on the AfCFTA consortium ledger as before, and a State Party's peer holds, endorses and verifies those anchors. The LEDGER delivery channel (the party-inbox private inbox, the on-chain acknowledgement, the receive probe and the member relay that read the inbox) and country attestations (ITS-ACT/1) are removed, not switched off. Every announcement now goes over HTTPS to the country's approved receiving endpoint, and every act is submitted over REST and validated by ITS, as before. A country that was on LEDGER is on REST. Decision record docs/decisions/ledger-delivery-removed.md.
  • One announcement body, ETD_DOCUMENT_V1. POST /v1/etd/notifications receives the signed document only: the fields that name the version, attestation and document. The signed notice, ETD_SIGNED_NOTICE_V1 (schema EtdSignedNotice), is retired, and the partner contract's request body is EtdDocumentAnnouncement alone. The contract version stays v1. A version no other country is concerned by is still recorded, by reference, with no recipients. On the dev deployment only, an announcement enrolled as the signed notice before this change is still delivered over HTTPS with that body; the contract already told receivers to accept it. Partner contract; integration guide §12.
  • The delivery-channel endpoints are removed. Partner: GET /api/v1/onboarding/organisations/me/delivery-channels, POST /api/v1/onboarding/organisations/me/delivery-channels and POST /api/v1/onboarding/organisations/me/delivery-channels/{channelId}/probe. Secretariat: GET /api/v1/onboarding/delivery-channels, GET /api/v1/onboarding/organisations/{organisationId}/delivery-channels, and POST /api/v1/onboarding/delivery-channels/{channelId}/approve, /reapprove, /withdraw and /probe. A receiving endpoint is still declared with POST /api/v1/onboarding/organisations/me/endpoints and approved by the Secretariat.
  • Fields removed from responses. ?include=deliveries rows lose channel, receipt_tx_id and ledger_key. ?include=integrity loses country_attestation. GET /api/public/verify/{code} loses country_attestations. GET /api/v1/ledger/consortium members lose attestations. GET /api/v1/ledger/status loses delivery_enabled, inbox_enabled and sender_id; its anchoring and broadcast fields are unchanged.
  • Consortium members are named by MSP id. GET /api/v1/ledger/consortium named a member from the LEDGER channel in force for it. With no channels, the Secretariat is named and every other member is shown by its MSP id (KEMSP), until a member's MSP id is recorded on its organisation record.
  • Notice integration.delivery-channel-changed is retired. It is no longer raised. Notices already in a feed keep their text until they expire.
  • During the deploy that brings this change, an act can fail and must be resent. While the rolling update replaces the old instances (a few minutes), an act served by an old instance whose announcement has a recipient is refused and rolled back whole; resending it after the deploy succeeds.
Retired error codes​

These numbers are never reused. BUS-ETD-126 (ARRANGEMENT_ALREADY_RECORDED), which sits among them, stays.

  • BUS-ETD-112 (LEDGER_DELIVERY_DISABLED), BUS-ETD-113 (LEDGER_NOT_MEMBER), BUS-ETD-114 (LEDGER_PROBE_REQUIRED), BUS-ETD-115 (CHANNEL_REQUIRES_HTTP_ENDPOINT), BUS-ETD-116 (CHANNEL_NOT_APPROVABLE), BUS-ETD-118 (CHANNEL_DELEGATION_INVALID) and BUS-ETD-122 (LEDGER_PROBE_NOT_APPLICABLE): delivery-channel approval and probing.
  • VAL-ETD-117 (INVALID_MSP_ID) and VAL-ETD-120 (DELIVERY_CHANNEL_FILTER_UNSUPPORTED): a declared channel's MSP id and the channel listing's filter.
  • RES-ETD-119 (DELIVERY_CHANNEL_NOT_FOUND): no such delivery channel.
  • CFG-ETD-121 (LEDGER_DELIVERY_MISCONFIGURED): ledger delivery switched on but not configured.
  • INT-ETD-123 (LEDGER_PROBE_UNDELIVERED): the receive probe could not be delivered.
  • INT-ETD-124 (ATTESTATION_MISMATCH) and INT-ETD-125 (ATTESTATION_NOT_PROVEN): a country attestation that did not match or was not proved.
  • SYS-ETD-127 (LEDGER_DELIVERY_RECORD_UNREADABLE): ITS could not read its record of an earlier attestation request's delivery.

2026-10-20​

Changed — breaking​
  • The exporter's TIN is required. POST /api/v1/etd without general_information.exporter_consignor.tin, or with it blank, is refused with 400 ERR-015 naming that field in validation_errors, exactly as a missing name or address is; an amendment (POST /api/v1/etd/{serial_no}/versions) that changes section A meets the same rule, and one that leaves section A alone does not. ITS is the country-of-origin model: the declaration is lodged by the administration of the country the goods leave, about a consignment somebody there is sending, and that administration has already identified its own exporter. The number is still recorded as sent, with no format check and no country attribution. The importer's TIN (box 4) and the transporter's (box 5) stay optional. In the published OpenAPI document box 3 is now its own schema, EtdExporterDto, with tin among its required properties; boxes 4 and 5 keep EtdPartyDto. Declarations issued before this change read back unchanged, their box 3 TIN absent where it was never sent. Integration guide table 6.1 rows 8 and 9.
Changed​
  • An older version's print names its own state beside today's. GET /api/v1/etd/{serial_no}/versions/{version_no}/pdf (and the current route with as_of) prints the declaration's current state in the header's STATUS cell and as the diagonal mark, as before, so an old version of a cancelled or discharged declaration never prints clean. It did not say that the status was today's rather than the version's. When the printed version's own signed state differs, the STATUS cell now carries a second line, At version 1: Registered in form, with the state that version was signed with, in the caption language. A current print, and an older version whose state is unchanged, print exactly as before. The ETag changes for the prints that gain the line. Integration guide §13.1; TDD Table 5.4 rows 1 and 18.

2026-10-18​

Changed​
  • lang is read against the registered locales. GET /api/v1/etd/{serial_no}/pdf (and the version and public tracking routes) printed the whole TD in English for lang=fr or lang=ar, because only fr-SN and ar-SA are registered. A tag now prints in the locale registered for it: the same code in any case, else the registered locale of the same language, so fr, fr-CA and fr-SN all print French captions. A language nobody has registered still prints the adopted English. Integration guide §11 point 5.
  • The printed TD keeps every box's value inside its box, and an English TD groups numbers in thousands. GET /api/v1/etd/{serial_no}/pdf (and the version and public tracking routes) used to let a value with no space in it that was wider than its box run on into the next one: a 17-character container number (box 08) into box 09, and totals at their widest (boxes 09–11) into each other. Every boxed value now wraps inside its own box, as table D's cells already did; nothing is cut and no hyphen is added. On a TD printed in English, quantities and amounts are grouped in thousands with commas — 6,152,093,847,261.58 — in boxes 06, 07, 09–11, table D's packages, weights and values, the guarantee amount and the fees; the decimal point and the declared decimal places are unchanged, and commodity line numbers are not grouped. Every other language prints the digits ungrouped, as before, because a comma is the decimal mark in French, Portuguese and Spanish. The JSON is unchanged. Leaflet I's one-page rule gains one case: in Spanish, a declaration with every field but the declarant's own text at its limit, a 150-character first commodity line and further lines on item sheets now runs onto a second page as well. Integration guide §11.
  • Box 14 prints the number of attached documents, not their kinds. It listed each attached document's kind under the count, with no bound, so a declaration with many kinds could push leaflet I onto a second page. It now prints the count alone, or NONE. Read the documents with GET /api/v1/etd/{serial_no}/attachments or in the portal. Integration guide §11.

2026-10-16​

Changed — breaking​
  • A customs office your country has closed is now refused. An office of your own country that the customs-office register records as closed (withdrawn, or past its effective_to date) is refused with 400 VAL-ETD-136 when it is box 1's departure office, the departure stamp's station, or the station of any lifecycle stamp; the detail names the office and the date it closed. It used to be accepted and reported like an office the register does not list. An office the register does not list at all is still accepted and reported in header.additional_details, and offices of other countries are unchanged (VAL-ETD-004). If an office was closed by mistake, reopen it in your customs-office register. Integration guide, the own-station rule and Appendix A.
  • A party's address is at most 150 characters, and the declarant's own declaration at most 250. general_information.exporter_consignor.address, .importer_consignee.address and .shipper_transporter.address had no limit; they now take what name takes, 150. And declarant.declaration_text takes 250. Both are printed whole on leaflet I of the TD, which must stay one page in every language; these are the lengths it was measured to hold. A longer value is a 400 validation error on that field (size must be between 0 and 150, or 250), at issuance, and on an amendment only when it changes the section holding the field — A for the addresses, E for the declaration — as for every intake limit. A declaration stored before today with a longer address or declaration is unaffected: it can still be amended in any other section, and it still prints. Integration guide §6 (field table).
Changed​
  • The printed TD keeps leaflet I to one page and prints the commodity lines it cannot hold on item sheets. GET /api/v1/etd/{serial_no}/pdf (and the version route) no longer lets leaflet I run onto further pages, where they had no header band and boxes were cut across the break, for any declaration within the intake limits but one: with every party's name and address, the declaration and the other boxes all at their limits and a first commodity line at its 150-character printed limit, leaflet I keeps that one line and runs onto a second page. Leaflet I carries as many commodity lines as its page holds; an ordinary declaration prints as before, two pages. The lines past that are printed on item sheets after leaflet I, five to a sheet as a rule, each one page with the header band and "item sheet n of m"; leaflet I's table then says which lines are on them. A customs office's name prints to its first 60 characters. leaflet=I returns leaflet I and any item sheets; leaflet=II is unchanged. Same route, same parameters. Integration guide §11.

2026-10-15​

Added​
  • A failed transmission names the kind of organisation that sent it. Each row of GET /api/v1/etd/rejections adds external_type (state_party, rec or secretariat) and external_id (a State Party's ISO alpha-2 code, a REC's acronym such as EAC), the same fields and values the organisation register serves. A REC's refusals, which carry no country_code, can now be shown as that REC. Both are null when no organisation was resolved. Integration guide "What we refused, and why".

  • An entry ITS did not expect is reported: notice etd.unexpected-entry. An entry stamp is still never refused, and it still answers 200. An entry is expected when the entering country is the next_country_code on the latest departure or transit stamp that names one, or is the declaration's current destination; where partial onboarding is switched on (its.onboarding-aware.enabled=true; off by default), an entry following a named next country that is not connected is also expected. Any other entry raises one ATTENTION notice to the country that was holding the goods (or, when nobody held them, the country whose transit released them) and to the departure country; never to the entering country. At a one-stop border post, an entry made while another country still holds is judged when that country's part of the journey ends — its transit (text keys its.notifications.key.etd.unexpected-entry.at-transit.*), or its discharge or the declaration's cancellation (….at-journey-end.*) — or at once if that holder is the destination or was itself an unexpected entrant. Params: serial, enteringCountry, enteringCountryName, expectedCountries, expectedCountryNames, holderCountry, holderCountryName, departureCountry. One notice per entry stamp; a country re-entering later is a new one. The AfCFTA Secretariat receives these entries in a digest.

  • A closed declaration refuses new attachments. POST /api/v1/etd/{serial_no}/attachments on a declaration that is DISCHARGED or CANCELLED is now refused with 409 BUS-ETD-009, the code every other act gets on a closed declaration; it used to be accepted and appended an ATTACHMENT version to a finished transit. Nothing of the refused request is recorded. Integration guide §10a and §12.

Changed — breaking​
  • Amending a declaration requires an Idempotency-Key, as TDD 10.6 says of every write path. POST /api/v1/etd/{serial_no}/versions without the header is refused with 400 VAL-ETD-130; it used to be accepted. Send a value of your choosing, at most 64 characters (400 VAL-ETD-131 beyond that), unique to the amendment. Nothing else changes: the same key and the same body still answer 201 with the version the first request created, and the same key with a different body is still 409 BUS-ETD-025. Integration guide §4.5 and §9.
  • An amendment is checked against the same reference data as issuance. An amendment carrying an unknown country (vehicle nationality, country of origin, exporting country, an office's country), currency, package kind or terms of payment is now refused 400 VAL-ETD-003, as issuance already refuses it; before, only HS codes and transport modes were re-checked. The check covers what the amendment changes (the sections it touches), HS codes and transport modes included: a code withdrawn since issuance in a section you leave unchanged does not block the amendment. Nothing is written on a refusal. Integration guide §8 and §10.
  • Attach answers 201 Created. POST …/attachments now answers 201 Created, as documented; it answered 200.
  • An unknown nationality on a stamp or departure vehicle is now refused. The nationality of the vehicle on a lifecycle stamp and of departure_formalities.vehicle at issuance is checked against the country register, as it already is on boxes 15 and 17: an unknown country answers 400 VAL-ETD-003, the same code as an unknown country anywhere else. Integration guide, "Recording a change of vehicle".
  • A malformed as_of has its own error code. GET /api/v1/etd/{serial_no} (and the PDF read) now answers 400 VAL-ETD-134 when as_of is not an ISO-8601 instant with an offset, or when as_of is sent together with version; it used to answer VAL-ETD-011, whose text described a stamp-time rule that no longer exists. VAL-ETD-011 is retired and never reused. Integration guide Appendix A.
  • Exit is now transit, everywhere the lifecycle speaks. POST /api/v1/etd/{serial_no}/endorsements/exit is removed; record a transit with POST …/endorsements/transit (same body, same Idempotency-Key rule; /exit now answers 400 VAL-ETD-064 like any unknown act). Stamp types TRANSIT_ENTRY and EXIT are now ENTRY and TRANSIT; the state IN_TRANSIT is TRANSITED and the operation EXIT is TRANSIT, on every read, list row, lifecycle result and corridor stop. The list filter takes state@@TRANSITED; IN_TRANSIT is refused 400 VAL-ETD-034. The sandbox milestone EXIT_ETD is TRANSIT_ETD. The etd.endorsed notice's params.act says transit. Ledger: new ITS-ACT/1 attestations carry act_kind ENTRY or TRANSIT (information model v1.4). Versions signed before this change keep the words they were signed with, byte for byte, and still verify; their attestations keep TRANSIT_ENTRY/EXIT. Reworded: VAL-ETD-034, BUS-ETD-063, VAL-ETD-064 (codes unchanged). Integration guide §4–§10 and Appendix A.
Changed​
  • The OpenAPI document now declares Idempotency-Key where ITS requires it, and gives every eTD operation an operationId. The header is required on issue, stamp, cancel and acknowledgement (cancel and acknowledgement answer VAL-IDEM-001 without it, as before) and optional on amendment; nothing about how ITS answers has changed. Ids are stable, for example issueEtd, endorseEtd, amendEtd, cancelEtd, acknowledgeEtdDelivery.
  • Notices stored before a correction now read as new ones do. After each deploy, ITS brings the eTD notices it stored earlier into line with what it writes today. Each notice keeps its sequence_no, notice_key, time and read state, so nothing is announced twice and no feed reorders. Three corrections are carried back:
    • A country no longer holds notices of its own acts. Before 29 September 2026 the acting country was in the audience of its own stamp, lodging and state change. Those notices leave its feed; every other country keeps them.
    • An old stamp names its act. A stamp's notice stored before 29 September carried no params.act and read "recorded a customs act". It now carries the act its endorsement records (entry, release, transit, discharge) and that act's sentence. Where the declaration is no longer in the database, the notice stays generic until it expires.
    • params.act exit is transit on the transit notices stored before today's rename.
Added​
  • A person can mute a notification category. The portal's notification settings call GET/PUT /api/v1/notifications/preferences. A muted category's INFO notices leave that person's unread count, unread listing, latest and stream. ATTENTION and CRITICAL are never muted, and every notice stays in the full listing. This is a setting for people at a screen, so the path is not in the integrator document and has no partner route. Your listing and your since_sequence catch-up are unchanged. New code VAL-ETD-135 (400) refuses a set of muted categories that cannot be saved (more than 50, or one that is blank or longer than 40 characters), and nothing is changed.

2026-10-14​

Changed — breaking​
  • The partner contract is one version, v1. Everything a State Party's systems implement for ITS is now v1: the single-seal tracking read, the batch read (POST /v1/tracking/positions), the position history (GET /v1/tracking/{e_seal_id}/history), the guarantee check and the announcement (POST /v1/etd/notifications). Versions v2, v3 and v4 no longer exist, and ITS calls every path under {base_url}/v1/. The version stays the first path segment, so a future breaking change can be published beside v1 rather than in place of it. Partner contract; integration guide §4, §12 and §13.

  • A receiving endpoint is declared at v1 only. contract_version must be v1; omitted or blank means v1. Any other value, v2, v3 and v4 included, is refused at declaration with 400 (VAL-ETD-065 when it reaches the service). A REC that receives for a member declares the member at v1. Integration guide §4.

  • An announcement is always signed, and its shape follows the delivery channel alone. Over HTTPS it is the signed document, ETD_DOCUMENT_V1: the fields that name the version, attestation, and document, so your system verifies it without a read. Over the ledger it is the signed notice, ETD_SIGNED_NOTICE_V1: the same fields and attestation, without document; your system reads the declaration back and verifies it. Accept both bodies on /v1/etd/notifications, since a change of channel can put either on either route, and accept bodies of a few megabytes. The contract version no longer chooses the shape. Integration guide §12.

  • The pointer is retired. ETD_VERSION_NOTIFICATION_V1 (schema EtdVersionNotification), the announcement that said a version exists and left your system to read it, is no longer sent to anyone. If your system handles only the pointer, implement the signed document or the signed notice for the channel you are on. On the ledger, your inbox entries keep the envelope kind ETD_VERSION_NOTIFICATION; what they carry is the signed notice.

  • Every connected country concerned by a declaration is told. No country is left out of announcements because of the contract version it declared. A version nobody else is concerned by still has its signed notice recorded.

Unreleased​

Changed — breaking​
  • A stamp resent under its Idempotency-Key is answered with its first answer, for as long as the declaration exists; and a country cannot enter twice. POST /api/v1/etd/{serial_no}/endorsements/{act} still requires the header, but ITS now keeps the key with the version the stamp appended instead of in a cache that forgot it after 7 days. A resend with the same key and the same act and body answers 200 with the same version_no, content_hash, current_state and operation the first attempt received, records nothing, and is answered so even after the declaration has moved on or closed. Codes change: no key is 400 VAL-ETD-130 (was VAL-IDEM-001), a key longer than 64 characters is 400 VAL-ETD-131, and the same key on the same declaration with a different act or body is 409 BUS-ETD-025 (was 422 VAL-IDEM-003). A key is used once per declaration, whichever act it came with. Two identical requests at once both receive the one answer; 409 BUS-IDEM-002 is no longer returned for a stamp. A refused stamp keeps no key, so a corrected request may be resent with the same key. Remarks in header.additional_details are given on the first answer only. New: an entry by a country that has entered and not exited since is refused with 409 BUS-ETD-133; until now a second entry was recorded, and one sent after the country's own exit put the goods back in that country and blocked the next country's release. Re-entry after the country's own exit is accepted as before. Cancel and acknowledgement are unchanged. Integration guide §4.5 and §10.

  • Issuing a declaration requires an Idempotency-Key, and a resend no longer lodges a second declaration. POST /api/v1/etd without the header is refused with 400 VAL-ETD-130; it used to be accepted, and the header was ignored when sent. Send a value of your choosing, at most 64 characters (400 VAL-ETD-131 beyond that), unique to the declaration. If the response is lost, send the same request again with the same key: ITS answers 201 with the declaration the first request issued, as first issued, and lodges nothing more. Until now a resend created a second declaration under a second serial number, and the advice was to search the list first; that advice is withdrawn. The same key with a different declaration is 409 BUS-ETD-025. Two identical requests at the same instant: one issues, the other gets 409 BUS-ETD-132 and its resend receives the declaration. ITS keeps the key with the declaration for as long as the declaration exists, and a key belongs to your organisation, so it cannot collide with another caller's. "The same declaration" is judged on content: member order and whitespace may differ between attempts. A request that was refused left no key behind, so correct it and resend with the same key. Integration guide §4.5.

  • GET /api/v1/etd/statistics answers one number. This is the Portal's read (it is not in the integrator contract). It returned eight counts; it now returns overdue_transits and overdue_transits_capped. active_transits, registered_today, arrived_awaiting_release, held_by_me, discharged_today, cancelled_today and by_state are gone: no screen showed them, and producing them read every declaration the caller could see on every poll. Totals by state and by day are in the reports. overdue_transits now stops at 10,000 and says so with overdue_transits_capped: true. It is answered from an index in a few milliseconds where it took seconds at continental volume.

  • You state the mode of transport; ITS no longer assumes road. transport_mode is now required on every means of transport you send: means_of_transport.at_departure, means_of_transport.crossing_border when you declare it, and the vehicle on a stamp when an office records one. Omit it and the call is refused with ERR-015 on that field; there is no default. It was response-only and always 3. Send one of the five modes in force — 1 maritime, 2 rail, 3 road, 4 air, 8 inland water — which is what GET /api/reference/transport-modes/active returns. 5, 6, 7 and 9 are refused with VAL-ETD-003. Never send 6 (multimodal): state each means of transport's own mode and let them differ; ITS reports the declaration as multimodal when they do. The two boxes need not agree, and a stamp's mode need not match the declared one. The same rule applies to an amendment of section B. plate_registration_no keeps its name and holds what identifies the means of transport for its mode: a plate, a wagon number, a vessel's or an aircraft's registration. Integration guide §2, "Transport modes".

Added​
  • The notification stream sends a heartbeat. GET /api/v1/notifications/stream now sends an event named heartbeat every 20 seconds, carrying {"at": …, "interval_seconds": 20}, so a client can tell a quiet feed from a dead connection. A notification is still an unnamed event and its payload is unchanged. If you read the stream with your own parser, skip any frame that has an event: line; a browser's EventSource already ignores it. The listing and since_sequence are unaffected.

  • Customs offices have a position: latitude and longitude. Both are on every row of GET /api/reference/customs-offices and of the register (/api/v1/customs-offices): decimal degrees, WGS 84, south and west negative, at most six decimal places. They are optional and travel together. Absent means nobody has said where the office is; it is never 0,0. ITS seeded a starting position for 2,626 of the 3,189 offices from UN/LOCODE and GeoNames. A seeded point is the town's, good to about two kilometres, not a survey of the post; 41 of the 123 frontier posts have none yet. The administration that operates an office corrects its position through the register, by single edit or by upload: the workbook has Latitude and Longitude columns, and an export carries them.

  • Half a position is refused with 400 VAL-ETD-129; a latitude outside ±90, a longitude outside ±180, or more than six decimal places is refused with 400 ERR-015 on the field.

  • Position data: contains data from GeoNames, licensed under CC BY 4.0, and from UN/LOCODE (UNECE).

  • transport_mode_name beside every transport_mode. The mode in words (Rail transport), resolved by ITS and read-only, on both means of transport and on a stamp's vehicle. The printed TD shows it inside boxes 15 and 17 under MODE OF TRANSPORT, with the identity under PLATE NO, and in the TRANSIT RECORD strip. Versions signed before this change carry the code alone.

  • Partner contract v4: the announcement can carry the signed document. Declare your receiving endpoint at contract_version v4 and each announcement is ETD_DOCUMENT_V1 instead of the pointer: the same nine fields, then attestation (signature_status, key_id, signed_at, signature) and document, the version's canonical content exactly as ITS signed and stores it and as GET /api/v1/etd/{serial_no}?version= serves it. Verify it without calling ITS: canonicalise document (RFC 8785), check its SHA-256 is content_hash, and verify the detached JWS in attestation.signature over those bytes with the key key_id names in GET /.well-known/jwks.json. ITS POSTs it to {base_url}/v4/etd/notifications. v2 and v3 are unchanged and remain the default (v2 when you name none); each country receives exactly one shape. v4 over the ledger receives the notice, ETD_SIGNED_NOTICE_V1 (the same fields and attestation, no document): a document never goes on chain, so the full document travels only to HTTPS endpoints. Accept both v4 bodies. A REC that receives for a member declares the member's version, and the member is announced in that shape. Bodies grow with the commodity lines — about 3 KiB for one line and about 280 bytes per further line — so accept request bodies of a few megabytes on this path. Partner contract, /etd/notifications; integration guide §4 and §12.

  • Notice integration.incident: refused calls in the feed within about two minutes. One notice per route, error code and UTC day, rewritten in place as more refusals arrive (same dedupe_key, new sequence_no, unread again, latest count in params.refused). CRITICAL when it can hold up cargo, ATTENTION for lookups. The AfCFTA Secretariat receives every CRITICAL incident too, naming the organisation. action_ref carries the Failed transmissions filter. Notifications guide, "What arrives".

  • Failed transmissions: cursor paging, a summary to poll, and which declaration was refused. GET /api/v1/etd/rejections pages by limit and cursor (the previous response's next_cursor); the page-number form still works. New filters serial_no, error_code, route and outcome (lookup, its_error). Each row adds path_params (serial_no, stamp_type, version_no, attachment_id where the route had them), resolved_path, urgency (CRITICAL / ATTENTION), organisation_name and origin (system / console). New GET /api/v1/etd/rejections/summary: latest_received_at, new_since after a since watermark, and a total with include_total=true, both counted to 10,000. Integration guide "What we refused, and why".

  • POST /api/v1/notifications/read: mark several notifications read in one call. Send {"sequence_nos": [...]} with 1 to 500 sequence numbers; the answer is your counts, as marking one returns. A number you may not see, or that no longer exists, is skipped rather than refused, and one already read is not an error. A console marking what it has shown makes one call instead of one per notice.

  • Transit rules, set by the AfCFTA Secretariat. A new governance dataset, /api/v1/governance/transit-rule, with three continental rules: OVERDUE_GRACE_DAYS (0–30, unset 0), MAX_TRANSIT_DAYS (1–365, unset 365) and BACKDATE_DAYS (0–30, unset 0). Rows carry setting_key and setting_value. Integration guide §7, "Transit rules the Secretariat sets".

  • GET /api/v1/transit-rules: read the transit rules before you send. The three in force today and every change scheduled, under transit-rule:read, which every role holds, on the partner host and in the integrator contract. Strong ETag, 304, a 30-second Cache-Control.

  • Notice governance.transit-rule-changed, to every State Party's and REC's administrators, once per change; ATTENTION when the rule tightens.

  • Secretariat only: POST /api/v1/governance/transit-rule/impact. For the maximum duration and back-dating, how many declarations in the last 30 days (at most 90) the proposed rule would refuse, by submitter and country; for the overdue grace, how many open transits are overdue now and would be with it.

  • Secretariat only: operations settings. /api/v1/governance/operations-setting holds INVITATION_LIFESPAN_DAYS (1–30, unset 7), HEALTH_FAILURE_THRESHOLD (1–100, unset 3) and HEALTH_WINDOW_DAYS (1–30, unset 7); GET /api/v1/operations-settings reads them for the Secretariat's and organisation administrators (operations-setting:read), not in the integrator contract. A change is told to the Secretariat (governance.operations-setting-changed).

  • Intake limits, set by the AfCFTA Secretariat. A new governance dataset, /api/v1/governance/intake-limit, caps how many commodity lines one declaration may carry, each money box, each line's weights, and the computed weight totals (boxes 9 and 10). The caps are continental and change at runtime; until one is set the hard ceiling applies, which is what was accepted before (9999 lines, 9999999999999.99 for money, 99999999999.999 kg for weights). A breach is 400 ERR-015 on issuance and on amendment, with every breach listed in validation_errors under its own field (commodities, commodities[3].commodity_value, general_information.total_gross_weight_kg, …) and a message stating the cap. Integration guide §7.

  • GET /api/v1/intake-limits: read the intake limits before you send. Every cap in force today and every change already scheduled, with its ceiling, whether the Secretariat set it or the system ceiling applies, and its dates. Integrator contract, on the partner host, under the new permission intake-limit:read, which every role holds, partner-system included. A strong ETag and a 30-second Cache-Control, so poll with If-None-Match. On Sandbox it serves the values mirrored from Production. Integration guide §7, "Reading the limits before you send".

  • Notice governance.intake-limit-changed. When the Secretariat schedules or changes an intake limit, every State Party's and every REC's administrators are told in the notification feed: which limit, the old and new value, and from which day. One notice per change. Severity ATTENTION when the cap is lowered, INFO when it is raised. No e-mail.

  • Secretariat only: POST /api/v1/governance/intake-limit/impact. Before saving a cap, shows how many declarations issued or amended in the last 30 days (at most 90) would breach it, with one row per submitter and country, so a REC acting for a member is listed apart from that member. A declaration counts against whoever sent its current version: the latest amendment's sender, or the issuer. Not in the integrator contract.

  • Who changed a governance row, and when. Every row of every /api/v1/governance/{dataset} dataset now carries created_by and created_at (who recorded it, and when) and updated_by and updated_at (who last corrected, activated or deactivated it). The actor is the Keycloak username; the times are UTC instants. Read-only: ignored on create and update. filter and order-by on the dataset listing accept the same four names.

  • Browsers can revalidate. Cross-origin requests may send If-None-Match, and responses expose ETag, so a browser page can make a conditional read of GET /api/v1/intake-limits or the TD PDF and get 304 Not Modified.

  • filter=current_holder and filter=station on GET /api/v1/etd. current_holder::KE lists the declarations Kenya holds now — the country whose entry is the earliest still open, the same current_holder the corridor reports; a declaration nobody holds matches no value. station::KEMBA lists the declarations any of whose stamps was cut at that customs office, written as its country then its office code. Both take :: and @@, and both narrow your own scope without widening it. A malformed office is 400 VAL-ETD-034. Integration guide §11, "The filter grammar".

Changed​
  • ITS keeps the token your sign-in server issues, and asks again only when it must. This is about the calls ITS makes to your systems (announcements, guarantee checks, tracking reads) when your endpoint is registered with OIDC_CLIENT_CREDENTIALS. ITS used to request a new token from your token endpoint before every one of those calls. It now requests one, presents it until 30 seconds before the expires_in you stated, and then requests the next; a response with no expires_in is treated as good for 60 seconds. Your token endpoint will see far fewer requests. If your endpoint answers 401, ITS drops the token and signs in again on its next call to you. For an announcement that means the delivery is retried with a new token; it used to be recorded as refused for good. State the lifetime you mean in expires_in, and answer 401, not 403, for a token you no longer accept.

  • An entry stamp on a cancelled declaration is refused. POST /api/v1/etd/{serial_no}/endorsements/entry on a declaration that is CANCELLED or DISCHARGED answers 409 BUS-ETD-009 and records nothing. A discharged declaration already answered so. A cancelled one did not: an entry by any country other than the one that filed it was accepted with 200 and transition_fired: false, and a stamp and a signed version were added to a declaration that was finished. If your system received such a 200, the stamp it recorded is on a cancelled declaration and moved nothing.

  • A declaration outside your scope is answered as a serial number never issued, on every route. This was already so for reads. It is now so for an amendment (POST /api/v1/etd/{serial_no}/versions), a release, an exit and a discharge (.../endorsements/depart, /exit, /discharge), a cancellation (.../cancel) and a delivery acknowledgement (.../deliveries/ack): a caller who may not read the declaration receives 404 RES-ETD-001, where it used to receive 403 AUTHZ-ETD-008, 409 BUS-ETD-009, 409 BUS-ETD-063, 412 BUS-ETD-019 or 404 RES-ETD-030 with details of a declaration it could not see. The text beside RES-ETD-001 is also the same in both cases now. Nothing changes for a caller acting on a declaration it can read, and an entry stamp is unaffected. Two refusals that do not depend on the declaration are now given before it is looked up, so they no longer differ by serial number: an unknown stamp kind (400 VAL-ETD-064) and a request with no data.

  • An error message in a language not yet translated now carries the same wording an English request reads. Error text is looked up in the language you ask for (X-Locale, then Accept-Language), then in the default locale en-US, then in the text ITS ships with. The middle step is new. Where the Secretariat has corrected an error's English wording and your language has no translation of it yet, you used to receive the older shipped English; you now receive the corrected wording, as an English request always has. Codes, status codes and the envelope are unchanged. Match on the code, never on the message.

  • The printed Transit Document is reproducible, archival, and has a strong ETag. GET /api/v1/etd/{serial_no}/pdf and /versions/{n}/pdf now return PDF/A-2b, and the same request returns the same bytes: the PDF's internal dates are the version's recorded time, not the clock. The ETag is no longer W/"<content-hash>.<render-revision>.<leaflet>.<language>". It is a strong, opaque hash of everything that decides the bytes, the declaration's current state included. Two things follow. A validator you stored before this change no longer matches, so your next conditional request returns 200 once. And an older version reprinted after the declaration's state changed (cancelled, departed) is now a different file with a different ETag, where it used to answer 304 and leave a stale leaflet in your cache. Keep sending it as If-None-Match; do not parse it, and never send it as If-Match. Integration guide §11, "Printing the document".

  • Downloads name their file the same way everywhere. The register and arrangement exports (/customs-offices/export, /customs-offices/template, the REC arrangements export) now send Content-Disposition with both filename="..." and filename*=UTF-8''..., as the Transit Document and attachment downloads already did.

  • A receiving endpoint's contract_version must be v2, v3 or v4. Anything else, v1 included, is refused at declaration with 400 (VAL-ETD-065 when it reaches the service): v1 is never notified, and an unknown version would resolve and then fail on every announcement. Omitted still means v2. VAL-ETD-065's message now names every reason it is raised for. Integration guide §4.

  • Breaking: the transit guarantee is required. Boxes 20–23 — guarantee.reference_no, amount, currency and date — must all be sent, as your customs guarantee system issued them (TDD v3 §5.1). A missing box is 400 ERR-015 on its own field, every one at once; this applies at issuance and to an amendment, which sends the whole declaration. Before, the block could be {}, and a reference without an amount and currency was VAL-ETD-005.

  • GET /api/v1/etd counts its total to 10,000 and no further. pagination.total_capped is true when there are more: total_records is then 10000 and means "10,000 or more", and total_pages is what 10,000 rows make. Below the cap the total is exact and total_capped is false, as before. Pages past a capped total_pages are served as usual, so walk until data is empty. An exact total read every declaration the caller may see on every request. Integration guide, "Finding declarations".

  • A transit may be authorised for at most 365 days, unless the Secretariat sets a shorter maximum. Before, there was no maximum. 400 BUS-ETD-006.

  • Amendments now check the transit dates when they change section G: an end before the start, a start back-dated beyond the allowance, or a duration above the maximum is 400 BUS-ETD-006, as at issuance. Before, an amendment could set any dates.

  • "Today" for a transit start is the UTC day by ITS's database clock, not the server's.

  • overdue, overdue_transits and reporting punctuality follow the overdue grace: a transit ending on day E is overdue from day E + grace + 1 (unset, as before, E + 1).

  • Money and weights may not be negative. total_declared_value, commodity_value, guarantee.amount, declarant.fees, gross_weight_kg and net_weight_kg refuse a negative value with 400 ERR-015 on the field; zero is accepted. The published schema states minimum: 0 on the money fields. Integration guide §7.

  • Breaking, at 10,000 commodity lines. A declaration with more than 9,999 lines is now refused on commodities, where the old door accepted any number.

  • Money boxes take at most 13 integer digits. general_information.total_declared_value, commodities[].commodity_value, guarantee.amount and declarant.fees accept up to 9999999999999.99: 13 integer digits and 2 decimal places, 15 significant digits in all. That is the widest number the signed document carries exactly (§14). The limit itself is not new, only where it is enforced: a value of 14 to 16 integer digits used to pass validation and was then refused by the signer with 400 VAL-ETD-027, which named no field. It is now refused at the door with 400 ERR-015 and a validation_errors entry on the field that is too wide. The published schema states the bound as maximum on each of the four fields. Integration guide §7.

  • Breaking: box 26 (commodities[].hs_code) needs 8 to 12 digits. A bare six-digit HS subheading such as 090111 is now refused with 400 and a validation_errors entry on commodities[n].hs_code that says what to send: the six-digit subheading followed by the national tariff digits (09011100 in the EAC and SACU, 0901110000 in ECOWAS and Morocco). Six is too broad to identify the goods, and every African tariff files at least eight. The rule applies to every write, an amendment of a declaration filed before this change included: send the full tariff line on every commodity. Only the first six digits are checked against the HS register, as before. Integration guide §5.

  • REST notifications may now arrive in parallel. ITS sends up to eight announcements at once (kairos.broadcast.dispatch.concurrency=8), so two versions of one eTD can reach POST /{version}/etd/notifications in either order even without a retry. Each carries its version_no and is idempotent: order by version_no, never by arrival. Partner contract, /etd/notifications.

  • Breaking: the guarantee include is guarantee_status, and its answer arrives under data.guarantee_status. It was ?include=guarantee, answered under data.guarantee, which is also the key of section C of the document. A read asking for it therefore carried two "guarantee" keys in data. Most JSON parsers keep the last, so section C was replaced by the platform's answer, and a partner re-canonicalising the document to verify its signature (guide §14) failed a genuine signature. Send ?include=guarantee_status and read data.guarantee_status. The old name is refused with 400 VAL-ETD-059, which lists the valid set, rather than answered, so a client still sending it finds out at once. data.guarantee is section C again on every read. Integration guide §11.

  • ?include=deliveries from a country that may read the declaration but not its delivery ledger is now 403 AUTHZ-ETD-111, not 404 RES-ETD-001. The ledger is open only to the Secretariat and to whoever may act for the filing country, and that has not changed. What changed is the answer to everybody else who may read the declaration — a destination or transit country: a read asking for deliveries among its includes used to come back as though the declaration did not exist. It now refuses by name, so drop deliveries and read again. A caller who may not read the declaration at all still gets 404 RES-ETD-001. Integration guide §11, §12.

  • The printed TD's box 44 is filled on a discharged declaration. On the destination's leg it prints the officer's discharge (sub-captioned discharge at office of destination), where it used to print not yet stamped; box 43's sub-caption there reads office of entry at destination instead of transit office 1. A system closure still leaves box 44 on the last connected country's exit. Rendering only: no stored document, hash or signature changes. Integration guide §5, §9 and §11.

  • A transit whose destination is not on ITS closes at the last connected country's exit. When a connected country stamps its exit, nobody holds the declaration, and neither the next_country_code it names nor the destination is connected, ITS closes the transit in the same act: the exit is recorded as its own version, and a second version follows with the declaration DISCHARGED, discharge_kind: SYSTEM_DESTINATION_NOT_ONBOARDED, a DISCHARGE stamp attributed to the exiting country at its exit station with system_actor: "system:destination-not-onboarded" and no officer, announced with no acting_country. It used to wait for the declaration's own transit_time_end. The exit's response now answers with the closure — current_state: DISCHARGED, operation: DISCHARGE, and the closure's version_no and content_hash — and additional_details says the transit was closed. The closure can precede the goods' real arrival and is not evidence of it; a destination that comes on ITS mid-journey no longer reopens the transit. Declarations left waiting under the old behaviour are closed once after the upgrade. Integration guide §5, §9.

  • No announcement is queued for a country that is not connected. Where the deployment distinguishes connected countries, ?include=deliveries no longer lists PENDING / NO_ENDPOINT rows for countries with no system on ITS, which were re-tried for ever; those already queued are withdrawn once after the upgrade. A connected country without a registered endpoint still gets NO_ENDPOINT rows that drain when its address lands. Integration guide §12.

  • The remark for an unregistered office of destination in a country not on ITS now says the office was stored as given because that country is not on ITS, instead of telling the filer to register it in their own register. Your own unregistered offices keep the old wording. Integration guide §8.

  • GET /api/v1/etd/scope is not an integrator operation. It serves the human-facing Portal and remains in the full OpenAPI document; national customs systems and REC gateways must not call it.

  • A historical read serves the version as it was signed. On GET /api/v1/etd/{serial_no} with ?version= or ?as_of=, envelope.state is now the state at that version. It used to be overwritten with the declaration's current state, so an old version of a declaration since exited or cancelled was served with bytes that did not hash to its own content hash: its signature and its ledger anchor failed to verify on a sound document. What the declaration is now is the new current_state (below). The current version reads exactly as before, and the PDF of any version still prints the current state.

  • envelope.issued_at is always written with six fractional digits (2026-09-25T06:44:12.120000Z), exactly as it is signed. The API used to drop trailing zeros (…12.12Z), so on roughly one document in ten the served document did not re-canonicalise to its signed bytes and a sound signature failed the §14 check. Any ISO-8601 parser reads both forms.

Additive​
  • country_attestation carries ledger_time in ?include=integrity, on an ATTESTED version: the Attest transaction's own timestamp on the ledger (its channel header), as the attesting member claims it. It is not checked against a clock and does not order anything — block_number does — and it is absent when the transaction carried none. attested_at is unchanged: when ITS proved the attestation, by ITS's clock. Public verify is unchanged too: it shows the country and the day of attested_at, never ledger_time. Integration guide §11, ledger information model §18.6.
  • GET /api/v1/ledger/status (ledger:read): this deployment's ledger switches — delivery_enabled, inbox_enabled, sender_id, anchoring_enabled, stream — and its backlogs: anchor_pending (entries on that stream not yet batched; null with no stream), anchor_oldest_pending_seconds (age of the oldest entry the ledger does not hold yet, counting entries in a batch the ledger has not committed, so it can be above 0 while anchor_pending is 0; null with no stream), anchor_last_error (the reason the ledger last gave for not taking the stream's waiting batch; null when nothing has been refused), broadcast_pending and broadcast_failed. Read from configuration and ITS's own tables, never from the ledger, so it answers while the ledger is unreachable.
  • ?include=deliveries rows carry ledger_key on a LEDGER copy: its key in the recipient's inbox (anchoring information model §18.3.1), to find it on the ledger with ReadInbox, QueryDeliveryHash or ReadReceipt. Absent on an HTTP copy. The include stays open only to the Secretariat and whoever may act for the filing country (AUTHZ-ETD-111). Integration guide §11.
  • ?include=versions rows carry stamp_type: the stamp a version records (DEPARTURE, RELEASE, TRANSIT_ENTRY, EXIT or DISCHARGE), null on a version that records none (an amendment, a state change, an attachment). Version 1 carries DEPARTURE: issuance writes the departure authorization with it. Tells a reader which versions can carry a country_attestation without reading each one. Integration guide, the audit trail.
  • Country attestations are built. When a country whose channel in force is its own LEDGER inbox records a TRANSIT_ENTRY, EXIT or DISCHARGE stamp, ITS also puts an ETD_ACT_RECORDED request into that country's own inbox: the ITS-ACT/1 fields of the act and ITS's expected digest (anchoring information model §4.5, §18.6). The member's relay rebuilds the digest from its own authenticated read of the version and attests it on its own peer with its own identity. ITS records the attestation only once it is proved — the Attest transaction is VALID, signed by that country's inbox organisation, and the ledger's hash of the attested bytes equals SHA-256 of ITS's own digest. A country on REST is never asked, and neither is a member whose inbox a REC hosts; a request whose country left LEDGER before it was delivered is withdrawn, never POSTed. ITS validates every act exactly as before: an attestation adds the country's own statement, it does not replace ITS's acceptance.
  • ?include=integrity carries country_attestation on a version that records a TRANSIT_ENTRY, EXIT or DISCHARGE stamp by a country: status ATTESTED (with attester_msp, ledger_key, tx_id, block_number, attested_at), REQUESTED, MISMATCH, or ITS_ATTESTED_ONLY for a country that does not attest on the ledger; plus act_kind, country, customs_office and, when requested, ITS's act_digest. Absent on every other version. Integration guide §11.
  • GET /api/public/verify/{code} may carry country_attestations, once the declaration is closed: only when it is DISCHARGED (by the destination's officer, or by ITS's closure at the last connected exit), and then at most two rows — the departure country's proved EXIT attestation and the destination country's proved DISCHARGE attestation — each the country (country_code, country_name) and the day, attested_on. Nothing while the declaration is open or if it was cancelled: any border act's attestation, even the departure's exit, says where the goods have got to, and the public tier never hints at that. Never a TRANSIT_ENTRY and never a transit country. No act, office, transaction or time. Absent when there is none.
  • GET /api/v1/ledger/consortium members carry attestations: how many of its own acts each organisation has attested on its node, as ITS has proved them.
  • POST /api/v1/onboarding/organisations/me/delivery-channels/{channelId}/probe: an organisation probes its own LEDGER channel's inbox itself, so the technical contact setting up the relay need not ask the Secretariat to. The same probe as POST /api/v1/onboarding/delivery-channels/{channelId}/probe, with the same answers (BUS-ETD-112, BUS-ETD-113, BUS-ETD-122, INT-ETD-123, SYS-ETD-109), under onboarding-self:write, which the technical contact holds. Its own means a channel GET /api/v1/onboarding/organisations/me/delivery-channels lists: for the caller's country, or for a member its union files for. Any other id is 404 RES-ETD-119, the answer an id that does not exist gets. Approving, switching back and withdrawing stay with the Secretariat.
  • LEDGER delivery is built. A country whose channel in force is LEDGER now has its announcements put into its private inbox on the consortium ledger (party-inbox), as inbox envelope v1 whose body_b64 is byte for byte the body a REST member is POSTed, under the key sha256(sender|serial|version|country|deliveryId) (anchoring information model §18.3.1). Its relay acknowledges on chain; ITS proves each acknowledgement (the Ack transaction is VALID and signed by the inbox's own organisation) and closes the delivery exactly as POST /api/v1/etd/{serial_no}/deliveries/ack does, with the Ack transaction as ack_ref. The REST acknowledgement stays valid on a LEDGER channel, and either closes the delivery once. Nothing changes for a country with no LEDGER channel in force, and nothing changes anywhere while ITS_LEDGER_DELIVERY_ENABLED is off (the default): an approved LEDGER country then waits, deferred, rather than being sent another way.
  • ?include=deliveries rows carry channel and receipt_tx_id. channel is HTTP or LEDGER — the channel that delivered that copy, absent until it has been delivered. receipt_tx_id is the on-chain Ack transaction that proved a LEDGER delivery was received, absent otherwise. Integration guide §11.
  • POST /api/v1/onboarding/delivery-channels/{channelId}/probe sends the LEDGER_RECEIVE probe to a declared, superseded or displaced LEDGER channel's inbox and marks the channel's probe_status SENT; the member's relay acknowledging it on chain within 15 minutes makes it PASSED, otherwise FAILED. Approving a LEDGER channel needs PASSED; switching back to one (/reapprove) needs a PASSED no older than 24 hours (BUS-ETD-114 otherwise). Callable by the Secretariat and by the organisation that declares for the channel's country (onboarding:read, then narrowed). Delivery-channel rows gain probe_ref: the probe's inbox key while SENT, the Ack transaction once PASSED.
  • Delivery channels: REST or LEDGER, per country. A country may declare how ITS delivers its announcements — HTTP, a POST to its approved receiving endpoint, or LEDGER, its private inbox on the consortium ledger — and the Secretariat approves it. A country with no channel in force is HTTP, which is every country today, so nothing about delivery changes until a channel is approved, and no LEDGER channel can be approved while the deployment switch (ITS_LEDGER_DELIVERY_ENABLED) is off (the default) or before its receive probe has passed. Partner: GET/POST /api/v1/onboarding/organisations/me/delivery-channels (onboarding-self, as the endpoint routes). Secretariat: GET /api/v1/onboarding/delivery-channels (the queue with filter=status::DECLARED), GET /api/v1/onboarding/organisations/{organisationId}/delivery-channels, and POST /api/v1/onboarding/delivery-channels/{channelId}/approve, /reapprove (switch back to an earlier channel) and /withdraw (onboarding:write; a withdrawn declaration stays, as WITHDRAWN). Listings take filter on status, transport and country_code. Every change is audited and raises the integration.delivery-channel-changed notice to the country and the Secretariat. Anchoring information model §18; decision record docs/decisions/ledger-delivery-channel.md.
  • The Consortium screen is readable by a State Party's or REC's administrator (ledger:read now reaches organisation-admin), so a member can see the consortium it would join. Members are named from the LEDGER channels in force; an MSP no channel declares is shown by its MSP id, where it used to be guessed into a country from its spelling (UGMSP was "Uganda").
  • Partner contract: the announcement is transport-agnostic. POST /{version}/etd/notifications now says that a country's delivery channel may be REST (today, and the default) or LEDGER, where ITS writes the byte-identical announcement into the country's private inbox on the consortium ledger and the country's relay posts it to the same endpoint. The contract lists a ledger member's duties: run a peer, approve both chaincodes, run the relay, acknowledge on chain within the window, purge, and attest its own stamps. Description only: no operation, field or contract version changes, and the LEDGER channel is designed, not yet built. Anchoring information model v1.3 §18; decision record docs/decisions/ledger-delivery-channel.md.
  • ?include=corridor carries not_connected_countries: the countries the corridor names (the destination and every exit's next_country_code) that are not connected to ITS today, sorted. Absent when all are connected, and always absent where the deployment does not distinguish connected countries. Judged on read, never part of the signed document. Integration guide §11.
  • GET /api/v1/etd/{serial_no} carries current_state beside the document: the declaration's state now, whichever version is read. Integration guide §11.
  • GET /api/v1/etd/rejections takes from and to, ISO-8601 instants bounding the listing to the half-open period [from, to). Each row carries tenant_id and, for a State Party, country_code. The Secretariat reads every organisation with ?tenant_id=*, or by naming none; anyone else asking for * is refused with 403.
  • Ledger anchoring. Every eTD version is recorded for the consortium ledger in the act's own transaction and anchored in batches. GET /api/v1/etd/{serial_no}?include=integrity gains integrity.anchor: its status, and once anchored the inclusion proof of the anchoring information model §8.1 (format: kairos-anchor-proof/1). The anonymous GET /api/public/verify/{code} gains anchor_status and anchored_on (a day, never an instant). Both are absent where the deployment does not anchor. The entry a State Party rebuilds from ETD_VERSION_NOTIFICATION_V1 is exactly the one anchored.
  • GET /api/v1/etd/{serial_no} carries overdue: true when the authorised transit time (transit_time_end) has run out and the transit is neither discharged nor cancelled. It is the rule the register's overdue count applies, read against the current UTC day, so there is no need to work it out from the document.
  • The corridor's declared_next_country is absent once the country it names has recorded the goods (an entry, a release or a discharge). A discharged declaration no longer names a next country.
Removed​
  • Notice integration.rejections is no longer published. It was one digest of the previous UTC day's refusals, swept every six hours; integration.incident replaces it. Notices already in a feed stay until they expire. A system that switched on integration.rejections should switch on integration.incident.
  • The pending_closure_at list filter. It named the date from which ITS could close a transit whose destination is not on ITS; the exit closes such a transit itself now, so there is no such date. A filter naming it is refused with VAL-ETD-034 like any unknown field.
Error catalogue​
  • BUS-ETD-133 (ALREADY_ENTERED, 409): an entry by a country that has already recorded its entry for this declaration, or lodged it, and has not exited since.
  • VAL-ETD-130 (IDEMPOTENCY_KEY_REQUIRED, 400): POST /api/v1/etd or a stamp was sent with no Idempotency-Key. Its text now says "unique to this request" rather than "to this declaration".
  • VAL-ETD-131 (IDEMPOTENCY_KEY_TOO_LONG, 400): an Idempotency-Key on an issuance, an amendment or a stamp is longer than 64 characters. On an amendment this used to surface as a 500.
  • BUS-ETD-132 (ISSUANCE_IN_PROGRESS, 409): the same issuing request arrived twice at once and this one lost; nothing was recorded for it. Resend with the same key.
  • BUS-ETD-025 (IDEMPOTENCY_KEY_CONFLICT) is now also returned by an issuance and by a stamp, and its text no longer says "on this declaration".
  • VAL-ETD-129 (CUSTOMS_OFFICE_COORDINATES_INCOMPLETE, 400): a customs office was written with a latitude and no longitude, or the reverse. Give both or neither.
  • VAL-ETD-128 (NOTIFICATION_READ_BATCH_INVALID, 400): POST /api/v1/notifications/read sent no sequence numbers, or more than 500. Refused rather than truncated, so a 200 always means every listed notice was handled.
  • SYS-ETD-127 (LEDGER_DELIVERY_RECORD_UNREADABLE, 503): ITS could not read its own record of an earlier delivery of an attestation request it is about to withdraw, so it cannot tell whether the member's inbox already holds it; the delivery is retried, never withdrawn blind. Never returned over HTTP: it is the delivery's last_error_code, where it used to read LEDGER_RECORD_FAILED (a row that could not be written before a send).
  • BUS-ETD-126 (ARRANGEMENT_ALREADY_RECORDED, 409): a REC membership, submission delegation, State Party participation or service-account binding added again with the same parties and effective_from. It used to answer 500 ERR-099 naming the database constraint. Reactivate the existing row to restore a withdrawn arrangement; a new period needs a different effective_from. The detail names the identity that matched.
  • Country attestations: INT-ETD-124 (ATTESTATION_MISMATCH) and INT-ETD-125 (ATTESTATION_NOT_PROVEN), both 409. Neither is ever returned over HTTP: they name an Attested event ITS refused — a member's own attestation of a different digest, or a transaction that is not that member's valid Attest of the request — in the parked event, the log and the alert.
  • LEDGER delivery: CFG-ETD-121 (LEDGER_DELIVERY_MISCONFIGURED, 500, at boot: delivery switched on without the ledger inbox or a declared sender), BUS-ETD-122 (LEDGER_PROBE_NOT_APPLICABLE, 409: only a declared, superseded or displaced LEDGER channel is probed), INT-ETD-123 (LEDGER_PROBE_UNDELIVERED, 502: the inbox did not take the probe). The probe also answers BUS-ETD-112, BUS-ETD-113, SYS-ETD-109 and AUTHZ-ETD-016.
  • Delivery channels: BUS-ETD-112 (LEDGER_DELIVERY_DISABLED), BUS-ETD-113 (LEDGER_NOT_MEMBER), BUS-ETD-114 (LEDGER_PROBE_REQUIRED), BUS-ETD-115 (CHANNEL_REQUIRES_HTTP_ENDPOINT), BUS-ETD-116 (CHANNEL_NOT_APPROVABLE), BUS-ETD-118 (CHANNEL_DELEGATION_INVALID), all 409; VAL-ETD-117 (INVALID_MSP_ID) and VAL-ETD-120 (DELIVERY_CHANNEL_FILTER_UNSUPPORTED), 400; RES-ETD-119 (DELIVERY_CHANNEL_NOT_FOUND), 404.
  • AUTHZ-ETD-111 (INCLUDE_NOT_PERMITTED): the caller may read the declaration but not an include it asked for — today only deliveries. 403; read again without it.
  • SYS-ETD-106 (ETD_ANCHOR_PROOF_INCONSISTENT): a version's anchoring proof could not be assembled from what was recorded. A fault on ITS's side; the version itself is unaffected.
  • VAL-ETD-105 (CUSTOMS_OFFICE_CODE_IMMUTABLE): a customs office's code cannot be changed by an edit. VAL-ETD-084 now applies to an edit as well as to a new office.

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.
  • 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. A bad as_of answers VAL-ETD-134 instead.
  • 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.