Banqup AFNOR Connector API
Technical Introduction
The Banqup AFNOR Connector API is an interface standardized under the French XP Z12-013 specification. It provides a uniform gateway to connect corporate Information Systems (IS), Dematerialization Operators (OD), and Compatible Solutions (SC) with Accredited Platforms (PA) for the data exchanges required by the French electronic invoicing reform. The API is built on a RESTful architecture and uses OAuth2 authentication to manage data transfers.
Architecture & Security Framework
Access control is enforced via OAuth2 using client credentials or authorization code grant flows. For end-to-end tracing across separate system boundaries, endpoints accept an optional metadata tracking parameter via the UUID-formatted Request-Id header. Operational uptime can be actively verified using the platform health check endpoint.
When the OAuth credential has access to more than one space, the header Organization-Id must be filled with the spaceId.
Data Models & Processing Logic
| Operational Component | Technical Classifications & Scope |
|---|---|
| Supported Syntaxes | CII, UBL, Factur-X, CDAR, and FRR mapped to Basic, CIUS, and Extended-CTC-FR profiles. |
| Flow Classifications | Customer, supplier, and state invoices; lifecycle tracking updates (CDAR); payment and transaction reports. |
| Transaction Scopes | Operational context rules covering B2B, B2B International, B2C, B2G, and B2G International frameworks. |
| Directory & Routing | Target resolution queries map addressing identifiers to distinct destination routing codes and platform types (WK or DFH). |
Detailed Endpoint Reference
⚠️ The webhook endpoints will be completely transformed when the latest AFNOR specification gets released.
| Category | HTTP Method | Path | Purpose |
|---|---|---|---|
| Siren | GET | /spaces/connectors/afnor/v1/siren/code-insee:{siren} | Fetch legal unit history and administrative profile by 9-digit SIREN. |
| Siren | POST | /spaces/connectors/afnor/v1/siren/search | Search companies using multiple match criteria. |
| Siret | GET | /spaces/connectors/afnor/v1/siret/code-insee:{siret} | Fetch establishment/facility profile by 14-digit SIRET. |
| Siret | POST | /spaces/connectors/afnor/v1/siret/search | Multi-criteria search for specific business facilities. |
| Directory | GET | /spaces/connectors/afnor/v1/directory-line/code:{addressingIdentifier} | Retrieve routing parameters for a specific business endpoint. |
| Directory | POST | /spaces/connectors/afnor/v1/directory-line/search | Dynamic multi-criteria platform directory queries. |
| Flow | POST | /spaces/connectors/afnor/v1/flows | Upload an electronic invoice, e-reporting, or lifecycle (CDAR) file. |
| Flow | POST | /spaces/connectors/afnor/v1/flows/search | Filter and query transaction flows by status or processing rules. |
| Flow | GET | /spaces/connectors/afnor/v1/flows/{flowId} | Download invoice metadata, original file, or transformed views. |
| Webhook | POST | /spaces/connectors/afnor/v1/webhooks | Subscribe a callback URL (Basic or OAuth2 auth supported) to flow changes. |
| Webhook | DELETE | /spaces/connectors/afnor/v1/webhooks/{webhookId} | Unsubscribe from an existing asynchronous event stream. |
| Supervisor | GET | /spaces/connectors/afnor/v1/healthcheck | Perform structural platform uptime monitoring. |
Interface Integration Behavior
Document ingestion requires a multipart/form-data POST request containing the binary document (application/pdf or application/xml) alongside a structured JSON metadata object (flowInfo) defining the payload attributes. Payloads can be validated for data integrity during transport using an optional SHA-256 hexadecimal fingerprint check.
When executing multi-criteria searches for directory lines, routing codes, corporate units (SIREN), or facilities (SIRET), collections that match more than 200 records are automatically truncated to the first 200 items and returned with an HTTP 206 Partial Content status unless a smaller limit is explicitly defined in the payload. ⚠️ In AFNOR v1.3 the HTTP206 status no longer exists. Instead, no data will be returned if the result set is too large.
All application exceptions are standardized under a uniform JSON schema detailing an errorCode, an errorMessage, functional details, and an instance URI context. Common technical error definitions include MISSING_REQUIRED_FIELD, UNPROCESSABLE_ENTITY, FILE_SIZE_EXCEEDED, and TOO_MANY_REQUESTS.