Référence de l'API

Factures

Les factures avec leurs lignes et leurs paiements : les rédiger, les modifier tant qu'elles sont des brouillons, les envoyer, les annuler et enregistrer des paiements.

Endpoints

GET /invoices Lister les factures
GET /invoices/{invoice} Récupérer une facture
POST /invoices Créer une facture
PATCH /invoices/{invoice} Modifier une facture
POST /invoices/{invoice}/send Envoyer une facture
POST /invoices/{invoice}/cancel Annuler une facture
POST /invoices/{invoice}/payments Enregistrer un paiement
DELETE /invoices/{invoice} Supprimer une facture

Lister les factures

GET /api/v1/invoices

Une liste de factures, les plus récentes d'abord, avec leurs lignes et les paiements enregistrés. Filtrez par statut, client ou date de modification. Avec filter[status]=paid et filter[updated_since], vous récupérez ce qui a été payé depuis votre dernière synchronisation.

Scope: invoices.read — Lire les factures, avec leurs lignes, leurs montants, les paiements et les coordonnées du client
Fonctionnalité requise: invoices

Paramètres de requête

Nom	Type	Description
`limit`	integer	Nombre de résultats par page. de 1 à 100 · par défaut : 50
`cursor`	string	Le next_cursor ou prev_cursor de meta dans la réponse précédente.
`sort`	string	Tri par created_at ou updated_at ; un signe moins devant trie par ordre décroissant. l'une des valeurs : -created_at, created_at, -updated_at, updated_at · par défaut : -created_at
`filter[status]`	string	Uniquement les factures avec ce statut, par exemple paid ou overdue. l'une des valeurs : draft, sent, viewed, paid, partial, overdue, cancelled, refunded
`filter[customer_id]`	string (uuid)	Uniquement ce qui appartient à ce client.
`filter[updated_since]`	string (date-time)	Uniquement ce qui a changé depuis ce moment : ISO 8601 avec fuseau horaire, par exemple 2026-09-14T10:15:00Z. Pratique pour synchroniser.

Exemple de requête

cURL

curl "https://app.klantly.com/api/v1/invoices?filter[status]=paid&sort=-updated_at" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"

