Guides : pagination, erreurs, limites

Pagination des listes, format des erreurs, limites de débit et exemple de chaîne complète de recouvrement via l'API.

Pagination

Les endpoints de liste acceptent limit (1-200, défaut 50) et offset (défaut 0), et renvoient une enveloppe stable :

{ "data": [], "total": 123, "limit": 50, "offset": 0 }

Erreurs

Toutes les erreurs suivent le même format :

{ "statusCode": 401, "code": "UNAUTHORIZED", "message": "Clé API invalide ou révoquée." }

Limites de débit (rate limits)

Le quota s'applique par clé et par minute, selon votre palier :

Au-delà : réponse 429. Prévoyez un retry avec backoff (attendre ~60 s).

Exemple : chaîne complète de recouvrement

BASE="https://api.rec-societe.com/api/v1/public"
AUTH="Authorization: Bearer sk_live_votre_cle"

# 1. Créer le débiteur (au moins un contact ; SIREN -> enrichissement automatique)
curl -s -X POST "$BASE/debtors" -H "$AUTH" -H "Content-Type: application/json" -d '{
  "isCompany": true, "companyName": "Client Mauvais Payeur SARL", "siren": "552081317",
  "address": "1 rue de la Paix", "postalCode": "75002", "city": "Paris",
  "contacts": [{ "name": "Jean Dupont", "email": "compta@mauvais-payeur.fr", "isPrimary": true }]
}'

# 2. Créer le dossier (statut DRAFT — rien n'est envoyé au débiteur)
curl -s -X POST "$BASE/cases" -H "$AUTH" -H "Content-Type: application/json" -d '{ "debtorId": "DEBTOR_ID" }'

# 3. Ajouter une facture
curl -s -X POST "$BASE/invoices" -H "$AUTH" -H "Content-Type: application/json" -d '{
  "caseId": "CASE_ID", "invoiceNumber": "F-2026-042",
  "issueDate": "2026-05-01", "dueDate": "2026-06-01", "totalAmount": 1200.00, "vatAmount": 200.00
}'

# 4. Joindre le PDF (requis pour lancer le dossier)
curl -s -X POST "$BASE/invoices/INVOICE_ID/pdf" -H "$AUTH" -F "file=@facture.pdf"

# 5. Lancer le workflow de relances
curl -s -X POST "$BASE/cases/CASE_ID/launch" -H "$AUTH" -H "Content-Type: application/json" -d '{}'

# 6. Suivre la timeline et les actions
curl -s "$BASE/cases/CASE_ID/events" -H "$AUTH"
curl -s "$BASE/actions" -H "$AUTH"

Versionnement

L'API est versionnée par le préfixe d'URL (/api/v1/). Les évolutions rétro-compatibles peuvent survenir sans changement de version ; les changements cassants donneront lieu à un /api/v2/ annoncé à l'avance.

Référence complète

Explorez tous les endpoints (paramètres, corps de requête, réponses) dans la référence interactive de l'API.

Pour une intégration ou de la génération de code, la spécification OpenAPI brute (lisible par machine, format OpenAPI 3.0) est téléchargeable directement : https://rec-societe.com/openapi.json. C'est le format à privilégier pour alimenter un outil ou un assistant de codage.

Dernière mise à jour : 22/07/2026