API REST - Vue d'ensemble
L'API EFact est une API REST versionnée. Toutes les réponses sont au format JSON.
Base URL
| Environnement | URL |
|---|---|
| Production | https://api.efact.itzenata.com |
| Sandbox / Test | https://sandbox.efact.itzenata.com |
Versioning
L'API est versionnée via le préfixe d'URL. La version courante est v1 .
/v1/invoices
/v1/webhook_endpointsLes versions précédentes restent supportées pendant au moins 12 mois après la publication d'une nouvelle version.
Authentification
Toutes les requêtes doivent inclure la clé API secrète dans le header Authorization :
Authorization: Bearer sk_live_xxxPour les requêtes frontend en lecture seule (via client_secret), le header est :
Authorization: Bearer inv_01H..._secret_xxxVoir Authentification pour le détail complet.
Format des requêtes
- Content-Type :
application/json - Encoding : UTF-8
- Montants : en centimes DH (entiers) - ex :
12000= 120.00 DH - Dates : ISO 8601 avec timezone (
2026-04-07T10:00:00Z) - IDs : UUIDs v4
Format des réponses
Succès
{
"id": "inv_01HXXX",
"status": "pending",
"amount": 12000,
"currency": "MAD",
"created_at": "2026-04-07T10:00:00Z"
}Erreur
{
"error": {
"code": "invalid_request",
"message": "Le champ 'customer.ice' est obligatoire.",
"param": "customer.ice",
"status": 400
}
}Codes de statut HTTP
| Code | Signification |
|---|---|
200 OK | Requête réussie (GET) |
201 Created | Ressource créée avec succès (POST) |
400 Bad Request | Payload invalide ou champ manquant |
401 Unauthorized | Clé API manquante ou invalide |
403 Forbidden | Scope insuffisant (ex : clé publiable sur endpoint d'écriture) |
404 Not Found | Ressource introuvable (ou n'appartenant pas au tenant courant) |
409 Conflict | Conflit d'idempotency (même idempotency key, payload différent) |
422 Unprocessable Entity | Règle métier violée (ex : montant négatif) |
429 Too Many Requests | Rate limiting dépassé |
500 Internal Server Error | Erreur côté EFact - support à contacter |
Codes d'erreur métier
| Code | Description |
|---|---|
invalid_request | Champ manquant ou format invalide |
invalid_api_key | Clé API non reconnue |
api_key_revoked | Clé API révoquée |
resource_not_found | Facture ou webhook introuvable |
amount_too_small | Montant inférieur au minimum légal |
invalid_ice | ICE client non conforme (15 chiffres) |
dgi_transmission_failed | Échec transmission après 5 tentatives |
signature_error | Erreur lors de la signature XAdES |
idempotency_conflict | Clé d'idempotency déjà utilisée avec un payload différent |
Idempotency
Les requêtes POST acceptent un header optionnel Idempotency-Key pour éviter les doublons en cas de retry réseau :
POST /v1/invoices
Idempotency-Key: INV-2026-042-retry-1Si une requête avec la même clé a déjà réussi, EFact retourne la réponse originale sans créer de doublon. Si le payload est différent, l'API retourne 409 Conflict.
Rate limiting
| Scope | Limite |
|---|---|
| Par clé API secrète | 100 requêtes / minute |
| Par clé publiable | 300 requêtes / minute |
Les headers X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset sont inclus dans chaque réponse.
Pagination
Les endpoints de liste utilisent une pagination par curseur :
GET /v1/invoices?limit=20&starting_after=inv_01HABCParamètres
| Paramètre | Type | Description |
|---|---|---|
limit | integer | Nombre de résultats (1-100, défaut : 20) |
starting_after | string | ID du dernier objet de la page précédente |
ending_before | string | ID du premier objet (pagination inverse) |
Réponse
{
"data": [...],
"has_more": true,
"next_cursor": "inv_01HXYZ"
}Endpoints disponibles (V0.1)
| Méthode | Endpoint | Description |
|---|---|---|
POST | /v1/invoices | Créer une facture |
GET | /v1/invoices/:id | Récupérer une facture |
GET | /v1/invoices | Lister les factures du tenant |
POST | /v1/webhook_endpoints | Créer un endpoint webhook |
GET | /v1/webhook_endpoints | Lister les endpoints |
DELETE | /v1/webhook_endpoints/:id | Supprimer un endpoint |