PATCH/v1/cards/{card_id}

Atjaunināt kartīti

update_card

Autentifikācija

Nosūtiet API atslēgu galvenē Authorization: Authorization: Bearer <atslēga>.

Ceļa parametri

card_idstringobligāts

Galvenes parametri

Idempotency-Keystring
Atslēga drošam rakstīšanas darbības atkārtojumam: 1–255 drukājamas ASCII rakstzīmes; ieteicams viens UUID v4 katrai loģiskajai operācijai. Atkārtojums ar to pašu atslēgu 24 stundu laikā operāciju neizpilda vēlreiz: tiek atgriezta saglabātā atbilde (statuss, galvenes un saturs) ar galveni Idempotency-Replayed: true. Tā pati atslēga ar citu metodi, ceļu, Content-Type vai saturu atgriež 409 api.idempotency_mismatch; kamēr pirmais pieprasījums vēl izpildās – 409 api.idempotency_in_progress ar Retry-After: 1. Pēc atbildes 5xx vai 429 atslēga tiek atbrīvota, un atkārtojums izpilda operāciju vēlreiz. Atslēga ir piesaistīta organizācijai un izsaucējam (API atslēgai, lietotājam vai pielāgotā avota atslēgai).
length ≥ 1, length ≤ 255
X-View-Asstring
Tikai API atslēgām ar lomu admin. Izpilda pieprasījumu datu profila <profile>[:viewer|verifier|editor] vārdā, piemēram, employee:viewer. Instalācijas atslēga šo galveni lietot nevar (403).

Sīkdatņu parametri

kb_view_asstring
Režīma „View as“ (skatīt kā) sīkdatne sesijai. POST /auth/view-as to iestata, un DELETE /auth/view-as to notīra.

Pieprasījuma saturs

application/json

Objekts: CardUpdate

external_idstring | null
Iestata vai maina kartītes external_id; "" vai null to noņem. Ja to izmanto cita organizācijas kartīte, pieprasījums atgriež 409 cards.external_id_taken. Avota kartītes external_id nemainās (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

Atbildes

200Veiksmīga atbilde

Atbildes galvenes

RateLimit-Policy
Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.
RateLimit
Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).
X-RateLimit-Remaining
Atlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-Reset
Sekundes līdz stingrākā limita atiestatīšanai.
Idempotency-Replayed
true nozīmē, ka atbilde ir atkārtota no šai Idempotency-Key saglabātās atbildes: operācija netika izpildīta vēlreiz.

application/json

Objekts: Card

expandedCardExpanded
permissionsObjectPermissionList
accessstring
Atļautās vērtības: wholepartial
access_contactstring
Pie kā vērsties pēc piekļuves (tikai tad, ja access=partial).
aclobject
Lauki
- verifybooleanobligāts
- writebooleanobligāts
categorystringobligāts
category_confidencenumber | nullobligāts
category_lockedbooleanobligāts
category_reviewbooleanobligāts
category_sourceCategorySource | nullobligāts
collectionstringobligāts
collection_idintegerobligāts
collection_titlestring
commentsarray of CardComment
content_jsonContentJSON | null
Pēdējās publicētās versijas redaktora saturs. Lauka var nebūt; tādā gadījumā redaktora saturu iegūstiet no melnraksta (POST /v1/drafts ar card_id).
editing_lockEditingLock | null
Aktīvā rediģēšanas bloķēšana. Lauka var nebūt; tādā gadījumā redaktors uzzina, kam pieder bloķēšana, no 409 cards.locked atbildē uz POST /v1/cards/{card_id}/lock.
created_atstring (date-time)obligāts
days_since_verifiedintegerobligāts
errorstring | nullobligāts
eventsarray of CardEvent
feedback_negintegerobligāts
feedback_posintegerobligāts
foldersarray of CardFolderRef
Tikai kartīšu sarakstā: mapes, kurās ir kartīte (lietotājam redzamās), ar to ceļiem no kolekcijas saknes. Tukšs saraksts nozīmē, ka kartīte nav nevienā mapē.
has_tablesboolean
Tikai kartīšu sarakstā.
hidden_partsboolean
idstringobligāts
jobJob | null
kindCardKindobligāts
org_idintegerobligāts
owner_activeboolean | null
owner_idinteger | nullobligāts
owner_namestring | nullobligāts
pagesinteger | nullobligāts
parserstring | nullobligāts
Dokumenta nolasīšanas veids kā neitrāls kods: document (pilna struktūra: lappuses, virsraksti, tabulas, skenētas lappuses), pdf (PDF teksta slānis), docx, xlsx, csv, markdown, html, text. Saraksts var paplašināties.
partsarray of CardPartobligāts
sensitivebooleanobligāts
sha256string | nullobligāts
sizeintegerobligāts
snoozed_atstring (date-time) | null
snoozed_byinteger | null
snoozed_untilstring | null
source_changedbooleanobligāts
source_pathstring | nullobligāts
source_urlstring | nullobligāts
statusstringobligāts
Atļautās vērtības: processingreadyerrorarchived
tablesarray of CardTable
tagsarray of stringobligāts
titlestringobligāts
trustnumberobligāts
trust_if_verifiednumber
trust_partsTrustPartsobligāts
updated_atstring (date-time)obligāts
verificationVerificationobligāts
verified_atstring (date-time) | nullobligāts
verified_byinteger | nullobligāts
verified_by_namestring | null
verifier_idsarray of integerobligāts
verifiersarray of object
Lauki
- activebooleanobligāts
- idintegerobligāts
- namestringobligāts
verify_interval_daysintegerobligāts
versionintegerobligāts
versionsarray of CardVersion
source_archiveArchiveSource
created_byinteger | null
manual_optionsobject
Manuālie nolasīšanas iestatījumi (priekšskatījums).
doc_kindDocKind | null
Dokumenta tips. null, ja tips nav noteikts (piemēram, kartītēm, kas indeksētas pirms dokumentu tipu ieviešanas).
doc_kind_confidencenumber | null
Pārliecības līmenis par dokumenta tipu, no 0 līdz 1.
doc_kind_sourcestring | null
Kas noteica tipu: noteikumi (rules), lietotājs (manual) vai automātiska klasifikācija. Saraksts var paplašināties: nezināmu vērtību uzskatiet par automātisku klasifikāciju.
Atļautās vērtības: rulesmanualnull
invoiceDocInvoiceExtraction | null
Rēķina, kredītrēķina vai čeka lauki (tikai šiem tipiem un tikai kartītē, ne sarakstā). null, ja jums nav piekļuves visam dokumentam, jo lauki tiek iegūti no visa dokumenta.
warningsarray of ReviewWarning
Dokumenta nolasīšanas brīdinājumi (ReviewWarning; tikai kartītē, ne sarakstā).
enrichmentCardEnrichmentStatus | null
Bagātināšanas statuss (tikai kartītē, ne sarakstā). Dokumenta tips, rēķina lauki un finanšu ieraksti tiek pievienoti fonā pēc indeksēšanas un vēlāk var tikt pārrēķināti; tie parādās kartītē, kad ir gatavi. null nozīmē, ka statuss nav pieejams (kartīte indeksēta bez bagātināšanas fonā).
external_idstring | null
Kartītes ID integratora sistēmā. Tas ir unikāls organizācijā starp kartītēm, kas nenāk no avotiem; null nozīmē, ka tas nav iestatīts. /v1/cards-by-external-id/{external_id} pēc tā nolasa un aizstāj kartīti.
length ≤ 512
metadataMetadata