PHP

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'invoices', [
    'query' => [
        'filter[status]' => 'paid',
        'sort' => '-updated_at',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];

JavaScript

const response = await fetch('https://app.klantly.com/api/v1/invoices?filter[status]=paid&sort=-updated_at', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();

Python

import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/invoices",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
    params={
        "filter[status]": "paid",
        "sort": "-updated_at"
    },
)
data = response.json()["data"]

Réponse 200

La réponse est une liste avec pagination par curseur : data contient les objets, meta la pagination.

Exemple de réponse

{
  "data": [
    {
      "object": "invoice",
      "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
      "number": "FAC-00042",
      "status": "sent",
      "title": "Veranda 400 × 300",
      "description": null,
      "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
      "customer": {
        "type": "business",
        "name": "De Vries Bouw",
        "email": "jan@example.com",
        "phone": "+31 6 12345678",
        "address": "Dorpsstraat 1",
        "postal_code": "3511 AB",
        "city": "Utrecht",
        "country": "NL",
        "company_name": "De Vries Bouw",
        "vat_number": null,
        "coc_number": null
      },
      "quote_id": "9d3f8449-afe1-4a6e-9dbc-c1dfe0f1a2ba",
      "deal_id": null,
      "language": "nl",
      "currency": "EUR",
      "invoice_date": "2026-09-16",
      "due_date": "2026-10-16",
      "payment_term_days": 30,
      "is_term_invoice": false,
      "term_percentage": null,
      "terms_conditions": null,
      "notes": null,
      "outro_text": null,
      "hide_line_amounts": false,
      "discount_percentage": "0.00",
      "discount_amount": "0.00",
      "discount_description": null,
      "subtotal": "2450.00",
      "tax_amount": "514.50",
      "total": "2964.50",
      "amount_paid": "0.00",
      "amount_due": "2964.50",
      "sent_at": null,
      "viewed_at": null,
      "paid_at": null,
      "cancelled_at": null,
      "items": [
        {
          "object": "invoice_item",
          "id": "9d3f87ac-d2b4-4d9b-8aef-f4a2b3c4d5ee",
          "type": "product",
          "name": "Veranda",
          "description": null,
          "sku": null,
          "quantity": "1.00",
          "unit": "stuk",
          "unit_price": "2450.00",
          "unit_price_incl": null,
          "discount_percentage": "0.00",
          "discount_amount": "0.00",
          "discount_description": null,
          "line_total": "2450.00",
          "line_total_incl": null,
          "is_taxable": true,
          "tax_rate": "21.00"
        }
      ],
      "payments": [
        {
          "object": "invoice_payment",
          "id": "9d3f88cd-e3c5-4eac-9bf0-a5b3c4d5e6ff",
          "amount": "2964.50",
          "type": "full",
          "status": "paid",
          "payment_method": "bank_transfer",
          "description": null,
          "paid_at": "2026-09-16T10:15:00Z",
          "created_at": "2026-09-16T10:15:00Z"
        }
      ],
      "created_at": "2026-09-14T10:15:00Z",
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ],
  "meta": {
    "limit": 50,
    "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0",
    "prev_cursor": null
  }
}

Erreurs possibles

403 insufficient_scope — Cette clé API n'a pas accès à cette action.
422 validation_failed — Les données saisies ne sont pas valides.

En outre, chaque endpoint peut renvoyer les erreurs générales, comme une clé invalide ou une limite atteinte. Voir tous les codes d'erreur.

Récupérer une facture

GET /api/v1/invoices/{invoice}

Une facture par id, avec ses lignes, ses montants et ses paiements. La réponse contient un ETag que vous pouvez renvoyer dans If-Match lors d'une modification.

Scope: invoices.read — Lire les factures, avec leurs lignes, leurs montants, les paiements et les coordonnées du client
Fonctionnalité requise: invoices

Paramètres de chemin

Nom	Type	Description
`invoice` obligatoire	string (uuid)	L'id (UUID) de la facture.

Exemple de requête

cURL

curl "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"

PHP

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70');

$data = json_decode((string) $response->getBody(), true)['data'];

JavaScript

const response = await fetch('https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();

Python

import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Réponse 200

Exemple de réponse

{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "status": "sent",
    "title": "Veranda 400 × 300",
    "description": null,
    "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "customer": {
      "type": "business",
      "name": "De Vries Bouw",
      "email": "jan@example.com",
      "phone": "+31 6 12345678",
      "address": "Dorpsstraat 1",
      "postal_code": "3511 AB",
      "city": "Utrecht",
      "country": "NL",
      "company_name": "De Vries Bouw",
      "vat_number": null,
      "coc_number": null
    },
    "quote_id": "9d3f8449-afe1-4a6e-9dbc-c1dfe0f1a2ba",
    "deal_id": null,
    "language": "nl",
    "currency": "EUR",
    "invoice_date": "2026-09-16",
    "due_date": "2026-10-16",
    "payment_term_days": 30,
    "is_term_invoice": false,
    "term_percentage": null,
    "terms_conditions": null,
    "notes": null,
    "outro_text": null,
    "hide_line_amounts": false,
    "discount_percentage": "0.00",
    "discount_amount": "0.00",
    "discount_description": null,
    "subtotal": "2450.00",
    "tax_amount": "514.50",
    "total": "2964.50",
    "amount_paid": "0.00",
    "amount_due": "2964.50",
    "sent_at": null,
    "viewed_at": null,
    "paid_at": null,
    "cancelled_at": null,
    "items": [
      {
        "object": "invoice_item",
        "id": "9d3f87ac-d2b4-4d9b-8aef-f4a2b3c4d5ee",
        "type": "product",
        "name": "Veranda",
        "description": null,
        "sku": null,
        "quantity": "1.00",
        "unit": "stuk",
        "unit_price": "2450.00",
        "unit_price_incl": null,
        "discount_percentage": "0.00",
        "discount_amount": "0.00",
        "discount_description": null,
        "line_total": "2450.00",
        "line_total_incl": null,
        "is_taxable": true,
        "tax_rate": "21.00"
      }
    ],
    "payments": [
      {
        "object": "invoice_payment",
        "id": "9d3f88cd-e3c5-4eac-9bf0-a5b3c4d5e6ff",
        "amount": "2964.50",
        "type": "full",
        "status": "paid",
        "payment_method": "bank_transfer",
        "description": null,
        "paid_at": "2026-09-16T10:15:00Z",
        "created_at": "2026-09-16T10:15:00Z"
      }
    ],
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Erreurs possibles

403 insufficient_scope — Cette clé API n'a pas accès à cette action.
404 not_found — Introuvable.

En outre, chaque endpoint peut renvoyer les erreurs générales, comme une clé invalide ou une limite atteinte. Voir tous les codes d'erreur.

Créer une facture

POST /api/v1/invoices

Crée une facture pour un client, toujours en brouillon. Klantly attribue le numéro et calcule les totaux ; le nom, l'adresse et les coordonnées proviennent du client. Avec quote_id, vous la reliez à un devis.

Scope: invoices.write — Créer et modifier des factures (brouillons uniquement), les annuler et enregistrer des paiements
Fonctionnalité requise: invoices

Envoyez une Idempotency-Key : une nouvelle tentative après un délai d'attente ne crée alors jamais de doublon.

Corps (JSON)

Champ	Type	Description
`customer_id` obligatoire	string (uuid)	Le client. Obligatoire à la création ; le nom, l'adresse et les coordonnées proviennent du client.
`title` obligatoire	string	Titre de la facture. Obligatoire à la création. au maximum 255 caractères
`items` obligatoire	array	Les lignes (200 au maximum). À l'envoi : une liste avec, par ligne, name (obligatoire) et éventuellement type, description, sku, quantity, unit, unit_price, unit_price_incl, discount_percentage, discount_amount, discount_description, tax_rate et is_taxable. Elles remplacent toutes les lignes existantes.
`quote_id` facultatif	string (uuid)	Le devis dont provient cette facture, ou null. peut être vide (null)
`description` facultatif	string	Brève description ; affichée au-dessus des lignes. peut être vide (null) · au maximum 20000 caractères
`language` facultatif	string	Langue de la facture : nl, en, de ou fr. l'une des valeurs : nl, en, de, fr
`invoice_date` facultatif	string (date)	Date de facture (AAAA-MM-JJ).
`due_date` facultatif	string (date)	Date d'échéance (AAAA-MM-JJ). Sans indication, c'est la date de facture plus le délai de paiement.
`payment_term_days` facultatif	integer	Délai de paiement en jours. Sans indication, le délai par défaut de l'entreprise s'applique. de 0 à 365
`terms_conditions` facultatif	string	Conditions figurant sur la facture. peut être vide (null) · au maximum 20000 caractères
`notes` facultatif	string	Remarques pour le client sur la facture. Lors de l'enregistrement d'un paiement : une note sur ce paiement. peut être vide (null) · au maximum 20000 caractères
`outro_text` facultatif	string	Texte de clôture sous les lignes. peut être vide (null) · au maximum 20000 caractères
`hide_line_amounts` facultatif	boolean	Masque les montants par ligne sur la facture ; le client ne voit que le total.
`discount_percentage` facultatif	number	Remise sur le total, en pourcentage. de 0 à 100
`discount_amount` facultatif	number	Remise sur le total, en montant. de 0 à 9999999
`discount_description` facultatif	string	Pourquoi la remise a été accordée ; figure sur la facture. peut être vide (null) · au maximum 500 caractères

Exemple de requête

cURL

curl -X POST "https://app.klantly.com/api/v1/invoices" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f" \
  -d '{
  "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
  "title": "Veranda 400 × 300",
  "items": [
    {
      "name": "Veranda",
      "quantity": 1,
      "unit_price": "2450.00",
      "tax_rate": "21.00"
    }
  ]
}'

PHP

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'invoices', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
    'json' => [
        'customer_id' => '9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70',
        'title' => 'Veranda 400 × 300',
        'items' => [
            0 => [
                'name' => 'Veranda',
                'quantity' => 1,
                'unit_price' => '2450.00',
                'tax_rate' => '21.00',
            ],
        ],
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];

JavaScript

const response = await fetch('https://app.klantly.com/api/v1/invoices', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
  body: JSON.stringify({
  "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
  "title": "Veranda 400 × 300",
  "items": [
    {
      "name": "Veranda",
      "quantity": 1,
      "unit_price": "2450.00",
      "tax_rate": "21.00"
    }
  ]
}),
});

const { data } = await response.json();

Python

import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/invoices",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
    json={
        "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
        "title": "Veranda 400 × 300",
        "items": [
            {
                "name": "Veranda",
                "quantity": 1,
                "unit_price": "2450.00",
                "tax_rate": "21.00"
            }
        ]
    },
)
data = response.json()["data"]

