Migrálás v3-ra

• 1. rész, a koncepció. Ezt olvasd el először. A v3 nem átnevezés, hanem újratervezés: ha a régi végpontokat egy az egyben leképezed, hadakozni fogsz az API-val. Az itt eltöltött tíz perc napokat spórol később.
• 2. rész, az API. Végpontonkénti leképezés, kéréspéldák, állapotgépek és egy migrációs ellenőrzőlista.

​

1. rész, a koncepció

​

1.1 Miért létezik a v3

​

1.2 Az objektummodell

1. A képességek mindent kapuznak. A számlák egy ready képesség alatt kerülnek kiállításra; az árajánlatok egy képesség ellenében árazódnak. A regisztráció az, hogy a szükséges képességeket ready állapotba juttatod.
2. A feladatok bárhová kapcsolódhatnak. Egy képesség, egy számla vagy egy futó átutalás is hordozhat openTaskIds mezőt. Bárhol is látod, a hurok ugyanaz: feladat olvasása, válaszok beküldése, felülvizsgálat kivárása, szülő újraolvasása.

​

1.3 A készenlét képességenkénti, nem ügyfélenkénti

• „Tud tranzakciózni X-en?” azzá válik, hogy X képesség status == "ready".
• „Tenniük kell valamit?” azzá válik, hogy van-e olyan feladat, amelynek státusza action_required (a képesség jellemzően restricted-et mutat, statusReason.resolution: "complete_tasks" értékkel).
• „A Swipeluxra várunk?” azzá válik, hogy feladatok in_review, képesség pending állapotban.

​

1.4 A feladathurok

• Egy feladat requirements[] tömböt hordoz, ezek az egyéni kérések. Mindegyiknek van egy feladatonkénti requirementId azonosítója, egy stabil key mezője, amely megnevezi a kérést (például lakcímigazolás, ez alapján deduplikáld az UI-t), valamint egy típusos request mező, amely pontosan leírja a várt bemenetet (szöveg, dátum, választás, dokumentum, nyilatkozat stb.).
• A beküldés felülvizsgálatköteles: soha nem módosítja közvetlenül a képesség vagy a számla állapotát, csak az elfogadás. Egy kivétel: a profile válaszok beküldéskor átírják az ügyfélprofilt (2.3). Beküldés után pollozd a feladatot vagy a szülő erőforrást.
• A taskRevision (a feladat revision-jének visszaküldése) egyidejűségi őr: ha a feladat megváltozott, mióta beolvastad, olvasd újra és építsd újra a válaszokat.
• Az absence egy elsőrangú válasz („nem rendelkezem ezzel, mert…”), használd ezt ahelyett, hogy a követelményeket megválaszolatlanul hagynád.

​

1.5 Pénzmozgás

​

1.6 Erőforrásonként egy állapotgép

​

1.7 Konvenciók

• Ugyanazon kulcs újrahasználata eltérő testtel 409 idempotency_conflict, ameddig a kulcsot megőrizzük (legalább 7 nap), ezért soha ne tervezz kulcs-újrahasználatot. Generálj friss UUID-t minden logikai művelethez, és tárold a feladattal együtt.
• Az újrajátszás a hibákat is lefedi: ha az eredeti kérés terminális 4xx-szel végződött, ugyanaz a kulcs plusz test újra ugyanazt a problémaválaszt adja vissza.
• Két egyidejű kérés ugyanazzal a kulccsal: az egyik nyer, a másik 409-et kap. Az újrapróbálást a vesztes csak azután végezze el, hogy a nyertes lezárult; az újrajátszás az eredeti választ adja vissza.

​

1.8 Az aranyút

​

2. rész, az API

​

2.1 Ügyfelek

// POST /v3/customers        Idempotency-Key: <fresh uuid>
{
  "type": "individual",
  "externalId": "user-1042",
  "individual": {
    "firstName": "Maria",
    "lastName": "Silva",
    "birthDate": "1990-04-12",
    "nationalities": ["BR"],
    "residenceCountry": "BR",
    "email": "maria@example.com",
    "residentialAddress": {
      "streetLine1": "Av. Paulista 1000",
      "city": "Sao Paulo",
      "postalCode": "01310-100",
      "country": "BR"
    }
  },
  "financialProfile": {
    "accountPurposes": ["cross_border_remittance"],
    "sourcesOfFunds": ["salary"]
  }
}

