PATCH/v1/cards/{card_id}

Päivitä kortti

update_card

Todennus

Lähetä API-avain Authorization-otsakkeessa: Authorization: Bearer <avain>.

Polkuparametrit

card_idstringpakollinen

Otsakeparametrit

Idempotency-Keystring
Avain kirjoituksen turvalliseen uusintayritykseen: 1–255 tulostettavaa ASCII-merkkiä; suositus on yksi UUID v4 jokaista loogista toimintoa kohden. Uusintayritys samalla avaimella 24 tunnin kuluessa ei suorita toimintoa uudelleen: se palauttaa tallennetun vastauksen (tila, otsakkeet ja runko) Idempotency-Replayed: true -otsakkeella. Sama avain eri metodilla, polulla, Content-Type-arvolla tai rungolla palauttaa 409 api.idempotency_mismatch; kun ensimmäinen pyyntö on vielä käynnissä, vastaus on 409 api.idempotency_in_progress ja Retry-After: 1. 5xx- tai 429-vastauksen jälkeen avain vapautuu, ja uusintayritys suorittaa toiminnon uudelleen. Avain on sidottu organisaatioon ja kutsujaan (API-avain, käyttäjä tai mukautetun lähteen avain).
length ≥ 1, length ≤ 255
X-View-Asstring
Vain API-avaimille, joilla on admin-rooli. Suorittaa pyynnön dataprofiilin <profile>[:viewer|verifier|editor] puolesta, esimerkiksi employee:viewer. Asennusavain ei voi käyttää tätä otsaketta (403).

Evästeparametrit

kb_view_asstring
Istunnon ”View as” -tilan eväste. POST /auth/view-as asettaa sen ja DELETE /auth/view-as poistaa sen.

Pyynnön runko

application/json

Objekti: CardUpdate

external_idstring | null
Asettaa tai muuttaa kortin external_id-tunnuksen; "" tai null poistaa sen. Jos organisaation toinen kortti käyttää sitä, pyyntö palauttaa 409 cards.external_id_taken. Lähteen kortin external_id ei muutu (409 cards.managed_by_source).
length ≤ 512
metadataMetadataPatch
titlestring | null
owner_idinteger | null
verifier_idsarray of integer | null
verify_interval_daysinteger | null
≥ 1, ≤ 3650
tagsarray of string | null
statusstring | null
source_urlstring | null
categorystring | null
sensitiveboolean | null
table_categoriesmap of object | null

Vastaukset

200Onnistunut vastaus

Vastausotsakkeet

RateLimit-Policy
Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.
RateLimit
Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).
X-RateLimit-Remaining
Tiukimman rajan puitteissa jäljellä olevat pyynnöt.
X-RateLimit-Reset
Sekunteja siihen, kun tiukin raja nollautuu.
Idempotency-Replayed
true tarkoittaa, että vastaus toistettiin tälle Idempotency-Key-arvolle tallennetusta vastauksesta: toimintoa ei suoritettu uudelleen.

application/json

Objekti: Card

