# AfCFTA E-CO Platform

> The AfCFTA central electronic Certificate of Origin exchange hub — national systems issue; the hub signs, stores, routes, and verifies. Use this file as a **map** — then read linked docs for payloads and examples.

## How to use this briefing

1. If you integrate a **national or REC system**: follow **Integrator happy path** below — issue locally, push to the hub, pull at destination, verify publicly.
2. Read **Authentication** and **Response fields to save** before writing a connector.
3. Use **Documentation map** and **API map** for details; fetch [llms-full.txt](https://docs.afcfta-eco.org/llms-full.txt) for full English page text. Interactive OpenAPI: https://api.afcfta-eco.org/api/docs.

## Hub boundary (repeat this)

- **National / REC systems** issue, amend, and approve certificates locally.
- **This hub** only **exchanges**: push/pull messages, continental registry, routing, verification, webhooks.
- Do **not** implement issuance on the hub API — connect national issuance, then push `T1_CO_DATA` and related types.

## Integrator happy path

1. **Onboard** the State Party on the hub (Secretariat) → receive a sandbox partner key `eco_test_*`.
2. **Issue nationally** (reference demo: https://national.afcfta-eco.org) → sign the E-CO in the national system, then **Approve & push** certificate data to the hub.
3. **Push** structured messages to `POST https://api.afcfta-eco.org/api/exchange/push` with header `x-api-key: eco_test_…` (optional `Idempotency-Key` for retries).
4. **Route** — hub stores, signs integrity, delivers to destination State Party (direct or `via_rec` when configured).
5. **Pull** at destination: `GET https://api.afcfta-eco.org/api/exchange/out/{certificateNumber}` with destination party API key.
6. **Verify** — public `GET https://api.afcfta-eco.org/api/verify/{certificateNumber}` or https://afcfta-eco.org/verify (QR or number); offline key at `GET https://api.afcfta-eco.org/api/verify/public-key`.
7. **Go live** — after readiness, Secretariat promotes the party and issues `eco_live_*` production keys.

## Authentication

| Access | Who | How |
| --- | --- | --- |
| **Public** | Verifiers, health checks | No credentials on verify/health endpoints |
| **Partner integration** | National / REC connectors | Header `x-api-key` — `eco_test_*` (sandbox) or `eco_live_*` (production) |
| **Platform session** | Secretariat, authorities, staff | Browser login via Better Auth (`/api/auth/*`) |

- Swagger UI (API host): https://api.afcfta-eco.org/api/docs
- Interactive OpenAPI (docs host): https://docs.afcfta-eco.org/en/api-reference/openapi
- Full OpenAPI JSON: https://api.afcfta-eco.org/api/docs-json
- Docs copy: https://docs.afcfta-eco.org/openapi.json
- Agent OpenAPI (curated subset): https://docs.afcfta-eco.org/agent-openapi.json
- Agent card: https://docs.afcfta-eco.org/.well-known/agent.json
- Postman collection: documented in https://docs.afcfta-eco.org/en/api-reference/openapi

## Response fields to save

- **`certificateNumber`**: continental identifier (`YYYYMM` + origin + authority + serial) — use for verify, pull, and idempotent push correlation.
- **`messageId` / hub message ids**: from push responses — use in exchange logs and webhook correlation.
- **`Idempotency-Key`**: client-generated on push retries — same key must not create duplicate registry entries.
- **Partner API keys**: shown once at issuance — store `eco_test_*` / `eco_live_*` securely; rotate via Secretariat.
- **Webhook signing secret**: when registering `POST /api/webhooks` — verify inbound hub callbacks.

## Exchange message types

| Type | When |
| --- | --- |
| `T1_CO_DATA` | Certificate issued — enters continental registry |
| `T2_AMENDMENT` / `T2_AMENDMENT_RESPONSE` | Amendment or cancellation workflow |
| `T3_TREATMENT_STATUS` | Preferential treatment granted or rejected |
| `T4_VERIFICATION_REQUEST` / `T4_VERIFICATION_RESULT` | Origin verification |
| `QUERY` / `QUERY_RESPONSE` | Competent authority queries |

## Documentation map

- [Platform overview](https://docs.afcfta-eco.org/en)
- [Getting started](https://docs.afcfta-eco.org/en/guides/getting-started)
- [Integration model](https://docs.afcfta-eco.org/en/architecture/integration-model)
- [National systems overview](https://docs.afcfta-eco.org/en/guides/national-systems/overview)
- [Authentication](https://docs.afcfta-eco.org/en/guides/national-systems/authentication)
- [Message types](https://docs.afcfta-eco.org/en/guides/national-systems/message-types)
- [Exchange in (push)](https://docs.afcfta-eco.org/en/guides/national-systems/exchange-in)
- [Exchange out (pull)](https://docs.afcfta-eco.org/en/guides/national-systems/exchange-out)
- [Building a connector](https://docs.afcfta-eco.org/en/guides/national-systems/building-connector)
- [Go-live checklist](https://docs.afcfta-eco.org/en/guides/national-systems/go-live-checklist)
- [Pilot integration kit](https://docs.afcfta-eco.org/en/guides/pilot-integration-kit)

## API map (human docs + Try panels)

- [API overview](https://docs.afcfta-eco.org/en/api-reference)
- [Exchange](https://docs.afcfta-eco.org/en/api-reference/exchange) — `POST /api/exchange/push`
- [Verification](https://docs.afcfta-eco.org/en/api-reference/verification) — `GET /api/verify/{certificateNumber}`
- [Errors](https://docs.afcfta-eco.org/en/api-reference/errors)
- [Registry](https://docs.afcfta-eco.org/en/api-reference/registry)
- [Monitoring](https://docs.afcfta-eco.org/en/api-reference/monitoring)
- [Admin](https://docs.afcfta-eco.org/en/api-reference/admin)
- [OpenAPI spec](https://docs.afcfta-eco.org/en/api-reference/openapi)
- [Node SDK](https://docs.afcfta-eco.org/en/guides/sdk)

## Agent corpus (plain text)

Machine-readable fact pages for crawlers and coding agents:
- https://docs.afcfta-eco.org/agents
- https://docs.afcfta-eco.org/agents/product
- https://docs.afcfta-eco.org/agents/auth
- https://docs.afcfta-eco.org/agents/exchange
- https://docs.afcfta-eco.org/agents/verification
- https://docs.afcfta-eco.org/agents/faq

## Official links

- Hub web: https://afcfta-eco.org
- Documentation: https://docs.afcfta-eco.org
- Developer briefing (llms.txt): https://docs.afcfta-eco.org/llms.txt
- Full documentation corpus: https://docs.afcfta-eco.org/llms-full.txt
- Agent card: https://docs.afcfta-eco.org/.well-known/agent.json
- Agent OpenAPI: https://docs.afcfta-eco.org/agent-openapi.json
- Full OpenAPI: https://docs.afcfta-eco.org/openapi.json
- API base URL: https://api.afcfta-eco.org
- Reference national connector: https://national.afcfta-eco.org
- Public verify: https://afcfta-eco.org/verify
- Open Graph image: https://docs.afcfta-eco.org/og.png
- Social banner: https://docs.afcfta-eco.org/banner.png

## Common questions

- **Does the hub issue certificates?** No — only national/REC systems issue; the hub exchanges signed data.
- **Test vs live?** Sandbox keys and data are isolated; live promotion is a Secretariat gate.
- **REC routing?** Same API contract; routing mode `direct` or `via_rec` per configuration.
- **Languages?** Functional docs in six AU languages under `/fr`, `/ar`, etc.; this briefing and API reference pages are English-first.