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=manifestonGET /api/v1/etd/{serial_no}. Underdata.manifest, once the declaration is discharged:produced_at(when ITS wrote the manifest),source_version_no,discharged_at, andformats[]—code,name,media_typeandfile_extensionfor every formatGET /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. Underetd:read, like the other includes; the manifest itself stays behindmanifest:readon its own route. Times followtz.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/exportandGET /api/v1/governance/{dataset}/exporttake the narrowing their listings take, with the same names and the same meaning:filter,queryandorder-byon both,active_onlyon both, andmaintainable_onlyon the customs-office register. The file holds every row the listing would answer for those parameters, in that order;page-numberandpage-sizeare 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 ororder-bynaming a column the dataset does not have is a400, 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; sendactive_only=truefor 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/endpointsrefuses abase_urlthat does not,http://included, with400 ERR-015and avalidation_errorsentry onbase_urlreading "must start with https://: ITS calls a receiving endpoint over HTTPS only" (VAL-ETD-065when 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 anhttp://address are not rewritten and keep receiving announcements; declaring a replacement needs anhttps://address.VAL-ETD-065's message now names this reason, and its contract version is corrected tov1. The published request schema (DeclareReceivingEndpointDto) states the rule aspattern: ^https://.+onbase_url; the response still reports a storedhttp://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 andnullin JSON.format=json(the default, in the response envelope),format=asycuda-awmds(application/xml), or the code of a format the Secretariat publishes;tzfor the zone of the dates and time, UTC when absent. Needsmanifest:read, granted withetd:read, and opens to exactly the callers who may read the declaration. Served with anETag;If-None-Matchis answered304. New errors:409 BUS-ETD-134before discharge,400 VAL-ETD-138for 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/positionsandGET /v1/tracking/{e_seal_id}/historyare gone, with their schemas (TrackingResponse,TrackingData,TrackingBatchResponse,TrackingHistoryResponse,TrackPoint). ITS never calls a tracking path on a receiving endpoint. Nothing changes for readers:include=trackingand the public track route answer as before, from the cargo tracking system ITS's deployment is configured with, andTRACKING_UNAVAILABLEuntil it is connected. The guarantee check,GET /v1/guarantee/{reference}, andPOST /v1/etd/notificationsare unchanged. The contract also gains the401row ITS already applied to announcements: the token is dropped and the announcement retried with a new one, while a403is final. Partner contract; integration guide §13.
Changed
INT-ETD-045names 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 answersVERIFICATION_UNAVAILABLEorTRACKING_UNAVAILABLE.
2026-10-23 (users: telephone numbers)
Changed
- A telephone number is E.164 or it is refused.
phoneandalternative_phoneonPOST /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; aPUTthat leavesphoneout 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}/rolesno longer requiresname. Left out or blank, the key is derived fromdisplay_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 generatedrole-xxxxxxxx; a derived key a built-in role or another custom role of the tenant already holds takes a numeric suffix. The created role'snameis in the response and never changes. Anamethat 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}/emailwith{"data": {"email": "..."}}changes the address a person signs in with, for an administrator holdinguser:updateover 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_USERwhen another person holds the address. The address is identity, not profile: it is not a field onPUT /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}withpermission_idsis accepted for a built-in role (is_system_role), written through to Keycloak, and kept across restarts and the directory sync;is_editablesays so on the role.system-adminis protected (is_protected): it refuses every change, deactivation and deletion with400. 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 withAUTHZ_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-permissionis gone. Every permission onGET /api/v1/authz/permissionsnow carries aresource_category(one of Transit, Onboarding, Reference data, Reports, Administration, Audit & ledger — orPlatformfor the SDK's own tenant, member and sync resources, which a role editor hides) and a shortresource_display_name("Transit declarations", "Customs offices", "Roles"). The resourceauthz-permissionand 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 heldauthz-permission:readloses nothing it could use. - Roles are the Secretariat's to administer too.
secretariat-adminholds everyauthz-rolescope (read, create, update, delete, activate, deactivate), assystem-admindoes. The platform resources stay the operator's.
Added
- A role says whether it may be edited.
GET /api/v1/authz/tenants/{tenantId}/rolesand the single-role reads carryis_editable(a custom role always; a built-in role only where this deployment allows it) andis_protected(a built-in role closed to every change, including activation and deletion). A role editor reads these rather than guessing fromis_system_role. GET /api/v1/authz/me/tenantanswers the signed-in person's own tenant with no permission required, and204when 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-inboxprivate 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 recorddocs/decisions/ledger-delivery-removed.md. - One announcement body,
ETD_DOCUMENT_V1.POST /v1/etd/notificationsreceives the signed document only: the fields that name the version,attestationanddocument. The signed notice,ETD_SIGNED_NOTICE_V1(schemaEtdSignedNotice), is retired, and the partner contract's request body isEtdDocumentAnnouncementalone. The contract version staysv1. 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-channelsandPOST /api/v1/onboarding/organisations/me/delivery-channels/{channelId}/probe. Secretariat:GET /api/v1/onboarding/delivery-channels,GET /api/v1/onboarding/organisations/{organisationId}/delivery-channels, andPOST /api/v1/onboarding/delivery-channels/{channelId}/approve,/reapprove,/withdrawand/probe. A receiving endpoint is still declared withPOST /api/v1/onboarding/organisations/me/endpointsand approved by the Secretariat. - Fields removed from responses.
?include=deliveriesrows losechannel,receipt_tx_idandledger_key.?include=integritylosescountry_attestation.GET /api/public/verify/{code}losescountry_attestations.GET /api/v1/ledger/consortiummembers loseattestations.GET /api/v1/ledger/statuslosesdelivery_enabled,inbox_enabledandsender_id; its anchoring and broadcast fields are unchanged. - Consortium members are named by MSP id.
GET /api/v1/ledger/consortiumnamed 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-changedis 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) andBUS-ETD-122(LEDGER_PROBE_NOT_APPLICABLE): delivery-channel approval and probing.VAL-ETD-117(INVALID_MSP_ID) andVAL-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) andINT-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/etdwithoutgeneral_information.exporter_consignor.tin, or with it blank, is refused with400 ERR-015naming that field invalidation_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, withtinamong its required properties; boxes 4 and 5 keepEtdPartyDto. 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 withas_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: Registeredin 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
langis 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 forlang=frorlang=ar, because onlyfr-SNandar-SAare 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, sofr,fr-CAandfr-SNall 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}/attachmentsor 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_todate) is refused with400 VAL-ETD-136when 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 inheader.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.addressand.shipper_transporter.addresshad no limit; they now take whatnametakes, 150. Anddeclarant.declaration_texttakes 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 a400validation error on that field (size must be between 0 and 150, or250), 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=Ireturns leaflet I and any item sheets;leaflet=IIis 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/rejectionsaddsexternal_type(state_party,recorsecretariat) andexternal_id(a State Party's ISO alpha-2 code, a REC's acronym such asEAC), the same fields and values the organisation register serves. A REC's refusals, which carry nocountry_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 answers200. An entry is expected when the entering country is thenext_country_codeon 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 oneATTENTIONnotice 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 keysits.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}/attachmentson a declaration that isDISCHARGEDorCANCELLEDis now refused with409 BUS-ETD-009, the code every other act gets on a closed declaration; it used to be accepted and appended anATTACHMENTversion 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}/versionswithout the header is refused with400 VAL-ETD-130; it used to be accepted. Send a value of your choosing, at most 64 characters (400 VAL-ETD-131beyond that), unique to the amendment. Nothing else changes: the same key and the same body still answer201with the version the first request created, and the same key with a different body is still409 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 …/attachmentsnow answers201 Created, as documented; it answered200. - An unknown
nationalityon a stamp or departure vehicle is now refused. Thenationalityof thevehicleon a lifecycle stamp and ofdeparture_formalities.vehicleat issuance is checked against the country register, as it already is on boxes 15 and 17: an unknown country answers400 VAL-ETD-003, the same code as an unknown country anywhere else. Integration guide, "Recording a change of vehicle". - A malformed
as_ofhas its own error code.GET /api/v1/etd/{serial_no}(and the PDF read) now answers400 VAL-ETD-134whenas_ofis not an ISO-8601 instant with an offset, or whenas_ofis sent together withversion; it used to answerVAL-ETD-011, whose text described a stamp-time rule that no longer exists.VAL-ETD-011is retired and never reused. Integration guide Appendix A. - Exit is now transit, everywhere the lifecycle speaks.
POST /api/v1/etd/{serial_no}/endorsements/exitis removed; record a transit withPOST …/endorsements/transit(same body, sameIdempotency-Keyrule;/exitnow answers400 VAL-ETD-064like any unknown act). Stamp typesTRANSIT_ENTRYandEXITare nowENTRYandTRANSIT; the stateIN_TRANSITisTRANSITEDand the operationEXITisTRANSIT, on every read, list row, lifecycle result and corridor stop. The list filter takesstate@@TRANSITED;IN_TRANSITis refused400 VAL-ETD-034. The sandbox milestoneEXIT_ETDisTRANSIT_ETD. Theetd.endorsednotice'sparams.actsaystransit. Ledger: new ITS-ACT/1 attestations carryact_kindENTRYorTRANSIT(information model v1.4). Versions signed before this change keep the words they were signed with, byte for byte, and still verify; their attestations keepTRANSIT_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-Keywhere ITS requires it, and gives every eTD operation anoperationId. The header is required on issue, stamp, cancel and acknowledgement (cancel and acknowledgement answerVAL-IDEM-001without it, as before) and optional on amendment; nothing about how ITS answers has changed. Ids are stable, for exampleissueEtd,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.actand 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.actexitistransiton 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'sINFOnotices leave that person's unread count, unread listing, latest and stream.ATTENTIONandCRITICALare 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 yoursince_sequencecatch-up are unchanged. New codeVAL-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 nowv1: 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). Versionsv2,v3andv4no 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 besidev1rather than in place of it. Partner contract; integration guide §4, §12 and §13. -
A receiving endpoint is declared at
v1only.contract_versionmust bev1; omitted or blank meansv1. Any other value,v2,v3andv4included, is refused at declaration with400(VAL-ETD-065when it reaches the service). A REC that receives for a member declares the member atv1. 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, anddocument, so your system verifies it without a read. Over the ledger it is the signed notice,ETD_SIGNED_NOTICE_V1: the same fields andattestation, withoutdocument; 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(schemaEtdVersionNotification), 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 envelopekindETD_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-Keyis 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 answers200with the sameversion_no,content_hash,current_stateandoperationthe first attempt received, records nothing, and is answered so even after the declaration has moved on or closed. Codes change: no key is400 VAL-ETD-130(wasVAL-IDEM-001), a key longer than 64 characters is400 VAL-ETD-131, and the same key on the same declaration with a different act or body is409 BUS-ETD-025(was422 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-002is no longer returned for a stamp. A refused stamp keeps no key, so a corrected request may be resent with the same key. Remarks inheader.additional_detailsare given on the first answer only. New: anentryby a country that has entered and not exited since is refused with409 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/etdwithout the header is refused with400 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-131beyond that), unique to the declaration. If the response is lost, send the same request again with the same key: ITS answers201with 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 is409 BUS-ETD-025. Two identical requests at the same instant: one issues, the other gets409 BUS-ETD-132and 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/statisticsanswers one number. This is the Portal's read (it is not in the integrator contract). It returned eight counts; it now returnsoverdue_transitsandoverdue_transits_capped.active_transits,registered_today,arrived_awaiting_release,held_by_me,discharged_today,cancelled_todayandby_stateare 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_transitsnow stops at 10,000 and says so withoverdue_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_modeis now required on every means of transport you send:means_of_transport.at_departure,means_of_transport.crossing_borderwhen you declare it, and thevehicleon a stamp when an office records one. Omit it and the call is refused withERR-015on that field; there is no default. It was response-only and always3. Send one of the five modes in force —1maritime,2rail,3road,4air,8inland water — which is whatGET /api/reference/transport-modes/activereturns.5,6,7and9are refused withVAL-ETD-003. Never send6(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_nokeeps 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/streamnow sends an event namedheartbeatevery 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 anevent:line; a browser'sEventSourcealready ignores it. The listing andsince_sequenceare unaffected. -
Customs offices have a position:
latitudeandlongitude. Both are on every row ofGET /api/reference/customs-officesand 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 never0,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 hasLatitudeandLongitudecolumns, 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 with400 ERR-015on the field. -
Position data: contains data from GeoNames, licensed under CC BY 4.0, and from UN/LOCODE (UNECE).
-
transport_mode_namebeside everytransport_mode. The mode in words (Rail transport), resolved by ITS and read-only, on both means of transport and on a stamp'svehicle. The printed TD shows it inside boxes 15 and 17 underMODE OF TRANSPORT, with the identity underPLATE 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_versionv4and each announcement isETD_DOCUMENT_V1instead of the pointer: the same nine fields, thenattestation(signature_status,key_id,signed_at,signature) anddocument, the version's canonical content exactly as ITS signed and stores it and asGET /api/v1/etd/{serial_no}?version=serves it. Verify it without calling ITS: canonicalisedocument(RFC 8785), check its SHA-256 iscontent_hash, and verify the detached JWS inattestation.signatureover those bytes with the keykey_idnames inGET /.well-known/jwks.json. ITS POSTs it to{base_url}/v4/etd/notifications.v2andv3are unchanged and remain the default (v2when you name none); each country receives exactly one shape.v4over the ledger receives the notice,ETD_SIGNED_NOTICE_V1(the same fields andattestation, nodocument): a document never goes on chain, so the full document travels only to HTTPS endpoints. Accept bothv4bodies. 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 (samededupe_key, newsequence_no, unread again, latest count inparams.refused).CRITICALwhen it can hold up cargo,ATTENTIONfor lookups. The AfCFTA Secretariat receives everyCRITICALincident too, naming the organisation.action_refcarries 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/rejectionspages bylimitandcursor(the previous response'snext_cursor); thepage-numberform still works. New filtersserial_no,error_code,routeandoutcome(lookup,its_error). Each row addspath_params(serial_no,stamp_type,version_no,attachment_idwhere the route had them),resolved_path,urgency(CRITICAL/ATTENTION),organisation_nameandorigin(system/console). NewGET /api/v1/etd/rejections/summary:latest_received_at,new_sinceafter asincewatermark, and atotalwithinclude_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) andBACKDATE_DAYS(0–30, unset 0). Rows carrysetting_keyandsetting_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, undertransit-rule:read, which every role holds, on the partner host and in the integrator contract. StrongETag,304, a 30-secondCache-Control. -
Notice
governance.transit-rule-changed, to every State Party's and REC's administrators, once per change;ATTENTIONwhen 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-settingholdsINVITATION_LIFESPAN_DAYS(1–30, unset 7),HEALTH_FAILURE_THRESHOLD(1–100, unset 3) andHEALTH_WINDOW_DAYS(1–30, unset 7);GET /api/v1/operations-settingsreads 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 (9999lines,9999999999999.99for money,99999999999.999kg for weights). A breach is400 ERR-015on issuance and on amendment, with every breach listed invalidation_errorsunder 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 permissionintake-limit:read, which every role holds,partner-systemincluded. A strongETagand a 30-secondCache-Control, so poll withIf-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. SeverityATTENTIONwhen the cap is lowered,INFOwhen 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 carriescreated_byandcreated_at(who recorded it, and when) andupdated_byandupdated_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.filterandorder-byon the dataset listing accept the same four names. -
Browsers can revalidate. Cross-origin requests may send
If-None-Match, and responses exposeETag, so a browser page can make a conditional read ofGET /api/v1/intake-limitsor the TD PDF and get304 Not Modified. -
filter=current_holderandfilter=stationonGET /api/v1/etd.current_holder::KElists the declarations Kenya holds now — the country whose entry is the earliest still open, the samecurrent_holderthe corridor reports; a declaration nobody holds matches no value.station::KEMBAlists 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 is400 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 theexpires_inyou stated, and then requests the next; a response with noexpires_inis treated as good for 60 seconds. Your token endpoint will see far fewer requests. If your endpoint answers401, 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 inexpires_in, and answer401, not403, for a token you no longer accept. -
An entry stamp on a cancelled declaration is refused.
POST /api/v1/etd/{serial_no}/endorsements/entryon a declaration that isCANCELLEDorDISCHARGEDanswers409 BUS-ETD-009and 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 with200andtransition_fired: false, and a stamp and a signed version were added to a declaration that was finished. If your system received such a200, 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 receives404 RES-ETD-001, where it used to receive403 AUTHZ-ETD-008,409 BUS-ETD-009,409 BUS-ETD-063,412 BUS-ETD-019or404 RES-ETD-030with details of a declaration it could not see. The text besideRES-ETD-001is 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 nodata. -
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, thenAccept-Language), then in the default localeen-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}/pdfand/versions/{n}/pdfnow 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. TheETagis no longerW/"<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 returns200once. And an older version reprinted after the declaration's state changed (cancelled, departed) is now a different file with a differentETag, where it used to answer304and leave a stale leaflet in your cache. Keep sending it asIf-None-Match; do not parse it, and never send it asIf-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 sendContent-Dispositionwith bothfilename="..."andfilename*=UTF-8''..., as the Transit Document and attachment downloads already did. -
A receiving endpoint's
contract_versionmust bev2,v3orv4. Anything else,v1included, is refused at declaration with400(VAL-ETD-065when it reaches the service):v1is never notified, and an unknown version would resolve and then fail on every announcement. Omitted still meansv2.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,currencyanddate— must all be sent, as your customs guarantee system issued them (TDD v3 §5.1). A missing box is400 ERR-015on 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 wasVAL-ETD-005. -
GET /api/v1/etdcounts its total to 10,000 and no further.pagination.total_cappedistruewhen there are more:total_recordsis then10000and means "10,000 or more", andtotal_pagesis what 10,000 rows make. Below the cap the total is exact andtotal_cappedisfalse, as before. Pages past a cappedtotal_pagesare served as usual, so walk untildatais 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_transitsand 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_kgandnet_weight_kgrefuse a negative value with400 ERR-015on the field; zero is accepted. The published schema statesminimum: 0on 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.amountanddeclarant.feesaccept up to9999999999999.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 with400 VAL-ETD-027, which named no field. It is now refused at the door with400 ERR-015and avalidation_errorsentry on the field that is too wide. The published schema states the bound asmaximumon 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 as090111is now refused with400and avalidation_errorsentry oncommodities[n].hs_codethat says what to send: the six-digit subheading followed by the national tariff digits (09011100in the EAC and SACU,0901110000in 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 reachPOST /{version}/etd/notificationsin either order even without a retry. Each carries itsversion_noand is idempotent: order byversion_no, never by arrival. Partner contract,/etd/notifications. -
Breaking: the guarantee include is
guarantee_status, and its answer arrives underdata.guarantee_status. It was?include=guarantee, answered underdata.guarantee, which is also the key of section C of the document. A read asking for it therefore carried two"guarantee"keys indata. 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_statusand readdata.guarantee_status. The old name is refused with400 VAL-ETD-059, which lists the valid set, rather than answered, so a client still sending it finds out at once.data.guaranteeis section C again on every read. Integration guide §11. -
?include=deliveriesfrom a country that may read the declaration but not its delivery ledger is now403 AUTHZ-ETD-111, not404 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 fordeliveriesamong its includes used to come back as though the declaration did not exist. It now refuses by name, so dropdeliveriesand read again. A caller who may not read the declaration at all still gets404 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_codeit 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 declarationDISCHARGED,discharge_kind: SYSTEM_DESTINATION_NOT_ONBOARDED, aDISCHARGEstamp attributed to the exiting country at its exit station withsystem_actor: "system:destination-not-onboarded"and no officer, announced with noacting_country. It used to wait for the declaration's owntransit_time_end. The exit's response now answers with the closure —current_state: DISCHARGED,operation: DISCHARGE, and the closure'sversion_noandcontent_hash— andadditional_detailssays 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=deliveriesno longer listsPENDING/NO_ENDPOINTrows 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 getsNO_ENDPOINTrows 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/scopeis 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.stateis 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 newcurrent_state(below). The current version reads exactly as before, and the PDF of any version still prints the current state. -
envelope.issued_atis 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_attestationcarriesledger_timein?include=integrity, on anATTESTEDversion: theAttesttransaction'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_numberdoes — and it is absent when the transaction carried none.attested_atis unchanged: when ITS proved the attestation, by ITS's clock. Public verify is unchanged too: it shows the country and the day ofattested_at, neverledger_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 whileanchor_pendingis 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_pendingandbroadcast_failed. Read from configuration and ITS's own tables, never from the ledger, so it answers while the ledger is unreachable.?include=deliveriesrows carryledger_keyon a LEDGER copy: its key in the recipient's inbox (anchoring information model §18.3.1), to find it on the ledger withReadInbox,QueryDeliveryHashorReadReceipt. 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=versionsrows carrystamp_type: the stamp a version records (DEPARTURE,RELEASE,TRANSIT_ENTRY,EXITorDISCHARGE), null on a version that records none (an amendment, a state change, an attachment). Version 1 carriesDEPARTURE: issuance writes the departure authorization with it. Tells a reader which versions can carry acountry_attestationwithout reading each one. Integration guide, the audit trail.- Country attestations are built. When a country whose channel in force is its own
LEDGERinbox records aTRANSIT_ENTRY,EXITorDISCHARGEstamp, ITS also puts anETD_ACT_RECORDEDrequest into that country's own inbox: theITS-ACT/1fields 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 — theAttesttransaction isVALID, 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=integritycarriescountry_attestationon a version that records aTRANSIT_ENTRY,EXITorDISCHARGEstamp by a country:statusATTESTED(withattester_msp,ledger_key,tx_id,block_number,attested_at),REQUESTED,MISMATCH, orITS_ATTESTED_ONLYfor a country that does not attest on the ledger; plusact_kind,country,customs_officeand, when requested, ITS'sact_digest. Absent on every other version. Integration guide §11.GET /api/public/verify/{code}may carrycountry_attestations, once the declaration is closed: only when it isDISCHARGED(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 provedEXITattestation and the destination country's provedDISCHARGEattestation — each thecountry(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 aTRANSIT_ENTRYand never a transit country. No act, office, transaction or time. Absent when there is none.GET /api/v1/ledger/consortiummembers carryattestations: 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 asPOST /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), underonboarding-self:write, which the technical contact holds. Its own means a channelGET /api/v1/onboarding/organisations/me/delivery-channelslists: for the caller's country, or for a member its union files for. Any other id is404 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
LEDGERnow has its announcements put into its private inbox on the consortium ledger (party-inbox), as inbox envelope v1 whosebody_b64is byte for byte the body a REST member is POSTed, under the keysha256(sender|serial|version|country|deliveryId)(anchoring information model §18.3.1). Its relay acknowledges on chain; ITS proves each acknowledgement (theAcktransaction isVALIDand signed by the inbox's own organisation) and closes the delivery exactly asPOST /api/v1/etd/{serial_no}/deliveries/ackdoes, with theAcktransaction asack_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 whileITS_LEDGER_DELIVERY_ENABLEDis off (the default): an approved LEDGER country then waits, deferred, rather than being sent another way. ?include=deliveriesrows carrychannelandreceipt_tx_id.channelisHTTPorLEDGER— the channel that delivered that copy, absent until it has been delivered.receipt_tx_idis the on-chainAcktransaction that proved a LEDGER delivery was received, absent otherwise. Integration guide §11.POST /api/v1/onboarding/delivery-channels/{channelId}/probesends the LEDGER_RECEIVE probe to a declared, superseded or displaced LEDGER channel's inbox and marks the channel'sprobe_statusSENT; the member's relay acknowledging it on chain within 15 minutes makes itPASSED, otherwiseFAILED. Approving a LEDGER channel needsPASSED; switching back to one (/reapprove) needs aPASSEDno older than 24 hours (BUS-ETD-114otherwise). Callable by the Secretariat and by the organisation that declares for the channel's country (onboarding:read, then narrowed). Delivery-channel rows gainprobe_ref: the probe's inbox key whileSENT, theAcktransaction oncePASSED.- Delivery channels: REST or LEDGER, per country. A country may declare how ITS delivers its
announcements —
HTTP, a POST to its approved receiving endpoint, orLEDGER, its private inbox on the consortium ledger — and the Secretariat approves it. A country with no channel in force isHTTP, 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 withfilter=status::DECLARED),GET /api/v1/onboarding/organisations/{organisationId}/delivery-channels, andPOST /api/v1/onboarding/delivery-channels/{channelId}/approve,/reapprove(switch back to an earlier channel) and/withdraw(onboarding:write; a withdrawn declaration stays, asWITHDRAWN). Listings takefilteronstatus,transportandcountry_code. Every change is audited and raises theintegration.delivery-channel-changednotice to the country and the Secretariat. Anchoring information model §18; decision recorddocs/decisions/ledger-delivery-channel.md. - The Consortium screen is readable by a State Party's or REC's administrator (
ledger:readnow reachesorganisation-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 (UGMSPwas "Uganda"). - Partner contract: the announcement is transport-agnostic.
POST /{version}/etd/notificationsnow 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 recorddocs/decisions/ledger-delivery-channel.md. ?include=corridorcarriesnot_connected_countries: the countries the corridor names (the destination and every exit'snext_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}carriescurrent_statebeside the document: the declaration's state now, whichever version is read. Integration guide §11.GET /api/v1/etd/rejectionstakesfromandto, ISO-8601 instants bounding the listing to the half-open period[from, to). Each row carriestenant_idand, for a State Party,country_code. The Secretariat reads every organisation with?tenant_id=*, or by naming none; anyone else asking for*is refused with403.- 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=integritygainsintegrity.anchor: itsstatus, and once anchored the inclusion proof of the anchoring information model §8.1 (format: kairos-anchor-proof/1). The anonymousGET /api/public/verify/{code}gainsanchor_statusandanchored_on(a day, never an instant). Both are absent where the deployment does not anchor. The entry a State Party rebuilds fromETD_VERSION_NOTIFICATION_V1is exactly the one anchored. GET /api/v1/etd/{serial_no}carriesoverdue:truewhen 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_countryis 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.rejectionsis no longer published. It was one digest of the previous UTC day's refusals, swept every six hours;integration.incidentreplaces it. Notices already in a feed stay until they expire. A system that switched onintegration.rejectionsshould switch onintegration.incident. - The
pending_closure_atlist 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 withVAL-ETD-034like any unknown field.
Error catalogue
BUS-ETD-133(ALREADY_ENTERED,409): anentryby 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/etdor a stamp was sent with noIdempotency-Key. Its text now says "unique to this request" rather than "to this declaration".VAL-ETD-131(IDEMPOTENCY_KEY_TOO_LONG,400): anIdempotency-Keyon an issuance, an amendment or a stamp is longer than 64 characters. On an amendment this used to surface as a500.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/readsent 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'slast_error_code, where it used to readLEDGER_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 andeffective_from. It used to answer500 ERR-099naming the database constraint. Reactivate the existing row to restore a withdrawn arrangement; a new period needs a differenteffective_from. The detail names the identity that matched.- Country attestations:
INT-ETD-124(ATTESTATION_MISMATCH) andINT-ETD-125(ATTESTATION_NOT_PROVEN), both409. Neither is ever returned over HTTP: they name anAttestedevent ITS refused — a member's own attestation of a different digest, or a transaction that is not that member's validAttestof 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 answersBUS-ETD-112,BUS-ETD-113,SYS-ETD-109andAUTHZ-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), all409;VAL-ETD-117(INVALID_MSP_ID) andVAL-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 onlydeliveries.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-084now 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/etdissues 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 withversionoras_of; the paged list atGET /api/v1/etdwithpage-number,page-sizeandfilter; the printed declaration atGET /api/v1/etd/{serial_no}/pdf. - Amendment is
POST /api/v1/etd/{serial_no}/versions: a whole-document new version, guarded byIf-Match, with a reason and an idempotency key. - The lifecycle acts
DEPART,EXIT,ARRIVEandDISCHARGEare stamps, atPOST /api/v1/etd/{serial_no}/endorsements/{stamp_type}, by the country whose turn it is.POST /api/v1/etd/{serial_no}/cancelwithdraws 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, andGET /api/v1/etd/reconciliation/digestis the backstop for anything missed. GET /api/v1/notificationsis 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, andGET /api/public/track/{serial_no}with theX-Party-Tinheader lets the declarant or the consignee follow a consignment. Neither needs an account.GET /.well-known/jwks.jsonpublishes the public document-signing keys, retired keys included, so a declaration signed before a key rotation stays verifiable.GET /api/v1/error-cataloguelists 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 terminalDISCHARGEDandCANCELLED. - v5 adds one step,
IN_TRANSITtoDISCHARGED, 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 asSYSTEM_DESTINATION_NOT_ONBOARDEDand is not evidence that the goods arrived. Attempting it yourself isBUS-ETD-085. - Coming from lifecycle v4:
RECORD_DEPARTURE_EXITandRECORD_ARRIVALbecameDEPART,EXITandARRIVE, the stateEXITEDbecameDISCHARGED, 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-011was an ambiguous customs stamp time. The stamp-time field is gone: ITS records when it received each stamp from its own clock. A badas_ofanswersVAL-ETD-134instead.VAL-ETD-031was an unreadable list cursor. The list pages by number now, andcursorandlimitare no longer read.VAL-ETD-032was more than 100 serials in onePOST /api/v1/etd/batch. That endpoint is gone: filter the list withserial_no@@instead, where more than 100 serials isVAL-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, andGET /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/positionsfor many seals at once, andGET /v3/tracking/{e_seal_id}/historyfor the track over a window. There is deliberately no push: ITS stores no positions, so it asks and you answer.