AYISCORE — API Patnè

Dokimantasyon ofisyèl API a pou enstitisyon patnè yo · Vèsyon v1

Pwodiksyon https://api.ayiscore.com/v1

Sandbox (tès) https://api.ayiscore.com/sbx/v1

Fòma JSON — Content-Type: application/json

1. Rezime rapid

Ayiscore se biwo nòt kredi pou Ayiti. API patnè a pèmèt yon enstitisyon ki apwouve :

Konsilte nòt kredi yon moun — sèlman si moun lan bay konsantman aktif pou patnè sa a ak pou rezon sa a.
Kreye yon konsantman asiste an branch, lè kliyan an la an pèsòn.
Rapòte angajman (prè), peman, ak defo bay biwo a, pou nòt yo rete ajou pou tout rezo a.

Chak demann mande yon kle API nan antèt X-Ayiscore-Kle.
San konsantman aktif, okenn konsiltasyon pa posib — blokaj la teknik.
Chak konsiltasyon anrejistre (pretè, dat, rezon, konsantman), epi kliyan an wè l nan app li nan seksyon « Konsiltasyon yo ».
Limit vitès : 60 demann/min pa kle.
Sandbox la sèvi ak done fiktif sèlman, ak zewo efè sou done reyèl yo.

2. Otantifikasyon

Tout endpoint (sòf GET /sante) mande antèt sa a :

X-Ayiscore-Kle: <kle_api>

Kle a emèt lè biwo Ayiscore apwouve enstitisyon an kòm patnè.
Kle yo estoke anach (hash) bò sèvè — Ayiscore pa kenbe kle a an klè.
Yon kle ka revoke nenpòt lè (abi, fen kontra patnè, oswa demann enstitisyon an).
Si kle a manke, li envalid, oswa li revoke : 401 KLE_ENVALID.

curl -H "X-Ayiscore-Kle: <kle_api>" https://api.ayiscore.com/v1/sante

Pa janm mete kle pwodiksyon an nan kòd piblik, nan yon app mobil, ni nan yon dokiman pataje. Kle a rete sekrè enstitisyon an.

3. Tablo endpoint yo

Metòd	Endpoint	Deskripsyon
POST	`/konsiltasyon`	Konsilte nòt kredi yon moun (konsantman obligatwa)
POST	`/konsantman-branch`	Konsantman asiste an branch / kay patnè a (kòd konfimasyon)
POST	`/rapo/angajman`	Rapòte yon nouvo angajman (prè / kredi)
POST	`/rapo/peman`	Rapòte yon peman sou yon angajman
POST	`/rapo/defo`	Rapòte yon defo — `prev_ref` obligatwa
GET	`/sante`	Tchèk sèvis la (health check)

Tout chemen yo egziste idantik anba baz pwodiksyon an (/v1) ak anba baz sandbox la (/sbx/v1).

Objè `moun` (itilize nan plizyè endpoint)

{
  "kod_kliyan": "…",
  "telefon": "…",
  "pyes_nimewo": "…"
}

Chan	Deskripsyon
`kod_kliyan`	Kòd kliyan moun lan (jan patnè a oswa biwo a idantifye l)
`telefon`	Nimewo telefòn moun lan
`pyes_nimewo`	Nimewo pyès idantite moun lan

4. Konsantman — règ san konpwomi

San konsantman, san konsiltasyon. Blokaj la teknik.

Pou yon POST /konsiltasyon pase, fòk gen yon konsantman aktif ki koresponn egzakteman ak 3 bagay an menm tan : kliyan an, patnè a (idantifye pa kle API li a), epi rezon an (rezon_kod). Si youn pa koresponn, oswa konsantman an ekspire / revoke, sèvè a reponn 403 KONSANTMAN_MANKE. Pa gen eksepsyon manyèl, pa gen kontounman.

Menm repons 403 KONSANTMAN_MANKE a soti si dosye moun lan frize (pa egzanp pandan yon kontestasyon oswa yon verifikasyon idantite).
Konsantman an ka kreye pa kliyan an li menm nan app Ayiscore li a, oswa an branch / kay patnè a ak flo asiste POST /konsantman-branch la.
Chak konsiltasyon ki reyisi anrejistre nèt : pretè a, dat la, rezon an, ak konsantman ki te sèvi a. Kliyan an wè tras sa a nan app li, seksyon « Konsiltasyon yo ». Yon patnè pa ka konsilte « an silans ».

Valè `rezon_kod` yo

`rezon_kod`	Sans
`nouvo_demann_kredi`	Moun lan fè yon nouvo demann kredi / prè
`revizyon_kont`	Revizyon peryodik yon kont ki egziste deja
`vant_a_kredi`	Vant a kredi (machandiz / sèvis yo peye an plizyè fwa)

