Pular para o conteúdo
Sursa Developers

POST/v1/finance/report

Obter um relatório financeiro resumido

finance_report

Retorna os totais das faturas ou dos pagamentos da organização, agrupados por até três dimensões (categoria, grupo, tipo de atividade do fornecedor, fornecedor, comprador, contraparte, direção, moeda, mês, trimestre, ano), com as medidas invoiced, paid, unpaid e tax. Os totais incluem só os documentos visíveis para o usuário (as coleções e as categorias do perfil de dados dele e a configuração “responder só com cartões verificados”); os filtros da requisição restringem essa abrangência, mas nunca a ampliam.

No modo reporting (padrão), os valores são convertidos para a moeda dos relatórios da organização pela taxa da data do documento, e os valores sem taxa são listados em conversion.unconverted. No modo original, os valores em moedas diferentes não são somados, e a moeda passa a ser uma dimensão da linha. Se houver mais linhas que limit, truncated é true, e totals continua cobrindo todas as linhas. Exige um perfil de dados com acesso aos dados financeiros (finance.forbidden).

O relatório, as listas de faturas e de pagamentos e as exportações deles são operações de leitura, embora usem POST: estão disponíveis no modo “View as” e para chaves de API com o escopo read (e, como antes, para chaves com o escopo write).

Autenticação

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

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.

Corpo da requisição

application/json

Objeto: FinanceReportRequest

  • basisstring

    invoices: faturas, notas de crédito e recibos. payments: o registro de pagamentos (fluxo de caixa). Com payments, a única medida é paid, e a dimensão direction e o total mostram o movimento do dinheiro, in ou out, enquanto uma transferência entre suas próprias pessoas jurídicas é internal.

    Valores permitidos: invoicespayments

    Padrão: "invoices"

  • group_byarray of FinanceDimension

    items ≤ 3

  • measuresarray of FinanceMeasure

    Padrão: invoiced (paid para payments).

  • currency_modeFinanceCurrencyMode
  • date_basisstring

    Qual data define o período e o filtro from/to: a data do documento ou a data do pagamento.

    Valores permitidos: documentpayment

    Padrão: "document"

  • filtersFinanceFilter
  • order_bystring

    Medida ou dimensão usada na ordenação. Por padrão, a primeira medida em ordem decrescente.

  • order_descboolean

    Padrão: true

  • limitinteger

    Padrão: 1000≥ 1, ≤ 10000

  • languagestring

    Idioma dos rótulos de categorias e grupos, en|ru. Padrão: en.

Respostas

200O relatório

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: FinanceReport

  • currency_modeFinanceCurrencyModeobrigatório
  • currencystring

    Moeda dos relatórios (modo reporting).

  • rowsarray of FinanceReportRowobrigatório
  • totalsarray of FinanceReportTotalobrigatório

    Totais de todas as linhas antes do corte, um item por moeda (em um relatório dividido por direção, por moeda e direção, FinanceReportTotal.direction).

  • truncatedbooleanobrigatório
  • limitintegerobrigatório
  • total_rowsintegerobrigatório

    Número de linhas agrupadas antes do corte.

  • conversionFinanceConversion
  • warningsarray of string

    Códigos de aviso: profile_missing, os dados da empresa da organização não estão preenchidos, por isso a direção das faturas é in por padrão; catalog_missing, o cadastro de empresas não está carregado; fx_rate_missing, alguns valores não têm taxa de câmbio (conversion.unconverted); fx_rate_stale, algumas taxas estão desatualizadas; enrichment_pending, alguns documentos ainda estão sendo processados e não entram nos totais. Mostre um código desconhecido com uma mensagem genérica.

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

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

503Um serviço do qual esta requisição depende está temporariamente indisponível. Tente novamente mais tarde.

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

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.

← finance · Referência da API