L'API Arcalotl

• Une seule URL de base, limitée à une communauté

  Toutes les ressources vivent sous https://api.arcalotl.com/v1. Chaque ressource est limitée à la communauté propriétaire de la clé d'API utilisée pour l'appel. Un identifiant appartenant à une autre communauté répond 404 plutôt que 403, pour que les réponses ne servent pas à sonder les données d'une autre communauté.

• Des clés d'API bearer à portées explicites

  Chaque requête porte un en-tête Authorization avec une clé bearer créée dans le tableau de bord, sous Développeurs puis Clés d'API. Une clé détient les portées choisies à sa création, et une requête sans la portée exigée par une route renvoie 403 avec le code missing_scope. La clé complète n'est affichée qu'une fois, à la création ; seul un préfixe d'affichage est conservé ensuite.

• Les lectures couvrent toute la facturation

  Les endpoints GET renvoient les abonnements avec filtres par statut, formule et palier, les paliers de formules avec leurs formules de facturation imbriquées, les membres avec leurs identités de plateforme, les droits d'accès résolus d'un membre, les achats uniques, les codes promo avec leur nombre de validations, et un résumé statistique avec le MRR, les abonnés actifs et les inscriptions et résiliations récentes.

• Les écritures sont rares et délibérées

  Les écritures couvrent tout le cycle de vie d'un abonnement : créer un lien de paiement pour un acheteur précis, faire passer un abonnement d'une formule à une autre, le résilier en fin de période ou le réactiver, ouvrir l'espace membre pour un membre, rattacher votre propre identifiant utilisateur à un membre, et gérer les endpoints de webhook. Les liens de paiement acceptent une identité de plateforme connectée, un identifiant de membre existant, ou un identifiant utilisateur externe que vous contrôlez, ce qui permet à une application que vous exploitez de vendre via Arcalotl.

• La pagination se fait par curseur

  Les endpoints de liste prennent un curseur opaque et une limite, avec un maximum de 100 et une valeur par défaut de 25, et renvoient un next_cursor. Le champ est null ou absent sur la dernière page. Renvoyez la valeur telle quelle : la forme interne d'un curseur ne fait pas partie du contrat, donc n'en construisez pas et n'en analysez pas.

• Les clés d'idempotence rendent les reprises sûres

  Les requêtes de résiliation et de lien de paiement acceptent un en-tête Idempotency-Key. La même clé avec le même corps dans les 24 heures rejoue la réponse initiale et ajoute Idempotent-Replayed: true. La même clé avec un corps différent renvoie 422 idempotency_key_reuse, et la réutiliser pendant que la première requête tourne encore renvoie 409 request_in_flight. Générez une clé neuve par opération logique.

• Les erreurs sont des documents problem au format RFC 9457

  Les échecs renvoient application/problem+json avec un membre code stable, par exemple unauthorized, missing_scope, not_found, invalid_request, conflict, not_eligible ou rate_limited. Basez-vous sur code. Les champs title et detail sont destinés aux humains et leur formulation peut changer sans préavis.

• Les limites de débit sont publiées dans chaque réponse

  Le trafic authentifié est limité par clé à 300 requêtes par minute avec une réserve de 60. Les requêtes sans clé valide sont limitées par adresse IP à 20 par minute avec une réserve de 10, sans effet sur les appels correctement authentifiés. Chaque réponse porte RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset, et un 429 ajoute Retry-After en secondes.

• Les webhooks suivent la spécification Standard Webhooks

  Chaque livraison porte les en-têtes webhook-id, webhook-timestamp et webhook-signature. La signature est un HMAC-SHA256 sur l'identifiant, l'horodatage et le corps brut joints par des points, avec la partie décodée de votre secret whsec_ comme clé. Vérifiez sur le corps brut avant d'analyser le JSON, acceptez n'importe lequel des jetons v1 séparés par des espaces pour que la rotation du secret fonctionne, et rejetez un horodatage éloigné de plus de cinq minutes de votre horloge.

• Livraison au moins une fois, avec reprises et désactivation automatique

  Tout 2xx compte comme un succès. Tout le reste est réessayé selon un calendrier fixe d'une dizaine de tentatives étalées sur environ 2,3 jours, après quoi la livraison est marquée épuisée. Un endpoint qui cumule dix livraisons épuisées consécutives est désactivé automatiquement, et le moindre succès remet ce compteur à zéro. Une communauté peut déclarer jusqu'à cinq endpoints HTTPS, consulter le journal des tentatives et remettre une livraison précise en file.

• Le flux d'événements couvre ce que les webhooks manquent

  GET /v1/events renvoie les mêmes enveloppes que reçoivent vos endpoints, les plus récentes d'abord, filtrables par type et par after_id, pour suivre un point de reprise plutôt qu'un horodatage. Les événements projetés sont conservés 90 jours et les journaux de livraison 30, donc vous pouvez rattraper le retard longtemps après l'expiration d'un journal.

• Les changements au sein d'une version sont uniquement additifs

  L'API et l'enveloppe de webhook partagent une même chaîne de version. Au sein d'une version, vous recevez de nouveaux champs, de nouveaux paramètres facultatifs, de nouveaux types d'événements et de nouveaux endpoints, et les champs existants ne changent ni de forme ni de sens. Ignorez les champs que vous ne connaissez pas et les ajouts ne casseront jamais votre intégration.

• Le contrat est publié en OpenAPI 3.1

  Le contrat complet des requêtes et des réponses est un document OpenAPI 3.1 servi depuis le site, et les pages de référence de l'API sont générées depuis ce même document, donc la référence ne peut pas diverger de la spécification que lit votre générateur de code.

Portées des clés d'API