Skip to main content

Attachments and documents

A declaration can carry supporting documents, such as an invoice, a packing list or a certificate of origin. ITS can also render any version of a declaration as the adopted AfCFTA Transit Document.

Attach supporting documents​

POST /etd/{serial_no}/attachments

Send the files as multipart/form-data:

PartRequiredNotes
fileYesOne document. Repeat the part to send several.
document_typeNoWhat kind of document these are, in your own words, such as INVOICE, PACKING_LIST or CERTIFICATE_OF_ORIGIN. It applies to every file in the request.
curl --fail-with-body --silent --show-error \
--header "Authorization: Bearer $ITS_TOKEN" \
--form "file=@invoice.pdf" \
--form "file=@packing-list.pdf" \
--form "document_type=INVOICE" \
"$ITS_PARTNER_URL/etd/KEMBATD26081138/attachments"

A successful call answers 201 with the declaration's attachments after the act.

Send the whole set in one request. Each request is one act: it appends one version of the declaration and announces it once to every country the declaration concerns. Twelve pages sent one at a time would make twelve versions and twelve announcements for every other country to receive and acknowledge.

  • Who may attach: any country the declaration concerns, not only the departure country, with the etd:attach permission. A REC may attach for the members it acts for.
  • All or nothing: nothing is stored unless every file in the request is accepted.
  • Type is checked from the content: ITS detects each file's type from its bytes, not from the header you send. A file whose content contradicts its declared type is refused, and so is a type this deployment does not accept.
  • Retries are harmless: a file ITS already holds is identified by its digest and returned rather than stored twice.
  • There is no delete: an attachment is evidence. Supersede it by attaching another.
  • A closed declaration takes no more: attaching to a declaration that is DISCHARGED or CANCELLED is refused with 409 BUS-ETD-009, as every other act on it is. Nothing is stored.

What ITS accepts​

LimitValue
File typesPDF (application/pdf), JPEG (image/jpeg), PNG (image/png) and TIFF (image/tiff). Nothing else, whatever the file is called.
Size of one fileAt most 10 MB (10,485,760 bytes).
Size of one requestThe whole multipart body at most 12 MB, so several files sent together must fit in 12 MB between them.
ScanningEvery file is scanned for malware before it is stored. A file is never stored unscanned.

These are the service's own settings, the same in Sandbox and Live unless the Secretariat tells you otherwise. A type is judged from the file's content: a PNG renamed .pdf is refused.

StatusMeaning
201Stored
400No file sent (VAL-ETD-037), a file was empty (VAL-ATT-008), or malware scanning rejected a file (VAL-ATT-004)
403You may see the declaration but not add to it (AUTHZ-ETD-036)
404No such declaration in your scope
409The declaration is closed: DISCHARGED or CANCELLED (BUS-ETD-009)
413A file is larger than 10 MB (VAL-ATT-003), or the whole request is larger than 12 MB
415A file is not PDF, JPEG, PNG or TIFF, or its content contradicts its declared type (VAL-ATT-002)
503ITS cannot scan files right now (SYS-ATT-009). Nothing was stored. Not your fault; try again later.

List the attachments​

GET /etd/{serial_no}/attachments

Each entry carries:

FieldMeaning
idThe number to download the file by. It is this deployment's handle on the stored file, not part of the signed content.
sha256The lowercase hex SHA-256 of the file's bytes
filenameThe name the file was uploaded under, for display only
document_typeThe document_type it was attached with

The attach response (201) returns the same entries, id included.

The signed document carries the same list, without id, as envelope.attachments, on every read. There is no include=attachments: you already have it.

Download an attachment​

GET /etd/{serial_no}/attachments/{attachment_id}/download

attachment_id is the id from the attachment list or the attach response. An unknown id is 404 RES-ETD-035.

The file is streamed through ITS under the same authorisation as every other read, with Cache-Control: private, no-store.

Verify what you receive. Hash the bytes and compare them with the sha256 in envelope.attachments. If they differ, the file is not the one the declaration was signed with.

GET /etd/{serial_no}/pdf
GET /etd/{serial_no}/versions/{version_no}/pdf

Both need etd:read, the same permission as reading the JSON. The response is application/pdf: the adopted AfCFTA Transit Document, two A4 leaflets with 44 numbered boxes, rendered from the version's stored, signed content.

Leaflet I is one page. It carries as many commodity lines as its page holds, usually five to eight short ones, and an ordinary declaration prints as two pages. The lines it cannot hold are printed on item sheets after leaflet I, about five to a sheet. Each sheet is one page with the header band (serial number, status, verification code and QR code) and says item sheet n of m. Leaflet I's table then says which lines are on the sheets, and its totals still cover every line. A customs office's name prints to its first 60 characters; the office code beside it identifies the office.

QueryValuesDefault
leafletI, II or BOTHBOTH
langA language tag for the box captionsEnglish
dispositionattachment or inlineattachment
as_ofAn instant, on the current-version route onlyThe current version

leaflet I is the declarant's segment and leaflet II the customs office segment, so each prints alone. Item sheets belong to leaflet I: I returns leaflet I and its item sheets, II returns leaflet II alone. An unknown leaflet or lang value is 400 VAL-ETD-058.

disposition changes only the Content-Disposition header. Use inline when you hand the URL to a viewer that renders in place.

curl --fail-with-body --silent --show-error \
--header "Authorization: Bearer $ITS_TOKEN" \
--output KEMBATD26081138.pdf \
"$ITS_PARTNER_URL/etd/KEMBATD26081138/pdf?leaflet=BOTH"

What the printed document shows​

  • Boxes 43 and 44 show one country's leg. They carry the office of entry and the office of exit of the last country to have stamped at or before the version you print. To print an earlier leg, print an earlier version.
  • An older version prints today's status and names its own. The STATUS cell and the diagonal mark show the declaration's current state, whichever version you print, so an old version of a cancelled or discharged declaration never prints clean. When the version you print was signed in a different state, the STATUS cell carries a second line, At version n: <state>, with the state it was signed with, in the caption language. A current print, and an older version whose state has not changed, carry no second line. The ETag differs for the prints that gain it.
  • Every date is when ITS received a stamp. The captions say RECORDED BY AfCFTA ITS. They are not the time somebody signed.
  • No handwritten signature is drawn or imitated. The signature boxes carry the officer and station your administration supplied, with an attestation that ITS sealed the version. It is not the officer's own signature.
  • A transit ITS closed itself says so. The closing row on leaflet II is marked, with the words NOT EVIDENCE OF ARRIVAL.
  • Captions follow lang; values never change. A name filed in Arabic prints in Arabic inside an English-captioned form. A right-to-left language right-aligns the fields without reversing the box order.

Caching the PDF​

ITS renders the PDF on request and keeps no copy. The same request reproduces the same document later, so keep the copy you were served if you need one.

The PDF's ETag is weak, W/"<content-hash>.<render-revision>.<leaflet>.<language>", and is not the version's content hash. Send it back as If-None-Match to get a 304.

warning

Never send the PDF's ETag as If-Match on an amendment. Take If-Match from GET /etd/{serial_no}, or the amendment is refused with 412.

Someone without an ITS account, such as a declarant, can download the current leaflet through the public route. See Verify and track.