POST/v1/cards/{card_id}/verify

Confirmar que una entrada està al dia

verify_card

Autenticació

Envieu una clau d’API a la capçalera Authorization: Authorization: Bearer <clau>.

Paràmetres de camí

card_idstringobligatori

Paràmetres de capçalera

Idempotency-Keystring
Clau per reintentar una escriptura de manera segura: d’1 a 255 caràcters ASCII imprimibles; es recomana un UUID v4 per operació lògica. Un reintent amb la mateixa clau en un termini de 24 hores no torna a executar l’operació: retorna la resposta desada (estat, capçaleres i cos) amb la capçalera Idempotency-Replayed: true. La mateixa clau amb un mètode, un camí, un Content-Type o un cos diferents retorna 409 api.idempotency_mismatch; mentre la primera sol·licitud encara s’executa, 409 api.idempotency_in_progress amb Retry-After: 1. Després d’una resposta 5xx o 429 la clau s’allibera, i un reintent torna a executar l’operació. L’abast de la clau és l’organització i qui fa la crida (clau d’API, usuari o clau de font personalitzada).
length ≥ 1, length ≤ 255
X-View-Asstring
Només per a claus d’API amb el rol admin. Fa la sol·licitud com el perfil de dades <profile>[:viewer|verifier|editor], per exemple employee:viewer. La clau d’instal·lació no pot fer servir aquesta capçalera (403).

Paràmetres de galeta

kb_view_asstring
Galeta del mode «View as» per a una sessió. POST /auth/view-as l’estableix i DELETE /auth/view-as l’esborra.

Cos de la sol·licitud

application/json

Objecte: VerifyRequest

notestring | null

Respostes

200Resposta correcta

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.
Idempotency-Replayed
true indica que la resposta s’ha reproduït a partir de la desada per a aquesta Idempotency-Key: l’operació no s’ha tornat a executar.

application/json

Objecte: Card

expandedCardExpanded
permissionsObjectPermissionList
accessstring
Valors permesos: wholepartial
access_contactstring
Persona a qui cal adreçar-se per obtenir accés (només quan access=partial).
aclobject
Camps
- verifybooleanobligatori
- writebooleanobligatori
categorystringobligatori
category_confidencenumber | nullobligatori
category_lockedbooleanobligatori
category_reviewbooleanobligatori
category_sourceCategorySource | nullobligatori
collectionstringobligatori
collection_idintegerobligatori
collection_titlestring
commentsarray of CardComment
content_jsonContentJSON | null
Contingut de l’editor de l’última versió publicada. El camp pot no ser-hi; en aquest cas, obteniu el contingut de l’editor d’un esborrany (POST /v1/drafts amb card_id).
editing_lockEditingLock | null
Bloqueig d’edició actiu. El camp pot no ser-hi; en aquest cas, l’editor sap qui té el bloqueig per la resposta 409 cards.locked de POST /v1/cards/{card_id}/lock.
created_atstring (date-time)obligatori
days_since_verifiedintegerobligatori
errorstring | nullobligatori
eventsarray of CardEvent
feedback_negintegerobligatori
feedback_posintegerobligatori
foldersarray of CardFolderRef
Només a la llista d’entrades: les carpetes que contenen l’entrada (les que l’usuari pot veure), amb els seus camins des de l’arrel de la col·lecció. Una llista buida vol dir que l’entrada no és a cap carpeta.
has_tablesboolean
Només a la llista d’entrades.
hidden_partsboolean
idstringobligatori
jobJob | null
kindCardKindobligatori
org_idintegerobligatori
owner_activeboolean | null
owner_idinteger | nullobligatori
owner_namestring | nullobligatori
pagesinteger | nullobligatori
parserstring | nullobligatori
Analitzador del document com a codi neutre: document (estructura completa: pàgines, títols, taules, pàgines escanejades), pdf (la capa de text del PDF), docx, xlsx, csv, markdown, html, text. La llista pot créixer.
partsarray of CardPartobligatori
sensitivebooleanobligatori
sha256string | nullobligatori
sizeintegerobligatori
snoozed_atstring (date-time) | null
snoozed_byinteger | null
snoozed_untilstring | null
source_changedbooleanobligatori
source_pathstring | nullobligatori
source_urlstring | nullobligatori
statusstringobligatori
Valors permesos: processingreadyerrorarchived
tablesarray of CardTable
tagsarray of stringobligatori
titlestringobligatori
trustnumberobligatori
trust_if_verifiednumber
trust_partsTrustPartsobligatori
updated_atstring (date-time)obligatori
verificationVerificationobligatori
verified_atstring (date-time) | nullobligatori
verified_byinteger | nullobligatori
verified_by_namestring | null
verifier_idsarray of integerobligatori
verifiersarray of object
Camps
- activebooleanobligatori
- idintegerobligatori
- namestringobligatori
verify_interval_daysintegerobligatori
versionintegerobligatori
versionsarray of CardVersion
source_archiveArchiveSource
created_byinteger | null
manual_optionsobject
Configuració manual de l’anàlisi (previsualització).
doc_kindDocKind | null
Tipus de document. null si el tipus no s’ha determinat (per exemple, en entrades indexades abans que s’introduïssin els tipus de document).
doc_kind_confidencenumber | null
Grau de certesa del tipus de document, de 0 a 1.
doc_kind_sourcestring | null
Què ha determinat el tipus: regles (rules), un usuari (manual) o la classificació automàtica. La llista pot créixer: tracteu un valor desconegut com a classificació automàtica.
Valors permesos: rulesmanualnull
invoiceDocInvoiceExtraction | null
Camps d’una factura, una nota d’abonament o un rebut (només per a aquests tipus, i només a l’entrada, no a la llista). null si no teniu accés a tot el document, perquè els camps s’extreuen del document sencer.
warningsarray of ReviewWarning
Avisos de l’anàlisi del document (ReviewWarning; només a l’entrada, no a la llista).
enrichmentCardEnrichmentStatus | null
Estat de l’enriquiment (només a l’entrada, no a la llista). El tipus de document, els camps de la factura i els registres financers s’afegeixen en segon pla després de la indexació i es poden tornar a calcular més endavant; apareixen a l’entrada quan estan llestos. null vol dir que no hi ha cap estat disponible (l’entrada es va indexar sense enriquiment en segon pla).
external_idstring | null
ID de l’entrada al sistema de l’integrador. És únic a l’organització entre les entrades que no provenen de fonts; null vol dir que no està definit. /v1/cards-by-external-id/{external_id} llegeix i substitueix l’entrada a partir d’aquest ID.
length ≤ 512
metadataMetadata

