EInvoicing
E-invoicing networks, registration, validation, and document submission
Get identifier requirements for a country
GET /api/v1/einvoicing/identifiers/requirements
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : einvoicing.view
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
country_code |
query | string | oui | |
nature |
query | string | non |
Réponses
| Statut | Description |
|---|---|
| 500 | |
| 200 | For non-paginated data, return as before |
| 422 |
Exemple de requête
curl -X GET "https://kworia.com/api/v1/einvoicing/identifiers/requirements" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
List e-invoicing invoices
GET /api/v1/einvoicing/invoices
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : einvoicing.view
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
status |
query | string | non | |
provider |
query | string | non | |
page |
query | integer | non | |
per_page |
query | integer | non |
Réponses
| Statut | Description |
|---|---|
| 200 | For non-paginated data, return as before |
| 422 |
Exemple de requête
curl -X GET "https://kworia.com/api/v1/einvoicing/invoices" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Submit an invoice to the e-invoicing network
POST /api/v1/einvoicing/invoices
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : einvoicing.send
provider est optionnel: il est résolu depuis l'entité légale de l'organisation (à défaut, depuis son pays), comme dans l'interface et via MCP; un provider qui n'est pas celui de l'organisation renvoie 422. L'Italie est bloquée dans les deux sens: un émetteur ou un destinataire italien renvoie 422 avant tout appel au prestataire. Le pays de l'acheteur enregistré est également contrôlé; modifier recipient_country_code ne permet pas de contourner le blocage. Le schéma d'identifiant compte aussi comme destination: un schéma italien (IT:IVA/0211, IT:CFI/0210, IT:CUUO/0201), fourni dans recipient_identifier_scheme ou enregistré sur la fiche client, est refusé de la même manière, avec un 422. Le message de refus coverage.gate.unavailable ne dépasse pas 200 caractères. La facturation ordinaire reste disponible pour les organisations italiennes existantes. Les Émirats arabes unis sont bloqués de la même manière, dans les deux sens.
Corps de la requête
| Champ | Type | Requis | Description |
|---|---|---|---|
organization_id |
integer | oui | |
invoice_id |
integer | oui | |
recipient_identifier_scheme |
string | oui | |
recipient_identifier_value |
string | oui | |
recipient_name |
string | oui | |
recipient_country_code |
string | oui | |
provider |
string | non | |
exchange_rate |
number | non | slice B (DGI rule 4): the exchange rate to XOF for an FNE B2F invoice in a foreign currency; stored on the invoice. |
Réponses
| Statut | Description |
|---|---|
| 500 | |
| 422 | |
| 201 | A degraded success (accepted by the network, audit record not written) is still 201: an error here would make the client retry a document that is already on the network. |
| 400 |
Exemple de requête
curl -X POST "https://kworia.com/api/v1/einvoicing/invoices" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"organization_id": 1,
"invoice_id": 1,
"recipient_identifier_scheme": "string",
"recipient_identifier_value": "string",
"recipient_name": "string",
"recipient_country_code": "string",
"provider": "string",
"exchange_rate": 1
}'
Get e-invoicing invoice details
GET /api/v1/einvoicing/invoices/{id}
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : einvoicing.view
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
id |
path | integer | oui |
Réponses
| Statut | Description |
|---|---|
| 200 | For non-paginated data, return as before |
Exemple de requête
curl -X GET "https://kworia.com/api/v1/einvoicing/invoices/{id}" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Get document evidence for an e-invoice
GET /api/v1/einvoicing/invoices/{id}/evidence
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : einvoicing.view
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
id |
path | integer | oui |
Réponses
| Statut | Description |
|---|---|
| 200 | For non-paginated data, return as before |
| 404 |
Exemple de requête
curl -X GET "https://kworia.com/api/v1/einvoicing/invoices/{id}/evidence" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Get e-invoice status and tracking information
GET /api/v1/einvoicing/invoices/{id}/status
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : einvoicing.view
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
id |
path | integer | oui |
Réponses
| Statut | Description |
|---|---|
| 200 | For non-paginated data, return as before |
Exemple de requête
curl -X GET "https://kworia.com/api/v1/einvoicing/invoices/{id}/status" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Get available e-invoicing networks
GET /api/v1/einvoicing/networks
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : einvoicing.view
The networks of the countries we serve, from the coverage rows: a network is listed only where we deliver over it today.
Réponses
| Statut | Description |
|---|---|
| 200 | For non-paginated data, return as before |
Exemple de requête
curl -X GET "https://kworia.com/api/v1/einvoicing/networks" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Search for a participant on the e-invoicing network
GET /api/v1/einvoicing/participants/search
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : einvoicing.view
provider est facultatif: le prestataire est déduit de l'entité légale de l'organisation (à défaut, de son pays), comme dans l'interface et via MCP; un provider qui n'est pas celui de l'organisation renvoie 422.
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
organization_id |
query | integer | oui | |
identifier_scheme |
query | string | oui | |
identifier_value |
query | string | oui | |
country_code |
query | string | oui | |
provider |
query | string | non |
Réponses
| Statut | Description |
|---|---|
| 500 | |
| 404 | |
| 200 | For non-paginated data, return as before For non-paginated data, return as before |
| 503 | |
| 422 |
Exemple de requête
curl -X GET "https://kworia.com/api/v1/einvoicing/participants/search" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Get available e-invoicing providers
GET /api/v1/einvoicing/providers
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : einvoicing.view
Réponses
| Statut | Description |
|---|---|
| 200 | For non-paginated data, return as before |
Exemple de requête
curl -X GET "https://kworia.com/api/v1/einvoicing/providers" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Inscrire l'organisation à la facturation électronique
POST /api/v1/einvoicing/register
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : einvoicing.configure
Crée l'entité légale et ses identifiants réseau via le service d'inscription partagé (même chemin que l'interface). Requiert identifier_scheme + identifier_value (p. ex. 0208, FR:SIRET, ou FR:CTC pour le maillage SIREN du CTC français) ainsi que legal_name, country_code et l'adresse; vat_number (optionnel) ajoute l'identifiant TVA du pays. Les identifiants FR:CTC portent l'annuaire DGFiP: annuaire_start_date fixe la date à partir de laquelle la ligne est routable pour la transmission et doit être au moins à deux jours (défaut et minimum: aujourd'hui + 2; une date antérieure renvoie 422), et les maillages avec code routage (SIREN_SIRET_coderoutage) exigent en plus routing_code_label + routing_code_address sous forme d'objet {line1, zip, city, country} — line1, zip et city sont obligatoires, country vaut FR par défaut (422 sinon). Le prestataire est résolu depuis le pays — un provider divergent renvoie 422. Les inscriptions en modèle réseau restent pending jusqu'à l'approbation superadmin. Renvoie la même forme que GET /einvoicing/registration.
Corps de la requête
| Champ | Type | Requis | Description |
|---|---|---|---|
organization_id |
integer | oui | |
legal_name |
string | oui | |
country_code |
string | oui | |
city |
string | oui | |
postal_code |
string | oui | |
address_line1 |
string | oui | |
address_line2 |
string | non | |
state |
string | non | |
identifier_scheme |
string | oui | |
identifier_value |
string | oui | |
vat_number |
string | non | |
tax_reference_id |
string | non | |
acts_as_sender |
boolean | non | |
acts_as_receiver |
boolean | non | |
tax_registered |
boolean | non | |
document_types |
array | non | |
provider |
string | non | |
annuaire_start_date |
string | non | FR:CTC annuaire/routing metadata; ignored for other schemes |
routing_code_label |
string | non | |
es_sii_registered |
boolean | non | Spanish tax-regime declaration: mandatory for ES, ignored elsewhere |
es_foral_territory |
string | non | |
routing_code_address |
object | non |
Réponses
| Statut | Description |
|---|---|
| 201 | For non-paginated data, return as before |
| 500 | |
| 422 |
Exemple de requête
curl -X POST "https://kworia.com/api/v1/einvoicing/register" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"organization_id": 1,
"legal_name": "string",
"country_code": "string",
"city": "string",
"postal_code": "string",
"address_line1": "string",
"address_line2": "string",
"state": "string",
"identifier_scheme": "string",
"identifier_value": "string",
"vat_number": "string",
"tax_reference_id": "string",
"acts_as_sender": true,
"acts_as_receiver": true,
"tax_registered": true,
"document_types": [],
"provider": "string",
"annuaire_start_date": "string",
"routing_code_label": "string",
"es_sii_registered": true,
"es_foral_territory": "string",
"routing_code_address": {}
}'
Get the e-invoicing registration status
GET /api/v1/einvoicing/registration
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : einvoicing.view
Registration status, roles and the network identifiers of the organization's legal entity. Each identifier row carries scheme, identifier, status and the verbatim networks_specification — for FR:CTC that is the dual peppol+dgfip block including the annuaire start_date.
Réponses
| Statut | Description |
|---|---|
| 200 | For non-paginated data, return as before For non-paginated data, return as before |
Exemple de requête
curl -X GET "https://kworia.com/api/v1/einvoicing/registration" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Update the e-invoicing registration scope/roles
PATCH /api/v1/einvoicing/registration
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : einvoicing.configure
Accepts acts_as_sender / acts_as_receiver and pushes the change to the network provider server-side (Storecove PATCH) when the entity is registered there; a failed provider push reverts the local change and returns 502. At least one role must stay enabled (422 otherwise). provider is accepted but must match the resolved provider — switching providers is a re-registration, not a scope update (422). Returns the same shape as the GET.
Corps de la requête
| Champ | Type | Requis | Description |
|---|---|---|---|
organization_id |
integer | oui | |
acts_as_sender |
boolean | non | |
acts_as_receiver |
boolean | non | |
provider |
string | non | |
es_sii_registered |
boolean | non | Re-declaration of the Spanish tax regime: both or neither. No 'sometimes' — it would skip required_with on the absent half. |
es_foral_territory |
string | non |
Réponses
| Statut | Description |
|---|---|
| 200 | For non-paginated data, return as before |
| 502 | |
| 422 | |
| 404 |
Exemple de requête
curl -X PATCH "https://kworia.com/api/v1/einvoicing/registration" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"organization_id": 1,
"acts_as_sender": true,
"acts_as_receiver": true,
"provider": "string",
"es_sii_registered": true,
"es_foral_territory": "string"
}'
Validate invoice before sending (preflight check)
POST /api/v1/einvoicing/validate
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : einvoicing.view
provider est optionnel: il est résolu depuis l'entité légale de l'organisation (à défaut, depuis son pays), comme dans l'interface et via MCP; un provider qui n'est pas celui de l'organisation renvoie 422. Un émetteur ou un destinataire italien renvoie data.valid=false avec le message partagé coverage.gate.unavailable, avant le contrôle préalable auprès du prestataire. Un schéma d'identifiant italien, fourni dans recipient_identifier_scheme ou enregistré sur la fiche client, donne le même résultat. Le statut HTTP reste 200 pour ce résultat de validation. Il en va de même pour un émetteur ou un destinataire situé aux Émirats arabes unis.
Corps de la requête
| Champ | Type | Requis | Description |
|---|---|---|---|
organization_id |
integer | oui | |
invoice_id |
integer | oui | |
recipient_identifier_scheme |
string | oui | |
recipient_identifier_value |
string | oui | |
recipient_name |
string | oui | |
recipient_country_code |
string | oui | |
provider |
string | non | |
exchange_rate |
number | non |
Réponses
| Statut | Description |
|---|---|
| 500 | |
| 200 | For non-paginated data, return as before |
| 422 |
Exemple de requête
curl -X POST "https://kworia.com/api/v1/einvoicing/validate" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"organization_id": 1,
"invoice_id": 1,
"recipient_identifier_scheme": "string",
"recipient_identifier_value": "string",
"recipient_name": "string",
"recipient_country_code": "string",
"provider": "string",
"exchange_rate": 1
}'