Réponse 201

Exemple de réponse

{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "status": "sent",
    "title": "Veranda 400 × 300",
    "description": null,
    "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "customer": {
      "type": "business",
      "name": "De Vries Bouw",
      "email": "jan@example.com",
      "phone": "+31 6 12345678",
      "address": "Dorpsstraat 1",
      "postal_code": "3511 AB",
      "city": "Utrecht",
      "country": "NL",
      "company_name": "De Vries Bouw",
      "vat_number": null,
      "coc_number": null
    },
    "quote_id": "9d3f8449-afe1-4a6e-9dbc-c1dfe0f1a2ba",
    "deal_id": null,
    "language": "nl",
    "currency": "EUR",
    "invoice_date": "2026-09-16",
    "due_date": "2026-10-16",
    "payment_term_days": 30,
    "is_term_invoice": false,
    "term_percentage": null,
    "terms_conditions": null,
    "notes": null,
    "outro_text": null,
    "hide_line_amounts": false,
    "discount_percentage": "0.00",
    "discount_amount": "0.00",
    "discount_description": null,
    "subtotal": "2450.00",
    "tax_amount": "514.50",
    "total": "2964.50",
    "amount_paid": "0.00",
    "amount_due": "2964.50",
    "sent_at": null,
    "viewed_at": null,
    "paid_at": null,
    "cancelled_at": null,
    "items": [
      {
        "object": "invoice_item",
        "id": "9d3f87ac-d2b4-4d9b-8aef-f4a2b3c4d5ee",
        "type": "product",
        "name": "Veranda",
        "description": null,
        "sku": null,
        "quantity": "1.00",
        "unit": "stuk",
        "unit_price": "2450.00",
        "unit_price_incl": null,
        "discount_percentage": "0.00",
        "discount_amount": "0.00",
        "discount_description": null,
        "line_total": "2450.00",
        "line_total_incl": null,
        "is_taxable": true,
        "tax_rate": "21.00"
      }
    ],
    "payments": [
      {
        "object": "invoice_payment",
        "id": "9d3f88cd-e3c5-4eac-9bf0-a5b3c4d5e6ff",
        "amount": "2964.50",
        "type": "full",
        "status": "paid",
        "payment_method": "bank_transfer",
        "description": null,
        "paid_at": "2026-09-16T10:15:00Z",
        "created_at": "2026-09-16T10:15:00Z"
      }
    ],
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Erreurs possibles

403 insufficient_scope — Cette clé API n'a pas accès à cette action.
422 validation_failed — Les données saisies ne sont pas valides.
422 unknown_field — Les données contiennent un champ inconnu.
415 unsupported_media_type — Ce format n'est pas pris en charge.
413 payload_too_large — Le corps de la requête est trop volumineux.
403 limit_reached — La limite de l'abonnement est atteinte.
422 idempotency_key_reused — Cette Idempotency-Key a déjà été utilisée pour une autre requête.
409 idempotency_in_progress — Une requête avec cette Idempotency-Key est encore en cours.

En outre, chaque endpoint peut renvoyer les erreurs générales, comme une clé invalide ou une limite atteinte. Voir tous les codes d'erreur.

Modifier une facture

PATCH /api/v1/invoices/{invoice}

Ne modifie que les champs que vous envoyez. items remplace toutes les lignes en bloc. Seul un brouillon peut encore changer : une fois la facture envoyée, elle se trouve dans la comptabilité du client et vous obtenez 409.

Scope: invoices.write — Créer et modifier des factures (brouillons uniquement), les annuler et enregistrer des paiements
Fonctionnalité requise: invoices

Envoyez l'ETag dans If-Match : vous n'écraserez jamais par erreur une version plus récente.

Paramètres de chemin

Nom	Type	Description
`invoice` obligatoire	string (uuid)	L'id (UUID) de la facture.

Corps (JSON)