expandedCardExpanded
permissionsObjectPermissionList
accessstring
Sallitut arvot: wholepartial
access_contactstring
Keneen ottaa yhteyttä käyttöoikeuden saamiseksi (vain kun access=partial).
aclobject
Kentät
- verifybooleanpakollinen
- writebooleanpakollinen
categorystringpakollinen
category_confidencenumber | nullpakollinen
category_lockedbooleanpakollinen
category_reviewbooleanpakollinen
category_sourceCategorySource | nullpakollinen
collectionstringpakollinen
collection_idintegerpakollinen
collection_titlestring
commentsarray of CardComment
content_jsonContentJSON | null
Viimeisimmän julkaistun version sisältö editorin muodossa. Kenttä voi puuttua; silloin hae editorin sisältö luonnoksesta (POST /v1/drafts ja card_id).
editing_lockEditingLock | null
Voimassa oleva muokkauslukitus. Kenttä voi puuttua; silloin editori saa tietää lukituksen haltijan 409 cards.locked-vastauksesta POST /v1/cards/{card_id}/lock-toiminnossa.
created_atstring (date-time)pakollinen
days_since_verifiedintegerpakollinen
errorstring | nullpakollinen
eventsarray of CardEvent
feedback_negintegerpakollinen
feedback_posintegerpakollinen
foldersarray of CardFolderRef
Vain korttiluettelossa: kansiot, joissa kortti on (käyttäjälle näkyvät), polkuineen kokoelman juuresta. Tyhjä luettelo tarkoittaa, että kortti ei ole missään kansiossa.
has_tablesboolean
Vain korttiluettelossa.
hidden_partsboolean
idstringpakollinen
jobJob | null
kindCardKindpakollinen
org_idintegerpakollinen
owner_activeboolean | null
owner_idinteger | nullpakollinen
owner_namestring | nullpakollinen
pagesinteger | nullpakollinen
parserstring | nullpakollinen
Asiakirjan jäsennin neutraalina koodina: document (koko rakenne: sivut, otsikot, taulukot, skannatut sivut), pdf (PDF:n tekstikerros), docx, xlsx, csv, markdown, html, text. Luettelo voi laajentua.
partsarray of CardPartpakollinen
sensitivebooleanpakollinen
sha256string | nullpakollinen
sizeintegerpakollinen
snoozed_atstring (date-time) | null
snoozed_byinteger | null
snoozed_untilstring | null
source_changedbooleanpakollinen
source_pathstring | nullpakollinen
source_urlstring | nullpakollinen
statusstringpakollinen
Sallitut arvot: processingreadyerrorarchived
tablesarray of CardTable
tagsarray of stringpakollinen
titlestringpakollinen
trustnumberpakollinen
trust_if_verifiednumber
trust_partsTrustPartspakollinen
updated_atstring (date-time)pakollinen
verificationVerificationpakollinen
verified_atstring (date-time) | nullpakollinen
verified_byinteger | nullpakollinen
verified_by_namestring | null
verifier_idsarray of integerpakollinen
verifiersarray of object
Kentät
- activebooleanpakollinen
- idintegerpakollinen
- namestringpakollinen
verify_interval_daysintegerpakollinen
versionintegerpakollinen
versionsarray of CardVersion
source_archiveArchiveSource
created_byinteger | null
manual_optionsobject
Manuaaliset jäsennysasetukset (esikatselu).
doc_kindDocKind | null
Asiakirjan tyyppi. null, jos tyyppiä ei ole määritetty (esimerkiksi korteilla, jotka indeksoitiin ennen asiakirjatyyppien käyttöönottoa).
doc_kind_confidencenumber | null
Asiakirjan tyypin varmuustaso välillä 0–1.
doc_kind_sourcestring | null
Mikä määritti tyypin: säännöt (rules), käyttäjä (manual) tai automaattinen luokittelu. Luettelo voi laajentua: käsittele tuntematon arvo automaattisena luokitteluna.
Sallitut arvot: rulesmanualnull
invoiceDocInvoiceExtraction | null
Laskun, hyvityslaskun tai kuitin kentät (vain näillä tyypeillä ja vain kortissa, ei luettelossa). null, jos sinulla ei ole pääsyä koko asiakirjaan, koska kentät poimitaan koko asiakirjasta.
warningsarray of ReviewWarning
Asiakirjan jäsennyksen varoitukset (ReviewWarning; vain kortissa, ei luettelossa).
enrichmentCardEnrichmentStatus | null
Rikastuksen tila (vain kortissa, ei luettelossa). Asiakirjan tyyppi, laskun kentät ja taloustietueet lisätään taustalla indeksoinnin jälkeen, ja ne voidaan laskea myöhemmin uudelleen; ne näkyvät kortissa, kun ne ovat valmiita. null tarkoittaa, ettei tilaa ole saatavilla (kortti indeksoitiin ilman taustarikastusta).
external_idstring | null
Kortin tunnus integroijan järjestelmässä. Se on yksilöllinen organisaatiossa niiden korttien kesken, jotka eivät tule lähteistä; null tarkoittaa, ettei sitä ole asetettu. /v1/cards-by-external-id/{external_id} lukee ja korvaa kortin sen mukaan.
length ≤ 512
metadataMetadata

