Référence de l'API

• Adresse : https://api.tano.africa
• Contrat complet (OpenAPI 3) : /v1/openapi.json. Importez-le dans Postman, Insomnia ou votre générateur de client.
• Authentification : Authorization: Bearer <clé> ; les créations sont signées.

Dossiers

Méthode	Chemin	Rôle
POST	/v1/cases	Ouvrir un dossier. Signé.
GET	/v1/cases	Lister les dossiers.
GET	/v1/cases/{case_id}	Lire un dossier : son état, ses étapes et leur verdict, sa décision.
GET	/v1/cases/{case_id}/results	Les résultats : l’état en un mot, la décision, la reprise demandée, les contrôles, les pièces. Sans donnée personnelle.
GET	/v1/cases/{case_id}/data	Les données personnelles. Permission personal_data.
GET	/v1/cases/{case_id}/images/{piece_id}	Une image du dossier. Permission personal_data.
POST	/v1/cases/{case_id}/decision	Trancher un dossier en revue. Permission decisions. Signé.
POST	/v1/cases/{case_id}/erasure	Effacer les données personnelles d’un dossier clos. Permission personal_data. Signé.

Corps de POST /v1/cases :

Champ	Obligatoire	Description
flow_name	oui	Le nom du parcours, en minuscules (identite_ci).
country	oui	Le pays du dossier, code ISO à deux lettres (CI).
external_ref	non	Votre référence, 128 caractères au plus.
declared	non	Ce que vous savez de la personne : surname, given_names, birth_date. Confronté à la pièce, jamais cru sur parole.

GET /v1/cases accepte external_ref (votre référence, exacte), q (début de référence ou identifiant), status, country, created_after, created_before, limit et cursor.

Les résultats d’un dossier

state dit où en est le dossier, en un mot :

state	Ce que cela veut dire
awaiting_applicant	Le parcours attend la personne.
processing	Les photos sont arrivées, les contrôles tournent.
in_review	Un opérateur examine le dossier.
resubmission_requested	La personne doit reprendre des photos (resubmission.steps) : ce n’est pas un refus.
approved	Approuvé.
rejected	Refus définitif (decision.reason_code). Une révision reste possible : case.decision_revised.
expired, abandoned	Le dossier n’a pas abouti.

checks rend le compte rendu de chaque contrôle — status (ok, attention, failed), reasons (des codes), measures (des nombres) —, duplicates les autres dossiers qui portent la même pièce ou le même visage, pieces les images reçues (available : encore conservée).

Les données personnelles

GET /v1/cases/{case_id}/data rend l’identité lue sur la pièce (et sa concordance avec la zone imprimée), ce que vous aviez déclaré, ce que la personne a saisi et ses réponses aux questionnaires ; /images/{piece_id} rend une image. Ces deux routes demandent une clé créée avec la permission personal_data (console, page Clés d’API) — aucune clé ne la reçoit par défaut — et chaque lecture s’inscrit au journal des consultations du dossier, que votre équipe voit dans la console comme un démasquage.

Décider d’un dossier en revue

POST /v1/cases/{case_id}/decision
{"outcome": "approve", "reason_code": "identity_confirmed"}

outcome : approve, reject, ou resubmit avec steps (document, face). Le motif vient de la même liste fermée qu’à la console. Seulement sur un dossier en revue (case_not_in_review sinon) ; la décision passe par le même chemin qu’un opérateur, puis le dossier conclut : case.decided ou case.resubmission_requested.

Une clé qui décide tranche seule : ni verrou, ni habilitation par pays, ni double validation. La décision est inscrite au journal du dossier comme celle de la clé (key:<identifiant>). Créez une clé avec la permission decisions (console, page Clés d’API) — aucune ne la reçoit par défaut — et gardez-la sur le serveur qui en a besoin.

Effacer les données d’un dossier

POST /v1/cases/{case_id}/erasure efface, sur un dossier clos, tout ce qui dit qui était la personne : images, identité lue, portraits et gabarits de visage, données déclarées et saisies, réponses aux questionnaires, champs lus sur la pièce et ses empreintes, commentaires et corrections de revue. Reste la trace : le dossier, ses étapes, ses verdicts, ses décisions et le journal — la preuve qu’une vérification a eu lieu et comment. La réponse et le webhook case.personal_data_erased disent ce qui a été effacé ; rejouer l’appel rend des zéros.

Vérifiez vos obligations de conservation avant d’effacer : la réglementation contre le blanchiment impose souvent de garder les éléments d’identification plusieurs années après la fin de la relation.

Sessions du parcours hébergé

Méthode	Chemin	Rôle
POST	/v1/sessions	Créer une session et obtenir le lien du parcours. Signé.
GET	/v1/sessions/{session_id}	Lire l’état d’une session.

Les autres routes /v1/sessions/… sont celles du parcours hébergé lui-même : vous n’avez pas à les appeler.

Webhooks

Méthode	Chemin	Rôle
POST	/v1/webhook-endpoints	Déclarer une adresse. Signé.
GET	/v1/webhook-endpoints	Lister les adresses.
GET	/v1/webhook-endpoints/{id}/deliveries	Consulter les livraisons.
POST	/v1/webhook-endpoints/{id}/replay	Rejouer une livraison.
POST	/v1/webhook-endpoints/{id}/resume	Relancer une adresse suspendue.

Intégration dans votre page

Méthode	Chemin	Rôle
GET	/v1/journey-embedding	Les origines autorisées à afficher le parcours dans leurs pages.
POST	/v1/journey-embedding	Les remplacer : {"origins": ["https://…"]}, vingt au plus. Signé.

Voir Afficher le parcours dans votre page.

Clés et consommation

Méthode	Chemin	Rôle
GET	/v1/api-keys	Lister les clés.
DELETE	/v1/api-keys/{key_id}	Révoquer une clé.
GET	/v1/usage	La consommation de la période.
GET	/v1/contract	Le contrat et les services souscrits.

Le format des erreurs

Toute erreur a la même forme, sur toutes les routes :

{
  "error": {
    "type": "validation_error",
    "code": "unsupported_document_type",
    "message": "Le parcours n'accepte pas les pièces émises par ML.",
    "doc_url": "https://docs.tano.africa/errors/unsupported_document_type",
    "request_id": "req_…",
    "field": "subject"
  }
}

Testez le code, qui est stable ; le message peut changer. Voir la liste des erreurs.