Intégrez Flexy dans votre produit

Démarrage

1. Créez un compte partenaire depuis la page d'inscription.
2. Attendez qu'un administrateur active votre compte.
3. Connectez-vous → Développement → API → créez un jeton. Copiez le secret immédiatement (affiché une seule fois).
4. Alimentez votre portefeuille (recharge CCP / CIB), puis commencez à appeler l'API avec votre jeton.

URL de base

URL de base de production (à utiliser dans toutes les intégrations) :

https://flexy-pro.com/api/external/v1/flexy

Authentification

Chaque requête sous /api/external/v1/** exige un jeton Bearer créé dans le portail partenaire.

Authorization: Bearer fp_live_YOUR_SECRET

• Stockez le secret dans un gestionnaire de secrets — il n'est plus jamais affiché après création/rotation.
• Les jetons désactivés ou supprimés renvoient HTTP 401.
• Les cookies de session ne sont pas utilisés pour l'API externe.

curl -sS \\
  -H 'Authorization: Bearer fp_live_YOUR_SECRET' \\
  -H 'Accept: application/json' \\
  'https://flexy-pro.com/api/external/v1/flexy/eligibility'

Format de réponse

Toutes les réponses utilisent une enveloppe commune :

{
  "status": "SUCCESS" | "ERROR",
  "message": "Human-readable message",
  "data": { ... },
  "timestamp": "2026-10-01T12:00:00Z",
  "errors": { "field": "optional field errors" }
}

Endpoints

{
  "status": "SUCCESS",
  "message": "OK",
  "data": {
    "minAmountDzd": 100,
    "balance": 1500.00,
    "canOperate": true
  },
  "timestamp": "2026-10-01T12:00:00Z"
}

{
  "status": "SUCCESS",
  "message": "OK",
  "data": {
    "offers": [
      { "planCode": "EXAMPLE_PLAN", "label": "Offer label", "amount": 500 }
    ],
    "terminalStatus": null,
    "providerMessage": null
  },
  "timestamp": "2026-10-01T12:00:00Z"
}

{
  "phone": "0551234567",
  "type": "detail",
  "amount": 100,
  "planCode": null
}

{
  "phone": "0771234567",
  "type": "gros",
  "amount": 500
}

{
  "phone": "0661234567",
  "type": "detail",
  "amount": 500,
  "planCode": "EXAMPLE_PLAN"
}

{
  "status": "SUCCESS",
  "message": "Flexy operation completed",
  "data": {
    "id": 12345,
    "balanceAfter": 1000.00,
    "totalGainsAfter": 12.50
  },
  "timestamp": "2026-10-01T12:00:00Z"
}

curl -sS -X POST \\
  -H 'Authorization: Bearer fp_live_YOUR_SECRET' \\
  -H 'Content-Type: application/json' \\
  -H 'Idempotency-Key: order-abc-001' \\
  -d '{"phone":"0551234567","type":"detail","amount":100}' \\
  'https://flexy-pro.com/api/external/v1/flexy/operations'

Idempotence

Sur POST /operations, envoyez un en-tête Idempotency-Key unique par opération métier (par ex. votre id de commande). Les retries avec la même clé renvoient la première réponse réussie au lieu de créer un Flexy en double.

Limites de débit

Les limites s'appliquent par jeton API :

En cas de dépassement, l'API renvoie 429 avec l'en-tête Retry-After (secondes) et le message flexy.error.rateLimited.

Erreurs et codes HTTP

Exemple de corps d'erreur

{
  "status": "ERROR",
  "message": "Insufficient balance for this amount.",
  "timestamp": "2026-10-01T12:00:00Z"
}

{
  "status": "ERROR",
  "message": "Missing or invalid Authorization Bearer token",
  "timestamp": "2026-10-01T12:00:00Z"
}

Flux d'intégration recommandé

1. Appelez GET /eligibility — vérifiez que canOperate est true et que le montant ≤ solde.
2. Pour les packs d'offres : GET /offers?phone=…, choisissez un planCode et le montant correspondant.
3. Appelez POST /operations avec un Idempotency-Key unique.
4. Stockez data.id. Interrogez GET /operations/{id} ou la liste jusqu'à un statut terminal (FULFILLED, REFUNDED, FAILED, …).
5. Sur 429, attendez Retry-After secondes et réessayez avec la même clé d'idempotence.

Bonnes pratiques

• N'embarquez jamais de secrets API dans des apps mobiles ou frontends publics.
• Faites tourner les jetons depuis Développement → API si un secret fuit.
• Envoyez toujours Idempotency-Key à la création pour éviter les doubles recharges sur retry réseau.
• Utilisez l'URL de production https://flexy-pro.com dans les systèmes live.
• Gardez les jetons côté serveur uniquement et suivez les opérations depuis votre portail partenaire.