• A létrehozás progresszív: önmagában a { "type": "individual" } is érvényes létrehozás. A hiányzó tények soha nem érvénytelenítik az ügyfelet, hanem később bevételi feladatokként jelennek meg az azokat igénylő képességeken.
• Az üzleti ügyfelek business mezőt plusz regisztrációs adatokat hordoznak. A v1 részvényes-CRUD-ja kapcsolt felekre képeződik le, kiterjesztve az igazgatókra, tisztségviselőkre és tulajdonosokra: hozz létre őket inline az ügyfél létrehozásakor (mindegyik stabil rp_ azonosítót kap), vagy kezeld őket a dedikált kapcsolt-fél végpontokon keresztül.
• Nincs ügyfél status mező, lásd 1.3.
• A meglévő ügyfelek átvihetők: a v1-en vagy v2-n létrehozott ügyfelek ugyanazzal az azonosítóval címezhetők a v3 végpontokon. A v3 olvasás egy szanitizált nézet, azok az örökölt értékek, amelyek nem felelnek meg a v3 validációnak, hiányzóként jönnek vissza. Az első v3 írás után ez a nézet állandósul: a hiányzó értékek nem térnek vissza maguktól. Ezért gazdagíts korán, tervezz egy egyszeri lépést, amely a saját nyilvántartásaidból PATCH-el a teljes profilt, mielőtt v3 olvasásokra támaszkodnál. A v1 metadata külön névtér, és nem kerül átvitelre, állítsd be újra a v3-on.
• Az externalId elsőrangú és egyedi az ügyfeleid között a v3-on, környezetenként (409 duplicate_external_id). Egy ügyfél archiválása nem szabadítja fel az externalId-t, tisztítsd PATCH-csel a DELETE előtt, ha újra akarod használni.
• A DELETE egy archiválási kaszkád (nincs visszaállítás; az azonosítókat soha nem használjuk újra). Blokkolt 409 customer_has_active_resources plusz blockingResources[] üzenettel, amíg bármely nem archivált számla vagy folyamatban lévő átutalás létezik.
• PATCH merge szabályok: az explicit null töröl egy nullázható mezőt, a tömbök teljesen felülíródnak (kivéve az inline kapcsolt feleket, amelyek azonosító szerint upsert-elődnek), a metadata kulcsok merge-elődnek. A teljes sémák és listaszűrők az OpenAPI specifikációban vannak.

​

2.2 A /rails, /banks és igénylések Képességekké válnak

• Egy képesség egyenlő: method (ach, wire, rtp, pix, sepa, swift, spei, pse, transfers_3_0, faster_payments, sepa_instant, uaefts, card, stablecoin_transfers stb.) plusz accountType (pooled vagy named, null nem-banki módoknál) plusz directions (payin vagy payout). A publikus capabilityId a minősített pár (sepa_pooled, ach_named) vagy a puszta módszer a card és stablecoin_transfers esetén.
• Minden képesség-igénylés egy application-t szül, a próbálkozásonkénti rekordot a .../capabilities/{capabilityId}/applications (plusz /{applicationId}/history) alatt, saját státuszokkal (1.6) és statusReason-nel. Ez egy kérés audit-nyoma; a napi munkához pollozd magát a képességet.
• A capabilities/supported visszaadja az elérhetőséget (available, beta vagy disabled), a jogosultságot és a kínált intézményeket. A bankválasztás a kérési időben történik az opcionális institutions tömbön keresztül, nincs külön /banks erőforrás. A kihagyása (vagy [] küldése) minden alapértelmezett intézményt kiválaszt; az isDefault: true egy ügyfél- és képesség-specifikus jelző, nem globális. Egy nem üres lista felülírja az alapértelmezéseket, és egy bank-alapú képesség, amelyre nem érvényes alapértelmezett, 422 capability_institutions_required hibát ad. Az intézmény-azonosítók átlátszatlanok, toleráld az újakat.
• A stablecoin_transfers automatikusan biztosított az ügyfél létrehozásakor és ready állapotban születik (tehát soha nem kérik, és nem törölhető). A card csak egyéni ügyfeleknél.
• A képességen található openTaskIds a „mi a következő teendőm” mutatód. A nyitott azt jelenti: action_required vagy in_review, és a gyűjtés tartalmazza az aktív függőségeken keresztül elért közös ügyfélszintű feladatokat is.
• A cancel csak pending vagy restricted állapotból működik és blokkoló erőforrások nélkül, egyébként 409 capability_not_cancelable, amelynek problématestje felsorolja a blockingResources-t. A törlés utáni újraigénylés egy friss létrehozás új idempotenciakulccsal.
• Pollozd a GET-et. A képesség állapota olvasáskor frissül; pollozd a GET .../capabilities/{capabilityId}-t, vagy iratkozz fel a capability.status_changed-re, ne cache-elj.
• Egy módszer kérése egyszerre teheti elérhetővé a kapcsolódó módszereket, kezeld a képességeket olyan halmazként, amit újraolvasol, nem pedig egyetlen sorként, amit követsz.
• Használd a tasks-preview-t, hogy megmutasd az onboarding-kéréseket, mielőtt elköteleződsz egy igénylés mellett.
• A verifikáció nem egyszeri: új feladatok jelenhetnek meg egy már ready képességen (periodikus vagy eseményvezérelt újraverifikáció). Tartsd bekötve a feladathurkot az ügyfél teljes életciklusára, ne csak az onboardingra.