5. Endpoint yo an detay

5.1 POST `/konsiltasyon` — Konsiltasyon nòt kredi

Kò demann lan :

{
  "moun": {
    "kod_kliyan": "…",
    "telefon": "…",
    "pyes_nimewo": "…"
  },
  "rezon_kod": "nouvo_demann_kredi",
  "konsantman_id": "…"
}

rezon_kod dwe youn nan : nouvo_demann_kredi · revizyon_kont · vant_a_kredi.

Egzanp curl :

curl -X POST https://api.ayiscore.com/v1/konsiltasyon \
  -H "Content-Type: application/json" \
  -H "X-Ayiscore-Kle: <kle_api>" \
  -d '{
    "moun": {
      "kod_kliyan": "KLI-000123",
      "telefon": "+50937000000",
      "pyes_nimewo": "…"
    },
    "rezon_kod": "nouvo_demann_kredi",
    "konsantman_id": "KONS-2026-000001"
  }'

Repons 200 :

{
  "not_vale": 682,
  "bann": "Bon",
  "nivo_idantite": "verifye",
  "angajman_ouvè": 2,
  "pi_gwo_reta_jou_90j": 12,
  "dat_kalkil": "2026-11-04T14:32:00-05:00"
}

Chan repons lan	Deskripsyon
`not_vale`	Nòt kredi a, sou echèl 300–850
`bann`	Bann kalitatif ki koresponn ak nòt la
`nivo_idantite`	Nivo verifikasyon idantite moun lan
`angajman_ouvè`	Kantite angajman (prè / kredi) ki ouvè kounye a
`pi_gwo_reta_jou_90j`	Pi gwo reta peman (an jou) sou 90 dènye jou yo
`dat_kalkil`	Dat ak lè nòt la te kalkile

Erè espesifik : 403 KONSANTMAN_MANKE (gade seksyon 4) · 404 MOUN_PA_JWENN si moun lan pa idantifye nan biwo a.

5.2 POST `/konsantman-branch` — Konsantman asiste an branch

Endpoint sa a sèvi lè kliyan an prezan an branch oswa kay patnè a. Flo a :

Patnè a voye demann lan ak moun lan, rezon an, epi metòd la.
Kliyan an resevwa yon kòd konfimasyon (pa SMS ak metòd kod_sms).
Konsantman an kreye sèlman lè kòd la antre kòrèkteman. Anvan sa, pa gen konsantman, epi pa gen konsiltasyon posib sou baz demann sa a.

Kò demann lan :

{
  "moun": {
    "kod_kliyan": "…",
    "telefon": "…",
    "pyes_nimewo": "…"
  },
  "rezon_kod": "nouvo_demann_kredi",
  "metod": "kod_sms"
}

Egzanp curl :

curl -X POST https://api.ayiscore.com/v1/konsantman-branch \
  -H "Content-Type: application/json" \
  -H "X-Ayiscore-Kle: <kle_api>" \
  -d '{
    "moun": {
      "kod_kliyan": "KLI-000123",
      "telefon": "+50937000000",
      "pyes_nimewo": "…"
    },
    "rezon_kod": "nouvo_demann_kredi",
    "metod": "kod_sms"
  }'

5.3 POST `/rapo/angajman` — Rapòte yon angajman (prè)

Lè patnè a louvri yon prè / kredi pou yon kliyan, li rapòte l bay biwo a. Se rapò sa yo ki nouri istwa kredi kliyan an — pou tout rezo a, pa pou yon sèl patnè.

Kò demann lan :

{
  "moun": {
    "kod_kliyan": "…",
    "telefon": "…",
    "pyes_nimewo": "…"
  },
  "angajman_ref": "…",
  "montan": 50000,
  "deviz": "HTG",
  "dat_louvri": "2026-11-04",
  "vesman": [
    { "dat_echeyans": "2026-12-04", "montan": 8750 },
    { "dat_echeyans": "2027-01-04", "montan": 8750 }
  ]
}

Chan	Deskripsyon
`angajman_ref`	Referans angajman an kay patnè a — kle lyen an pou tout rapò `peman` ak `defo` ki vin apre
`montan`	Montan total angajman an
`deviz`	`HTG` oswa `USD`
`dat_louvri`	Dat angajman an louvri
`vesman`	Lis echeyans yo : chak ak `dat_echeyans` ak `montan` li

Egzanp curl :

curl -X POST https://api.ayiscore.com/v1/rapo/angajman \
  -H "Content-Type: application/json" \
  -H "X-Ayiscore-Kle: <kle_api>" \
  -d '{
    "moun": {
      "kod_kliyan": "KLI-000123",
      "telefon": "+50937000000",
      "pyes_nimewo": "…"
    },
    "angajman_ref": "PRE-2026-0451",
    "montan": 50000,
    "deviz": "HTG",
    "dat_louvri": "2026-11-04",
    "vesman": [
      { "dat_echeyans": "2026-12-04", "montan": 8750 },
      { "dat_echeyans": "2027-01-04", "montan": 8750 }
    ]
  }'

