PATCH/v1/cards/{card_id}

Atualizar um cartão

update_card

Autenticação

Envie uma chave de API no cabeçalho Authorization: Authorization: Bearer <chave>.

Parâmetros de caminho

card_idstringobrigatório

Parâmetros de cabeçalho

Idempotency-Keystring
Chave para uma nova tentativa segura de uma gravação: de 1 a 255 caracteres ASCII imprimíveis; recomenda-se um UUID v4 por operação lógica. Uma nova tentativa com a mesma chave dentro de 24 horas não executa a operação de novo: retorna a resposta salva (status, cabeçalhos e corpo) com o cabeçalho Idempotency-Replayed: true. A mesma chave com outro método, caminho, Content-Type ou corpo retorna 409 api.idempotency_mismatch; enquanto a primeira requisição ainda está em execução, 409 api.idempotency_in_progress com Retry-After: 1. Depois de uma resposta 5xx ou 429, a chave é liberada, e uma nova tentativa executa a operação de novo. A chave vale para a organização e para quem faz a chamada (chave de API, usuário ou chave de fonte personalizada).
length ≥ 1, length ≤ 255
X-View-Asstring
Só para chaves de API com a função admin. Faz a requisição como o perfil de dados <profile>[:viewer|verifier|editor], por exemplo, employee:viewer. A chave de instalação não pode usar este cabeçalho (403).

Parâmetros de cookie

kb_view_asstring
Cookie do modo “View as” (ver a base como um perfil de dados a vê) de uma sessão. POST /auth/view-as o define e DELETE /auth/view-as o remove.

Corpo da requisição

application/json

Objeto: CardUpdate

external_idstring | null
Define ou altera o external_id do cartão; "" ou null o remove. Se outro cartão da organização o usar, a requisição retorna 409 cards.external_id_taken. O external_id de um cartão de uma fonte não muda (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

Respostas

200Resposta bem-sucedida

Cabeçalhos da resposta

RateLimit-Policy
Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.
RateLimit
O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).
X-RateLimit-Remaining
Requisições restantes no limite mais restritivo.
X-RateLimit-Reset
Segundos até o limite mais restritivo ser reiniciado.
Idempotency-Replayed
true significa que a resposta foi reproduzida a partir da resposta salva para esta Idempotency-Key: a operação não foi executada de novo.

application/json

Objeto: Card

expandedCardExpanded
permissionsObjectPermissionList
accessstring
Valores permitidos: wholepartial
access_contactstring
A quem pedir acesso (só quando access=partial).
aclobject
Campos
- verifybooleanobrigatório
- writebooleanobrigatório
categorystringobrigatório
category_confidencenumber | nullobrigatório
category_lockedbooleanobrigatório
category_reviewbooleanobrigatório
category_sourceCategorySource | nullobrigatório
collectionstringobrigatório
collection_idintegerobrigatório
collection_titlestring
commentsarray of CardComment
content_jsonContentJSON | null
Conteúdo do editor da última versão publicada. O campo pode estar ausente; nesse caso, obtenha o conteúdo do editor a partir de um rascunho (POST /v1/drafts com card_id).
editing_lockEditingLock | null
Bloqueio de edição ativo. O campo pode estar ausente; nesse caso, o editor descobre quem tem o bloqueio pelo 409 cards.locked em POST /v1/cards/{card_id}/lock.
created_atstring (date-time)obrigatório
days_since_verifiedintegerobrigatório
errorstring | nullobrigatório
eventsarray of CardEvent
feedback_negintegerobrigatório
feedback_posintegerobrigatório
foldersarray of CardFolderRef
Só na lista de cartões: as pastas que contêm o cartão (as visíveis para o usuário), com os caminhos a partir da raiz da coleção. Uma lista vazia significa que o cartão não está em nenhuma pasta.
has_tablesboolean
Só na lista de cartões.
hidden_partsboolean
idstringobrigatório
jobJob | null
kindCardKindobrigatório
org_idintegerobrigatório
owner_activeboolean | null
owner_idinteger | nullobrigatório
owner_namestring | nullobrigatório
pagesinteger | nullobrigatório
parserstring | nullobrigatório
Analisador do documento como código neutro: document (estrutura completa: páginas, títulos, tabelas, páginas digitalizadas), pdf (a camada de texto do PDF), docx, xlsx, csv, markdown, html, text. A lista pode crescer.
partsarray of CardPartobrigatório
sensitivebooleanobrigatório
sha256string | nullobrigatório
sizeintegerobrigatório
snoozed_atstring (date-time) | null
snoozed_byinteger | null
snoozed_untilstring | null
source_changedbooleanobrigatório
source_pathstring | nullobrigatório
source_urlstring | nullobrigatório
statusstringobrigatório
Valores permitidos: processingreadyerrorarchived
tablesarray of CardTable
tagsarray of stringobrigatório
titlestringobrigatório
trustnumberobrigatório
trust_if_verifiednumber
trust_partsTrustPartsobrigatório
updated_atstring (date-time)obrigatório
verificationVerificationobrigatório
verified_atstring (date-time) | nullobrigatório
verified_byinteger | nullobrigatório
verified_by_namestring | null
verifier_idsarray of integerobrigatório
verifiersarray of object
Campos
- activebooleanobrigatório
- idintegerobrigatório
- namestringobrigatório
verify_interval_daysintegerobrigatório
versionintegerobrigatório
versionsarray of CardVersion
source_archiveArchiveSource
created_byinteger | null
manual_optionsobject
Configurações manuais da análise do documento (prévia).
doc_kindDocKind | null
Tipo de documento. null se o tipo não foi determinado (por exemplo, nos cartões indexados antes da introdução dos tipos de documento).
doc_kind_confidencenumber | null
Grau de certeza do tipo de documento, de 0 a 1.
doc_kind_sourcestring | null
O que determinou o tipo: regras (rules), um usuário (manual) ou a classificação automática. A lista pode crescer: trate um valor desconhecido como classificação automática.
Valores permitidos: rulesmanualnull
invoiceDocInvoiceExtraction | null
Campos de uma fatura, nota de crédito ou recibo (só nesses tipos, e só no cartão, não na lista). null se você não tem acesso ao documento inteiro, porque os campos são extraídos do documento inteiro.
warningsarray of ReviewWarning
Avisos da análise do documento (ReviewWarning; só no cartão, não na lista).
enrichmentCardEnrichmentStatus | null
Status do enriquecimento (só no cartão, não na lista). O tipo de documento, os campos da fatura e os registros financeiros são acrescentados em segundo plano após a indexação e podem ser recalculados depois; eles aparecem no cartão quando ficam prontos. null significa que não há status disponível (o cartão foi indexado sem enriquecimento em segundo plano).
external_idstring | null
ID do cartão no sistema do integrador. É único na organização entre os cartões que não vêm de fontes; null significa que não está definido. /v1/cards-by-external-id/{external_id} lê e substitui o cartão por ele.
length ≤ 512
metadataMetadata