400Pieprasījums nav derīgs: parametra vērtība vai objekta stāvoklis neļauj veikt darbību (`detail` ir ziņojums).

Atbildes galvenes

RateLimit-Policy
Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.
RateLimit
Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).
X-RateLimit-Remaining
Atlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-Reset
Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

401Nav nosūtīti akreditācijas dati (ne sesijas sīkdatne, ne API atslēga), vai atslēga nav atrasta.

Atbildes galvenes

RateLimit-Policy
Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.
RateLimit
Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).
X-RateLimit-Remaining
Atlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-Reset
Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

403Darbība nav atļauta: loma nav pietiekama, nav piekļuves kolekcijai vai kartītei, pieprasījums izpildās režīmā „View as“ vai organizācija ir apturēta vai dzēsta (`detail` ir objekts ar `code: org_suspended | org_deleted`).

Atbildes galvenes

RateLimit-Policy
Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.
RateLimit
Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).
X-RateLimit-Remaining
Atlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-Reset
Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

404Objekts neeksistē vai jums nav pieejams. API neapstiprina, ka ierobežotas piekļuves objekts eksistē.

Atbildes galvenes

RateLimit-Policy
Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.
RateLimit
Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).
X-RateLimit-Remaining
Atlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-Reset
Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

422Validācijas kļūda: saturs vai parametri neatbilst shēmai (`detail` ir validācijas kļūdu saraksts), vai parametra vērtība ir ārpus pieļaujamā diapazona (`detail` ir ziņojums).

Atbildes galvenes

RateLimit-Policy
Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.
RateLimit
Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).
X-RateLimit-Remaining
Atlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-Reset
Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

429Pārāk daudz pieprasījumu (`api.rate_limited`), organizācijas minūtes, dienas vai mēneša kvota ir izlietota (`api.quota_exceeded`; `error.details` satur `quota`, `limit` un `reset_at`), sasniegts organizācijas limits vai atbilžu pakalpojums ir aizņemts (`answers.engine_busy`). Pagaidiet galvenē `Retry-After` norādīto laiku.

Atbildes galvenes

Retry-After
Sekunžu skaits, kas jāpagaida, pirms atkārtojat pieprasījumu.
RateLimit-Policy
Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.
RateLimit
Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).
X-RateLimit-Remaining
Atlikušo pieprasījumu skaits stingrākā limita ietvaros.
X-RateLimit-Reset
Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

Kļūdu kodi

Kodi, ko šī operācija var atgriezt laukā error.code papildus vispārīgajiem kodiem, kas iespējami jebkuram pieprasījumam.

Droši atkārtojumi

Ar katru POST un PATCH pieprasījumu nosūtiet galveni Idempotency-Key (piemēram, UUID). Atkārtots pieprasījums ar to pašu atslēgu 24 stundu laikā atgriež saglabāto atbildi, nevis izpilda pieprasījumu vēlreiz.

Pieprasījumu biežuma limiti

Atbildēs ir galvenes RateLimit un RateLimit-Policy, kā arī agrākās X-RateLimit-Limit, X-RateLimit-Remaining un X-RateLimit-Reset. Atbildē 429 ir galvene Retry-After sekundēs: nogaidiet un atkārtojiet pieprasījumu.

← cards · API rokasgrāmata

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"

Izmēģināt

API atslēga

Atslēga glabājas tikai šīs cilnes atmiņā un tiek sūtīta tikai uz https://api.sursa.com.

Pieprasījumi darbojas ar jūsu organizācijas reālajiem datiem.

Idempotency-Key header

X-View-As header

card_id path *

Idempotency-Key

Ja lauks ir tukšs, katram pieprasījumam tiek ģenerēta jauna atslēga.

Pieprasījuma saturs (JSON)