API CODFamilia

Créer des commandes en paiement à la livraison depuis votre boutique ou votre outil, et suivre chacune d'elles jusqu'à la livraison. Une clé, des appels JSON, des webhooks signés.

Adresse de base

https://api.codfamilia.com

Toutes les adresses sont en HTTPS. Les réponses sont en JSON, encodées en UTF-8, et enveloppées dans data.

1. Créer une clé

Dans la plateforme, allez dans Applications → API et créez une clé. Elle commence par cfk_ et n'est affichée qu'une fois : conservez-la comme un mot de passe. Une clé appartient à un vendeur, et c'est elle qui détermine le périmètre de chaque appel — aucun identifiant de vendeur ne se passe en paramètre, il ne pourrait qu'être falsifié.

Créer ma clé API

2. Vérifier qu'elle fonctionne

Le premier appel à faire. Il ne renvoie aucune donnée client, seulement de quoi confirmer que la clé est reconnue et à quel compte elle appartient.

curl -s https://api.codfamilia.com/v1/me \
  -H "Authorization: Bearer cfk_votre_cle"

{"data":{"account":"H7K2-9QRX","name":"…","lead_prefix":"TAH","api_version":"1.3","rate_limit_per_minute":120}}

Une réponse 401 unauthorized signifie que l'en-tête manque, que la clé est mal recopiée, ou qu'elle a été révoquée. Une clé révoquée ne redevient jamais valide : créez-en une autre.

3. Envoyer une commande

Un lead se crée avec le nom du client, son téléphone, sa ville, l'adresse, le montant à encaisser et la liste des articles (par SKU). Lisez /v1/products et /v1/cities une fois par jour pour connaître les SKU commandables et les villes livrées.

curl -s -X POST https://api.codfamilia.com/v1/leads \
  -H "Authorization: Bearer cfk_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "Yassine A.",
    "customer_phone": "0612345678",
    "city": "Casablanca",
    "address": "12 rue des Orangers",
    "total_client": "299.00",
    "items": [{"sku": "CF-TEETH-03", "quantity": 1}],
    "external_ref": "CMD-1042"
  }'

Deux réponses possibles, et c'est volontaire

`201`	Le lead est créé et part en file de confirmation. La réponse contient sa référence (`ref`), celle que vous retrouverez partout ensuite.
`202`	Quelque chose ne va pas (SKU inconnu, ville non reconnue, montant incohérent, doublon récent) : le lead est conservé comme « lead endommagé », visible dans l'espace du vendeur, avec la liste des anomalies. Aucune commande n'est jamais perdue — c'est le choix de fond de cette API : un client qui a passé commande existe, même si les données sont imparfaites.

Et ensuite

Référence des adresses — tous les champs, avec des exemples.
Webhooks — être prévenu des changements d'état sans interroger l'API en boucle.
Erreurs & limites — ce que signifie chaque code, et ce qu'il faut en faire.

Outils

Le contrat est publié pour être importé tel quel : OpenAPI 3.1 (Swagger, Insomnia, générateurs de clients) et collection Postman (remplissez api_key, essayez).

Idempotence et doublons

Renvoyez toujours votre propre référence dans external_ref. Un même téléphone avec le même produit dans un court intervalle est traité comme un doublon (le délai est réglé par la plateforme) et part en « lead endommagé » plutôt que de créer deux colis pour un seul client. Si votre appel échoue en réseau et que vous le rejouez, cette règle vous protège.