Migrācija uz v3

• 1. daļa, koncepcija. Izlasi to vispirms. v3 ir pārveidojums, nevis pārdēvēšana: ja tu vienu pret vienu attēlosi vecos galapunktus, tu cīnīsies ar API. Desmit minūtes šeit ietaupīs dienas vēlāk.
• 2. daļa, API. Galapunktu attēlojumi, pieprasījumu piemēri, stāvokļu mašīnas un migrācijas kontrolsaraksts.

​

1. daļa, koncepcija

​

1.1 Kāpēc pastāv v3

​

1.2 Objektu modelis

1. Spējas visu vārti. Konti tiek nodrošināti zem ready spējas; cenu piedāvājumi tiek cenoti pret spēju. Iekļaušana nozīmē vajadzīgo spēju novešanu līdz ready.
2. Uzdevumi piesaistās jebkur. Spēja, konts vai izpildē esošs pārskaitījums var nest openTaskIds. Kur vien tos redzi, cilpa ir viena un tā pati: lasi uzdevumu, iesniedz atbildes, gaidi pārskatīšanu, atkārtoti lasi vecāku.

​

1.3 Gatavība ir katrai spējai, ne katram klientam

• „Vai viņi var veikt darījumus X?” kļūst par spēju X status == "ready".
• „Vai viņiem kaut kas jādara?” kļūst par jebkuru uzdevumu ar statusu action_required (spēja parasti rāda restricted ar statusReason.resolution: "complete_tasks").
• „Vai gaidām uz Swipelux?” kļūst par uzdevumiem in_review, spēju pending.

​

1.4 Uzdevumu cilpa

• Uzdevums nes requirements[], atsevišķus lūgumus. Katram ir katrā uzdevumā requirementId, stabils key, kas nosauc lūgumu (piemēram, adreses pierādījums, izmanto to UI dedublēšanai) un tipizēts request, kas precīzi apraksta vēlamo ievadi (teksts, datums, izvēle, dokuments, apliecinājums un tā tālāk).
• Iesniegšana ir pārskatīšanas vārtoti: tā nekad tieši nemaina spējas vai konta stāvokli, tikai pieņemšana to dara. Viens izņēmums: profile atbildes iesniegšanas brīdī tiek rakstītas klienta profilā (2.3). Pēc iesniegšanas apjautā uzdevumu vai vecāka resursu.
• taskRevision (uzdevuma revision atbalss) ir konkurentuma sargs: ja uzdevums ir mainījies kopš tā, kad tu to nolasīji, nolasi vēlreiz un pārbūvē atbildes.
• absence ir pirmās klases atbilde („man tā nav, jo…”), izmanto to tā vietā, lai prasības paliktu nepabeigtas.

​

1.5 Naudas kustība

​

1.6 Viena stāvokļu mašīna vienam resursam

​

1.7 Konvencijas

• Atslēgas atkārtota izmantošana ar atšķirīgu saturu ir 409 idempotency_conflict tik ilgi, kamēr atslēga tiek saglabāta (vismaz 7 dienas), tāpēc nekad neplāno atslēgu atkārtoti izmantot. Ģenerē svaigu UUID katrai loģiskai operācijai un saglabā to kopā ar savu darbu.
• Atkārtojums aptver arī kļūdas: ja sākotnējais pieprasījums beidzās ar termināli 4xx, tā pati atslēga plus saturs atgriež to pašu problēmas atbildi vēlreiz.
• Divi vienlaicīgi pieprasījumi ar to pašu atslēgu: viens uzvar, otrs saņem 409. Atkārto zaudētāju pēc tam, kad uzvarētājs ir noslēdzies; atkārtojums atgriež sākotnējo atbildi.

​

1.8 Zelta ceļš

​

2. daļa, API

​

2.1 Klienti

// 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"]
  }
}

