API RefCampaign

L'API RefCampaign couvre la surface marchande publique livrée : campagnes, affiliés, candidatures, commissions, attribution des conversions et résumés dashboard.

Les endpoints sont versionnés sous /api/v1/* et authentifiés par un token Bearer (préfixé rc_live_ / rc_test_) émis depuis le tableau de bord. Les réponses suivent une enveloppe cohérente, les erreurs renvoient des codes machine-readable, et la spec est publiée en OpenAPI 3.1.

Par où commencer

• Démarrage — inscription, génération d'une clé API, première requête.
• Authentification — fonctionnement des clés API, format du header, rotation.
• Intégration / SDK — installation du paquet officiel @refcampaign/sdk dans une app JS / TS.
• Intégration / postback S2S — suivi des conversions directement depuis votre backend, sans SDK.
• Gestion des erreurs — enveloppe d'erreur, codes, retries.
• Référence API — auto-générée, chaque endpoint avec try-it-out.

Stabilité et versioning

La version publique actuelle est v1. Le préfixe d'URL porte le contrat de version : les endpoints marchands publics vivent sous /api/v1/*, et le document OpenAPI liste les opérations supportées. Les réponses n'incluent pas aujourd'hui de header dédié RefCampaign-API-Version, car le préfixe de route est le signal de version faisant foi.

Les dépréciations sont annoncées par un header HTTP Deprecation au moins 90 jours avant suppression lorsqu'une opération v1 livrée doit être retirée.

Frontières de la surface publique

La surface d'intégration publique est l'API marchande /api/v1/* documentée, ainsi que les endpoints SDK/browser et la livraison des webhooks marchands explicitement documentés. Les routes dashboard, admin, internes, auth et les routes d'implémentation webhooks provider sont des routes applicatives, pas des promesses d'API publique.

Un endpoint n'est pas considéré public simplement parce qu'il existe dans le codebase. Pour être public, une route doit être exposée intentionnellement, couverte par le registre OpenAPI et documentée dans la référence API.

Changements breaking

Les changements breaking demandent un nouveau préfixe de version ou une fenêtre de dépréciation explicite. Exemples :

• Supprimer ou renommer un endpoint.
• Supprimer un champ de réponse ou changer son type ou son sens.
• Renommer des champs de requête, changer les champs requis ou rejeter un payload auparavant valide.
• Changer les règles d'authentification, d'autorisation, de pagination, d'idempotence ou de codes HTTP pour une opération existante.

Changements non-breaking

v1 peut recevoir des ajouts compatibles sans nouveau préfixe de version. Exemples :

• Ajouter un nouveau champ de requête optionnel.
• Ajouter un nouveau champ de réponse.
• Ajouter un nouvel endpoint sous /api/v1/*.
• Ajouter un nouveau code d'erreur pour un nouveau cas de validation tout en conservant l'enveloppe d'erreur existante.
• Préciser la documentation, les exemples, les limites de débit ou les métadonnées OpenAPI générées sans changer le comportement runtime.

Compatibilité SDK

Le SDK v1 @refcampaign/sdk cible l'API v1. Tout changement breaking d'API demande un plan de compatibilité avant release : versions de SDK supportées, notes de migration et maintien éventuel des anciennes versions pendant la fenêtre de dépréciation.

Garde-fous

Le registre OpenAPI est la source de vérité de la documentation des routes publiques v1, et les tests de spec comparent les opérations documentées aux handlers /api/v1/* implémentés. Ces tests empêchent les routes dashboard, admin, internes, auth ou les routes d'implémentation webhooks provider d'être documentées comme publiques par accident.

Besoin d'aide ?

Ouvrez une issue sur le repo SDK ou contactez-nous depuis le tableau de bord.