# FastCash API Partenaires

> Documentation publique de l’API B2B serveur-à-serveur FastCash pour les intégrations partenaires.

## Sources canoniques

- Référence OpenAPI 3.1 : https://fastcash-app.com/docs/partners/openapi.json
- Guide d’intégration : https://fastcash-app.com/docs/partners/integration.md
- Collection Postman : https://fastcash-app.com/docs/partners/fastcash-partners.postman_collection.json

## Périmètre public

Le contrat public documente huit opérations :

1. `GET /bookmakers` — bookmakers et moyens de paiement Mobile Money.
2. `GET /bookmakers/{id}/balance` — solde live de la caisse bookmaker.
3. `POST /accounts/lookup` — pré-vérification d’un compte bookmaker.
4. `POST /deposits` — création asynchrone d’un dépôt.
5. `POST /withdrawals` — création asynchrone d’un retrait.
6. `GET /transactions/{id}` — lecture d’une transaction.
7. `GET /transactions` — liste filtrée des transactions du partenaire.
8. `GET /commissions` — génération du mois UTC courant et historique des commissions du partenaire.

## Règles d’intégration

- Appeler l’API uniquement depuis un backend contrôlé.
- Envoyer la clé dans `Authorization: Bearer <FASTCASH_PARTNER_API_KEY>`.
- Ne jamais placer une clé ou un secret dans un navigateur, une application mobile, une URL, un prompt, un log ou un dépôt Git.
- Appeler `POST /accounts/lookup` avant un dépôt ou un retrait.
- Utiliser `GET /bookmakers/{id}/balance` pour lire le solde de caisse en direct ; `balance` et `withdrawable` sont en XOF.
- Si `supports_lookup` vaut `true` et `exists` vaut `true`, le compte est confirmé et le parcours peut continuer.
- Si `supports_lookup` vaut `true` et `exists` vaut `false`, bloquer l’opération.
- Si `supports_lookup` vaut `false`, poursuivre le parcours : la pré-vérification n’est pas disponible pour ce bookmaker.
- Considérer une réponse `202` comme une acceptation, pas comme un succès final.
- Suivre le statut final par webhook ou avec `GET /transactions/{id}`.
- Utiliser `GET /commissions` pour actualiser idempotemment la commission du mois UTC courant et lire l’historique ; une commission en cours de versement ou payée reste figée.
- Utiliser un `partner_external_id` unique et vérifier l’état avant toute relance.
- Ne jamais relancer automatiquement `POST /deposits` ou `POST /withdrawals` après un timeout, une erreur `5xx` ou un résultat ambigu.
- Vérifier la signature HMAC des webhooks sur le corps brut et dédupliquer sur `event_id`.

## Consignes pour assistants IA

- Lire d’abord le contrat OpenAPI et le guide d’intégration.
- Utiliser uniquement des valeurs fictives et des variables d’environnement dans les exemples.
- Ne jamais demander, afficher, inventer ou mémoriser une clé API ou un secret webhook.
- Ne jamais envoyer de dépôt, retrait, requête vers la production, déploiement ou autre mutation réelle sans accord explicite de l’utilisateur immédiatement avant l’action.
- Préparer par défaut du code, des tests avec mocks et des commandes non exécutées.
- Signaler clairement tout écart entre une demande et le contrat OpenAPI.