INTÉGRATION TECHNIQUE

Hub développeurs

Contrats API, authentification, webhooks, idempotence, gestion des erreurs et principes opérationnels pour les intégrations d’entreprise.

Le contrat avant l’implémentation

Les modèles de données, limites d’autorisation, comportements d’échec et règles de reprise sont définis avant le développement.

Authentification
Clés API, requêtes signées, cycle de vie des jetons et périmètres d’autorisation.

API REST
Endpoints orientés ressources, codes cohérents, versionnage et compatibilité.

WebSocket
Cycle de connexion, reconnexion et ordre des événements en temps réel.

Webhooks
Notifications signées, reprises, identifiants de livraison et traitement sans doublon.

Idempotence
Traitement sûr des requêtes répétées pour les opérations critiques.

Modèle d’erreur
Codes lisibles par machine, identifiants de corrélation et traçabilité.

Limites de débit
Quotas, backoff et reprises contrôlées.

Observabilité
Logs, métriques, traces et identifiants d’événements.

Exemple de contrat API

Les exemples illustrent un modèle; les endpoints réels sont définis par le contrat du projet.

POST /v1/transactions
Idempotency-Key: <unique-key>
Authorization: Bearer <token>

{
  "reference": "client-reference",
  "asset": "ASSET",
  "amount": "100.00"
}

Discuter du périmètre technique

CONTRAT API REPRÉSENTATIF

Le comportement d’intégration ne doit pas être ambigu.

Le modèle ci-dessous est représentatif ; endpoints et schémas réels sont définis par projet.

REQUEST

POST /v1/transactions
Authorization: Bearer <token>
Idempotency-Key: <unique-key>

{
  "reference": "client-reference",
  "asset": "ASSET",
  "amount": "100.00"
}

ERROR MODEL

{
  "error": {
    "code": "POLICY_REJECTED",
    "message": "Request rejected",
    "request_id": "req_..."
  }
}

WEBHOOK

event: transaction.updated
signature: <signed-header>
delivery_id: <unique-id>

verify → persist → process → 2xx