Customer
Customer management, archival, and per-customer statistics
Display a listing of customers
GET /api/v1/customers
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : customers.view
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
search |
query | string | non | |
is_active |
query | string | non | |
sort |
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/customers" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Store a newly created customer
POST /api/v1/customers
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : customers.create
vat_number est LE numéro de TVA du client: il devient l'identifiant TVA de l'acheteur sur les factures électroniques (EN 16931 BT-48), dans tous les pays. tax_number est l'identifiant fiscal local, jamais utilisé comme numéro de TVA. Un client professionnel italien adressé par son codice destinatario (einvoicing_identifier_scheme IT:CUUO) doit avoir un vat_number: sans lui, la transmission d'une facture électronique est refusée avant tout envoi. Les deux champs sont stockés chiffrés et renvoyés déchiffrés à l'organisation propriétaire. Envoyer null ou une chaîne vide efface un champ; l'omettre le laisse inchangé.
Corps de la requête
| Champ | Type | Requis | Description |
|---|---|---|---|
name |
string | oui | |
email |
string | non | |
phone |
string | non | |
website |
string | non | |
tax_number |
string | non | |
vat_number |
string | non | THE buyer VAT number (BT-48,); tax_number stays the local tax id. |
address_line1 |
string | non | |
address_line2 |
string | non | |
city |
string | non | |
state |
string | non | |
postal_code |
string | non | |
country |
string | non | |
billing_subdivision_code |
string | non | ISO 3166-2 subdivision code for the billing address (e.g. CA-QC). Validated against the country_subdivisions reference table. |
shipping_subdivision_code |
string | non | ISO 3166-2 subdivision code for the shipping address (e.g. CA-QC). Validated against the country_subdivisions reference table. |
notes |
string | non | |
language |
string | non | Customer locale defaults and e-invoicing network identifier. Scheme and value only make sense together; either both or neither. |
currency |
string | non | |
einvoicing_identifier_scheme |
string | non | |
einvoicing_identifier_value |
string | non |
Réponses
| Statut | Description |
|---|---|
| 201 | For non-paginated data, return as before |
| 422 | |
| 403 |
Exemple de requête
curl -X POST "https://kworia.com/api/v1/customers" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"email": "string",
"phone": "string",
"website": "string",
"tax_number": "string",
"vat_number": "string",
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"postal_code": "string",
"country": "string",
"billing_subdivision_code": "string",
"shipping_subdivision_code": "string",
"notes": "string",
"language": "string",
"currency": "string",
"einvoicing_identifier_scheme": "string",
"einvoicing_identifier_value": "string"
}'
Display the specified customer
GET /api/v1/customers/{id}
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : customers.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/customers/{id}" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Update the specified customer
PUT /api/v1/customers/{id}
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : customers.update
vat_number est LE numéro de TVA du client: il devient l'identifiant TVA de l'acheteur sur les factures électroniques (EN 16931 BT-48), dans tous les pays. tax_number est l'identifiant fiscal local, jamais utilisé comme numéro de TVA. Un client professionnel italien adressé par son codice destinatario (einvoicing_identifier_scheme IT:CUUO) doit avoir un vat_number: sans lui, la transmission d'une facture électronique est refusée avant tout envoi. Les deux champs sont stockés chiffrés et renvoyés déchiffrés à l'organisation propriétaire. Envoyer null ou une chaîne vide efface un champ; l'omettre le laisse inchangé.
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
id |
path | integer | oui |
Corps de la requête
| Champ | Type | Requis | Description |
|---|---|---|---|
name |
string | non | |
email |
string | non | |
phone |
string | non | |
website |
string | non | |
tax_number |
string | non | |
vat_number |
string | non | THE buyer VAT number (BT-48,); tax_number stays the local tax id. |
address_line1 |
string | non | |
address_line2 |
string | non | |
city |
string | non | |
state |
string | non | |
postal_code |
string | non | |
country |
string | non | |
billing_subdivision_code |
string | non | ISO 3166-2 subdivision code for the billing address (e.g. CA-QC). Validated against the country_subdivisions reference table. |
shipping_subdivision_code |
string | non | ISO 3166-2 subdivision code for the shipping address (e.g. CA-QC). Validated against the country_subdivisions reference table. |
notes |
string | non | |
language |
string | non | Customer locale defaults and e-invoicing network identifier. Scheme and value only make sense together; either both or neither. |
currency |
string | non | |
einvoicing_identifier_scheme |
string | non | |
einvoicing_identifier_value |
string | non |
Réponses
| Statut | Description |
|---|---|
| 200 | For non-paginated data, return as before |
| 422 | |
| 403 |
Exemple de requête
curl -X PUT "https://kworia.com/api/v1/customers/{id}" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"email": "string",
"phone": "string",
"website": "string",
"tax_number": "string",
"vat_number": "string",
"address_line1": "string",
"address_line2": "string",
"city": "string",
"state": "string",
"postal_code": "string",
"country": "string",
"billing_subdivision_code": "string",
"shipping_subdivision_code": "string",
"notes": "string",
"language": "string",
"currency": "string",
"einvoicing_identifier_scheme": "string",
"einvoicing_identifier_value": "string"
}'
Remove the specified customer
DELETE /api/v1/customers/{id}
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : customers.delete
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 DELETE "https://kworia.com/api/v1/customers/{id}" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Get customer's invoices
GET /api/v1/customers/{id}/invoices
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : customers.view
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
id |
path | integer | oui | |
status |
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/customers/{id}/invoices" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Get customer's quotes
GET /api/v1/customers/{id}/quotes
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : customers.view
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
id |
path | integer | oui | |
status |
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/customers/{id}/quotes" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Customer statement of account
GET /api/v1/customers/{id}/statement
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : customers.view
Opening balance, invoice/payment/credit-note entries and closing balance for the period (date_from/date_to required), in the organization currency.
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
id |
path | integer | oui | |
date_from |
query | string | oui | |
date_to |
query | string | oui |
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/customers/{id}/statement" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Get customer statistics
GET /api/v1/customers/{id}/statistics
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : customers.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/customers/{id}/statistics" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Validate the customer's e-invoicing identifier on the network
GET /api/v1/customers/{id}/validate-network
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : customers.view
Looks up the customer's stored einvoicing_identifier_scheme/einvoicing_identifier_value on the e-invoicing network of the provider resolved for the customer's country, and persists a successful verification (einvoicing_identifier_verified). Returns 422 when the customer has no identifier stored, when no country can be resolved (the customer country, billing country, or a country-specific identifier scheme all absent), or when the resolved provider (e.g. FNE clearance countries) does not support participant lookup. When the customer has no stored country it is inferred from a country-specific identifier scheme (e.g. 0208 → BE). A verified: false result never clears an earlier successful verification, because provider transport errors are indistinguishable from a genuine not-found.
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
id |
path | integer | oui |
Réponses
| Statut | Description |
|---|---|
| 422 | |
| 200 | For non-paginated data, return as before |
Exemple de requête
curl -X GET "https://kworia.com/api/v1/customers/{id}/validate-network" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"