Erè espesifik : 422 DONE_ENKONPLE si yon chan obligatwa manke (pa egzanp lis vesman an vid).

5.4 POST `/rapo/peman` — Rapòte yon peman

Kò demann lan :

{
  "angajman_ref": "…",
  "dat_echeyans": "2026-12-04",
  "montan": 8750,
  "dat_peman": "2026-12-03"
}

Chan	Deskripsyon
`angajman_ref`	Referans angajman an (menm ak sa rapò angajman an te bay la)
`dat_echeyans`	Echeyans peman sa a koresponn avè l
`montan`	Montan ki peye a
`dat_peman`	Dat peman an fèt tout bon an

Egzanp curl :

curl -X POST https://api.ayiscore.com/v1/rapo/peman \
  -H "Content-Type: application/json" \
  -H "X-Ayiscore-Kle: <kle_api>" \
  -d '{
    "angajman_ref": "PRE-2026-0451",
    "dat_echeyans": "2026-12-04",
    "montan": 8750,
    "dat_peman": "2026-12-03"
  }'

Peman ki rapòte a tan, se siyal ki pi fò nan nòt la. Rapòte peman yo regilyèman — se konsa istwa pozitif kliyan ou yo bati.

5.5 POST `/rapo/defo` — Rapòte yon defo (negatif)

Yon defo se yon enfòmasyon negatif ki lou pou kliyan an. Se poutèt sa li gen 2 pwoteksyon obligatwa : prèv dokimante ak dwa repons kliyan an.

Kò demann lan :

{
  "angajman_ref": "…",
  "montan_dwe": 17500,
  "dat_defo": "2027-02-10",
  "prev_ref": "KONTRA-PRE-2026-0451-SIGNE.pdf"
}

Chan	Deskripsyon
`angajman_ref`	Referans angajman an
`montan_dwe`	Montan ki rete dwe a
`dat_defo`	Dat defo a konstate
`prev_ref`	OBLIGATWA — referans dokiman prèv la (kontra, resi, desizyon). San `prev_ref` : 422 PREV_MANKE, rapò a refize nèt.

Egzanp curl :

curl -X POST https://api.ayiscore.com/v1/rapo/defo \
  -H "Content-Type: application/json" \
  -H "X-Ayiscore-Kle: <kle_api>" \
  -d '{
    "angajman_ref": "PRE-2026-0451",
    "montan_dwe": 17500,
    "dat_defo": "2027-02-10",
    "prev_ref": "KONTRA-PRE-2026-0451-SIGNE.pdf"
  }'

Dwa repons kliyan an : defo a parèt nan app kliyan an — kliyan an wè l, li pa kache pou li. Kliyan an ka konteste l depi app li a. Depi gen kontestasyon, defo a make « an kontestasyon » jiskaske li rezoud. Yon defo san prèv pa janm antre nan sistèm lan : se prev_ref ki pòt la.

5.6 GET `/sante` — Tchèk sèvis la

Sèvi pou verifye sèvis la vivan (health check), pa egzanp nan siveyans (monitoring) patnè a.

Egzanp curl :

curl https://api.ayiscore.com/v1/sante \
  -H "X-Ayiscore-Kle: <kle_api>"

Repons 200 (egzanp) :

{
  "estati": "ok",
  "vesyon": "v1"
}

6. Erè estanda

Tout erè yo retounen an JSON ak yon kòd HTTP ak yon kòd erè stab patnè a ka pwograme sou li :

{
  "ere_kod": "KONSANTMAN_MANKE",
  "mesaj": "Pa gen konsantman aktif ki koresponn ak kliyan sa a, patnè sa a ak rezon sa a."
}

HTTP	Kòd erè	Sans	Ki lè
401	KLE_ENVALID	Kle API a envalid, manke, oswa revoke	Antèt `X-Ayiscore-Kle` pa bon
403	KONSANTMAN_MANKE	Pa gen konsantman aktif ki koresponn, oswa dosye a frize	`POST /konsiltasyon` san konsantman ki matche (kliyan + patnè + rezon)
404	MOUN_PA_JWENN	Moun lan pa jwenn / pa idantifye nan biwo a	Idantifyan `moun` yo pa koresponn ak okenn dosye
422	PREV_MANKE	Referans prèv la manke	`POST /rapo/defo` san `prev_ref`
422	DONE_ENKONPLE	Done obligatwa manke oswa enkonplè	Nenpòt POST ak chan obligatwa ki manke
429	LIMIT_VITES	Limit vitès depase	Plis pase 60 demann/min pa kle

