Factures

Lister les factures#

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. Les avoirs figurent dans la même liste (type credit_note, avec des montants négatifs) ; avec filter[type], vous récupérez uniquement les factures ou uniquement les avoirs.

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

Exemple de requête

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

$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'];

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();

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.

{
  "data": [
    {
      "object": "invoice",
      "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
      "number": "FAC-00042",
      "type": "invoice",
      "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,
      "term_amount": 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,
      "credited_invoice_id": null,
      "credited_invoice_number": null,
      "credit_reason": null,
      "refund_amount": null,
      "refunded_at": null,
      "credit_note_state": null,
      "credited_amount": "0.00",
      "credit_note_ids": [],
      "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",
          "credited_item_id": null
        }
      ],
      "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#

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

Exemple de requête

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

$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'];

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();

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

{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "type": "invoice",
    "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,
    "term_amount": 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,
    "credited_invoice_id": null,
    "credited_invoice_number": null,
    "credit_reason": null,
    "refund_amount": null,
    "refunded_at": null,
    "credit_note_state": null,
    "credited_amount": "0.00",
    "credit_note_ids": [],
    "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",
        "credited_item_id": null
      }
    ],
    "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#

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 des factures (aussi à partir d'un devis) et les modifier (brouillons uniquement), les annuler, enregistrer des paiements, les créditer et enregistrer un remboursement

Fonctionnalité requise

invoices

Corps (JSON)

Exemple de requête

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

$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'];

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();

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

{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "type": "invoice",
    "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,
    "term_amount": 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,
    "credited_invoice_id": null,
    "credited_invoice_number": null,
    "credit_reason": null,
    "refund_amount": null,
    "refunded_at": null,
    "credit_note_state": null,
    "credited_amount": "0.00",
    "credit_note_ids": [],
    "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",
        "credited_item_id": null
      }
    ],
    "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#

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 des factures (aussi à partir d'un devis) et les modifier (brouillons uniquement), les annuler, enregistrer des paiements, les créditer et enregistrer un remboursement

Fonctionnalité requise

invoices

Paramètres de chemin

Corps (JSON)

Exemple de requête

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

$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'];

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();

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

{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "type": "invoice",
    "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,
    "term_amount": 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,
    "credited_invoice_id": null,
    "credited_invoice_number": null,
    "credit_reason": null,
    "refund_amount": null,
    "refunded_at": null,
    "credit_note_state": null,
    "credited_amount": "0.00",
    "credit_note_ids": [],
    "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",
        "credited_item_id": null
      }
    ],
    "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#

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. Pour un avoir ou une facture (partiellement) créditée, le statut reste inchangé ; seul sent_at est mis à jour.

Scope

invoices.send — Envoyer les factures par e-mail aux clients et obtenir le lien de paiement pour le client

Fonctionnalité requise

invoices

Paramètres de chemin

Corps (JSON)

Exemple de requête

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

$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'];

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();

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

{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "type": "invoice",
    "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,
    "term_amount": 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,
    "credited_invoice_id": null,
    "credited_invoice_number": null,
    "credit_reason": null,
    "refund_amount": null,
    "refunded_at": null,
    "credit_note_state": null,
    "credited_amount": "0.00",
    "credit_note_ids": [],
    "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",
        "credited_item_id": null
      }
    ],
    "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.

Marquer comme envoyée (sans e-mail)#

Passe un brouillon à envoyée sans que Klantly envoie d'e-mail au client, comme le bouton dans l'application. Utilisez ceci si vous avez remis la facture vous-même : par votre propre e-mail, sur papier ou via votre logiciel comptable. sent_at est rempli et l'événement invoice.sent suit. Vous pouvez ensuite y enregistrer un paiement. Si la facture est déjà envoyée ou plus avancée, elle est renvoyée inchangée ; un brouillon annulé donne 409. Envoyez une Idempotency-Key.

Scope

invoices.write — Créer des factures (aussi à partir d'un devis) et les modifier (brouillons uniquement), les annuler, enregistrer des paiements, les créditer et enregistrer un remboursement

Fonctionnalité requise

invoices

Paramètres de chemin

Exemple de requête

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

$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/mark-sent', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
]);

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

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

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

import os

