Pular para o conteúdo
Sursa Developers

GET/v1/cards

Listar cartões

list_cards

Retorna cartões com filtros, ordenação e paginação. Com preview=1 (para a visualização em blocos), cada cartão também tem preview (os primeiros 200 caracteres do texto) e preview_tables (planilhas com o número de linhas de cada uma), dentro do seu perfil de dados.

Autenticação

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

Parâmetros de consulta

  • collectionstring | null
  • folderstring | null

    <folder ID> retorna os cartões da pasta e de todas as subpastas dela. none retorna os cartões da coleção que não estão em nenhuma pasta e exige collection (caso contrário, 400 cards.invalid_folder_filter). Se a pasta não existir ou não estiver visível para você, a requisição retorna 404 folders.not_found.

    length ≤ 64

  • statusstring | null

    Valores permitidos: processingreadyerrorarchivedall

  • ownerstring | null

    me, none ou o ID de um usuário.

  • owner_idinteger | null
  • verificationstring | null

    Valores permitidos: verifiedneeds_verificationstale

  • kindCardKind
  • typestring | null

    table retorna cartões com tabelas de fatos, text retorna cartões sem elas.

    Valores permitidos: tabletext

  • tagsstring | null

    Etiquetas separadas por vírgula (o cartão precisa ter todas).

  • idsstring | null

    IDs de cartões separados por vírgula.

  • searchstring | null
  • categorystring | null
  • sensitiveboolean | null
  • sortCardSort

    Padrão: "created_at"

  • orderstring

    Valores permitidos: ascdesc

    Padrão: "desc"

  • limitinteger

    Padrão: 200

  • offsetinteger

    Padrão: 0

  • previewboolean

    true acrescenta preview (os primeiros 200 caracteres) e preview_tables para a visualização em blocos.

    Padrão: false

  • updated_sincestring (date-time)

    Só cartões com updated_at igual ou posterior a este momento (RFC 3339 com deslocamento de fuso horário), para sincronização. Sem sort e order explícitos, a lista é ordenada por updated_at em ordem crescente e depois por id. Cartões excluídos não aparecem na lista: as exclusões chegam como eventos.

  • metadatamap of string

    Filtro por metadata: metadata[<key>]=<value> corresponde exatamente. Até 3 condições, e todas precisam ser atendidas (?metadata[team]=support&metadata[crm_id]=A-1042). Mais de 3 condições ou uma chave inválida retornam 400 api.metadata_invalid.

  • collection_idinteger

    Coleção por ID. Quando collection também é enviado, prevalece collection_id. Uma coleção que não existe na organização ou não está visível retorna 404 collections.not_found.

  • external_idstring

    Só o cartão com este external_id.

  • cursorstring

    Cursor da próxima página, vindo de X-Next-Cursor ou de next_cursor da resposta anterior com os mesmos filtros; ele carrega o tamanho da página. Junto com offset: 422 validation.failed; um cursor de outra lista, de outros filtros ou malformado: 400 api.cursor_invalid.

    length ≤ 512

  • expand[]array of string

    Objetos relacionados a incluir na resposta (desde a versão 1.62.0): um caminho da lista x-expandable da operação. Repita o parâmetro até 10 vezes. Um caminho tem até 2 segmentos separados por ponto (collection.default_owner). Em uma lista, o caminho começa com data. e vale para cada item da página (expand[]=data.owner). Um objeto expandido vai para o objeto expanded do item, e o campo de ID continua no lugar. Um objeto que quem faz a chamada não pode ver pelas conferências da própria operação de leitura dele é expandido como null. Um caminho desconhecido, mais de 10 caminhos ou um caminho com mais de 2 segmentos retornam 400 api.expand_invalid.

    items ≤ 10

Parâmetros de cabeçalho

  • 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.

Respostas

200Resposta bem-sucedida

Cabeçalhos da resposta

  • Link

    Endereço da próxima página, <…>; rel="next". Sem o cabeçalho, esta é a última página.

  • X-Next-Cursor

    Cursor da próxima página para o parâmetro cursor. Sem o cabeçalho, esta é a última página.

  • 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: CardList

array of 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.

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