​

2.3 A Dokumentumok és KYC Feladatokká és Beadványokká válnak

• Nyers fájltárolás: POST/GET/DELETE /v3/customers/{customerId}/documents (plusz /{documentId}), tölts fel egyszer az API-kulcsoddal, majd hivatkozz a dokumentum-azonosítókra a beküldési válaszokban. Ez felváltja az összes upload-token és direct-upload bevételt.
• Új olvasások: GET /v3/tasks (kereskedő-szintű bejövő láda), GET /v3/transfers/{transferId}/tasks, GET .../tasks/{taskId}/history, GET .../tasks/{taskId}/submissions (plusz /{submissionId}).

// POST /v3/customers/{cus}/tasks/{task}/submissions   Idempotency-Key: <fresh uuid>
{
  "taskRevision": 3,
  "answers": [
    { "requirementId": "req_a1", "answer": { "type": "document", "documentIds": ["doc_passport1"] } },
    { "requirementId": "req_b2", "answer": { "type": "text", "value": "Import/export business" } },
    { "requirementId": "req_c3", "answer": { "type": "absence", "reason": "not_applicable" } }
  ]
}

• Válasz-típusok: profile, text, date, single_select, multi_select, boolean, attestation, document, resource_reference, absence. Minden követelmény request objektuma megmondja, milyen típust vár.
• Egy beküldésnek meg kell válaszolnia az aktuális kör minden cselekvésre váró követelményét, azzal a pontos taskRevision-nel, amit beolvastál. A részleges beküldéseket elutasítjuk.
• A profile válaszok átírnak: frissítik az ügyfélprofilt a normál validációs úton, és azonnal újraértékelnek minden képességet, amely ugyanarra a bevételi munkára hivatkozik. Azok a testvér-bevételi feladatok, amelyek követelményei mind teljesülnek, automatikusan lezárulnak.
• A követelmények alternatív csoportokat alkothatnak (alternativeKey): pontosan egyet küldj be a csoportból.
• A changes_requested növeli a remediationRound-ot és reviewFeedback-et hordoz. Olvasd újra a feladatot, küldj be újra friss idempotenciakulccsal.
• A hosztolt verifikációs URL-ek csak az ügyfél-hatókörű feladatrészletben (GET /v3/customers/{customerId}/tasks/{taskId}) jelennek meg, és csak amíg a munkamenet cselekvésre kész; a listák és a GET /v3/tasks/{taskId} szándékosan URL-mentesek.
• A felhasználási feltételek is feladat: az openTaskIds tartalmazhat egy category: "terms_of_service" feladatot, amelynek hosztolt elfogadási oldala ugyanígy van linkelve (csak ügyfél-hatókörű részlet). Az általános beküldések nem fogadhatnak el feltételeket, és a KYC-jóváhagyás soha nem implikálja a feltételek elfogadását.
• A feladatok képességenkénti hatókörűek, így „ugyanaz” a kérés (például lakcímigazolás) képességenként egyszer jelenhet meg. Deduplikálj az UI-ban a követelmény key mezője alapján.
• Nincs fordítási réteg: a /v1/documents-re való posztolás nem oldja fel a v3 képességeket. Amint egy ügyfél v3-on van, vezess minden kérést feladatokon keresztül.

