API Reference Bemba

L'API Bemba est une API REST qui permet d'interagir avec toutes les fonctionnalités du système.

Base URL

https://sig.example.com/api

Authentification

L'API utilise des JSON Web Tokens (JWT) pour l'authentification.

Obtenir un Token

curl -X POST https://sig.example.com/api/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password"}'

Réponse :

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "refresh_token": "abc123...",
  "user": {
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "email": "user@example.com",
    "roles": ["ROLE_USER"],
    "nom": "Exemple",
    "prenom": "Agent"
  }
}

Le JWT vit 1 heure, le refresh token 30 jours. Si la double authentification est activée, la réponse porte requires2FA: true et le jeton s'obtient ensuite par POST /api/2fa/verify (voir Login).

Session par cookies et CSRF

La connexion pose aussi les cookies BEARER, REFRESH_TOKEN (httpOnly) et XSRF-TOKEN. Un client qui s'appuie sur ces cookies (cas du navigateur) doit renvoyer la valeur de XSRF-TOKEN dans l'en-tête X-CSRF-TOKEN à chaque POST, PUT, PATCH ou DELETE, sinon la requête est refusée en 403. Un client qui envoie uniquement l'en-tête Authorization: Bearer n'est pas concerné.

Utilisateur courant et permissions

Endpoint	Description
GET /api/me	Profil de l'utilisateur connecté
GET /api/me/permissions	Codes de permission module.action accordés (ex. registre.menages_edit)

Chaque endpoint protégé vérifie une permission de ce type ; les données renvoyées sont en plus limitées au périmètre de l'utilisateur (institution et projets).

Utiliser le Token

Incluez le token dans le header Authorization :

curl https://sig.example.com/api/menages \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."

Rafraichir le Token

curl -X POST https://sig.example.com/api/token/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "abc123..."}'

Le refresh token est renouvelé à chaque appel (rotation). La déconnexion se fait par POST /api/token/invalidate (voir Logout).

---

Format des Reponses

L'API expose deux familles d'endpoints, avec deux formats.

Contrôleurs métier : { success, data }

La plupart des endpoints (bénéficiaires, transferts, paiements, plaintes, suivi-évaluation, assistant…) renvoient :

{
  "success": true,
  "data": [ { "...": "..." } ],
  "pagination": { "page": 1, "limit": 20, "total": 1234, "pages": 62 }
}

pagination n'apparaît que sur les listes paginées (paramètres page et limit). En cas d'erreur : { "success": false, "error": "message" } (ou message) avec le code HTTP adapté.

Ressources API Platform : JSON-LD / Hydra

Les ressources de référence (ménages, régions, secteurs, localités, projets…) suivent le format Hydra :

{
  "@context": "/api/contexts/Menage",
  "@id": "/api/menages",
  "@type": "hydra:Collection",
  "hydra:totalItems": 1234,
  "hydra:member": [ { "@id": "/api/menages/0f8fad5b-…", "@type": "Menage", "codeMenage": "…" } ],
  "hydra:view": {
    "@id": "/api/menages?page=1",
    "@type": "hydra:PartialCollectionView",
    "hydra:first": "/api/menages?page=1",
    "hydra:last": "/api/menages?page=62",
    "hydra:next": "/api/menages?page=2"
  }
}

Envoyer Accept: application/json donne un tableau JSON simple, sans métadonnées Hydra.

Les erreurs de ces ressources suivent la RFC 7807 (application/problem+json) :

{
  "type": "/errors/404",
  "title": "An error occurred",
  "status": 404,
  "detail": "Not Found"
}

Les identifiants sont des UUID.

---

Codes HTTP

Code	Description
200	Succes
201	Ressource creee
204	Succes sans contenu (DELETE)
400	Requete invalide (champ manquant, valeur hors liste)
401	Pas de session : jeton absent, expiré ou invalide
403	Session valide mais permission manquante, objet hors du périmètre de l'utilisateur, ou en-tête CSRF absent
404	Ressource introuvable, y compris pour un identifiant mal formé (non UUID)
422	Erreur de validation (ressources API Platform)
429	Trop de requêtes (connexion, assistant)
500	Erreur serveur