400A requisição é inválida: o valor de um parâmetro ou o estado do objeto não permite a ação (`detail` é uma mensagem).

Cabeçalhos da resposta

RateLimit-Policy
Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.
RateLimit
O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).
X-RateLimit-Remaining
Requisições restantes no limite mais restritivo.
X-RateLimit-Reset
Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: Error

401Nenhuma credencial foi enviada (nem cookie de sessão nem chave de API), ou a chave não foi encontrada.

Cabeçalhos da resposta

RateLimit-Policy
Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.
RateLimit
O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).
X-RateLimit-Remaining
Requisições restantes no limite mais restritivo.
X-RateLimit-Reset
Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: Error

403A ação não é permitida: a função é insuficiente, não há acesso à coleção ou ao cartão, a requisição é executada no modo “View as” ou a organização está suspensa ou excluída (`detail` é um objeto com `code: org_suspended | org_deleted`).

Cabeçalhos da resposta

RateLimit-Policy
Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.
RateLimit
O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).
X-RateLimit-Remaining
Requisições restantes no limite mais restritivo.
X-RateLimit-Reset
Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: Error

404O objeto não existe ou não está disponível para você. A API não confirma que um objeto restrito existe.

Cabeçalhos da resposta

RateLimit-Policy
Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.
RateLimit
O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).
X-RateLimit-Remaining
Requisições restantes no limite mais restritivo.
X-RateLimit-Reset
Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: Error

422Erro de validação: o corpo ou os parâmetros não correspondem ao esquema (`detail` é uma lista de erros de validação), ou o valor de um parâmetro está fora do intervalo (`detail` é uma mensagem).

Cabeçalhos da resposta

RateLimit-Policy
Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.
RateLimit
O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).
X-RateLimit-Remaining
Requisições restantes no limite mais restritivo.
X-RateLimit-Reset
Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: Error

429Requisições demais (`api.rate_limited`), a cota da organização para o minuto, o dia ou o mês se esgotou (`api.quota_exceeded`; `error.details` contém `quota`, `limit` e `reset_at`), o limite da organização foi atingido ou o serviço de respostas está ocupado (`answers.engine_busy`). Aguarde o tempo indicado no cabeçalho `Retry-After`.

Cabeçalhos da resposta

Retry-After
Número de segundos a esperar antes de tentar a requisição novamente.
RateLimit-Policy
Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.
RateLimit
O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).
X-RateLimit-Remaining
Requisições restantes no limite mais restritivo.
X-RateLimit-Reset
Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: Error

Códigos de erro

Códigos que este endpoint pode retornar em error.code, além dos códigos gerais de qualquer requisição.

Novas tentativas seguras

Envie um cabeçalho Idempotency-Key (por exemplo, um UUID) em cada POST e PATCH. Uma nova tentativa com a mesma chave em até 24 horas retorna a resposta salva, em vez de executar a requisição de novo.

Limites de taxa

As respostas trazem os cabeçalhos RateLimit e RateLimit-Policy e os anteriores X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Uma resposta 429 traz Retry-After em segundos: aguarde e tente de novo.

← cards · Referência da API

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"

Testar

Chave de API

A chave fica na memória desta aba e é enviada só para https://api.sursa.com.

As requisições atuam sobre os dados reais da sua organização.

Idempotency-Key header

X-View-As header

card_id path *

Idempotency-Key

Com o campo vazio, uma nova chave é gerada para cada requisição.

Corpo da requisição (JSON)