EInvoicing
E-invoicing networks, registration, validation, and document submission
Get identifier requirements for a country
GET /api/v1/einvoicing/identifiers/requirements
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: einvoicing.view
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
country_code |
query | string | yes | |
nature |
query | string | no |
Responses
| Status | Description |
|---|---|
| 500 | |
| 200 | For non-paginated data, return as before |
| 422 |
Example request
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
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: einvoicing.view
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
status |
query | string | no | |
provider |
query | string | no | |
page |
query | integer | no | |
per_page |
query | integer | no |
Responses
| Status | Description |
|---|---|
| 200 | For non-paginated data, return as before |
| 422 |
Example request
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
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: einvoicing.send
provider is optional: it is resolved from the organization's legal entity (else its country), as in the app and MCP; a provider that is not the organization's returns 422. Italy is gated in both directions: an Italian sender or receiver returns 422 before any provider call. The stored buyer country is also checked; changing recipient_country_code cannot bypass the gate. The identifier scheme counts as a destination too: an Italian scheme (IT:IVA/0211, IT:CFI/0210, IT:CUUO/0201), supplied in recipient_identifier_scheme or stored on the customer, returns 422 the same way. The coverage.gate.unavailable refusal is at most 200 characters. Ordinary invoicing remains available for existing Italian organizations. The United Arab Emirates are gated the same way, in both directions.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
organization_id |
integer | yes | |
invoice_id |
integer | yes | |
recipient_identifier_scheme |
string | yes | |
recipient_identifier_value |
string | yes | |
recipient_name |
string | yes | |
recipient_country_code |
string | yes | |
provider |
string | no | |
exchange_rate |
number | no | slice B (DGI rule 4): the exchange rate to XOF for an FNE B2F invoice in a foreign currency; stored on the invoice. |
Responses
| Status | 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 |
Example request
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}
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: einvoicing.view
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | integer | yes |
Responses
| Status | Description |
|---|---|
| 200 | For non-paginated data, return as before |
Example request
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
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: einvoicing.view
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | integer | yes |
Responses
| Status | Description |
|---|---|
| 200 | For non-paginated data, return as before |
| 404 |
Example request
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
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: einvoicing.view
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | integer | yes |
Responses
| Status | Description |
|---|---|
| 200 | For non-paginated data, return as before |
Example request
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
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: einvoicing.view
The networks of the countries we serve, from the coverage rows: a network is listed only where we deliver over it today.
Responses
| Status | Description |
|---|---|
| 200 | For non-paginated data, return as before |
Example request
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
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: einvoicing.view
provider is optional: it is resolved from the organization's legal entity
(else its country), as in the app and MCP; a provider that is not the
organization's returns 422.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
organization_id |
query | integer | yes | |
identifier_scheme |
query | string | yes | |
identifier_value |
query | string | yes | |
country_code |
query | string | yes | |
provider |
query | string | no |
Responses
| Status | Description |
|---|---|
| 500 | |
| 404 | |
| 200 | For non-paginated data, return as before For non-paginated data, return as before |
| 503 | |
| 422 |
Example request
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
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: einvoicing.view
Responses
| Status | Description |
|---|---|
| 200 | For non-paginated data, return as before |
Example request
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"
Register the organization for e-invoicing
POST /api/v1/einvoicing/register
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: einvoicing.configure
Creates the legal entity and its network identifiers through the shared registration service (same path as the app UI). Requires identifier_scheme + identifier_value (e.g. 0208, FR:SIRET, or FR:CTC for the French CTC SIREN mesh) plus legal_name, country_code and address fields; optional vat_number adds the country VAT identifier. FR:CTC identifiers carry the DGFiP annuaire: annuaire_start_date sets when the line becomes routable and must be at least two days out (default and minimum: today + 2; earlier dates return 422), and routing-code meshes (SIREN_SIRET_routingcode) additionally require routing_code_label + routing_code_address as an object {line1, zip, city, country} — line1, zip and city are mandatory, country defaults to FR (422 without them). The provider is resolved from the country — a mismatching provider returns 422. Network-model registrations stay pending until superadmin approval; the provider is never called at this point. Returns the same shape as GET /einvoicing/registration. A country_code whose onboarding is gated (see /coverage, e.g. Spain until VeriFactu conformance) returns 422 on country_code unless the organization itself is established in that country.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
organization_id |
integer | yes | |
legal_name |
string | yes | |
country_code |
string | yes | |
city |
string | yes | |
postal_code |
string | yes | |
address_line1 |
string | yes | |
address_line2 |
string | no | |
state |
string | no | |
identifier_scheme |
string | yes | |
identifier_value |
string | yes | |
vat_number |
string | no | |
tax_reference_id |
string | no | |
acts_as_sender |
boolean | no | |
acts_as_receiver |
boolean | no | |
tax_registered |
boolean | no | |
document_types |
array | no | |
provider |
string | no | |
annuaire_start_date |
string | no | FR:CTC annuaire/routing metadata; ignored for other schemes |
routing_code_label |
string | no | |
es_sii_registered |
boolean | no | Spanish tax-regime declaration: mandatory for ES, ignored elsewhere |
es_foral_territory |
string | no | |
routing_code_address |
object | no |
Responses
| Status | Description |
|---|---|
| 201 | For non-paginated data, return as before |
| 500 | |
| 422 |
Example request
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
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: 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.
Responses
| Status | Description |
|---|---|
| 200 | For non-paginated data, return as before For non-paginated data, return as before |
Example request
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
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: 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.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
organization_id |
integer | yes | |
acts_as_sender |
boolean | no | |
acts_as_receiver |
boolean | no | |
provider |
string | no | |
es_sii_registered |
boolean | no | 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 | no |
Responses
| Status | Description |
|---|---|
| 200 | For non-paginated data, return as before |
| 502 | |
| 422 | |
| 404 |
Example request
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
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: einvoicing.view
provider is optional: it is resolved from the organization's legal entity (else its country), as in the app and MCP; a provider that is not the organization's returns 422. An Italian sender or receiver returns data.valid=false with the shared coverage.gate.unavailable message, before provider preflight. An Italian identifier scheme, supplied in recipient_identifier_scheme or stored on the customer, gives the same result. HTTP remains 200 for this validation result. The same applies to a sender or receiver in the United Arab Emirates.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
organization_id |
integer | yes | |
invoice_id |
integer | yes | |
recipient_identifier_scheme |
string | yes | |
recipient_identifier_value |
string | yes | |
recipient_name |
string | yes | |
recipient_country_code |
string | yes | |
provider |
string | no | |
exchange_rate |
number | no |
Responses
| Status | Description |
|---|---|
| 500 | |
| 200 | For non-paginated data, return as before |
| 422 |
Example request
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
}'