400La sol·licitud no és vàlida: el valor d’un paràmetre o l’estat de l’objecte no permeten l’acció (`detail` és un missatge).

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

401No s’han enviat credencials (ni una galeta de sessió ni una clau d’API), o no s’ha trobat la clau.

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

403L’acció no està permesa: el rol és insuficient, no hi ha accés a la col·lecció o a l’entrada, la sol·licitud s’executa en mode «View as», o l’organització està suspesa o eliminada (`detail` és un objecte amb `code: org_suspended | org_deleted`).

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

404L’objecte no existeix o no està disponible per a vós. L’API no confirma que existeixi un objecte restringit.

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

422Error de validació: el cos o els paràmetres no coincideixen amb l’esquema (`detail` és una llista d’errors de validació), o el valor d’un paràmetre és fora de l’interval permès (`detail` és un missatge).

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

429Massa sol·licituds (`api.rate_limited`), s’ha esgotat la quota de l’organització per al minut, el dia o el mes (`api.quota_exceeded`; `error.details` conté `quota`, `limit` i `reset_at`), s’ha arribat al límit de l’organització o el servei de respostes està ocupat (`answers.engine_busy`). Espereu el temps que indica la capçalera `Retry-After`.

Capçaleres de la resposta

Retry-After
Nombre de segons que cal esperar abans de reintentar la sol·licitud.
RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

Codis d’error

Codis que aquest punt final pot retornar a error.code, a més dels codis generals de totes les sol·licituds.

Reintents segurs

Envieu una capçalera Idempotency-Key (per exemple, un UUID) amb cada POST i PATCH. Un reintent amb la mateixa clau en un termini de 24 hores retorna la resposta desada en lloc de tornar a executar la sol·licitud.

Límits de freqüència

Les respostes porten les capçaleres RateLimit i RateLimit-Policy i les anteriors X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset. Una resposta 429 té Retry-After en segons: espereu i torneu-ho a provar.

← cards · Referència de l’API

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

Provar

Clau d’API

La clau es queda a la memòria d’aquesta pestanya i només s’envia a https://api.sursa.com.

Les sol·licituds actuen sobre les dades reals de la vostra organització.

Idempotency-Key header

X-View-As header

card_id path *

Idempotency-Key

Si és buit, es genera una clau nova per a cada sol·licitud.

Cos de la sol·licitud (JSON)