• Izveide ir pakāpeniska: { "type": "individual" } viens pats ir derīga izveide. Trūkstoši fakti nekad neatceļ klientu, tie vēlāk parādās kā uzņemšanas uzdevumi uz tām spējām, kurām tie nepieciešami.
• Uzņēmumiem ir business plus reģistrācijas dati. v1 shareholder CRUD attēlojas uz related parties, paplašinātām, lai aptvertu direktorus, amatpersonas un īpašniekus: izveido tos iekļauti klienta izveidē (katrs saņem stabilu rp_ id) vai pārvaldi tos caur dedicētajiem related-parties galapunktiem.
• Nav klienta status lauka, skati 1.3.
• Esošie klienti tiek pārnesti: v1 vai v2 izveidoti klienti ir adresējami ar to pašu id uz v3 galapunktiem. v3 lasījums ir attīrīts skats, mantotās vērtības, kas neiztur v3 validāciju, atgriežas prombūtnē. Pēc tavas pirmās v3 rakstīšanas šis skats kļūst pastāvīgs: prombūtnes vērtības pašas neatgriežas. Tāpēc bagātini agri, ieplāno vienreizēju piegājienu, kas PATCHo pilnu profilu no taviem paša ierakstiem, pirms paļaujies uz v3 lasījumiem. v1 metadata ir atsevišķa vārdu telpa un netiek pārnesta, iestati to no jauna uz v3.
• externalId ir pirmās klases un unikāls starp taviem klientiem uz v3, katrā vidē (409 duplicate_external_id). Klienta arhivēšana neatbrīvo tā externalId, notīri to ar PATCH pirms DELETE, ja plāno to atkārtoti izmantot.
• DELETE ir arhivēšanas kaskāde (nav atjaunošanas; id nekad netiek atkārtoti izmantoti). Tas tiek bloķēts ar 409 customer_has_active_resources plus blockingResources[], kamēr eksistē kāds nearchivēts konts vai izpildē esošs pārskaitījums.
• PATCH sapludināšanas noteikumi: skaidrs null notīra nullable lauku, masīvi tiek aizstāti pilnībā (izņemot iekļautas related parties, kas tiek upsertētas pēc id), metadata atslēgas tiek sapludinātas. Pilnas shēmas un saraksta filtri ir OpenAPI specifikācijā.

​

2.2 /rails, /banks, pieteikumi kļūst par Capabilities

• Spēja ir method (ach, wire, rtp, pix, sepa, swift, spei, pse, transfers_3_0, faster_payments, sepa_instant, uaefts, card, stablecoin_transfers un tā tālāk) plus accountType (pooled vai named, null ne-banku metodēm) plus directions (payin vai payout). Publiskais capabilityId ir kvalificēts pāris (sepa_pooled, ach_named) vai kailā metode card un stablecoin_transfers gadījumā.
• Katrs spējas pieprasījums rada application, ierakstu par katru mēģinājumu zem .../capabilities/{capabilityId}/applications (plus /{applicationId}/history), ar saviem statusiem (1.6) un statusReason. Tas ir pieprasījuma audita pēdas; ikdienā apjautā pašu spēju.
• capabilities/supported atgriež pieejamību (available, beta vai disabled), tiesības un piedāvātās iestādes. Bankas izvēle notiek pieprasījuma brīdī caur opcionālo institutions masīvu, nav atsevišķa /banks resursa. Tā izlaišana (vai [] sūtīšana) izvēlas katru noklusējuma iestādi; isDefault: true ir klienta-un-spējas specifisks karogs, ne globāls. Tukšs saraksts pārraksta noklusējumus, un banku spēja bez piemērota noklusējuma atgriež 422 capability_institutions_required. Iestāžu id ir necaurspīdīgi, pieņem jaunus.
• stablecoin_transfers tiek automātiski piešķirts klienta izveidē un dzimst ready (tātad tas nekad netiek pieprasīts un nav atceļams). card ir tikai individuālajiem.
• openTaskIds uz spējas ir tavs „ko darīt tālāk” rādītājs. Atvērts nozīmē action_required vai in_review, un apkopojums iekļauj koplietotus klientu līmeņa uzdevumus, kas sasniegti caur aktīvām atkarībām.
• cancel darbojas tikai no pending vai restricted un bez bloķējošiem resursiem, citādi 409 capability_not_cancelable, kura problēmas saturs uzskaita blockingResources. Atkārtota pieprasīšana pēc atcelšanas ir svaiga izveide ar jaunu idempotences atslēgu.
• Apjautā GET. Spējas stāvoklis atjaunojas, kad tu to lasi; apjautā GET .../capabilities/{capabilityId} vai abonē capability.status_changed, neveido kešu.
• Vienas metodes pieprasīšana var uzreiz padarīt pieejamas saistītas metodes, izturies pret spējām kā pret kopu, ko atkārtoti lasi, ne kā pret vienu rindu, ko izseko.
• Izmanto tasks-preview, lai parādītu uzņemšanas lūgumus pirms apņemšanās pie pieprasījuma.
• Verifikācija nav vienreizēja: jauni uzdevumi var parādīties uz jau ready spējas (periodiska vai notikumu vadīta atkārtota verifikācija). Turi uzdevumu cilpu ievadītu visu klienta dzīves ciklu, ne tikai uzņemšanai.

​

