# API SMICO Flash USSD — contrat JSON

Source : *Documentation de l’API SMICO FLASH USSD*, Joël SOSSOU, version **1.0.2** du 05/10/2022 (1.0.1 le 14/07/2022). Un seul endpoint, POST JSON. Le routage se fait par le champ `methode`.

Ce n’est pas le contrat Juakali (`apikey` + `codeclient`). Ici l’authentification métier est un **jeton de session** (`methode` = `token`), puis `nomagent` = `FLASH` et le champ `token`.

Les exemples nominatifs, MSISDN, numéros de compte, dossiers, soldes et jetons du PDF ne sont pas recopiés. Les noms de champs et les règles le sont.

## Transport

| Élément | Valeur |
|---|---|
| Protocole | REST JSON sur HTTPS, port 443 |
| Chemin PDF (test, 2022) | `/SMICO_FLASH_USSD_DEV_WEB/FR/APIEXTERNE/pmobileapi.awp` |
| Hôtes cités dans le PDF | `https://10.99.22.4` et `https://demovision.cagecfi.pro` — hôtes CAGECFI, pas les hôtes SMICO |
| Auth HTTP citée dans le PDF | Basic, utilisateur et mot de passe non fournis dans le document (`{user}` / `{password}`) |
| Auth métier | Jeton renvoyé par `methode` = `token` |
| Site IIS constaté en prod SMICO (2026-10-02) | `http://10.243.11.6/API_FLASH_USSD_V1_WEB/FR/APIEXTERNE/pmobileapi.awp` |

Le PDF annonce aussi deux MSISDN de test. Ils identifient un client nommé dans les exemples : ils restent dans le PDF, pas ici.

## Codes de réponse (PDF)

| Code | Sens dans ce document |
|---|---|
| `100000` | SUCCESS |
| `100001` | ERREUR INTERNE |
| `100003` | INFORMATION NON TROUVEE |

Orthographes réellement présentes dans les exemples, à accepter telles quelles :

- `codeReponse` sur la réponse de `token` ; `codereponse` partout ailleurs
- `detailreponse` sur la plupart des enveloppes
- `descriptreponse` sur `wchangementpin` (pas `descriptionreponse`)
- `descriptionreponse` sur les lignes de `wlistedossiercreditclient` et `wtableauremboursement`

## Enveloppe commune (sauf `token`)

```json
{
  "codeapi": "API_MOBILE",
  "nomagent": "FLASH",
  "token": "{jeton renvoyé par methode=token}",
  "methode": "{nom ci-dessous}"
}
```

`token` n’envoie ni `codeapi`, ni `nomagent`, ni `token`.

## 1. `token` — ouvrir une session

Génère la clé de session utilisée ensuite.

Requête :

```json
{
  "methode": "token",
  "agentcode": "flash",
  "agentpasse": "{mot de passe agent}"
}
```

Réponse :

| Champ | Rôle |
|---|---|
| `methodeoperation` | `token` |
| `codeReponse` | `100000` si succès |
| `detailreponse` | `SUCCESS` |
| `referencereponse` | le jeton à renvoyer dans `token` |

## 2. `signaletique` — fiche client

Lecture. Clé d’entrée : le MSISDN, pas le `codeclient`.

| Champ entrée | Rôle |
|---|---|
| `msisdn` | numéro de téléphone |
| `referenceope` | référence d’appel |
| `typeCompte` | vide = tous les comptes ; `E` = épargne ; `D` = DAT ; `C` = crédit |

Réponse (enveloppe + fiche) :

| Champ | Rôle |
|---|---|
| `methodeoperation` | `signaletique` |
| `referenceope` | écho |
| `numerocompte` | peut être vide ; les comptes sont dans `detailcompte` |
| `codereponse` / `detailreponse` | |
| `ulrphoto` / `ulrpiece` / `ulrsignature` | URL (orthographe `ulr` dans le PDF) |
| `encodephoto` / `encodepieceid` / `encodesignature` | contenu encodé |
| `numtel` | |
| `nom` / `prenom` / `sexe` / `email` | |
| `adressegeo` | |
| `datenaissance` | `YYYYMMDD` |
| `codeclient` | code adhérent |
| `idclient` | entier ; c’est la valeur à passer à `wcomptes.identite` |
| `nomagence` | |
| `detailcompte` | tableau |

Chaque élément de `detailcompte` :

| Champ | Rôle |
|---|---|
| `idcompte` | |
| `numerocompte` | |
| `codedevise` | ex. code numérique de devise |
| `nomproduit` / `nomcompte` / `typeproduit` / `nomdevise` / `idproduit` | |
| `iban` | peut être vide |

## 3. `wcomptes` — comptes à lier

Lecture. Liste les comptes d’un client pour une opération.

| Champ entrée | Rôle |
|---|---|
| `identite` | `idclient` renvoyé par `signaletique` |
| `operationAutorise` | `DEPOT` (comptes qui acceptent un dépôt) ou `RETRAIT` (comptes qui acceptent un retrait) |

La réponse du PDF est un **tableau JSON**, pas une enveloppe `codereponse`.

