Authentification

Toutes les requêtes vers l'API EnvoiFacile sont authentifiées via une clé API transmise dans les headers HTTP.

Clé API Headers requis Scopes Rotation de clé Rate limits Erreurs

Clé API

Votre clé API est générée depuis le dashboard administrateur ou via la commande artisan. Elle prend la forme :

text Format de la clé

ef_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ef_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Préfixe	Environnement	Usage
`ef_live_`	Production	Transactions réelles
`ef_test_`	Sandbox	Tests sans fonds réels

Headers requis

Chaque requête doit inclure le header X-API-KEY :

bash Exemple de requête authentifiée

curl -X POST https://envoifacile.com/api/v1/merchant/payin \
  -H "X-API-KEY: ef_live_xxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: unique-request-id-001" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Header	Requis	Description
`X-API-KEY`	Requis	Votre clé API secrète
`Idempotency-Key`	Requis	Identifiant unique de la requête (max 64 chars). Voir Idempotency.
`Content-Type`	Requis	Doit être `application/json`

Scopes (permissions)

Chaque clé API peut avoir des scopes limités pour restreindre les opérations autorisées :

Scope	Permissions
`payin`	Initier des collectes de fonds
`payout`	Initier des envois de fonds
`status`	Consulter le statut des transactions
`payin,payout`	Accès complet payin + payout

Principe du moindre privilège

Créez des clés distinctes par application et accordez uniquement les scopes nécessaires. Une clé front-end ne devrait avoir que le scope payin.

Rotation de clé

En cas de compromission, générez immédiatement une nouvelle clé et désactivez l'ancienne via le dashboard ou la commande :

bash Génération d'une nouvelle clé

php artisan merchant:generate-key \
  --user=1 \
  --name="Nouvelle clé Prod" \
  --env=live \
  --scopes=payin,payout

Rate limits

Les limites de taux sont appliquées par clé API et non par IP. Si vous utilisez plusieurs clés API, chacune dispose de son propre quota.

Endpoint	Limite	Fenêtre
`POST /payin`	60 requêtes	Par minute
`POST /payout`	60 requêtes	Par minute
`GET /transactions/{id}`	120 requêtes	Par minute

Webhook secret

Pour que vos webhooks soient signés et que les retries automatiques fonctionnent, configurez un webhook_secret sur votre clé API. Sans celui-ci, les retries seront abandonnés.

Erreurs d'authentification

HTTP	Code	Cause
401	`UNAUTHORIZED`	Header X-API-KEY manquant ou clé invalide
403	`FORBIDDEN_SCOPE`	La clé n'a pas le scope requis pour cette action
403	`IP_NOT_ALLOWED`	L'IP source n'est pas dans la liste blanche
403	`KEY_EXPIRED`	La clé API a expiré

json Réponse 401

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key."
  }
}