GET/v1/cards-by-external-id/{external_id}

Ottenere una scheda tramite ID esterno

get_card_by_external_id

Restituisce la stessa scheda, con gli stessi controlli di accesso, di GET /v1/cards/{card_id}, individuata dall’external_id dell’integratore. Se l’organizzazione non ha una scheda con questo external_id o la scheda non è visibile a chi effettua la chiamata, la richiesta restituisce 404 cards.not_found.

Autenticazione

Invia una chiave API nell’intestazione Authorization: Authorization: Bearer <chiave>.

Parametri di percorso

external_idstringobbligatorio
external_id della scheda: una stringa di 1–512 caratteri, univoca nell’organizzazione.
length ≥ 1, length ≤ 512

Parametri di query

expand[]array of string
Oggetti correlati da includere nella risposta (dalla 1.62.0): un percorso dell’elenco x-expandable dell’operazione. Ripeti il parametro fino a 10 volte. Un percorso ha fino a 2 segmenti separati da un punto (collection.default_owner). In un elenco, il percorso inizia con data. e si applica a ogni elemento della pagina (expand[]=data.owner). Un oggetto espanso va nell’oggetto expanded dell’elemento, e il campo con l’ID resta. Un oggetto che chi effettua la chiamata non può vedere secondo i controlli della sua operazione di lettura viene espanso come null. Un percorso sconosciuto, più di 10 percorsi o un percorso con più di 2 segmenti restituiscono 400 api.expand_invalid.
items ≤ 10

Parametri di intestazione

X-View-Asstring
Solo per le chiavi API con il ruolo admin. Esegue la richiesta come il profilo dati <profile>[:viewer|verifier|editor], ad esempio employee:viewer. La chiave di installazione non può usare questa intestazione (403).

Parametri cookie

kb_view_asstring
Cookie della modalità “View as” per una sessione. POST /auth/view-as lo imposta e DELETE /auth/view-as lo cancella.

Risposte

200Risposta riuscita

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Card

expandedCardExpanded
permissionsObjectPermissionList
accessstring
Valori ammessi: wholepartial
access_contactstring
Chi contattare per l’accesso (solo quando access=partial).
aclobject
Campi
- verifybooleanobbligatorio
- writebooleanobbligatorio
categorystringobbligatorio
category_confidencenumber | nullobbligatorio
category_lockedbooleanobbligatorio
category_reviewbooleanobbligatorio
category_sourceCategorySource | nullobbligatorio
collectionstringobbligatorio
collection_idintegerobbligatorio
collection_titlestring
commentsarray of CardComment
content_jsonContentJSON | null
Contenuto dell’editor dell’ultima versione pubblicata. Il campo può essere assente; in tal caso, ottieni il contenuto dell’editor da una bozza (POST /v1/drafts con card_id).
editing_lockEditingLock | null
Blocco di modifica attivo. Il campo può essere assente; in tal caso, l’editor scopre chi detiene il blocco dalla risposta 409 cards.locked di POST /v1/cards/{card_id}/lock.
created_atstring (date-time)obbligatorio
days_since_verifiedintegerobbligatorio
errorstring | nullobbligatorio
eventsarray of CardEvent
feedback_negintegerobbligatorio
feedback_posintegerobbligatorio
foldersarray of CardFolderRef
Solo nell’elenco delle schede: le cartelle che contengono la scheda (quelle visibili all’utente), con i loro percorsi dalla radice della raccolta. Un elenco vuoto indica che la scheda non è in nessuna cartella.
has_tablesboolean
Solo nell’elenco delle schede.
hidden_partsboolean
idstringobbligatorio
jobJob | null
kindCardKindobbligatorio
org_idintegerobbligatorio
owner_activeboolean | null
owner_idinteger | nullobbligatorio
owner_namestring | nullobbligatorio
pagesinteger | nullobbligatorio
parserstring | nullobbligatorio
Metodo di analisi del documento come codice neutro: document (struttura completa: pagine, titoli, tabelle, pagine scansionate), pdf (il livello di testo del PDF), docx, xlsx, csv, markdown, html, text. L’elenco può crescere.
partsarray of CardPartobbligatorio
sensitivebooleanobbligatorio
sha256string | nullobbligatorio
sizeintegerobbligatorio
snoozed_atstring (date-time) | null
snoozed_byinteger | null
snoozed_untilstring | null
source_changedbooleanobbligatorio
source_pathstring | nullobbligatorio
source_urlstring | nullobbligatorio
statusstringobbligatorio
Valori ammessi: processingreadyerrorarchived
tablesarray of CardTable
tagsarray of stringobbligatorio
titlestringobbligatorio
trustnumberobbligatorio
trust_if_verifiednumber
trust_partsTrustPartsobbligatorio
updated_atstring (date-time)obbligatorio
verificationVerificationobbligatorio
verified_atstring (date-time) | nullobbligatorio
verified_byinteger | nullobbligatorio
verified_by_namestring | null
verifier_idsarray of integerobbligatorio
verifiersarray of object
Campi
- activebooleanobbligatorio
- idintegerobbligatorio
- namestringobbligatorio
verify_interval_daysintegerobbligatorio
versionintegerobbligatorio
versionsarray of CardVersion
source_archiveArchiveSource
created_byinteger | null
manual_optionsobject
Impostazioni manuali dell’analisi del documento (anteprima).
doc_kindDocKind | null
Tipo di documento. null se il tipo non è determinato (ad esempio, per le schede indicizzate prima dell’introduzione dei tipi di documento).
doc_kind_confidencenumber | null
Livello di confidenza nel tipo di documento, da 0 a 1.
doc_kind_sourcestring | null
Che cosa ha determinato il tipo: regole (rules), un utente (manual) o la classificazione automatica. L’elenco può crescere: tratta un valore sconosciuto come classificazione automatica.
Valori ammessi: rulesmanualnull
invoiceDocInvoiceExtraction | null
Campi di una fattura, nota di credito o ricevuta (solo per questi tipi, e solo nella scheda, non nell’elenco). null se non hai accesso all’intero documento, perché i campi vengono estratti dall’intero documento.
warningsarray of ReviewWarning
Avvisi dell’analisi del documento (ReviewWarning; solo nella scheda, non nell’elenco).
enrichmentCardEnrichmentStatus | null
Stato dell’arricchimento (solo nella scheda, non nell’elenco). Il tipo di documento, i campi della fattura e i dati finanziari vengono aggiunti in background dopo l’indicizzazione e possono essere ricalcolati in seguito; compaiono nella scheda quando sono pronti. null indica che non è disponibile alcuno stato (la scheda è stata indicizzata senza arricchimento in background).
external_idstring | null
ID della scheda nel sistema dell’integratore. È univoco nell’organizzazione tra le schede che non provengono da fonti; null indica che non è impostato. /v1/cards-by-external-id/{external_id} legge e sostituisce la scheda tramite questo ID.
length ≤ 512
metadataMetadata