| Champ | Rôle |
|---|---|
| `idcompte` / `idproduit` / `nomproduit` | |
| `numcpte` | numéro de compte (pas `numerocompte`) |
| `nomcompte` | |
| `iddevise` / `nomdevisecourt` | |
| `dateouverture` | `YYYY-MM-DD` |
| `cautionsolde` | |
| `operationsautorisees` | texte multi-lignes. Valeurs vues dans l’exemple : `DEPOT`, `RETRAIT`, `TRANSFERT`, `RECEPTION_VIREMENT` |

## 4. `consultation` — solde

Lecture.

| Champ entrée | Rôle |
|---|---|
| `referenceope` | |
| `numerocompte` | |
| `pinclient` | code PIN |
| `pinotp` | code OTP |

Le PDF précise : selon le paramétrage, PIN ou OTP ; dans l’exemple le PIN est obligatoire et `pinotp` est vide.

Réponse :

| Champ | Rôle |
|---|---|
| `methodeoperation` | `consultation` |
| `referenceope` / `numerocompte` | |
| `soldedisponible` / `soldecomptable` | nombres |
| `codereponse` / `detailreponse` | |

## 5. `releve` — opérations du compte

Lecture. Le nom n’est pas `relevecompte` (contrat Juakali). L’exemple n’a **pas** de `datedebut` / `datefin` : mêmes champs que `consultation` (`referenceope`, `numerocompte`, `pinclient`, `pinotp`). Même règle PIN ou OTP.

Réponse : enveloppe `methodeoperation`, `referenceope`, `codereponse`, `detailreponse`, `numerocompte`, plus `detail` (tableau).

Chaque ligne de `detail` :

| Champ | Rôle |
|---|---|
| `ref` | référence d’opération |
| `dateope` | `DD-MM-YYYY` |
| `montant` | signé |
| `libelleope` | |
| `ordretrie` | clé de tri, date `YYYYMMDD` collée à la référence |

## 6. `wchangementpin` — changement de PIN

Écriture. Ne pas appeler sur un client réel pour un test.

| Champ entrée | Rôle |
|---|---|
| `msisdn` | |
| `codepinanc` | PIN actuel |
| `codepinnv` | nouveau PIN |

Réponse :

| Champ | Rôle |
|---|---|
| `methodeoperation` | `wchangementpin` |
| `referenceope` | peut être vide |
| `codereponse` | |
| `descriptreponse` | `SUCCESS` dans l’exemple |
| `referencereponse` | dans l’exemple, reprend le nouveau PIN |

## 7. `wlistedossiercreditclient` — dossiers de crédit

Lecture. Le titre et la réponse sont une liste de dossiers. La phrase du PDF (« ajouter une transaction dans le corebanking ») ne correspond pas à l’exemple : elle n’est pas reprise comme règle.

| Champ entrée | Rôle |
|---|---|
| `msisdn` | |
| `pinclient` / `pinotp` | même règle que `consultation` |

Réponse : **tableau JSON**. Chaque élément :

| Champ | Rôle |
|---|---|
| `codereponse` / `descriptionreponse` | |
| `idclient` | dans l’exemple, le code client (pas l’entier `idclient` de `signaletique`) |
| `numerodossier` | |
| `codeproduit` / `nomproduit` | |
| `montant` | montant accordé |
| `dateeffet` | `YYYYMMDD` |
| `nbrecheance` | |
| `periode` | ex. `M` |
| `tauxannuel` / `tauxeffectif` | |
| `numerocontrat` | |
| `encours` | |
| `etatpret` | |
| `datederniereeche` / `datepremiereeche` | peuvent être vides |
| `totaldu` / `totalduremb` / `mensualite` / `differe` / `grace` | |

## 8. `wtableauremboursement` — situation des remboursements

Lecture d’échéances déjà remboursées. La phrase du PDF (« changer la situation des remboursements ») ne correspond pas à l’exemple, qui ne fait que renvoyer des lignes : elle n’est pas reprise comme règle.

Même nom de méthode que Juakali, corps différent : ici `msisdn` + `numdossier` + PIN, pas `apikey`.

| Champ entrée | Rôle |
|---|---|
| `msisdn` | |
| `numdossier` | |
| `pinclient` / `pinotp` | |

Réponse : **tableau JSON**. Chaque élément :

| Champ | Rôle |
|---|---|
| `descriptionreponse` / `codereponse` | |
| `numerodossier` | |
| `numerotransaction` | |
| `dateecheance` / `dateremb` | `YYYYMMDD` |
| `capitalremb` / `interetremb` / `epargneremb` / `commissionremb` / `penaliteremb` | |

## Annoncées sans corps dans la 1.0.2

Le sommaire cite trois chapitres en page 14. Le fichier s’arrête avant : aucun JSON, aucun champ.

- Opération
- Vérification d’opérations
- Annulation d’opérations

## Constat prod SMICO (2026-10-02), hors PDF

- Le site `API_FLASH_USSD_V1_WEB` répond sur `10.243.11.6`. Le `TOKEN_API` du fichier INI, envoyé comme `apikey` Juakali, est refusé (`100003`, apikey incorrect).
- La même URL `pmobileapi.awp` accepte la clé Juakali pour une liste de référence (`wlistepays` → `100000`). Ce n’est pas le contrat `token` / `nomagent` de ce document.
- L’INI nomme une méthode par défaut `flashcallback`. Elle n’est pas dans le PDF et n’a pas été appelée.