Conventions

Formats, identifiants, dates, montants et structure des requêtes et des réponses.

JSON#

Les requêtes et les réponses sont en JSON (UTF-8). Envoyez toujours Content-Type: application/json avec un POST ou un PATCH. Le corps ne peut pas dépasser 1 Mo.

Objets#

Chaque objet possède un champ object indiquant son type, ainsi qu'un id. Un objet seul est renvoyé sous data :

{
  "data": {
    "object": "customer",
    "id": "9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    "email": "jan@example.com"
  }
}

Tous les champs d'un objet sont toujours présents. Un champ sans valeur vaut null ; aucun champ ne disparaît.

Identifiants#

Les identifiants sont des chaînes. Les clients ont un UUID. Traitez un identifiant comme un texte opaque et n'en déduisez rien.

Dates et heures#

Les heures sont au format ISO 8601 en UTC, par exemple 2026-09-14T10:15:00Z. Les dates sans heure ont la forme 2026-09-14.

Montants#

Les montants sont des chaînes décimales avec deux décimales, accompagnées de la devise : {"total": "1234.50", "currency": "EUR"}. Cela évite les erreurs d'arrondi. En entrée, vous pouvez aussi envoyer un nombre ; plus de deux décimales donnent une erreur de validation.

Modification partielle#

PATCH ne modifie que les champs que vous envoyez. Un champ inconnu renvoie 422 unknown_field, de sorte qu'une faute de frappe dans un nom de champ se remarque immédiatement.

Actions#

Un changement de statut passe par un endpoint d'action dédié, par exemple POST /customers/{id}/convert. Ainsi, toutes les règles de Klantly s'appliquent toujours, comme les automatisations et l'historique client.

Langue#

Les messages d'erreur sont rédigés dans la langue indiquée par Accept-Language (nl, en, de ou fr). Si vous n'envoyez rien, vous obtenez la langue de votre entreprise. Le code d'une erreur est toujours en anglais.

Identifiant de requête#

Chaque réponse contient un en-tête X-Request-Id. Indiquez-le lorsque vous contactez le support : nous retrouverons immédiatement votre requête.

Versions#

Cette documentation décrit la version 1 (/api/v1). Au sein de la v1, des éléments sont uniquement ajoutés : nouveaux endpoints, champs ou codes d'erreur. Rendez donc votre intégration tolérante aux champs inconnus dans les réponses. Toutes les modifications figurent dans le journal des modifications.

Dernière mise à jour le 14 septembre 2026