Skip to content
On this page

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