AdvancedFeatures
Credit notes and invoice templates
List credit notes for the authenticated organization
GET /api/v1/credit-notes
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : credit_notes.view
Returns paginated credit notes filtered by organization_id, eager-loading the customer and original invoice relationships.
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
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/credit-notes" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Create a credit note from an invoice
POST /api/v1/credit-notes
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : credit_notes.create
Création rapide d'un avoir lié à une facture existante (invoice_id, amount, reason, credit_type facultatif). Le champ facultatif credit_note_type_code définit le code de type UNCL1001: les routes nationales FR (vendeur français et client français) acceptent 261, 262, 381, 396, 502, 503; toutes les autres routes acceptent la liste Peppol BIS 81, 83, 381, 396, 532 (422 dans le cas contraire). Il est enregistré sur l'avoir et écrit dans l'UBL et le CII (Factur-X) de l'avoir lorsqu'ils sont générés. Les avoirs ne sont pas transmis via le réseau PEPPOL par cette API. S'il est omis, la valeur 381 est utilisée lors de l'envoi. Le montant amount ne doit pas dépasser ce qu'il reste à créditer sur la facture (son total moins ses avoirs qui ne sont ni annulés ni invalidés); sinon la réponse est 422 avec error_code: credit_limit_exceeded, la phrase figurant dans error et message (par exemple "Credit note total (30.00) exceeds the creditable amount (21.00) for invoice INV-2026-0001.") et aucun détail par champ dans errors; rien n'est créé.
Corps de la requête
| Champ | Type | Requis | Description |
|---|---|---|---|
invoice_id |
integer | oui | |
amount |
number | oui | |
reason |
string | oui | |
credit_type |
string | non | |
credit_note_type_code |
string | non |
Réponses
| Statut | Description |
|---|---|
| 201 | For non-paginated data, return as before |
| 422 |
Exemple de requête
curl -X POST "https://kworia.com/api/v1/credit-notes" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"invoice_id": 1,
"amount": 1,
"reason": "string",
"credit_type": "string",
"credit_note_type_code": "string"
}'
Show a credit note with its line items
GET /api/v1/credit-notes/{id}
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : credit_notes.view
Single-resource fetch mirroring the invoice/quote detail endpoints; includes items, customer and original_invoice.
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/credit-notes/{id}" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Download the credit-note PDF
GET /api/v1/credit-notes/{id}/pdf
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : credit_notes.view
Binary PDF, like the invoice/quote PDF endpoints. FNE (Côte d'Ivoire) organizations get the regulatory CI template with stamping/QR data automatically.
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
id |
path | integer | oui |
Réponses
| Statut | Description |
|---|---|
| 200 |
Exemple de requête
curl -X GET "https://kworia.com/api/v1/credit-notes/{id}/pdf" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Send the credit note to the customer
POST /api/v1/credit-notes/{id}/send
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : credit_notes.create
Transmet l'avoir via le portail sécurisé de documents et par e-mail. recipients[] est facultatif (par défaut, l'adresse e-mail du client) ainsi que message. Un avoir en brouillon passe à sent uniquement après au moins une transmission réussie; si toutes les transmissions échouent, la réponse est 422 avec error_code: delivery_failed (utilisez-le pour le traitement; error et message sont des textes d'affichage), un message par destinataire dans errors, et un code stable par destinataire dans error_codes (delivery_failed, pdf_generation_failed, fiscal_storage_unavailable, recipient_has_no_email, invalid_sender_email,...). Un échec que le service n'avait pas prévu renvoie un message générique accompagné d'une référence à communiquer au support, jamais le texte de l'exception. L'envoi d'un brouillon l'émet: si son total dépasse ce qu'il reste à créditer sur la facture (son total moins les avoirs déjà émis, sent ou applied), rien n'est transmis, l'avoir reste en brouillon, et la réponse est 422 avec error_code: credit_limit_exceeded et la même phrase qu'à la création.
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
id |
path | integer | oui |
Corps de la requête
| Champ | Type | Requis | Description |
|---|---|---|---|
resend |
boolean | non | |
contact_ids |
array | non |
Réponses
| Statut | Description |
|---|---|
| 200 | For non-paginated data, return as before |
| 422 | |
| 409 |
Exemple de requête
curl -X POST "https://kworia.com/api/v1/credit-notes/{id}/send" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"resend": true,
"contact_ids": []
}'
List templates
GET /api/v1/templates
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : invoices.view
Réponses
| Statut | Description |
|---|---|
| 501 |
Exemple de requête
curl -X GET "https://kworia.com/api/v1/templates" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Create invoice template
POST /api/v1/templates
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : invoices.create
Réponses
| Statut | Description |
|---|---|
| 501 |
Exemple de requête
curl -X POST "https://kworia.com/api/v1/templates" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Create invoice from template
POST /api/v1/templates/{templateId}/create-invoice
Nécessite une authentification (jeton Bearer) et l’en-tête X-Organization-Id.
Portée du jeton API : invoices.create
Paramètres
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
templateId |
path | integer | oui |
Réponses
| Statut | Description |
|---|---|
| 501 |
Exemple de requête
curl -X POST "https://kworia.com/api/v1/templates/{templateId}/create-invoice" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"