​

2.4 Számlák és tárcák

// issued bank account (capability must be ready)
{ "origin": "issued", "type": "bank", "method": "sepa",
  "currency": "EUR", "settlement": { "accountId": "acc_wallet1" } }

// external wallet the customer already owns (replaces /import)
{ "origin": "external", "type": "wallet", "currency": "USDC",
  "network": "polygon", "details": { "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F" } }

• A country kiállított bankszámlákon opcionális (metódusonként alapértelmezett); külső bankszámlákon add meg explicit módon. A tárca-számlákon egyáltalán nincs ország.
• A settlement.accountId kötelező kiállított bankszámlákon: azt a kiállított tárca-számlát nevezi meg, amely megkapja a bankszámlára beérkező befizetésekből elszámolt pénzeszközöket.
• A kiállított számlák közzéteszik: details (IBAN vagy routing plusz számla vagy cím), verzionált routing (a befizetési koordináták forogva változhatnak, mindig a legfrissebb olvasást rendereld), fees, balances.
• Hálózatok: polygon, ethereum, base, arbitrum, optimism, bsc, avalanche.
• A képesség-kapu csak a kiállított számlákra vonatkozik: egy nem-ready képesség elleni létrehozás képességkódos hibával elbukik, kérd meg először a képességet (2.2). A külső számláknak nincs szükségük képességre (és ügyfél-jóváhagyásra sem); csak kérés-séma és bankadat-validációt kapnak.
• A kiállított bankszámlák provisioning-ban születnek details: null-lal. Pollozd a számlát vagy figyeld az account.status_changed-et, amíg ready nem lesz.
• A DELETE archivál, soha nem véglegesen töröl. A folyamatban lévő átutalások által hivatkozott számlák 409 account_has_active_transfers-t adnak. Próbáld újra, miután azok az átutalások terminális állapotba kerülnek.
• Új a v3-ban: Szabályok, állandó utasítások egy kiállított tárca-számlán (POST/GET /v3/customers/{customerId}/rules, GET/PATCH/DELETE .../rules/{ruleId}), amelyek automatikusan átseperik a bejövő pénzeszközöket egy másik számlára vagy tárca-rendeltetésre. Nincs v1 vagy v2 megfelelője.

​

2.5 Címzettek és rendeltetési helyek

• Recipient egyenlő azzal, hogy ki: individual (kereszt- és vezetéknév) vagy business (cégnév), kötelező relationship mezővel (employee, contractor, vendor, subsidiary, merchant, customer, landlord, family, other). A címzettek és rendeltetési helyek csak harmadik felekre vonatkoznak. Egy első felet érintő kifizetés egyáltalán nem használ címzettet: cél az ügyfél saját acc_ számláinak egyike, mint az árajánlat destinationId-je (2.6).
• Destination egyenlő azzal, hogy hova: módszerenként típusos, sepa (iban, bic opcionális), ach vagy wire (routing plusz számla), swift (teljes koordináták plusz opcionális közvetítő), spei (clabe), pse, transfers_3_0 (cbu) stb., plusz tárca-rendeltetések. Minden rendeltetésnek saját státusza van. Figyeld a destination.status_changed-et.
• A fiat rendeltetések a címzett teljes address mezőjét (utca, város, irányítószám, ország) igénylik létrehozás előtt. A hiányzó részek 422 recipient_address_required hibával buknak el. A tárca-rendeltetések átugorják a címet, de felső szintű ownership mezőt igényelnek (self_custodied, vagy custodial egy letétkezelő nevével).
• A kedvezményezett-név pontossága számít: a fogadó bankok a számla jogi nevét egyeztetik. Küldd el a pontos jogi keresztnév plusz vezetéknevet vagy cégnevet, ne egy megjelenítési becenevet.
• A módszerenkénti rendeltetésmező-sémák az OpenAPI specifikációban vannak.

