Endpoints

L’API expose deux endpoints facturés, plus un endpoint utilitaire GET /v1/me (non facturé) pour vérifier votre signature et votre solde.

Endpoint	Coût	Description
GET /v1/centres/candidats/{matricule}	1 crédit	Affectation du candidat (centre, salle, table).
GET /v1/resultats/candidats/{matricule}	1 crédit	Résultat publié — mention et série, admis uniquement.
GET /v1/me	0 crédit	Informations sur votre clé et votre solde.

Toutes les requêtes doivent être signées (voir Authentification). Une signature absente ou invalide renvoie 401 sans débit.

---

GET /v1/centres/candidats/{matricule}

Retourne l’affectation publiée du candidat pour la session d’examen la plus récente disponible (centre, salle, numéro de table, GPS quand disponible).

URL

GET https://partner.exatrust.cg/v1/centres/candidats/{matricule}

matricule est l’identifiant national du candidat. Format accepté : [A-Z0-9]{3,30}. Auto-mis en majuscules côté serveur.

Exemple

curl -sS \
  -H "Signature-Input: sig1=(\"@method\" \"@path\" \"@query\");created=1715680570;keyid=\"pk_orange_8a3b\";alg=\"ed25519\";nonce=\"MmJ6...\"" \
  -H "Signature: sig1=:WsV/LpsuuS5RVFA0u+xIG47oOHXjC6pyLuSSWVJspt4s2A8Djvt1...:" \
  https://partner.exatrust.cg/v1/centres/candidats/EANB260094

Réponse (200)

{
  "matricule": "EANB260094",
  "session_examen_id": 6,
  "candidat": {
    "nom": "LOUMOUAMOU",
    "prenom": "Mignon Marcel Petith",
    "date_naissance": "2009-09-30",
    "sexe": "M",
    "departement": "POINTE-NOIRE"
  },
  "affectation": {
    "centre": {
      "nom": "CENTRE N° 28 : ECOLE CHARLES MYNYNGOU 2",
      "latitude": -4.792712,
      "longitude": 11.875706
    },
    "salle": { "libelle": "Salle 04" },
    "numero_table": 16
  },
  "meta": {
    "request_id": "01HXY...",
    "credit_mode": "postpaid",
    "credits_remaining": 95
  }
}

Champs de réponse

Champ	Type	Description
matricule	string	Matricule normalisé (majuscules).
session_examen_id	int	Identifiant interne de la session d’examen résolue.
candidat.nom / prenom	string	Nom et prénoms officiels au format administratif.
candidat.date_naissance	string YYYY-MM-DD	Date de naissance déclarée.
candidat.sexe	"M" | "F" | null	Sexe déclaré.
candidat.departement	string	Département d’origine.
affectation.centre.nom	string	Nom officiel du centre.
affectation.centre.latitude / longitude	number | null	GPS du centre quand disponible (~80 % des centres).
affectation.salle.libelle	string	Libellé de la salle.
affectation.numero_table	int	Numéro de table.
meta.request_id	string	Identifiant de la requête, à fournir au support.
meta.credit_mode	"prepaid" | "postpaid"	Mode de facturation actif.
meta.credits_remaining	int	Solde restant après débit de cette requête.

Affectations publiées ~7 jours avant l'examen

Le champ affectation peut être null si la convocation n’est pas encore publiée. Aucun crédit n’est débité dans ce cas (404 EDITION_NOT_FOUND).

Erreurs typiques

Code HTTP	Code applicatif	Cause
401	INVALID_SIGNATURE	Signature absente, malformée ou non vérifiable.
402	INSUFFICIENT_CREDITS	Solde épuisé (mode prepaid).
404	CANDIDAT_NOT_FOUND	Matricule inconnu pour la session courante. 1 crédit débité.
404	EDITION_NOT_FOUND	Aucune session active publiée. Pas de débit.
429	RATE_LIMITED	Trop de requêtes (voir Erreurs & limites).

---

GET /v1/resultats/candidats/{matricule}

Retourne le résultat publié du candidat : mention, série (pour BAC), établissement d’admission. Le système de résultats ne contient que les candidats admis.

URL

GET https://partner.exatrust.cg/v1/resultats/candidats/{matricule}

Format du matricule : [A-Z0-9-]{3,30} (le tiret est accepté côté résultats).

Exemple

