Interface de programmation

La PNISAN offre deux voies d'échange automatisé. L'API entrante permet à un système sectoriel (santé, agriculture, hydraulique, éducation, protection sociale) de transmettre des valeurs d'indicateurs sans passer par un fichier : chaque requête est authentifiée par une clé et signée. Les données ouvertes du portail permettent à quiconque de télécharger les valeurs validées en CSV et d'intégrer des graphiques sur un autre site, sans compte. Cette page décrit les deux.

API entrante : principes #

• Adresse de base : https://pnisan.bi/api/v1. Échanges en JSON, encodage UTF-8, messages d'erreur en français.
• Chaque envoi entre dans la zone de transit (canal API entrante), puis suit exactement le circuit de l'import de fichier : normalisation, contrôles qualité, arbitrage des sources, validation provinciale et nationale.
• Les valeurs entrent au statut « Soumis » : aucune n'est publiée sans validation humaine. Une valeur déjà validée n'est jamais remplacée par l'API ; l'écriture est consignée comme conflit et attend la décision d'un administrateur.
• L'effectif est facultatif par cette voie : une valeur sans effectif est acceptée et signalée en avertissement.

Obtenir une clé #

Les clés sont émises dans la console, écran Clés d'accès applicatif, par un super-administrateur ou un administrateur national.

Un secret perdu ne se récupère pas : l'administrateur émet une nouvelle clé et révoque l'ancienne (bouton Révoquer, action définitive). Émission, modification, révocation et chaque envoi reçu sont consignés au Journal d'audit.

Signer une requête #

Trois en-têtes sont obligatoires sur chaque requête :

La chaîne à signer compte quatre lignes séparées par un saut de ligne, sans saut de ligne final :

METHODE
CHEMIN
HORODATAGE
EMPREINTE_DU_CORPS

• METHODE : GET ou POST, en majuscules ;
• CHEMIN : chemin tel qu'envoyé, paramètres compris, par exemple /api/v1/valeurs ;
• HORODATAGE : la valeur exacte de X-Horodatage ;
• EMPREINTE_DU_CORPS : SHA-256 hexadécimal du corps brut ; pour un GET sans corps, empreinte de la chaîne vide (e3b0c442...b855).

Le corps signé doit être exactement celui qui est envoyé : sérialisez le JSON une seule fois, signez ces octets, envoyez ces octets. L'horodatage doit être à moins de cinq minutes de l'horloge du serveur (synchronisez l'émetteur par NTP), et une même signature ne sert qu'une fois : pour renvoyer un lot, signez-le de nouveau avec un nouvel horodatage.

Points d'accès #

Champs d'une valeur #

Le lot peut porter un libelle et une reference (255 caractères chacun). La réponse 201 renvoie l'ingestion créée avec ses erreurs ligne par ligne : une ligne en erreur n'empêche pas les autres de passer. Un lot identique déjà reçu avec la même clé n'est pas retraité : réponse 200 avec "deja_recu": true.

Exemple de requête #

CLE="pnin_xxxxxxxxxxxxxxxxxxxxxxxx"
SECRET="..."
CHEMIN="/api/v1/valeurs"
CORPS='{"libelle":"Suivi nutritionnel, janvier 2026","valeurs":[{"indicateur":"NUT-01","code_territoire":"BI-GI","periode_debut":"2026-01-01","periode_fin":"2026-01-31","valeur":42.5,"effectif":1200}]}'
HORODATAGE=$(date +%s)
EMPREINTE=$(printf '%s' "$CORPS" | openssl dgst -sha256 -r | cut -d' ' -f1)
SIGNATURE=$(printf 'POST\n%s\n%s\n%s' "$CHEMIN" "$HORODATAGE" "$EMPREINTE" \
  | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)

curl -sS -X POST "https://pnisan.bi$CHEMIN" \
  -H "Content-Type: application/json" \
  -H "X-Cle: $CLE" -H "X-Horodatage: $HORODATAGE" -H "X-Signature: $SIGNATURE" \
  --data-binary "$CORPS"

Utilisez --data-binary et non -d, qui modifierait le corps signé. Réponse type :

{
  "message": "Envoi reçu : 1 valeur(s) en attente de validation, 0 ligne(s) en erreur, 0 conflit(s).",
  "deja_recu": false,
  "ingestion": { "id": 42, "statut": "en_validation", "lignes_total": 1, "lignes_valides": 1, "score_qualite": 100 }
}

En Python, la signature s'écrit :

corps = json.dumps(charge, ensure_ascii=False).encode("utf-8")
horodatage = str(int(time.time()))
chaine = "\n".join(["POST", "/api/v1/valeurs", horodatage, hashlib.sha256(corps).hexdigest()])
signature = hmac.new(SECRET.encode(), chaine.encode(), hashlib.sha256).hexdigest()

Codes d'erreur #

Les erreurs ont la forme {"erreur": {"code": "...", "message": "..."}} : le code est stable, destiné au programme ; le message s'adresse à l'exploitant.

Les envois reçus se consultent dans la console, écran Ingestion des données, canal API entrante. La spécification OpenAPI 3 complète est tenue par l'équipe technique (docs/openapi.yaml).

Données ouvertes du portail #

Sans compte ni clé, le portail publie les valeurs validées au niveau national, au-dessus du seuil de masquage :

Les fichiers CSV sont encodés en UTF-8 avec marque d'ordre des octets, séparés par des points-virgules, avec la virgule comme séparateur décimal. Le numéro {id} d'un indicateur figure dans l'adresse de sa Fiche indicateur.

Pour aller plus loin #

• Le circuit des données
• Liste des indicateurs
• Clés API