​

2.6 Árajánlatok és átutalások

// 1. Quote: amount on exactly one side picks mode (exact_in / exact_out).
// POST /v3/quotes            Idempotency-Key: <fresh uuid>
{
  "customerId": "cus_123",
  "capabilityId": "sepa_named",
  "in":  { "currency": "EUR", "amount": "150.00" },
  "out": { "currency": "USDC" },
  "destinationId": "acc_wallet1",   // fiat-funded: must be a customer-owned acc_ account
  "fees": { "breakdown": { "developer": { "fixed": "1.00", "bips": 50 } } }
}
// -> { mode: "exact_in", direction: "fiat_to_stablecoin", rate, fees[], expiresAt, ... }

// 2. Execute before expiresAt.
// POST /v3/transfers         Idempotency-Key: <fresh uuid>
{ "quoteId": "quo_789", "externalId": "order-991", "memo": "invoice 44" }

• A destinationId egy acc_ (ügyfél tulajdonában lévő számla) vagy dst_ (címzett rendeltetése) azonosítót vesz fel. A fiat-finanszírozású árajánlatoknak (befizetéseknek) egy acc_ számlát kell megcélozniuk, egy dst_ cél mindig kifizetést jelent (egyébként 422 quote_direction_invalid).
• Az árajánlatokon és átutalásokon szereplő externalId egy nem-egyedi korrelációs hivatkozás (visszaküldve az olvasásokon, szűrhető a listákon). A környezetenkénti egyediségi szabály (2.1) csak az ügyfél externalId-jére vonatkozik.
• Egy árajánlatot pontosan egyszer hajts végre, az expiresAt előtt. Egy lejárt árajánlat 409 quote_expired hibával bukik el, egy második végrehajtás 409 quote_already_executed-vel (a probléma hordozza a meglévő transferId-t).
• Az átutalás-visszavonás még nem támogatott: a POST .../cancel minden állapotban 409 transfer_not_cancelable-t ad vissza. A mai canceled átutalások a finanszírozási ablak lejártából származnak egy finanszírozatlan befizetésnél, nem ebből a végpontból.
• A befizetések awaiting_funds állapotban kezdenek: rendereld a GET .../instructions-t a fizetőnek, banki koordinátákat plusz hivatkozási vagy közleménykódot fiat esetén, letéti címet kripto esetén. A hivatkozási kód az, ahogy a befizetést egyeztetjük. Mindig jelenítsd meg.
• state plusz stateDetail a gépileg olvasható alállapotokhoz; az action_required azt jelenti, hogy egy megfelelőségi feladat van csatolva (openTaskIds, GET .../tasks), válaszolj beadványokon keresztül.
• A kiállított számlákon észlelt bejövő befizetések átutalásokként jelennek meg origin: "inbound_deposit" (szemben a "quoted"-val).
• A fizetési hálózati hivatkozások a references alá vannak konszolidálva: transactionHash, traceNumber, imad, uetr, explorerUrl, returnedTransferId.

• Az átutalások nem lépnek át verziók között. A v1-en vagy v2-n létrehozott átutalások nem olvashatók v3-ból. A lista kihagyja őket, és a GET /v3/transfers/{transferId} 404-et ad. Előbb a létrehozást vágd át, tartsd meg a v1 olvasási utat, amíg azok az átutalások terminális állapotba nem jutnak, majd dobd el.
• Nincs token-csere. A stablecoin_move ugyanazt a be- és kimeneti pénznemet igényli: USDC-ről USDT-re 422 recipient_destination_invalid-del bukik, currency_mismatch mezőhibát hordozva. Mindkét oldalon ugyanaz a hálózat, nincs bridge-elés, és a tárca-tárca mozgások jelenleg csak nulla díjas kézbesítést támogatnak: egy olyan árajánlat, amelynek platform- vagy fejlesztői díja nem nulla, 422 amount_not_deliverable-lel bukik.

​

2.7 Webhookok