Champ	Type	Description
`title` facultatif	string	Titre de la facture. Obligatoire à la création. au maximum 255 caractères
`description` facultatif	string	Brève description ; affichée au-dessus des lignes. peut être vide (null) · au maximum 20000 caractères
`language` facultatif	string	Langue de la facture : nl, en, de ou fr. l'une des valeurs : nl, en, de, fr
`invoice_date` facultatif	string (date)	Date de facture (AAAA-MM-JJ).
`due_date` facultatif	string (date)	Date d'échéance (AAAA-MM-JJ). Sans indication, c'est la date de facture plus le délai de paiement.
`payment_term_days` facultatif	integer	Délai de paiement en jours. Sans indication, le délai par défaut de l'entreprise s'applique. de 0 à 365
`terms_conditions` facultatif	string	Conditions figurant sur la facture. peut être vide (null) · au maximum 20000 caractères
`notes` facultatif	string	Remarques pour le client sur la facture. Lors de l'enregistrement d'un paiement : une note sur ce paiement. peut être vide (null) · au maximum 20000 caractères
`outro_text` facultatif	string	Texte de clôture sous les lignes. peut être vide (null) · au maximum 20000 caractères
`hide_line_amounts` facultatif	boolean	Masque les montants par ligne sur la facture ; le client ne voit que le total.
`discount_percentage` facultatif	number	Remise sur le total, en pourcentage. de 0 à 100
`discount_amount` facultatif	number	Remise sur le total, en montant. de 0 à 9999999
`discount_description` facultatif	string	Pourquoi la remise a été accordée ; figure sur la facture. peut être vide (null) · au maximum 500 caractères
`items` facultatif	array	Les lignes (200 au maximum). À l'envoi : une liste avec, par ligne, name (obligatoire) et éventuellement type, description, sku, quantity, unit, unit_price, unit_price_incl, discount_percentage, discount_amount, discount_description, tax_rate et is_taxable. Elles remplacent toutes les lignes existantes.

Exemple de requête

cURL

curl -X PATCH "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "notes": "Graag betalen binnen 14 dagen."
}'

PHP

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('PATCH', 'invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70', [
    'json' => [
        'notes' => 'Graag betalen binnen 14 dagen.',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];

JavaScript

const response = await fetch('https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "notes": "Graag betalen binnen 14 dagen."
}),
});

const { data } = await response.json();

Python

import os

import requests

response = requests.patch(
    "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
    json={
        "notes": "Graag betalen binnen 14 dagen."
    },
)
data = response.json()["data"]

Réponse 200

Exemple de réponse

{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "status": "sent",
    "title": "Veranda 400 × 300",
    "description": null,
    "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "customer": {
      "type": "business",
      "name": "De Vries Bouw",
      "email": "jan@example.com",
      "phone": "+31 6 12345678",
      "address": "Dorpsstraat 1",
      "postal_code": "3511 AB",
      "city": "Utrecht",
      "country": "NL",
      "company_name": "De Vries Bouw",
      "vat_number": null,
      "coc_number": null
    },
    "quote_id": "9d3f8449-afe1-4a6e-9dbc-c1dfe0f1a2ba",
    "deal_id": null,
    "language": "nl",
    "currency": "EUR",
    "invoice_date": "2026-09-16",
    "due_date": "2026-10-16",
    "payment_term_days": 30,
    "is_term_invoice": false,
    "term_percentage": null,
    "terms_conditions": null,
    "notes": null,
    "outro_text": null,
    "hide_line_amounts": false,
    "discount_percentage": "0.00",
    "discount_amount": "0.00",
    "discount_description": null,
    "subtotal": "2450.00",
    "tax_amount": "514.50",
    "total": "2964.50",
    "amount_paid": "0.00",
    "amount_due": "2964.50",
    "sent_at": null,
    "viewed_at": null,
    "paid_at": null,
    "cancelled_at": null,
    "items": [
      {
        "object": "invoice_item",
        "id": "9d3f87ac-d2b4-4d9b-8aef-f4a2b3c4d5ee",
        "type": "product",
        "name": "Veranda",
        "description": null,
        "sku": null,
        "quantity": "1.00",
        "unit": "stuk",
        "unit_price": "2450.00",
        "unit_price_incl": null,
        "discount_percentage": "0.00",
        "discount_amount": "0.00",
        "discount_description": null,
        "line_total": "2450.00",
        "line_total_incl": null,
        "is_taxable": true,
        "tax_rate": "21.00"
      }
    ],
    "payments": [
      {
        "object": "invoice_payment",
        "id": "9d3f88cd-e3c5-4eac-9bf0-a5b3c4d5e6ff",
        "amount": "2964.50",
        "type": "full",
        "status": "paid",
        "payment_method": "bank_transfer",
        "description": null,
        "paid_at": "2026-09-16T10:15:00Z",
        "created_at": "2026-09-16T10:15:00Z"
      }
    ],
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Erreurs possibles

403 insufficient_scope — Cette clé API n'a pas accès à cette action.
422 validation_failed — Les données saisies ne sont pas valides.
422 unknown_field — Les données contiennent un champ inconnu.
415 unsupported_media_type — Ce format n'est pas pris en charge.
413 payload_too_large — Le corps de la requête est trop volumineux.
404 not_found — Introuvable.
412 precondition_failed — L'enregistrement a été modifié entre-temps.
409 invalid_state_transition — Cette action n'est pas possible dans le statut actuel.

En outre, chaque endpoint peut renvoyer les erreurs générales, comme une clé invalide ou une limite atteinte. Voir tous les codes d'erreur.

Envoyer une facture

POST /api/v1/invoices/{invoice}/send

Envoie la facture par e-mail au client avec le modèle de notification de l'entreprise et passe le statut à envoyée. Un nouvel envoi compte comme un rappel : reminder_count augmente.

Scope: invoices.send — Envoyer les factures par e-mail aux clients
Fonctionnalité requise: invoices