2.3 Dokumenti un KYC kļūst par Tasks un Submissions

• Neapstrādāta failu glabāšana: POST/GET/DELETE /v3/customers/{customerId}/documents (plus /{documentId}), augšupielādē vienreiz ar savu API atslēgu, tad atsaucies uz dokumenta id iesniegumu atbildēs. Tas aizstāj katru upload-token un direct-upload uzņemšanu.
• Jauni lasījumi: GET /v3/tasks (tirgotāja mēroga iesūtne), GET /v3/transfers/{transferId}/tasks, GET .../tasks/{taskId}/history, GET .../tasks/{taskId}/submissions (plus /{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" } }
  ]
}

• Atbildes tipi: profile, text, date, single_select, multi_select, boolean, attestation, document, resource_reference, absence. Katras prasības request objekts pasaka, kādu tipu tas sagaida.
• Iesniegumam jāatbild uz katru rīcības prasīgu prasību pašreizējā kārtā, ar tieši to taskRevision, ko tu nolasīji. Daļēji iesniegumi tiek noraidīti.
• profile atbildes raksta cauri: tās atjaunina klienta profilu pa normālu validācijas ceļu un uzreiz pārvērtē katru spēju, kas atsaucas uz to pašu uzņemšanas darbu. Brāļu uzņemšanas uzdevumi, kuru prasības visas ir izpildītas, automātiski aizveras.
• Prasības var veidot alternatīvas grupas (alternativeKey): iesniedz tieši vienu no grupas.
• changes_requested palielina remediationRound un nes reviewFeedback. Nolasi uzdevumu vēlreiz, iesniedz vēlreiz ar svaigu idempotences atslēgu.
• Mitinātās verifikācijas URL parādās tikai klientam apjomotā uzdevuma detalizācijā (GET /v3/customers/{customerId}/tasks/{taskId}) un tikai kamēr sesija ir rīcības prasīga; saraksti un GET /v3/tasks/{taskId} ir apzināti bez URL.
• Lietošanas noteikumi arī ir uzdevums: openTaskIds var iekļaut category: "terms_of_service" uzdevumu, kura mitinātā pieņemšanas lapa ir saistīta tāpat (tikai klientam apjomota detalizācija). Vispārīgi iesniegumi nevar pieņemt noteikumus, un KYC apstiprinājums nekad nenozīmē noteikumu pieņemšanu.
• Uzdevumi ir apjomoti pa spējām, tāpēc „tas pats” lūgums (piemēram, adreses pierādījums) var parādīties vienreiz katrai spējai. Dedublē UI pēc prasības key.
• Nav tulkošanas slāņa: postēšana uz /v1/documents neatbloķēs v3 spējas. Kad klients ir uz v3, virzi visus lūgumus caur uzdevumiem.

​

2.4 Konti un maki

// 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" } }

• country uz izsniegtiem bankas kontiem ir opcionāls (noklusēts pēc metodes); uz ārējiem bankas kontiem norādi to skaidri. Maku kontiem nav valsts vispār.
• settlement.accountId ir obligāts uz izsniegtiem bankas kontiem: tas nosauc izsniegto maka kontu, kas saņem norēķinātos līdzekļus no iemaksām bankas kontā.
• Izsniegtie konti izliek details (IBAN vai routing plus konts vai adrese), versionētu routing (iemaksas koordinātas var mainīties, vienmēr renderē jaunāko lasījumu), fees, balances.
• Tīkli: polygon, ethereum, base, arbitrum, optimism, bsc, avalanche.
• Spējas vārti attiecas tikai uz issued kontiem: viena izveidošana pret ne-ready spēju neizdodas ar spējas kodētu kļūdu, pieprasi spēju vispirms (2.2). Ārējiem kontiem nav vajadzīga spēja (un nav vajadzīgs klienta apstiprinājums); tie saņem tikai pieprasījuma-shēmas un bankas-detaļu validāciju.
• Izsniegtie bankas konti piedzimst provisioning ar details: null. Apjautā kontu vai vēro account.status_changed, līdz ready.
• DELETE arhivē, nekad neveic pilnīgu dzēšanu. Konti, uz kuriem atsaucas izpildē esoši pārskaitījumi, atgriež 409 account_has_active_transfers. Atkārto pēc tam, kad šie pārskaitījumi sasniedz termināli stāvokli.
• Jauns v3: Rules, pastāvīgas instrukcijas uz izsniegta maka konta (POST/GET /v3/customers/{customerId}/rules, GET/PATCH/DELETE .../rules/{ruleId}), kas automātiski aizskalo ienākošos līdzekļus uz citu kontu vai maka galamērķi. Nav v1 vai v2 ekvivalenta.

