POST/v1/cards/{card_id}/verification/verify

Kaardi kontrollimine

verify_card_verification

Nõuab õigust CARD_VERIFY või määratud kontrollija staatust (otse, rühma kaudu või vastutajana). Märkus salvestatakse kaardi kommentaarina. Samas päringus saab muuta ka tähtaega (type, interval_days, until). Juba möödunud fikseeritud tähtaeg tuleb asendada uuega; vastasel juhul tagastab päring 409 verification.absolute_expired.

Autentimine

Saatke API-võti päises Authorization: Authorization: Bearer <võti>.

Teeparameetrid

card_idstringkohustuslik

Päiseparameetrid

Idempotency-Keystring
Võti kirjutamistoimingu turvaliseks kordamiseks: 1–255 prinditavat ASCII-märki; soovitatav on UUID v4 iga loogilise toimingu kohta. Kordus sama võtmega 24 tunni jooksul ei käivita toimingut uuesti: tagastatakse salvestatud vastus (olek, päised ja keha) päisega Idempotency-Replayed: true. Sama võti teise meetodi, tee, Content-Type või kehaga tagastab 409 api.idempotency_mismatch; kuni esimene päring veel töötab, tagastatakse 409 api.idempotency_in_progress koos päisega Retry-After: 1. Pärast vastust 5xx või 429 võti vabastatakse ja kordus käivitab toimingu uuesti. Võti kehtib organisatsiooni ja päringu tegija piires (API-võti, kasutaja või kohandatud allika võti).
length ≥ 1, length ≤ 255

Päringu keha

application/json

Objekt: VerifyCardRequest

notestring | null
length ≤ 4000
typeVerificationType | null
interval_daysinteger | null
≥ 1, ≤ 3650
untilstring (date-time) | null

Vastused

200Edukas vastus

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.
Idempotency-Replayed
true tähendab, et vastus esitati uuesti selle Idempotency-Key jaoks salvestatud vastusest: toimingut uuesti ei käivitatud.

application/json

Objekt: CardVerification

card_idstringkohustuslik
stateVerificationStatekohustuslik
typeVerificationTypekohustuslik
interval_daysintegerkohustuslik
next_verification_atstring (date-time) | null
verified_atstring (date-time) | null
verified_byinteger | null
last_verified_versioninteger | null
versioninteger
reasonVerificationReason | null
initiator_idinteger | null
initiated_atstring (date-time) | null
unverified_sincestring (date-time) | null
unverified_viewsintegerkohustuslik
unverified_copiesintegerkohustuslik
pending_auto_archivebooleankohustuslik
verifiersarray of Verifierkohustuslik
last_eventVerificationEvent | null
eventsarray of VerificationEventkohustuslik
permissionsarray of stringkohustuslik

400Päring on vigane: parameetri väärtus või objekti olek ei võimalda toimingut (`detail` on teade).

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

401Autentimisandmeid ei saadetud (ei seansiküpsist ega API-võtit) või võtit ei leitud.

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

403Toiming ei ole lubatud: rollist ei piisa, puudub juurdepääs kogule või kaardile, päring töötab režiimis „View as“ või organisatsioon on peatatud või kustutatud (`detail` on objekt väärtusega `code: org_suspended | org_deleted`).

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

404Objekti ei ole olemas või see ei ole teile kättesaadav. API ei kinnita piiratud juurdepääsuga objekti olemasolu.

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

409Objekti olek ei võimalda toimingut, näiteks duplikaat, käimasolev indekseerimine või juba töödeldud töö.

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

429Liiga palju päringuid (`api.rate_limited`), organisatsiooni minuti-, päeva- või kuukvoot on ära kasutatud (`api.quota_exceeded`; `error.details` sisaldab välju `quota`, `limit` ja `reset_at`), organisatsiooni limiit on täis või vastuseteenus on hõivatud (`answers.engine_busy`). Oodake päises `Retry-After` antud aeg.

Vastuse päised

Retry-After
Sekundite arv, mida oodata enne päringu kordamist.
RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

Veakoodid

Koodid, mida see lõpp-punkt võib lisaks iga päringu üldistele koodidele tagastada väljal error.code.

Turvalised korduskatsed

Saatke iga POST- ja PATCH-päringuga päis Idempotency-Key (näiteks UUID). Sama võtmega korduskatse 24 tunni jooksul tagastab salvestatud vastuse ega käivita päringut uuesti.

Sageduspiirangud

Vastustes on päised RateLimit ja RateLimit-Policy ning varasemad X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset. Vastuses 429 on päis Retry-After sekundites: oodake ja proovige uuesti.

← verification · API teatmik

curl -X POST 'https://api.sursa.com/v1/cards/CARD_ID/verification/verify' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"note":"string","type":"relative","interval_days":1}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Proovi

API-võti

Võti jääb ainult selle vahekaardi mällu ja see saadetakse üksnes aadressile https://api.sursa.com.

Päringud muudavad teie organisatsiooni päris andmeid.

Idempotency-Key header

card_id path *

Idempotency-Key

Kui väli on tühi, luuakse iga päringu jaoks uus võti.

Päringu keha (JSON)