Envoyez une Idempotency-Key : une nouvelle tentative après un délai d'attente ne crée alors jamais de doublon.

Paramètres de chemin

Nom	Type	Description
`invoice` obligatoire	string (uuid)	L'id (UUID) de la facture.

Corps (JSON)

Champ	Type	Description
`message` facultatif	string	Message personnel dans l'e-mail au client. peut être vide (null) · au maximum 5000 caractères

Exemple de requête

cURL

curl -X POST "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/send" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f" \
  -d '{
  "message": "Bijgaand de factuur voor de geplaatste veranda."
}'

PHP

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/send', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
    'json' => [
        'message' => 'Bijgaand de factuur voor de geplaatste veranda.',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];

JavaScript

const response = await fetch('https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/send', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
  body: JSON.stringify({
  "message": "Bijgaand de factuur voor de geplaatste veranda."
}),
});

const { data } = await response.json();

Python

import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/send",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
    json={
        "message": "Bijgaand de factuur voor de geplaatste veranda."
    },
)
data = response.json()["data"]

Réponse 200

Exemple de réponse

{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "status": "sent",
    "title": "Veranda 400 × 300",
    "description": null,
    "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "customer": {
      "type": "business",
      "name": "De Vries Bouw",
      "email": "jan@example.com",
      "phone": "+31 6 12345678",
      "address": "Dorpsstraat 1",
      "postal_code": "3511 AB",
      "city": "Utrecht",
      "country": "NL",
      "company_name": "De Vries Bouw",
      "vat_number": null,
      "coc_number": null
    },
    "quote_id": "9d3f8449-afe1-4a6e-9dbc-c1dfe0f1a2ba",
    "deal_id": null,
    "language": "nl",
    "currency": "EUR",
    "invoice_date": "2026-09-16",
    "due_date": "2026-10-16",
    "payment_term_days": 30,
    "is_term_invoice": false,
    "term_percentage": null,
    "terms_conditions": null,
    "notes": null,
    "outro_text": null,
    "hide_line_amounts": false,
    "discount_percentage": "0.00",
    "discount_amount": "0.00",
    "discount_description": null,
    "subtotal": "2450.00",
    "tax_amount": "514.50",
    "total": "2964.50",
    "amount_paid": "0.00",
    "amount_due": "2964.50",
    "sent_at": null,
    "viewed_at": null,
    "paid_at": null,
    "cancelled_at": null,
    "items": [
      {
        "object": "invoice_item",
        "id": "9d3f87ac-d2b4-4d9b-8aef-f4a2b3c4d5ee",
        "type": "product",
        "name": "Veranda",
        "description": null,
        "sku": null,
        "quantity": "1.00",
        "unit": "stuk",
        "unit_price": "2450.00",
        "unit_price_incl": null,
        "discount_percentage": "0.00",
        "discount_amount": "0.00",
        "discount_description": null,
        "line_total": "2450.00",
        "line_total_incl": null,
        "is_taxable": true,
        "tax_rate": "21.00"
      }
    ],
    "payments": [
      {
        "object": "invoice_payment",
        "id": "9d3f88cd-e3c5-4eac-9bf0-a5b3c4d5e6ff",
        "amount": "2964.50",
        "type": "full",
        "status": "paid",
        "payment_method": "bank_transfer",
        "description": null,
        "paid_at": "2026-09-16T10:15:00Z",
        "created_at": "2026-09-16T10:15:00Z"
      }
    ],
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Erreurs possibles

403 insufficient_scope — Cette clé API n'a pas accès à cette action.
422 validation_failed — Les données saisies ne sont pas valides.
422 unknown_field — Les données contiennent un champ inconnu.
415 unsupported_media_type — Ce format n'est pas pris en charge.
413 payload_too_large — Le corps de la requête est trop volumineux.
404 not_found — Introuvable.
403 forbidden — Accès refusé.
409 invalid_state_transition — Cette action n'est pas possible dans le statut actuel.
422 idempotency_key_reused — Cette Idempotency-Key a déjà été utilisée pour une autre requête.
409 idempotency_in_progress — Une requête avec cette Idempotency-Key est encore en cours.

En outre, chaque endpoint peut renvoyer les erreurs générales, comme une clé invalide ou une limite atteinte. Voir tous les codes d'erreur.

Annuler une facture

POST /api/v1/invoices/{invoice}/cancel

Passe la facture en annulée. Une facture payée ne peut pas être annulée ; créez un avoir pour cela.

Scope: invoices.write — Créer et modifier des factures (brouillons uniquement), les annuler et enregistrer des paiements
Fonctionnalité requise: invoices

Envoyez une Idempotency-Key : une nouvelle tentative après un délai d'attente ne crée alors jamais de doublon.

Paramètres de chemin

Nom	Type	Description
`invoice` obligatoire	string (uuid)	L'id (UUID) de la facture.

Exemple de requête

cURL

curl -X POST "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/cancel" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f"

PHP

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/cancel', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];

JavaScript

const response = await fetch('https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/cancel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
});

const { data } = await response.json();

Python

import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/cancel",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
)
data = response.json()["data"]

Réponse 200

Exemple de réponse

