Référence API

Vue d'ensemble de l'API SFE NAFA : authentification, conventions de requêtes, pagination et gestion des erreurs.

L'API SFE NAFA est exposée en HTTP et retourne des réponses en JSON. Cette section couvre les conventions communes à tous les endpoints.

Base URL

https://api.sfenafa.com/v1

Environnements

Environnement	Base URL	Usage
Production	`https://api.sfenafa.com/v1`	Données réelles
Sandbox	`https://sandbox-api.sfenafa.com/v1`	Développement et tests

Authentification

Toutes les requêtes doivent inclure un Bearer Token dans l'en-tête Authorization :

Authorization: Bearer votre_cle_api_ici

Consultez la page Authentification pour obtenir votre clé API.

N'utilisez jamais une clé de production dans un environnement de test.

Format des requêtes

Content-Type: application/json
Accept: application/json

Horodatage et dates

Les dates/horodatages doivent être envoyés au format ISO 8601.
Tous les montants sont exprimés dans l'unité de la devise (ex. XOF).

Pagination

Les endpoints qui retournent des listes supportent la pagination :

Paramètre	Type	Description	Défaut
`skip`	integer	Nombre d'éléments à ignorer	`0`
`take`	integer	Nombre d'éléments à retourner	`20`
`search`	string	Recherche textuelle	—

Réponse paginée :

{
  "data": [...],
  "total": 142
}

Tri et filtres

Selon l'endpoint, vous pouvez filtrer par statut, période, client, fournisseur, catégorie ou référence.

Exemple :

GET /v1/invoices?status=SENT&from=2026-01-01&to=2026-01-31&skip=0&take=20

Codes de statut HTTP

Code	Signification
`200`	Succès
`201`	Ressource créée
`400`	Requête invalide (données manquantes ou incorrectes)
`401`	Non authentifié
`403`	Accès refusé (permissions insuffisantes)
`404`	Ressource introuvable
`409`	Conflit (ex: référence déjà utilisée)
`422`	Erreur de validation
`429`	Trop de requêtes (rate limiting)
`500`	Erreur interne du serveur

Format des erreurs

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Le champ 'clientId' est obligatoire.",
    "details": {
      "field": "clientId",
      "rule": "required"
    }
  }
}

code est stable et doit être utilisé pour votre logique applicative ; message est destiné à l'affichage.

Bonnes pratiques de robustesse

Implémentez des retries avec backoff pour les erreurs 429 et 5xx.
Journalisez code, endpoint, payload et identifiant corrélé de la requête.
Évitez les retries aveugles sur 4xx (souvent erreur fonctionnelle).

Rate Limiting

Plan	Limite
Starter	100 requêtes / heure
Croissance	1 000 requêtes / heure
Entreprise	Illimité (fair use)

Les en-têtes de réponse incluent :

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1746230400

L'API est disponible sur les plans Croissance et Entreprise. Pour demander un accès anticipé sur le plan Starter, contactez support@sfenafa.com.

On this page