import requests

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

Réponse 200

{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "type": "invoice",
    "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,
    "term_amount": 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,
    "credited_invoice_id": null,
    "credited_invoice_number": null,
    "credit_reason": null,
    "refund_amount": null,
    "refunded_at": null,
    "credit_note_state": null,
    "credited_amount": "0.00",
    "credit_note_ids": [],
    "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",
        "credited_item_id": null
      }
    ],
    "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.

Annuler une facture#

Passe la facture en annulée. Une facture payée ou (partiellement) créditée ne peut pas être annulée (409) ; corrigez une facture envoyée avec Créditer une facture.

Scope

invoices.write — Créer des factures (aussi à partir d'un devis) et les modifier (brouillons uniquement), les annuler, enregistrer des paiements, les créditer et enregistrer un remboursement

Fonctionnalité requise

invoices

Paramètres de chemin

Exemple de requête

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"

$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'];

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();

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

{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "type": "invoice",
    "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,
    "term_amount": 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,
    "credited_invoice_id": null,
    "credited_invoice_number": null,
    "credit_reason": null,
    "refund_amount": null,
    "refunded_at": null,
    "credit_note_state": null,
    "credited_amount": "0.00",
    "credit_note_ids": [],
    "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",
        "credited_item_id": null
      }
    ],
    "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#

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 des factures (aussi à partir d'un devis) et les modifier (brouillons uniquement), les annuler, enregistrer des paiements, les créditer et enregistrer un remboursement

Fonctionnalité requise

invoices

Paramètres de chemin

Corps (JSON)

Exemple de requête

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

$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'];

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();

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

{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "type": "invoice",
    "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,
    "term_amount": 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,
    "credited_invoice_id": null,
    "credited_invoice_number": null,
    "credit_reason": null,
    "refund_amount": null,
    "refunded_at": null,
    "credit_note_state": null,
    "credited_amount": "0.00",
    "credit_note_ids": [],
    "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",
        "credited_item_id": null
      }
    ],
    "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.

Créditer une facture#

Crée un avoir sur une facture envoyée ou payée, comme le bouton dans l'application. mode=full crédite tout ce qui n'a pas encore été crédité, mode=lines une quantité par ligne (lines[].item_id et lines[].quantity) et mode=amount un montant libre TTC à un taux de TVA présent sur la facture. La réponse (201) est l'avoir : une invoice avec type credit_note, des lignes et totaux négatifs et credited_invoice_id. La partie qui peut être imputée sur le montant restant dû l'est ; le reste figure sur l'avoir en refund_amount et doit être remboursé au client. Créditer plus que ce qui reste sur la facture donne 422 sur amount, lines ou lines.N.quantity ; un brouillon, une facture annulée ou déjà entièrement créditée, ou un avoir, donne 409. Suivent les événements invoice.created (l'avoir) et invoice.credited (la facture). Envoyez toujours une Idempotency-Key.

Scope

invoices.write — Créer des factures (aussi à partir d'un devis) et les modifier (brouillons uniquement), les annuler, enregistrer des paiements, les créditer et enregistrer un remboursement

Fonctionnalité requise

invoices

Paramètres de chemin

Corps (JSON)

Exemple de requête

curl -X POST "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/credit" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f" \
  -d '{
  "mode": "amount",
  "reason": "Korting na klacht over de montage",
  "amount": "150.00",
  "tax_rate": "21.00"
}'

$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/credit', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
    'json' => [
        'mode' => 'amount',
        'reason' => 'Korting na klacht over de montage',
        'amount' => '150.00',
        'tax_rate' => '21.00',
    ],
]);

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

const response = await fetch('https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/credit', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
  body: JSON.stringify({
  "mode": "amount",
  "reason": "Korting na klacht over de montage",
  "amount": "150.00",
  "tax_rate": "21.00"
}),
});

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

import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/credit",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
    json={
        "mode": "amount",
        "reason": "Korting na klacht over de montage",
        "amount": "150.00",
        "tax_rate": "21.00"
    },
)
data = response.json()["data"]

Réponse 201