{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "status": "sent",
    "title": "Veranda 400 × 300",
    "description": null,
    "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "customer": {
      "type": "business",
      "name": "De Vries Bouw",
      "email": "jan@example.com",
      "phone": "+31 6 12345678",
      "address": "Dorpsstraat 1",
      "postal_code": "3511 AB",
      "city": "Utrecht",
      "country": "NL",
      "company_name": "De Vries Bouw",
      "vat_number": null,
      "coc_number": null
    },
    "quote_id": "9d3f8449-afe1-4a6e-9dbc-c1dfe0f1a2ba",
    "deal_id": null,
    "language": "nl",
    "currency": "EUR",
    "invoice_date": "2026-09-16",
    "due_date": "2026-10-16",
    "payment_term_days": 30,
    "is_term_invoice": false,
    "term_percentage": null,
    "terms_conditions": null,
    "notes": null,
    "outro_text": null,
    "hide_line_amounts": false,
    "discount_percentage": "0.00",
    "discount_amount": "0.00",
    "discount_description": null,
    "subtotal": "2450.00",
    "tax_amount": "514.50",
    "total": "2964.50",
    "amount_paid": "0.00",
    "amount_due": "2964.50",
    "sent_at": null,
    "viewed_at": null,
    "paid_at": null,
    "cancelled_at": null,
    "items": [
      {
        "object": "invoice_item",
        "id": "9d3f87ac-d2b4-4d9b-8aef-f4a2b3c4d5ee",
        "type": "product",
        "name": "Veranda",
        "description": null,
        "sku": null,
        "quantity": "1.00",
        "unit": "stuk",
        "unit_price": "2450.00",
        "unit_price_incl": null,
        "discount_percentage": "0.00",
        "discount_amount": "0.00",
        "discount_description": null,
        "line_total": "2450.00",
        "line_total_incl": null,
        "is_taxable": true,
        "tax_rate": "21.00"
      }
    ],
    "payments": [
      {
        "object": "invoice_payment",
        "id": "9d3f88cd-e3c5-4eac-9bf0-a5b3c4d5e6ff",
        "amount": "2964.50",
        "type": "full",
        "status": "paid",
        "payment_method": "bank_transfer",
        "description": null,
        "paid_at": "2026-09-16T10:15:00Z",
        "created_at": "2026-09-16T10:15:00Z"
      }
    ],
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Erreurs possibles

403 insufficient_scope — Cette clé API n'a pas accès à cette action.
404 not_found — Introuvable.
409 invalid_state_transition — Cette action n'est pas possible dans le statut actuel.
422 idempotency_key_reused — Cette Idempotency-Key a déjà été utilisée pour une autre requête.
409 idempotency_in_progress — Une requête avec cette Idempotency-Key est encore en cours.

En outre, chaque endpoint peut renvoyer les erreurs générales, comme une clé invalide ou une limite atteinte. Voir tous les codes d'erreur.

Enregistrer un paiement

POST /api/v1/invoices/{invoice}/payments

Enregistre un paiement reçu en dehors de Klantly, par exemple un virement. Le montant ne peut jamais dépasser le montant restant dû. Si la facture est ainsi entièrement réglée, elle passe à payée et l'événement invoice.paid suit.

Scope: invoices.write — Créer et modifier des factures (brouillons uniquement), les annuler et enregistrer des paiements
Fonctionnalité requise: invoices

Envoyez une Idempotency-Key : une nouvelle tentative après un délai d'attente ne crée alors jamais de doublon.

Paramètres de chemin

Nom	Type	Description
`invoice` obligatoire	string (uuid)	L'id (UUID) de la facture.

Corps (JSON)

Champ	Type	Description
`amount` obligatoire	number	Le montant du paiement que vous enregistrez. Jamais plus que le montant restant dû. de 0 à 9999999
`payment_method` facultatif	string	Comment le paiement a été effectué : bank_transfer, cash, card, ideal, credit_card, paypal, bancontact ou other. l'une des valeurs : bank_transfer, cash, card, ideal, credit_card, paypal, bancontact, other
`reference` facultatif	string	Votre propre référence pour le paiement, par exemple le relevé bancaire ou l'id de transaction. peut être vide (null) · au maximum 255 caractères
`notes` facultatif	string	Remarques pour le client sur la facture. Lors de l'enregistrement d'un paiement : une note sur ce paiement. peut être vide (null) · au maximum 1000 caractères

Exemple de requête

cURL

curl -X POST "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/payments" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f" \
  -d '{
  "amount": "2964.50",
  "payment_method": "bank_transfer",
  "reference": "NL02ABNA0123456789"
}'

PHP

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/payments', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
    'json' => [
        'amount' => '2964.50',
        'payment_method' => 'bank_transfer',
        'reference' => 'NL02ABNA0123456789',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];

JavaScript

const response = await fetch('https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/payments', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
  body: JSON.stringify({
  "amount": "2964.50",
  "payment_method": "bank_transfer",
  "reference": "NL02ABNA0123456789"
}),
});

const { data } = await response.json();

Python

import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/payments",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
    json={
        "amount": "2964.50",
        "payment_method": "bank_transfer",
        "reference": "NL02ABNA0123456789"
    },
)
data = response.json()["data"]

Réponse 200

Exemple de réponse