​

2.5 Saņēmēji un galamērķi

• Recipient ir kas: individual (vārds un uzvārds) vai business (uzņēmuma nosaukums), ar obligātu relationship (employee, contractor, vendor, subsidiary, merchant, customer, landlord, family, other). Saņēmēji un galamērķi ir tikai trešajām pusēm. Pirmās puses izmaksa nemaz neizmanto saņēmēju: mērķē uz vienu no klienta paša acc_ kontiem kā piedāvājuma destinationId (2.6).
• Destination ir kur: tipizēts pa metodei, sepa (iban, bic opcionāls), ach vai wire (routing plus konts), swift (pilnas koordinātas plus opcionāls starpnieks), spei (clabe), pse, transfers_3_0 (cbu) un tā tālāk, plus maku galamērķi. Katram galamērķim ir savs statuss. Vēro destination.status_changed.
• Fiat galamērķiem nepieciešama saņēmēja pilnīga address (iela, pilsēta, pasta indekss, valsts) pirms izveides. Trūkstošas daļas neizdodas ar 422 recipient_address_required. Maku galamērķi izlaiž adresi, bet prasa augšējā līmeņa ownership (self_custodied vai custodial ar glabātāja nosaukumu).
• Labuma saņēmēja vārda precizitāte ir svarīga: saņemošās bankas saskaņo konta juridisko vārdu. Sūti precīzu juridisko vārdu plus uzvārdu vai uzņēmuma nosaukumu, ne attēlojamo iesauku.
• Metodei specifisku galamērķa lauku shēmas ir OpenAPI specifikācijā.

​

2.6 Cenu piedāvājumi un pārskaitījumi

// 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" }

• destinationId ņem acc_ (klienta piederošs konts) vai dst_ (saņēmēja galamērķis) id. Fiat-finansētiem piedāvājumiem (iemaksām) jāmērķē uz acc_ kontu, dst_ mērķis vienmēr nozīmē izmaksu (422 quote_direction_invalid citādi).
• externalId uz piedāvājumiem un pārskaitījumiem ir nu unikāla korelācijas atsauce (atbalsota lasījumos, filtrējama sarakstos). Katra vides unikalitātes noteikums (2.1) attiecas tikai uz klienta externalId.
• Izpildi piedāvājumu tieši vienreiz, pirms expiresAt. Beidzies piedāvājums neizdodas ar 409 quote_expired, otrā izpilde ar 409 quote_already_executed (problēma nes esošo transferId).
• Pārskaitījuma atcelšana vēl netiek atbalstīta: POST .../cancel atgriež 409 transfer_not_cancelable katrā stāvoklī. Šodienas canceled pārskaitījumi nāk no finansēšanas loga beigām nefinansētai iemaksai, ne no šī galapunkta.
• Iemaksas sākas ar awaiting_funds: renderē GET .../instructions maksātājam, bankas koordinātas plus atsauces vai memo kodu fiat, iemaksas adresi kripto. Atsauces kods ir tas, kā iemaksa tiek saskaņota. Vienmēr to attēlo.
• state plus stateDetail mašīnlasāmiem apakšstāvokļiem; action_required nozīmē, ka ir pievienots atbilstības uzdevums (openTaskIds, GET .../tasks), atbildi caur iesniegumiem.
• Ienākošās iemaksas, kas atklātas uz izsniegtiem kontiem, parādās kā pārskaitījumi ar origin: "inbound_deposit" (pretstatā "quoted").
• Maksājumu tīkla atsauces konsolidētas zem references: transactionHash, traceNumber, imad, uetr, explorerUrl, returnedTransferId.

• Pārskaitījumi nešķērso versijas. Pārskaitījumi, kas izveidoti uz v1 vai v2, nav nolasāmi no v3. Saraksts tos izlaiž un GET /v3/transfers/{transferId} atgriež 404. Vispirms pārslēdz izveidi, saglabā v1 lasīšanas ceļu, līdz šie pārskaitījumi sasniedz termināli stāvokli, tad noņem to.
• Nav tokenu maiņas. stablecoin_move prasa vienu un to pašu valūtu iekšā un ārā: USDC uz USDT neizdodas ar 422 recipient_destination_invalid, kas nes currency_mismatch lauka kļūdu. Tas pats tīkls abās pusēs, nav tilta, un maka-uz-maka kustības šobrīd atbalsta tikai bezmaksas piegādi: piedāvājums, kura platformas vai izstrādātāja maksa nav nulle, neizdodas ar 422 amount_not_deliverable.