Lè w resevwa 429 LIMIT_VITES, tann epi reeseye — pa miltipliye demann yo an paralèl, sa p ap chanje limit la.

7. Sandbox — kijan w teste

Sandbox la se anviwònman tès la. Li egziste pou ekip teknik patnè a entegre epi verifye API a anvan yo ale an pwodiksyon.

Bagay	Sandbox	Pwodiksyon
Baz	`https://api.ayiscore.com/sbx/v1`	`https://api.ayiscore.com/v1`
Chemen yo	Idantik — menm endpoint, menm fòma	Idantik
Done	Fiktif sèlman	Reyèl
Kle tès (egzanp dokiman sa a)	`ayiscore_sbx_demonstrasyon`	Kle prive enstitisyon an (emèt lè l apwouve)
Efè sou done reyèl	Zewo — okenn	Wi, tout aksyon yo reyèl epi anrejistre

Etap tès yo

Pran baz sandbox la : https://api.ayiscore.com/sbx/v1.
Sèvi ak kle tès la nan antèt la : X-Ayiscore-Kle: ayiscore_sbx_demonstrasyon. Kle sa a se kle egzanp dokiman sa a pou sandbox la sèlman — li pa fonksyone an pwodiksyon.
Teste chak flo sou menm chemen yo : GET /sante → POST /konsantman-branch → POST /konsiltasyon → POST /rapo/angajman → POST /rapo/peman → POST /rapo/defo.
Verifye ka erè yo nan sandbox la tou : konsiltasyon san konsantman (403 KONSANTMAN_MANKE), defo san prev_ref (422 PREV_MANKE), move kle (401 KLE_ENVALID).

Egzanp curl — sandbox :

# 1. Sante (sandbox)
curl https://api.ayiscore.com/sbx/v1/sante \
  -H "X-Ayiscore-Kle: ayiscore_sbx_demonstrasyon"

# 2. Konsiltasyon (sandbox, done fiktif)
curl -X POST https://api.ayiscore.com/sbx/v1/konsiltasyon \
  -H "Content-Type: application/json" \
  -H "X-Ayiscore-Kle: ayiscore_sbx_demonstrasyon" \
  -d '{
    "moun": {
      "kod_kliyan": "TES-0001",
      "telefon": "+50937000000",
      "pyes_nimewo": "TES-FIKTIF-001"
    },
    "rezon_kod": "nouvo_demann_kredi",
    "konsantman_id": "KONS-SBX-0001"
  }'

Règ sandbox yo

Done ou kreye nan sandbox la rete nan sandbox la — yo pa janm melanje ak done reyèl yo.
Pa janm voye done reyèl yon kliyan nan sandbox la : sèvi ak done fiktif sèlman.
Pa janm sèvi ak kle pwodiksyon an nan sandbox la, ni kle sandbox la an pwodiksyon.
Lè entegrasyon an fin pase nan sandbox la, pase an pwodiksyon se chanje sèlman baz la (/sbx/v1 → /v1) ak kle a.

8. Trasabilite

Chak konsiltasyon anrejistre : pretè a, dat la, rezon an, konsantman an.
Kliyan an wè tout konsiltasyon yo nan app li : « Konsiltasyon yo ».
Rapò yo (angajman, peman, defo) mare ak angajman_ref patnè a, pou tout tras ka swiv depi rapò a rive nan nòt la.

1. Rezime rapid

2. Otantifikasyon

3. Tablo endpoint yo

Objè moun (itilize nan plizyè endpoint)

4. Konsantman — règ san konpwomi

Valè rezon_kod yo

5. Endpoint yo an detay

5.1 POST /konsiltasyon — Konsiltasyon nòt kredi

5.2 POST /konsantman-branch — Konsantman asiste an branch

5.3 POST /rapo/angajman — Rapòte yon angajman (prè)

5.4 POST /rapo/peman — Rapòte yon peman

5.5 POST /rapo/defo — Rapòte yon defo (negatif)

5.6 GET /sante — Tchèk sèvis la

6. Erè estanda

7. Sandbox — kijan w teste

Etap tès yo

Règ sandbox yo

8. Trasabilite

Objè `moun` (itilize nan plizyè endpoint)

Valè `rezon_kod` yo

5.1 POST `/konsiltasyon` — Konsiltasyon nòt kredi

5.2 POST `/konsantman-branch` — Konsantman asiste an branch

5.3 POST `/rapo/angajman` — Rapòte yon angajman (prè)

5.4 POST `/rapo/peman` — Rapòte yon peman

5.5 POST `/rapo/defo` — Rapòte yon defo (negatif)

5.6 GET `/sante` — Tchèk sèvis la