{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "status": "sent",
    "title": "Veranda 400 × 300",
    "description": null,
    "customer_id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "customer": {
      "type": "business",
      "name": "De Vries Bouw",
      "email": "jan@example.com",
      "phone": "+31 6 12345678",
      "address": "Dorpsstraat 1",
      "postal_code": "3511 AB",
      "city": "Utrecht",
      "country": "NL",
      "company_name": "De Vries Bouw",
      "vat_number": null,
      "coc_number": null
    },
    "quote_id": "9d3f8449-afe1-4a6e-9dbc-c1dfe0f1a2ba",
    "deal_id": null,
    "language": "nl",
    "currency": "EUR",
    "invoice_date": "2026-09-16",
    "due_date": "2026-10-16",
    "payment_term_days": 30,
    "is_term_invoice": false,
    "term_percentage": null,
    "terms_conditions": null,
    "notes": null,
    "outro_text": null,
    "hide_line_amounts": false,
    "discount_percentage": "0.00",
    "discount_amount": "0.00",
    "discount_description": null,
    "subtotal": "2450.00",
    "tax_amount": "514.50",
    "total": "2964.50",
    "amount_paid": "0.00",
    "amount_due": "2964.50",
    "sent_at": null,
    "viewed_at": null,
    "paid_at": null,
    "cancelled_at": null,
    "items": [
      {
        "object": "invoice_item",
        "id": "9d3f87ac-d2b4-4d9b-8aef-f4a2b3c4d5ee",
        "type": "product",
        "name": "Veranda",
        "description": null,
        "sku": null,
        "quantity": "1.00",
        "unit": "stuk",
        "unit_price": "2450.00",
        "unit_price_incl": null,
        "discount_percentage": "0.00",
        "discount_amount": "0.00",
        "discount_description": null,
        "line_total": "2450.00",
        "line_total_incl": null,
        "is_taxable": true,
        "tax_rate": "21.00"
      }
    ],
    "payments": [
      {
        "object": "invoice_payment",
        "id": "9d3f88cd-e3c5-4eac-9bf0-a5b3c4d5e6ff",
        "amount": "2964.50",
        "type": "full",
        "status": "paid",
        "payment_method": "bank_transfer",
        "description": null,
        "paid_at": "2026-09-16T10:15:00Z",
        "created_at": "2026-09-16T10:15:00Z"
      }
    ],
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Erreurs possibles

403 insufficient_scope — Cette clé API n'a pas accès à cette action.
422 validation_failed — Les données saisies ne sont pas valides.
422 unknown_field — Les données contiennent un champ inconnu.
415 unsupported_media_type — Ce format n'est pas pris en charge.
413 payload_too_large — Le corps de la requête est trop volumineux.
404 not_found — Introuvable.
409 invalid_state_transition — Cette action n'est pas possible dans le statut actuel.
422 idempotency_key_reused — Cette Idempotency-Key a déjà été utilisée pour une autre requête.
409 idempotency_in_progress — Une requête avec cette Idempotency-Key est encore en cours.

En outre, chaque endpoint peut renvoyer les erreurs générales, comme une clé invalide ou une limite atteinte. Voir tous les codes d'erreur.

Supprimer une facture

DELETE /api/v1/invoices/{invoice}

Supprime la facture. Seul un brouillon peut être supprimé : une facture envoyée reste.

Scope: invoices.delete — Supprimer les factures brouillon
Fonctionnalité requise: invoices

Paramètres de chemin

Nom	Type	Description
`invoice` obligatoire	string (uuid)	L'id (UUID) de la facture.

Exemple de requête

cURL

curl -X DELETE "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"

PHP

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('DELETE', 'invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70');

$data = json_decode((string) $response->getBody(), true)['data'];

JavaScript