{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "type": "invoice",
    "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,
    "term_amount": 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,
    "credited_invoice_id": null,
    "credited_invoice_number": null,
    "credit_reason": null,
    "refund_amount": null,
    "refunded_at": null,
    "credit_note_state": null,
    "credited_amount": "0.00",
    "credit_note_ids": [],
    "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",
        "credited_item_id": null
      }
    ],
    "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.

Enregistrer un remboursement#

Enregistre que la partie à rembourser d'un avoir (refund_amount) a été virée au client ; refunded_at est rempli et credit_note_state devient refunded. Uniquement sur un avoir avec credit_note_state refund_pending, sinon 409. Avec via=mollie, Klantly rembourse réellement le montant via Mollie (uniquement si la facture a été suffisamment payée via Mollie, sinon 409) ; si Mollie refuse, 422 sur refund. Après un remboursement partiel, credit_note_state reste refund_pending et un nouvel appel ne rembourse que le reste.

Scope

invoices.write — Créer des factures (aussi à partir d'un devis) et les modifier (brouillons uniquement), les annuler, enregistrer des paiements, les créditer et enregistrer un remboursement

Fonctionnalité requise

invoices

Paramètres de chemin

Corps (JSON)

Exemple de requête

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

$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/refunded', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
    'json' => [
        'payment_method' => 'bank_transfer',
        'reference' => 'NL02ABNA0123456789',
    ],
]);

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

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

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

import os

import requests

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

Réponse 200

{
  "data": {
    "object": "invoice",
    "id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "number": "FAC-00042",
    "type": "invoice",
    "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,
    "term_amount": 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,
    "credited_invoice_id": null,
    "credited_invoice_number": null,
    "credit_reason": null,
    "refund_amount": null,
    "refunded_at": null,
    "credit_note_state": null,
    "credited_amount": "0.00",
    "credit_note_ids": [],
    "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",
        "credited_item_id": null
      }
    ],
    "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 conflict — Ceci est en conflit avec l'état actuel.
• 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.

Facture en PDF#

Renvoie la facture en PDF, telle que le client la reçoit : à la charte de l'entreprise et dans la langue de la facture. Pratique pour la joindre à l'écriture dans votre comptabilité. La première fois, Klantly la génère ; ensuite elle vient du cache jusqu'à ce que la facture change. Compte dans la limite renforcée.

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

Exemple de requête

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

$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/pdf');

file_put_contents('document.pdf', (string) $response->getBody());

import { writeFile } from 'node:fs/promises';

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

await writeFile('document.pdf', Buffer.from(await response.arrayBuffer()));

import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/invoices/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/pdf",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
with open("document.pdf", "wb") as pdf:
    pdf.write(response.content)

Réponse 200

La réponse est le fichier lui-même (application/pdf), pas du JSON. Content-Disposition contient le nom du fichier.

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.

Obtenir le lien de paiement#

Renvoie la page où le client paie la facture en ligne avec Mollie, à partager vous-même, par exemple dans votre propre rappel ou via WhatsApp. Avec un échéancier, le client y choisit la prochaine échéance. Uniquement pour une facture envoyée et pas encore entièrement payée (sinon 409 invalid_state_transition) et si l'entreprise a connecté Mollie (sinon 409 conflict). Nécessite la fonctionnalité Paiements en ligne. Toute personne qui a le lien peut consulter et payer la facture : d'où le scope invoices.send.

Scope

invoices.send — Envoyer les factures par e-mail aux clients et obtenir le lien de paiement pour le client

Fonctionnalité requise

invoices, invoice_payments

Paramètres de chemin

Exemple de requête

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

$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/payment-link');

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

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

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

import os

import requests

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

Réponse 200

{
  "data": {
    "object": "invoice_payment_link",
    "invoice_id": "9d3f868b-c1a3-4c8a-9fde-e3f1a2b3c4dd",
    "url": "https://app.klantly.com/invoice/Xk2p9Qm4Rt7vB1nC8dE5fG3hJ6kL0mN2pQ4rS7tU9vW1xY3zA5bC7dE9fG1hJ3kL/pay",
    "amount_due": "1943.00",
    "currency": "EUR"
  }
}

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.
• 409 conflict — Ceci est en conflit avec l'état 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.

Supprimer une facture#

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

Exemple de requête

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

$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'];

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();

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

{
  "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.