---

Pagination

Ressources API Platform : paramètres page et itemsPerPage. La taille par défaut dépend de la ressource (20 pour les ménages, 30 sinon) ; itemsPerPage est plafonné à 200. Certaines ressources acceptent pagination=false.

Contrôleurs métier : paramètres page et limit (20 par défaut), réponse dans le bloc pagination.

curl "https://sig.example.com/api/menages?page=2&itemsPerPage=50" \
  -H "Authorization: Bearer TOKEN"

---

Filtres

Les ressources API Platform filtrent sur les propriétés, souvent par identifiant de relation :

Filtre	Description	Exemple
region.id	Filtrer par region	?region.id=<uuid>
secteur.id	Filtrer par secteur	?secteur.id=<uuid>
localite.id	Filtrer par localite	?localite.id=<uuid>
projet.id	Filtrer par projet	?projet.id=<uuid>
statut	Filtrer par statut	?statut=actif
order[champ]	Tri	?order[createdAt]=desc

Les contrôleurs métier utilisent des paramètres simples propres à chaque endpoint (search, statut, projet_id, region…) : voir la page de chaque endpoint.

---

Endpoints Principaux

Authentification

Methode	Endpoint	Description
POST	/api/login	Connexion
POST	/api/2fa/verify	Code de double authentification
POST	/api/token/refresh	Rafraichir token
POST	/api/token/invalidate	Deconnexion
GET	/api/me	Utilisateur courant
GET	/api/me/permissions	Permissions de l'utilisateur

Menages

Methode	Endpoint	Description
GET	/api/menages	Liste des menages
GET	/api/menages/\{id\}	Detail d'un menage
POST	/api/menages	Creer un menage
POST	/api/menages/\{id\}/update	Modifier un menage (formulaire complet)
DELETE	/api/menages/\{id\}	Supprimer un menage

Beneficiaires

Methode	Endpoint	Description
GET	/api/beneficiaires	Liste des beneficiaires
GET	/api/beneficiaires/\{id\}	Detail d'un beneficiaire

Transferts (cycles de paiement)

Methode	Endpoint	Description
GET	/api/cycles	Liste des transferts
POST	/api/cycles	Creer un transfert
POST	/api/cycles/\{id\}/generate-payments	Generer les paiements
POST	/api/cycles/\{id\}/soumettre	Soumettre a la validation
POST	/api/cycles/\{id\}/valider	Valider le niveau suivant

Autres modules

Préfixe	Description
/api/plaintes	Mécanisme de gestion des plaintes (voir Plaintes)
/api/suivi-evaluation	PTBA, indicateurs, risques, missions (voir Suivi & Évaluation)
/api/assistant	Assistant Bemba (voir Assistant)
/api/photos	Photos servies par URL signée (voir Photos)

---

Exemples de Code

JavaScript (Fetch)

const login = async (email, password) => {
  const response = await fetch('https://sig.example.com/api/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password })
  });
  return response.json();
};

const getMenages = async (token) => {
  const response = await fetch('https://sig.example.com/api/menages', {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  return response.json();
};

Python (Requests)

import requests

# Login
response = requests.post(
    'https://sig.example.com/api/login',
    json={'email': 'user@example.com', 'password': 'password'}
)
token = response.json()['token']

# Get menages
menages = requests.get(
    'https://sig.example.com/api/menages',
    headers={'Authorization': f'Bearer {token}'}
).json()

PHP (Guzzle)

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://sig.example.com/api']);

// Login
$response = $client->post('/api/login', [
    'json' => ['email' => 'user@example.com', 'password' => 'password']
]);
$token = json_decode($response->getBody())->token;

// Get menages
$menages = $client->get('/api/menages', [
    'headers' => ['Authorization' => "Bearer $token"]
]);