400Pyyntö on virheellinen: parametrin arvo tai objektin tila ei salli toimenpidettä (`detail` on viesti).

Vastausotsakkeet

RateLimit-Policy
Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.
RateLimit
Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).
X-RateLimit-Remaining
Tiukimman rajan puitteissa jäljellä olevat pyynnöt.
X-RateLimit-Reset
Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

401Tunnistetietoja ei lähetetty (ei istuntoevästettä eikä API-avainta), tai avainta ei löytynyt.

Vastausotsakkeet

RateLimit-Policy
Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.
RateLimit
Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).
X-RateLimit-Remaining
Tiukimman rajan puitteissa jäljellä olevat pyynnöt.
X-RateLimit-Reset
Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

403Toimenpide ei ole sallittu: rooli ei riitä, kokoelmaan tai korttiin ei ole käyttöoikeutta, pyyntö suoritetaan ”View as” -tilassa, tai organisaation toiminta on keskeytetty tai organisaatio on poistettu (`detail` on objekti, jossa on `code: org_suspended | org_deleted`).

Vastausotsakkeet

RateLimit-Policy
Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.
RateLimit
Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).
X-RateLimit-Remaining
Tiukimman rajan puitteissa jäljellä olevat pyynnöt.
X-RateLimit-Reset
Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

404Objektia ei ole tai se ei ole saatavillasi. API ei paljasta, onko rajoitettu objekti olemassa.

Vastausotsakkeet

RateLimit-Policy
Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.
RateLimit
Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).
X-RateLimit-Remaining
Tiukimman rajan puitteissa jäljellä olevat pyynnöt.
X-RateLimit-Reset
Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

422Validointivirhe: runko tai parametrit eivät vastaa skeemaa (`detail` on validointivirheiden lista), tai parametrin arvo on sallitun alueen ulkopuolella (`detail` on viesti).

Vastausotsakkeet

RateLimit-Policy
Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.
RateLimit
Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).
X-RateLimit-Remaining
Tiukimman rajan puitteissa jäljellä olevat pyynnöt.
X-RateLimit-Reset
Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

429Liian monta pyyntöä (`api.rate_limited`), organisaation minuutti-, päivä- tai kuukausikiintiö on käytetty (`api.quota_exceeded`; `error.details` sisältää kentät `quota`, `limit` ja `reset_at`), organisaation raja on saavutettu tai vastauspalvelu on kuormitettu (`answers.engine_busy`). Odota `Retry-After`-otsakkeen ilmoittama aika.

Vastausotsakkeet

Retry-After
Kuinka monta sekuntia odotetaan ennen pyynnön uusintayritystä.
RateLimit-Policy
Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.
RateLimit
Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).
X-RateLimit-Remaining
Tiukimman rajan puitteissa jäljellä olevat pyynnöt.
X-RateLimit-Reset
Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

Virhekoodit

Koodit, jotka tämä päätepiste voi palauttaa error.code-kentässä kaikkien pyyntöjen yleisten koodien lisäksi.

Turvalliset uusintayritykset

Lähetä jokaisen POST- ja PATCH-pyynnön mukana Idempotency-Key-otsake (esimerkiksi UUID). Kun pyyntö toistetaan samalla avaimella 24 tunnin kuluessa, palautetaan tallennettu vastaus eikä pyyntöä suoriteta uudelleen.

Nopeusrajoitukset

Vastauksissa ovat RateLimit- ja RateLimit-Policy-otsakkeet sekä aiemmat X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset. 429-vastauksessa on Retry-After sekunteina: odota ja yritä uudelleen.

← cards · API-viite

curl -X PATCH 'https://api.sursa.com/v1/cards/CARD_ID' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"crm-1042","metadata":{"key":"string"},"title":"Refund policy"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Kokeile

API-avain

Avain säilyy vain tämän välilehden muistissa, ja se lähetetään ainoastaan osoitteeseen https://api.sursa.com.

Pyynnöt kohdistuvat organisaatiosi todellisiin tietoihin.

Idempotency-Key header

X-View-As header

card_id path *

Idempotency-Key

Jos kenttä on tyhjä, jokaiselle pyynnölle luodaan uusi avain.

Pyynnön runko (JSON)