​

2.7 Webhooki

• GET /v3/webhooks/portal atgriež mitināta pārvaldības portāla URL piegādes žurnāliem, atkārtojumiem un manuālai atkārtošanai.
• transfer.created pašlaik tiek piegādāts ar mantoto v1 satura formu (v3 aploksne aktivizēsies, kad v1 webhooki beigsies). Uzskati to tikai kā norādi un GET pārskaitījumu; neveido pret tā saturu.
• Notikumi ir norādes: saņemot, GET resursu un rīkojies pēc lasījuma. Nekad neveido stāvokli no notikumu satura vai secības. Piegāde ir vismaz vienreiz un var būt aizkavēta vai pārkārtota. Dedublē pēc notikuma id un atgūsti izlaistus notikumus ar katra saraksta iekļaujošo updatedAfter filtru.
• Abonē api.deprecation, mašīnu kanālu versiju izbeigšanai.
• Šodien nav task.* notikuma: pēc iesniegšanas apjautā uzdevumu vai tā vecāku.

​

2.8 Sandbox

​

2.9 Mantotie galapunkti bez v3 aizvietojuma

​

2.10 Ieteicamā migrācijas secība

​

2.11 Kļūmju kontrolsaraksts

• Svaigs UUID par katru loģisko operāciju, saglabāts kopā ar darbu un atkārtoti izmantots atkārtotā mēģinājumā; nekad atkārtoti neizmanto atslēgu ar mainītu saturu (409 idempotency_conflict). Sandbox galapunkti ir atbrīvoti no galvenes.
• Bagātini esošos klientus (PATCH pilno profilu, iestati metadata no jauna, tā netiek pārnesta) pirms jebkuras citas v3 rakstīšanas, pirmā v3 rakstīšana padara attīrīto skatu pastāvīgu.
• externalId ir unikāls katrā vidē un netiek atbrīvots ar arhivēšanu, notīri to ar PATCH pirms DELETE, ja plāno to atkārtoti izmantot.
• Nav klienta status lauka, atvasini gatavību katrai spējai.
• action_required un in_review abi nozīmē atvērtu uzdevumu.
• Iesniegumi ir pārskatīšanas vārtoti (iesniegšana nav tas pats, kas atbloķēšana) un jāatbild uz katru rīcības prasīgu prasību ar tieši taskRevision. Neatbilstības gadījumā nolasi vēlreiz un pārbūvē.
• Nav task.* webhook, apjautā uzdevumu (vai tā vecāku) pēc katra iesnieguma.
• changes_requested atkārtojums ir: nolasi uzdevumu vēlreiz, svaigas atbildes, svaiga idempotences atslēga.
• Postēšana uz /v1/documents nekad neatbloķē v3 spēju, kad klients ir uz uzdevumiem, virzi katru lūgumu caur uzdevumiem.
• Jauni uzdevumi var parādīties uz jau ready spējas, turi uzdevumu cilpu ievadītu pēc uzņemšanas, ne tikai tās laikā.
• Spējas cancel darbojas tikai no pending vai restricted bez bloķējošiem resursiem (409 capability_not_cancelable); atkārtota pieprasīšana pēc atcelšanas ir svaiga izveide ar svaigu idempotences atslēgu.
• Spējai jābūt ready pirms zem tās var izsniegt kontus vai pret to piedāvāt.
• Piedāvājumam ir summa tieši vienā pusē; nav virziena lauka; izpildi tieši vienreiz pirms expiresAt (409 quote_expired vai 409 quote_already_executed).
• Stablecoin kustības ir tikai tās pašas valūtas, tā paša tīkla (USDC uz USDT neizdodas ar 422); maks-uz-maks atbalsta tikai bezmaksas piegādi.
• DELETE arhivē, nekad neveic pilnīgu dzēšanu. Konta dzēšanu bloķē izpildē esoši pārskaitījumi (409 account_has_active_transfers); klienta dzēšanu papildus bloķē jebkurš nearchivēts konts (409 customer_has_active_resources, blockingResources[] tos nosauc).
• v1 vai v2 pārskaitījumi nav redzami v3 lasījumiem (saraksts izlaiž, GET 404), lasi dubulti līdz iztukšošanai, tad noņem vecos ceļus.
• Iemaksas routing un instrukcijas var mainīties, vienmēr renderē jaunāko GET un vienmēr rādi atsauces kodu.
• Webhooki ir norādes; GET ir patiesība, dedublē pēc notikuma id, atgūsti izlaistus notikumus ar updatedAfter.

​

Nākamais solis