• A GET /v3/webhooks/portal egy hosztolt kezelőportál URL-t ad vissza a kézbesítési naplókhoz, újrapróbálkozásokhoz és kézi újrajátszáshoz.
• A transfer.created jelenleg az örökölt v1 payload-alakban van kézbesítve (a v3 boríték aktiválódik, amikor a v1 webhookok lejárnak). Kezeld tisztán jelzésként, és GET-eld az átutalást; ne építs a testére.
• Az események jelzések: fogadáskor GET-eld az erőforrást, és az olvasás alapján cselekedj. Soha ne építs állapotot esemény-payloadokra vagy sorrendre. A kézbesítés legalább egyszeri, késleltetett vagy átrendezett lehet. Deduplikálj esemény-azonosító alapján, és pótold a kihagyott eseményeket minden lista inkluzív updatedAfter szűrőjével.
• Iratkozz fel az api.deprecation-re, ez a verziók kivezetésének gépi csatornája.
• Ma nincs task.* esemény: beküldés után pollozd a feladatot vagy a szülőjét.

​

2.8 Sandbox

​

2.9 Örökölt végpontok v3 helyettesítés nélkül

​

2.10 Javasolt migrációs sorrend

​

2.11 Buktatók ellenőrzőlista

• Friss UUID logikai műveletenként, a feladattal együtt megőrizve és újrapróbálkozáskor újrahasználva; soha ne használj újra egy kulcsot megváltozott testtel (409 idempotency_conflict). A sandbox végpontok mentesek a fejléc alól.
• Gazdagítsd a meglévő ügyfeleket (PATCH a teljes profillal, állítsd be újra a metadata-t, az nem kerül át) minden más v3 írás előtt, az első v3 írás állandóvá teszi a szanitizált nézetet.
• Az externalId egyedi környezetenként és az archiválás nem szabadítja fel, tisztítsd PATCH-csel a DELETE előtt, ha újrahasználást tervezel.
• Nincs ügyfél status mező, származtasd a készenlétet képességenként.
• Az action_required és az in_review egyaránt nyitott feladatot jelent.
• A beküldések felülvizsgálatkötelesek (a beküldés nem ugyanaz, mint a feloldás), és meg kell válaszolniuk minden cselekvésre váró követelményt a pontos taskRevision-nel. Nem egyezés esetén olvasd újra és építsd újra.
• Nincs task.* webhook, pollozd a feladatot (vagy szülőjét) minden beküldés után.
• A changes_requested újrapróbálkozás egyenlő: olvasd újra a feladatot, friss válaszok, friss idempotenciakulcs.
• A /v1/documents-re való posztolás soha nem old fel v3 képességet, amint egy ügyfél feladatokon van, minden kérést feladatokon keresztül vezess.
• Új feladatok jelenhetnek meg egy már ready képességen, tartsd bekötve a feladathurkot az onboarding után is, ne csak közben.
• A képesség cancel csak pending vagy restricted állapotból működik blokkoló erőforrások nélkül (409 capability_not_cancelable); a törlés utáni újraigénylés friss létrehozás friss idempotenciakulccsal.
• A képességnek ready-nek kell lennie, mielőtt alatta számlákat állítasz ki vagy ellene árajánlatot kérsz.
• Az árajánlatnak pontosan egyik oldalon van összege; nincs irány mező; végrehajtsd pontosan egyszer az expiresAt előtt (409 quote_expired vagy 409 quote_already_executed).
• A stablecoin-mozgások csak azonos pénznemű, azonos hálózatúak (USDC-ről USDT-re 422-vel bukik); a tárca-tárca csak nulla díjas kézbesítést támogat.
• A DELETE archivál, soha nem véglegesen töröl. A számla-törlést blokkolják a folyamatban lévő átutalások (409 account_has_active_transfers); az ügyfél-törlést emellett bármely nem archivált számla is (409 customer_has_active_resources, blockingResources[] nevezi meg őket).
• A v1 vagy v2 átutalások láthatatlanok a v3 olvasások számára (a lista kihagyja, a GET 404), dual-read-elj a leürítésig, majd dobd el a régi utakat.
• A befizetési routing és utasítások forogva változhatnak, mindig a legfrissebb GET-et rendereld, és mindig mutasd meg a hivatkozási kódot.
• A webhookok jelzések; a GET az igazság, deduplikálj esemény-azonosító alapján, pótold a kihagyott eseményeket updatedAfter-rel.

​

Következő lépés