400La richiesta non è valida: il valore di un parametro o lo stato dell’oggetto non consente l’azione (`detail` è un messaggio).

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

401Non sono state inviate credenziali (né un cookie di sessione né una chiave API), oppure la chiave non è stata trovata.

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

403L’azione non è consentita: il ruolo non è sufficiente, manca l’accesso alla raccolta o alla scheda, la richiesta viene eseguita in modalità “View as”, oppure l’organizzazione è sospesa o eliminata (`detail` è un oggetto con `code: org_suspended | org_deleted`).

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

404L’oggetto non esiste o non è disponibile per te. L’API non conferma l’esistenza di un oggetto con accesso limitato.

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

422Errore di validazione: il corpo o i parametri non corrispondono allo schema (`detail` è un elenco di errori di validazione), oppure il valore di un parametro è fuori dall’intervallo ammesso (`detail` è un messaggio).

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

429Troppe richieste (`api.rate_limited`), la quota dell’organizzazione per il minuto, il giorno o il mese è esaurita (`api.quota_exceeded`; `error.details` contiene `quota`, `limit` e `reset_at`), è stato raggiunto il limite dell’organizzazione, oppure il servizio delle risposte è occupato (`answers.engine_busy`). Attendi il tempo indicato nell’intestazione `Retry-After`.

Intestazioni della risposta

Retry-After
Numero di secondi da attendere prima di ripetere la richiesta.
RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

Codici di errore

Codici che questo endpoint può restituire in error.code, oltre ai codici generali di ogni richiesta.

Limiti di frequenza

Le risposte contengono le intestazioni RateLimit e RateLimit-Policy e le precedenti X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Una risposta 429 contiene Retry-After in secondi: attendi e riprova.

← cards · Riferimento API

curl 'https://api.sursa.com/v1/cards-by-external-id/EXTERNAL_ID' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Prova

Chiave API

La chiave resta nella memoria di questa scheda del browser e viene inviata solo a https://api.sursa.com.

Le richieste vengono eseguite sui dati reali della tua organizzazione.

X-View-As header

external_id path *

expand[] query