const response = await fetch('https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();

Python

import os

import requests

response = requests.delete(
    "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Réponse 200

Exemple de réponse

{
  "data": {
    "object": "note",
    "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92",
    "deleted": true
  }
}

Erreurs possibles

403 insufficient_scope — Cette clé API n'a pas accès à cette action.
404 not_found — Introuvable.
409 invalid_state_transition — Cette action n'est pas possible dans le statut actuel.

En outre, chaque endpoint peut renvoyer les erreurs générales, comme une clé invalide ou une limite atteinte. Voir tous les codes d'erreur.

L'objet

Tous les champs sont toujours présents ; un champ sans valeur vaut null.

Champ	Type	Description
`object`	string	Toujours "invoice".
`id`	string (uuid)	Id unique (UUID).
`number`	string	Numéro de facture, par exemple FAC-00042 ; attribué par Klantly.
`status`	string	draft (brouillon), sent (envoyée), viewed (consultée), paid (payée), partial (partiellement payée), overdue (en retard), cancelled (annulée) ou refunded (remboursée). l'une des valeurs : draft, sent, viewed, paid, partial, overdue, cancelled, refunded
`title`	string	Titre de la facture. Obligatoire à la création. peut être vide (null)
`description`	string	Brève description ; affichée au-dessus des lignes. peut être vide (null)
`customer_id`	string (uuid)	Le client. Obligatoire à la création ; le nom, l'adresse et les coordonnées proviennent du client. peut être vide (null)
`customer`	object	Les coordonnées du client sur la facture, telles qu'elles étaient à la création.
`customer.type`	string	individual (particulier) ou business (entreprise). peut être vide (null)
`customer.name`	string	Nom ; pour une entreprise, la raison sociale. peut être vide (null)
`customer.email`	string	Adresse e-mail. peut être vide (null)
`customer.phone`	string	Numéro de téléphone. peut être vide (null)
`customer.address`	string	Rue et numéro. peut être vide (null)
`customer.postal_code`	string	Code postal. peut être vide (null)
`customer.city`	string	Ville. peut être vide (null)
`customer.country`	string	Pays. peut être vide (null)
`customer.company_name`	string	Raison sociale. peut être vide (null)
`customer.vat_number`	string	Numéro de TVA. peut être vide (null)
`customer.coc_number`	string	Numéro d'immatriculation. peut être vide (null)
`quote_id`	string (uuid)	Le devis dont provient cette facture, ou null. peut être vide (null)
`deal_id`	string (uuid)	L'affaire du pipeline à laquelle cette facture appartient, ou null. peut être vide (null)
`language`	string	Langue de la facture : nl, en, de ou fr. l'une des valeurs : nl, en, de, fr
`currency`	string	Toujours "EUR".
`invoice_date`	string (date)	Date de facture (AAAA-MM-JJ). peut être vide (null)
`due_date`	string (date)	Date d'échéance (AAAA-MM-JJ). Sans indication, c'est la date de facture plus le délai de paiement. peut être vide (null)
`payment_term_days`	integer	Délai de paiement en jours. Sans indication, le délai par défaut de l'entreprise s'applique. peut être vide (null)
`is_term_invoice`	boolean	S'il s'agit d'une facture partielle portant sur une partie d'un devis.
`term_percentage`	string	La part du devis couverte par cette facture partielle, en pourcentage ; sinon null. peut être vide (null)
`terms_conditions`	string	Conditions figurant sur la facture. peut être vide (null)
`notes`	string	Remarques pour le client sur la facture. Lors de l'enregistrement d'un paiement : une note sur ce paiement. peut être vide (null)
`outro_text`	string	Texte de clôture sous les lignes. peut être vide (null)
`hide_line_amounts`	boolean	Masque les montants par ligne sur la facture ; le client ne voit que le total.
`discount_percentage`	string	Remise sur le total, en pourcentage.
`discount_amount`	string	Remise sur le total, en montant.
`discount_description`	string	Pourquoi la remise a été accordée ; figure sur la facture. peut être vide (null)
`subtotal`	string	Total hors TVA, sous forme de texte à deux décimales.
`tax_amount`	string	Montant de la TVA.
`total`	string	Total TTC.
`amount_paid`	string	Ce qui a été payé jusqu'à présent.
`amount_due`	string	Ce qui reste dû.
`sent_at`	string (date-time)	Quand la facture a été envoyée au client. peut être vide (null)
`viewed_at`	string (date-time)	Quand le client l'a ouverte. peut être vide (null)
`paid_at`	string (date-time)	Quand la facture a été entièrement réglée. peut être vide (null)
`cancelled_at`	string (date-time)	Quand la facture a été annulée. peut être vide (null)
`items`	array<object>	Les lignes (200 au maximum). À l'envoi : une liste avec, par ligne, name (obligatoire) et éventuellement type, description, sku, quantity, unit, unit_price, unit_price_incl, discount_percentage, discount_amount, discount_description, tax_rate et is_taxable. Elles remplacent toutes les lignes existantes.
`items.object`	string	Toujours "invoice_item".
`items.id`	string (uuid)	Id unique de la ligne (UUID).
`items.type`	string	product, service, expense ou discount. l'une des valeurs : product, service, expense, discount
`items.name`	string	Nom de la ligne.
`items.description`	string	Description sous la ligne. peut être vide (null)
`items.sku`	string	Référence article. peut être vide (null)
`items.quantity`	string	Quantité.
`items.unit`	string	Unité, par exemple pièce ou heure. peut être vide (null)
`items.unit_price`	string	Prix unitaire, hors TVA.
`items.unit_price_incl`	string	Prix unitaire TVA comprise, tel que saisi. S'il est renseigné, la ligne est calculée à partir de ce montant (unit_price et line_total en sont déduits) et le total correspond au centime près au prix saisi. null = la ligne est calculée à partir de unit_price. peut être vide (null)
`items.discount_percentage`	string	Remise sur cette ligne, en pourcentage.
`items.discount_amount`	string	Remise sur cette ligne, en montant.
`items.discount_description`	string	Pourquoi la remise sur cette ligne a été accordée. peut être vide (null)
`items.line_total`	string	Total de la ligne hors TVA, après remise.
`items.line_total_incl`	string	Total de la ligne TVA comprise, après remise. Renseigné uniquement si la ligne est calculée à partir de unit_price_incl ; sinon null. peut être vide (null)
`items.is_taxable`	boolean	Si cette ligne compte pour la TVA.
`items.tax_rate`	string	Taux de TVA de cette ligne, en pourcentage.
`payments`	array<object>	Les paiements enregistrés sur cette facture, les plus anciens d'abord.
`payments.object`	string	Toujours "invoice_payment".
`payments.id`	string (uuid)	Id unique du paiement.
`payments.amount`	string	Le montant payé.
`payments.type`	string	full (intégral), deposit (acompte) ou partial (paiement partiel). l'une des valeurs : full, deposit, partial
`payments.status`	string	open, pending, paid, failed, expired, cancelled ou refunded. l'une des valeurs : open, pending, paid, failed, expired, cancelled, refunded
`payments.payment_method`	string	Comment le paiement a été effectué, par exemple bank_transfer ou ideal. peut être vide (null)
`payments.description`	string	Note sur le paiement. peut être vide (null)
`payments.paid_at`	string (date-time)	Quand le paiement est arrivé. peut être vide (null)
`payments.created_at`	string (date-time)	Quand le paiement a été enregistré.
`created_at`	string (date-time)	Quand la facture a été créée.
`updated_at`	string (date-time)	Quand la facture a été modifiée pour la dernière fois.

Factures

Endpoints

Lister les factures#

Paramètres de requête

Exemple de requête

Réponse 200

Erreurs possibles

Récupérer une facture#

Paramètres de chemin

Exemple de requête

Réponse 200

Erreurs possibles

Créer une facture#

Corps (JSON)

Exemple de requête

Réponse 201

Erreurs possibles

Modifier une facture#

Paramètres de chemin

Corps (JSON)

Exemple de requête

Réponse 200

Erreurs possibles

Envoyer une facture#

Paramètres de chemin

Corps (JSON)

Exemple de requête

Réponse 200

Erreurs possibles

Annuler une facture#

Paramètres de chemin

Exemple de requête

Réponse 200

Erreurs possibles

Enregistrer un paiement#

Paramètres de chemin

Corps (JSON)

Exemple de requête

Réponse 200

Erreurs possibles

Supprimer une facture#

Paramètres de chemin

Exemple de requête

Réponse 200

Erreurs possibles

L'objet#

Lister les factures

Récupérer une facture

Créer une facture

Modifier une facture

Envoyer une facture

Annuler une facture

Enregistrer un paiement

Supprimer une facture

L'objet