curl -sS \
  -H "Signature-Input: sig1=(\"@method\" \"@path\" \"@query\");created=1715680570;keyid=\"pk_orange_8a3b\";alg=\"ed25519\";nonce=\"MmJ6...\"" \
  -H "Signature: sig1=:WsV/LpsuuS5RVFA0u+xIG47oOHXjC6pyLuSSWVJspt4s2A8Djvt1...:" \
  https://partner.exatrust.cg/v1/resultats/candidats/EANB260094

Réponse (200)

{
  "matricule": "EANB260094",
  "session_id": 26,
  "session_name": "2025",
  "examen_id": 3,
  "examen_name": "BEPC",
  "candidat": {
    "nom": "LOUMOUAMOU",
    "prenom": "Mignon Marcel Petith",
    "date_naissance": "2009-09-30",
    "sexe": "M",
    "mention": "AB",
    "serie": null
  },
  "etablissement": {
    "code": "ETS001",
    "name": "École Charles Mynyngou",
    "region": "Brazzaville"
  },
  "meta": {
    "request_id": "01HXY...",
    "credit_mode": "prepaid",
    "credits_remaining": 4285
  }
}

Champs de réponse

Champ	Type	Description
matricule	string	Matricule normalisé.
session_id	int	Identifiant interne de la session de résultats.
session_name	string	Année de la session, ex. "2025".
examen_id	int	Identifiant interne de l’examen.
examen_name	"BAC" | "BEPC" | "CEP" | "BTS"	Type d’examen.
candidat.mention	"TB" | "B" | "AB" | "PAS" | null	Mention obtenue. Codes courts normalisés (Très Bien, Bien, Assez Bien, Passable).
candidat.serie	string | null	Série pour BAC uniquement : A, A4, C, D, E, F, G, H. null ailleurs.
etablissement.code	string	Code de l’établissement (référentiel résultats — différent de code_ets côté centres).
etablissement.name	string	Nom officiel.
etablissement.region	string	Région administrative.
meta.*	—	Voir endpoint centres.

Un 404 ne révèle pas l'échec du candidat

Le système de résultats ne contient que les admis. Un 404 CANDIDAT_NOT_FOUND peut signifier « matricule inconnu » ou « candidat non admis » — l’API ne distingue pas les deux cas. C’est volontaire : nous ne révélons jamais l’échec d’un candidat. Construisez votre UX autour d’un message neutre du type « Aucun résultat publié pour ce matricule » — n’induisez jamais l’échec.

Erreurs typiques

Code HTTP	Code applicatif	Cause	Crédit débité ?
401	INVALID_SIGNATURE	Signature invalide.	Non
402	INSUFFICIENT_CREDITS	Solde épuisé (prepaid).	Non
404	CANDIDAT_NOT_FOUND	Matricule inconnu ou candidat non admis.	Oui
404	EDITION_NOT_FOUND	Résultats pas encore publiés (typiquement 2 à 6 semaines après l’examen).	Non
429	RATE_LIMITED	Trop de requêtes.	Non

Pré-validez le matricule

Comme un 404 CANDIDAT_NOT_FOUND consomme 1 crédit, validez côté client la longueur et le format du matricule (regex [A-Z0-9-]{3,30}) avant de payer pour une faute de frappe.

---

GET /v1/me

Utilitaire non facturé. Retourne votre identité partenaire et votre solde.

{
  "user_id": 42,
  "email": "tech@orange.cg",
  "key_id": "pk_orange_8a3b",
  "credits": { "mode": "prepaid", "balance": 4287, "total_consumed": 5713 }
}

credits est null si votre compte n’a pas encore été provisionné. Cet endpoint ne consomme pas de crédit, même en cas de 429.

---

Diagramme du flux d’appel

sequenceDiagram
    autonumber
    participant App as Backend partenaire
    participant Sign as Lib de signature
    participant API as ExaTrust API

    App->>Sign: req = GET /v1/resultats/candidats/EANB260094
    Sign->>Sign: base = @method + @path + @query + params
    Sign->>Sign: signature = Ed25519.Sign(privKey, base)
    Sign-->>App: Signature-Input + Signature
    App->>API: HTTPS + Signature-Input + Signature (+ mTLS si activé)
    API->>API: Vérifie Ed25519 (50 µs)
    API->>API: Anti-replay (Redis, TTL 5 min)
    API->>API: Rate-limit
    API->>API: Crédits
    API-->>App: 200 JSON · X-Request-Id · meta.credits_remaining