Skip to main content

Before you begin

Have these ready before you make your first call to ITS.

Your organisation is admitted​

The AfCFTA Secretariat admits your organisation. Until it does, you cannot get credentials.

Admission alone does not let you lodge declarations. The Secretariat also records which countries your organisation may act for:

  • a State Party acts for its own country once its participation is recorded;
  • a REC acts only for the member States that have delegated submission to it.

Until the Secretariat records that arrangement, ITS refuses every declaration you send with AUTHZ-ETD-017. That is the system working as designed, not a broken permission.

Access to the System integration workspace​

A technical contact in your organisation needs to sign in to the ITS portal's System integration workspace. That is where you:

  • generate and rotate your client credentials, one per environment;
  • register the client certificate your system presents;
  • register the source addresses your system calls from, where your connection needs them;
  • declare the receiving endpoint where ITS announces changes to you.
note

A step-by-step onboarding guide for the workspace is coming.

A secret store​

The client secret is shown once, when you generate or rotate it.

  • Keep the client secret and your certificate's private key in a protected secret manager or in protected environment variables.
  • Never put them in source code, browser code, screenshots, logs, email or support tickets.
  • Keep Sandbox and Production credentials apart. Each environment has its own.

A client certificate​

Every call to the gateway uses mutual TLS. Your system presents an X.509 client certificate and its private key. Register the certificate in the workspace, and wait for the Secretariat to approve it, before you rely on it.

A system that can call HTTPS JSON APIs​

Your system must be able to:

  • send JSON over HTTPS with a client certificate;
  • send custom request headers, including Idempotency-Key and If-Match;
  • keep a token in memory and renew it before it expires;
  • retry a request with exactly the same body and the same Idempotency-Key.

JSON property names are snake_case throughout. Requests and responses wrap their payload in data.

Your customs data​

To lodge a test declaration you need:

  • your country's ISO 3166-1 alpha-2 code, for example KE;
  • the three-character code of a customs office in your country, for example MBA;
  • a destination country and one of its customs offices;
  • HS codes, package kinds and currencies from the ITS reference data. See Reference data.

ITS records a taxpayer identification number (TIN) exactly as you send it and does not check its format. Validate your own taxpayer numbers before you submit.

Use synthetic test data in Sandbox. Do not use real traders' records.

Accurate clocks and time zones​

ITS stamps every act with its own database clock, in UTC. You never send a stamp time. Keep your own server clocks accurate anyway, because you compare ITS times with your own logs.

Next step​

Read Authentication.