Aller au contenu
Sur cette page

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
}'