Aller au contenu
Sur cette page

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"