Documentação da API Belvo (1.221.0)

Introdução

Alcance novos públicos e converta mais usuários conectando-se fácil e seguramente aos dados financeiros deles, entendendo seu comportamento e possibilitando pagamentos instantâneos com open finance. Através da nossa API, você pode acessar:

Informações Disponíveis e Métodos de Pagamento

A Belvo é uma API de open banking para a América Latina que permite que empresas acessem informações bancárias e fiscais de maneira segura e ágil.

Através da nossa API, você pode acessar:

  • Informações Bancárias no Brasil
  • Informações de Emprego no Brasil
  • Informações de Emprego no México
  • Informações Fiscais no México
  • Informações Fiscais no Chile

Você também pode usar nossa API para realizar pagamentos em:

  • Brasil
  • México

Dicionários de Dados

Se você deseja a documentação de resposta em formato Excel ou CSV, por favor, faça o download a partir do nosso Repositório Público no GitHub: Belvo Open Finance Data Dictionaries.

Nossos arquivos EXCEL e CSV estão adicionalmente localizados em Espanhol e Português (Brasil).

Ambientes

Atualmente, oferecemos dois ambientes: sandbox e produção.

Sandbox

Disponível para:

  • 🟢 Agregação e Enriquecimento
  • ⚪️ Iniciação de Pagamento

Use nosso ambiente Sandbox para construir sua integração. Oferecemos dados fictícios que imitam casos de uso do mundo real, o que significa que você pode testar todos os endpoints, usar o widget e implementar webhooks - exatamente como faria com dados reais!

Tudo o que você precisa para começar com o ambiente Sandbox é obter suas chaves de API. Recomendamos fortemente que você comece a criar sua integração neste ambiente.

Produção

Disponível para:

  • 🟢 Agregação e Enriquecimento
  • 🟢 Iniciação de Pagamento

Depois de testar sua integração no ambiente Sandbox e estar pronto para entrar em operação, você precisará solicitar acesso ao nosso ambiente de Produção. Após solicitar o acesso, nossa equipe de Vendas entrará em contato para agendar uma reunião apenas para garantir que suas necessidades sejam atendidas, e então você precisará passar por um processo de certificação com um de nossos engenheiros para garantir que sua integração esteja funcionando de forma otimizada. Para se preparar para a reunião de certificação, basta seguir nossa lista de verificação de Integração.

Uma vez que sua integração esteja certificada, tudo o que você precisará fazer é:

  • Solicitar chaves de API de Produção (e alterar suas chaves de API do Sandbox no código para estas novas).
  • Alterar a URL base para a qual você faz solicitações de sandbox.belvo.com para api.belvo.com.
  • Se você estiver usando webhooks, certifique-se de definir uma URL de Produção para seus webhooks.

Códigos de Resposta

Usamos o seguinte código de status HTTP na resposta, dependendo do sucesso ou falha:

Código de StatusDescrição
200Sucesso - O conteúdo está disponível no corpo da resposta.
201Sucesso - O conteúdo foi criado com sucesso na Belvo.
204Sucesso - Nenhum conteúdo para retornar.
400Erro de Solicitação Inválida - A solicitação retornou um erro, detalhe no conteúdo.
401Não Autorizado - As credenciais da Belvo fornecidas não são válidas.
404Não Encontrado - O recurso que você tentou acessar não pode ser encontrado.
405Método Não Permitido - O método HTTP que você está usando não é aceito para este recurso.
408Tempo de Solicitação Esgotado - A solicitação expirou e foi encerrada pelo servidor.
428Token MFA Necessário - O token MFA foi exigido pela instituição para conectar.
500Erro Interno do Servidor - O detalhe do erro está disponível no corpo da resposta.

Tratamento de Erros

Os erros da API Belvo são retornados em formato JSON. Por exemplo, um erro pode ser assim:

[
    {
      "request_id": "a6e1c493d7a29d91aed4338e6fcf077d",
      "message": "Este campo é obrigatório.",
      "code": "required",
      "field": "link"
    }
]

Normalmente, uma resposta de erro terá os seguintes parâmetros:

  • request_id: um ID único para a solicitação, você deve compartilhá-lo com a equipe de suporte da Belvo para investigações.
  • message: descrição legível do erro.
  • code: um código único para o erro. Verifique a tabela abaixo para ver como lidar com cada código de erro.
  • field (opcional): O campo específico no corpo da solicitação que tem um problema.

Identificador de Solicitação

Quando você precisar de ajuda com um erro específico, inclua o identificador de solicitação (request_id) em sua mensagem para a equipe de suporte da Belvo. Isso acelerará as investigações e fará com que você volte a funcionar rapidamente.

Códigos de Erro e Solução de Problemas

Para uma lista completa de erros e como solucioná-los, consulte nosso artigo dedicado Tratamento de Erros.

Política de Repetição

Erros 50x

Implemente uma repetição automática exponencial de até cinco tentativas. Recomendamos usar um intervalo base de três segundos com um fator de dois. Por exemplo, a primeira repetição deve ser após três segundos, a segunda repetição após seis segundos (2 * 3), a terceira repetição após 12 segundos (2 * 6), a quarta repetição após 24 segundos (2 * 12) e a quinta repetição após 48 segundos (2 * 24).

Erros 40x

Você não deve tentar novamente fazer solicitações se receber uma resposta 40x, pois isso é um erro do cliente.

A única exceção é o erro "Muitas Sessões", pois isso significa que seu usuário final está acessando a conta de outro navegador ao mesmo tempo. Nesse caso, implemente a mesma política de repetição que para erros 50x.

Campos Obsoletos

Em nosso esquema, você pode ver que um campo foi marcado como deprecated. Isso significa que este campo não é mais mantido pela equipe da Belvo. Você ainda pode receber dados para este campo dependendo da instituição, no entanto, você não deve confiar neste campo.

OpenAPI: campos obrigatórios e anuláveis

Em nossa especificação de API, você verá que alguns parâmetros de resposta terão uma anotação required. De acordo com a especificação OpenAPI, quando um parâmetro de resposta é marcado como required, isso significa que a chave de resposta deve ser retornada. No entanto, o valor desse parâmetro de resposta pode ser null.

📘 Informação

Em resumo, qualquer parâmetro de resposta marcado como obrigatório será retornado pela nossa API, mas o valor pode ser definido como nulo.

Baixar o arquivo de descrição OpenAPI
Idiomas
Servidores
Mock server

https://developers.belvo.com/_mock/pt-br/apis/belvoopenapispec/

Ambiente de Testes

https://sandbox.belvo.com/

Institutions

Uma instituição é uma entidade da qual a Belvo pode acessar informações. Pode ser uma:

  • instituição bancária, como o Nubank Brasil.
  • instituição fiscal, como o Servicio de Administración Tributaria (SAT) no México.
  • instituição de emprego, como o Instituto Mexicano del Seguro Social (IMSS) no México ou o Instituto Nacional do Seguro Social (INSS) no Brasil.
Operações

Widget Access Token

Operações

Consents

Um consentimento é uma permissão dada pelo usuário final para acessar seus dados financeiros na Rede de Open Finance no Brasil.

Operações

Owners

Um proprietário representa a pessoa que tem acesso a um Link e é o proprietário de todas as contas dentro do Link.

Você pode usar este endpoint para obter informações úteis sobre seu cliente, como:

  • seu nome completo
  • informações de contato principais
  • informações sobre o documento de identidade que usaram ao abrir a conta
Operações

Accounts

Uma conta é a representação de uma conta bancária dentro de uma instituição financeira. Um usuário pode ter uma ou mais contas em uma instituição.

Por exemplo, um usuário (ou link) pode ter uma conta corrente, vários cartões de crédito e uma conta de empréstimo.

Consultar as informações da conta de um usuário é útil, pois você pode obter informações sobre:

  • quais tipos de contas o usuário possui.
  • o saldo de cada conta (poupança, corrente, cartão de crédito, empréstimo, etc.).
  • informações detalhadas sobre os gastos com cartão de crédito.
  • a situação atual de quaisquer empréstimos que possam ter.
Operações

Balances

Um saldo é a quantidade de dinheiro disponível em uma determinada conta bancária (corrente ou poupança) em um determinado momento.

Operações

Transactions

Uma transação contém as informações detalhadas de cada movimento dentro de uma conta. Por exemplo, uma compra em uma loja ou em um restaurante.

Operações

Bills

Uma bill refere-se à fatura do cartão de crédito que um usuário recebe para uma determinada conta.

Operações

Investments Brazil

Operações

Investment Transactions Brazil

Operações

Employments Brazil

Nosso recurso de empregos para o Brasil permite que você obtenha uma visão abrangente do histórico de emprego atual e das informações salariais do seu usuário.

Para cada usuário, nós retornamos:

  • histórico de trabalho (incluindo ocupações e dados do empregador)
  • informações salariais históricas e atuais (por empregador)

No momento, o recurso de empregos está disponível para:

  • 🇧🇷 Brasil (INSS)
Operações

Employment Records Mexico

Nosso recurso de registros de emprego para o México permite que você obtenha uma visão abrangente das contribuições atuais para a seguridade social e do histórico de emprego do seu usuário.

Com o recurso de registros de emprego da Belvo para o México, você pode acessar informações sobre as contribuições atuais para a seguridade social e o histórico de emprego do seu usuário. Para cada usuário, retornamos:

  • dados pessoais
  • histórico de trabalho
  • salário base diário histórico e atual
  • e mais!

No momento, o recurso de registros de emprego está disponível para:

  • 🇲🇽 México (IMSS)
  • 🇲🇽 México (ISSSTE)
Operações

Invoices

Operações

Objeto de Faturas (México)

idstring(uuid)

Identificador único da Belvo para o item atual.

Exemplo: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"
linkstring or null(uuid)

O link.id ao qual os dados pertencem.

Exemplo: "30cb4806-6e00-48a4-91c9-ca55968576c8"
collected_atstring(date-time)obrigatório

O carimbo de data/hora ISO-8601 quando o ponto de dados foi coletado.

Exemplo: "2022-02-09T08:45:50.406032Z"
created_atstring(date-time)

O carimbo de data e hora ISO-8601 de quando o ponto de dados foi criado no banco de dados da Belvo.

Exemplo: "2022-02-09T08:45:50.406032Z"
invoice_identificationstring or nullobrigatório

O ID único da instituição fiscal para a fatura.

Exemplo: "A1A1A1A1-2B2B-3C33-D44D-555555E55EE"
invoice_datestring or nullobrigatório

A data da fatura, no formato YYYY-MM-DD.

Exemplo: "2019-12-01"
statusstring or nullobrigatório

O status da fatura. Pode ser Vigente (válido) ou Cancelado (cancelado).

Exemplo: "Vigente"
invoice_typestring or nullobrigatório

A classificação da fatura pela instituição fiscal.

Para o SAT do México, retornamos um dos seguintes valores:

  • Egreso
  • Ingreso
  • Nómina
  • Pago
  • Traslado
Enum"Egreso""Ingreso""Nómina""Pago""Traslado"
Exemplo: "Ingreso"
typestring or nullobrigatório

A direção da fatura (do ponto de vista do proprietário do Link).

  • OUTFLOW indica uma fatura enviada.
  • INFLOW indica uma fatura recebida.
Enum"OUTFLOW""INFLOW"null
Exemplo: "INFLOW"
tax_detailsobject

Informações gerais sobre os impostos da fatura.

sender_idstring or nullobrigatório

O ID fiscal do remetente da fatura

Exemplo: "AAA111111AA11"
sender_fiscal_regimestring or null

O regime tributário do remetente, conforme definido pela pessoa jurídica no país.

Exemplo: "601"
sender_namestring or nullobrigatório

O nome do remetente da fatura.

Exemplo: "ACME CORP"
sender_tax_fraud_statusstring or null

Indica se o remetente está ou não na lista de fraude fiscal do SAT por ter enviado dados incorretos, ter pagamentos pendentes ou ter realizado negócios que violam os regulamentos da instituição fiscal.

O SAT atualiza a lista de fraude fiscal a cada três meses.

Para mais informações sobre os motivos pelos quais um contribuinte pode ser incluído na lista de fraude fiscal, consulte o Artigo 69 e o Artigo 69-B do Código Fiscal da Federação do México.

Os status possíveis são:

  • INVESTIGATING
    A instituição fiscal identificou irregularidades e abriu uma investigação sobre o contribuinte.
  • DISMISSED
    A instituição fiscal investigou o contribuinte e o declarou inocente.
  • CONFIRMED
    A instituição fiscal confirmou que o contribuinte é culpado.
  • OVERTURNED
    A instituição fiscal reavaliou um contribuinte previamente confirmado e, com base em novas evidências, retirou o contribuinte da lista de fraude fiscal.
  • NO_TAX_FRAUD_STATUS
    O receptor ou remetente não é encontrado na lista (ou seja, está em conformidade com os regulamentos da instituição fiscal).
Exemplo: "NO_TAX_FRAUD_STATUS"
receiver_idstring or nullobrigatório

O ID fiscal do destinatário da fatura.

Exemplo: "BBB222222BB22"
receiver_postal_codestring

O código postal do destinatário.

Exemplo: "11560"
receiver_fiscal_regimestring or null

O regime tributário do recebedor, conforme definido pela pessoa jurídica no país.

Exemplo: "601"
receiver_namestring or nullobrigatório

O nome do destinatário da fatura.

Exemplo: "BELVO CORP"
receiver_tax_fraud_statusstring or null

Indica se o destinatário está ou não na lista de fraude fiscal do SAT por ter enviado dados incorretos, ter pagamentos pendentes ou ter realizado negócios que violam os regulamentos da instituição fiscal.

O SAT atualiza a lista de fraude fiscal a cada três meses.

Para mais informações sobre os motivos pelos quais um contribuinte pode ser incluído na lista de fraude fiscal, consulte o Artigo 69 e o Artigo 69-B do Código Fiscal da Federação do México.

Os status possíveis são:

  • INVESTIGATING
    A instituição fiscal identificou irregularidades e abriu uma investigação sobre o contribuinte.
  • DISMISSED
    A instituição fiscal investigou o contribuinte e o declarou inocente.
  • CONFIRMED
    A instituição fiscal confirmou que o contribuinte é culpado.
  • OVERTURNED
    A instituição fiscal reavaliou um contribuinte previamente confirmado e, com base em novas evidências, retirou o contribuinte da lista de fraude fiscal.
  • NO_TAX_FRAUD_STATUS
    O destinatário ou remetente não é encontrado na lista (ou seja, está em conformidade com os regulamentos da instituição fiscal).
Exemplo: "NO_TAX_FRAUD_STATUS"
cancelation_statusstring or nullobrigatório

Se a fatura for cancelada, este campo indica o status do cancelamento.

cancelation_update_datestring or null(date)obrigatório

A data do cancelamento da fatura, no formato YYYY-MM-DD.

Exemplo: "2019-12-02"
certification_datestring or null(date)obrigatório

A data da certificação fiscal, no formato YYYY-MM-DD.

Exemplo: "2019-12-01"
certification_authoritystring or nullobrigatório

O ID fiscal do provedor de certificação.

Exemplo: "CCC333333CC33"
payment_typestring or nullobrigatório

O código do tipo de pagamento usado para esta fatura, conforme definido pela entidade legal do país.

Exemplo: "99"
payment_methodstring or null

O código do método de pagamento usado para esta fatura, conforme definido pela entidade legal do país.

Enum"PUE""PPD"null
Exemplo: "PUE"
usagestring or null

O código de uso da fatura, conforme definido pela entidade legal do país.

Exemplo: "P01"
versionstring or null

A versão CFDI da fatura.

Exemplo: "3.3"
place_of_issuestring or null

O código postal de onde a fatura foi emitida.

Exemplo: "01165"
invoice_detailsArray of objectsobrigatório

Uma lista de descrições para cada item (produto comprado ou serviço prestado) na fatura.

collected_atstring(date-time)

O carimbo de data/hora ISO-8601 quando o ponto de dados foi coletado.

Exemplo: "2022-02-09T08:45:50.406032Z"
descriptionstring or nullobrigatório

A descrição do item da fatura (uma fatura pode ter um ou mais itens).

Exemplo: "December 2019 accounting fees"
product_identificationstring or nullobrigatório

O código de identificação do produto ou serviço, conforme definido pela entidade legal no país.\n- \U0001F1F2\U0001F1FD México.

Exemplo: "84101600"
quantitynumber or null(float)obrigatório

A quantidade deste item da fatura.

Exemplo: 10
unit_codestring or nullobrigatório

A unidade de medida, conforme definida pela entidade legal no país. \n- \U0001F1F2\U0001F1FD México referência do catálogo SAT.

Exemplo: "E48"
unit_descriptionstring or nullobrigatório

A descrição do item, conforme definido pela entidade legal no país.\n- \U0001F1F2\U0001F1FD México referência do catálogo SAT.

Exemplo: "Unidad de servicio"
unit_amountnumber or null(float)obrigatório

O preço de um único item.

Exemplo: 200
tax_typestring or null

O tipo de imposto do item.

Exemplo: null
pre_tax_amountnumber or null(float)obrigatório

O preço total deste item antes da aplicação de impostos é (quantity x unit_amount).

Exemplo: 400
tax_percentagenumber or null(float)obrigatório

A porcentagem de imposto a ser aplicada.

Exemplo: 16
tax_amountnumber or null(float)obrigatório

O valor do imposto para este item da fatura (pre_tax_amount x tax_percentage).

Exemplo: 64
total_amountnumber or null(float)obrigatório

O preço total para este item da fatura (pre_tax_amount + tax_amount).

Exemplo: 464
retained_taxesArray of objects

O imposto retido no item da fatura.

transferred_taxesArray of objects

Os impostos transferidos relacionados à fatura.

currencystring or nullobrigatório

A moeda da fatura. Por exemplo:

  • 🇧🇷 BRL (Real Brasileiro)
  • 🇨🇴 COP (Peso Colombiano)
  • 🇲🇽 MXN (Peso Mexicano)
  • 🇺🇸 USD (Dólar dos Estados Unidos)
Exemplo: "MXN"
subtotal_amountnumber or null(float)obrigatório

O valor antes dos impostos desta fatura (soma do pre_tax_amount de cada item).

Exemplo: 400
exchange_ratenumber or null(float)obrigatório

A taxa de câmbio utilizada nesta fatura para a moeda.

Exemplo: 0.052
tax_amountnumber or null(float)obrigatório

O valor do imposto para esta fatura (soma do tax_amount de cada item).

Exemplo: 64
discount_amountnumber or null(float)obrigatório

O valor total descontado nesta fatura.

Exemplo: 10
total_amountnumber or null(float)obrigatório

O valor total da fatura (subtotal_amount + tax_amount - discount_amount)

Exemplo: 454
related_invoicesArray of objects

Uma lista de faturas relacionadas.

paymentsArray of objectsobrigatório

Uma lista detalhando todos os pagamentos de faturas.

datestring or null(date-time)obrigatório

Carimbo de data/hora ISO-8601 quando o pagamento foi realizado.

Exemplo: "2020-03-17T12:00:00.000Z"
payment_typestring or nullobrigatório

Código do tipo de pagamento usado para esta fatura, conforme definido pela entidade legal do país.

Exemplo: "03"
currencystring or nullobrigatório

A moeda do pagamento. Por exemplo:

  • 🇧🇷 BRL (Real Brasileiro)
  • 🇨🇴 COP (Peso Colombiano)
  • 🇲🇽 MXN (Peso Mexicano)

Por favor, note que outras moedas além das listadas acima podem ser retornadas.

Exemplo: "BRL"
exchange_ratestring or nullobrigatório

A taxa de câmbio de currency para MXN no momento em que o pagamento foi realizado.

Exemplo: "3.75"
amountnumber or null(float)obrigatório

O valor da fatura, na moeda da fatura original.

Exemplo: 8000.5
operation_numberstring or nullobrigatório

O identificador interno da instituição fiscal para a operação.

Exemplo: "831840"
beneficiary_rfcstring or null

O ID fiscal do beneficiário do pagamento.

Exemplo: "BNM840515VB1"
beneficiary_account_numberstring or nullobrigatório

O número da conta bancária do beneficiário do pagamento.

Exemplo: "12343453245633"
payer_rfcstring or nullobrigatório

O ID fiscal do emissor do pagamento.

Exemplo: "BKJM840515VB1"
payer_account_numberstring or nullobrigatório

O número da conta bancária do emissor do pagamento.

Exemplo: "13343663245699"
payer_bank_namestring or nullobrigatório

A instituição bancária que foi utilizada pelo emissor do pagamento.

Exemplo: "CITI BANAMEX"
related_documentsArray of objectsobrigatório

Uma lista de todas as faturas diferidas relacionadas afetadas pelo pagamento.

invoice_identificationstring or nullobrigatório

O ID exclusivo da instituição fiscal para a fatura diferida relacionada.

Exemplo: "7EE015F3-6311-11EA-B02A-00155D014007"
currencystring or nullobrigatório

A moeda da fatura relacionada. Por exemplo:

  • 🇧🇷 BRL (Real Brasileiro)
  • 🇨🇴 COP (Peso Colombiano)
  • 🇲🇽 MXN (Peso Mexicano)

Por favor, note que outras moedas além das listadas acima podem ser retornadas.

Exemplo: "MXN"
payment_methodstring or nullobrigatório

O método de pagamento da fatura relacionada.

Exemplo: "PPD"
partiality_numberinteger(int32)

O número da parcela de pagamento.

Exemplo: 1
previous_balancenumber or null(float)obrigatório

O valor da fatura antes do pagamento.

Exemplo: 18877.84
amount_paidnumber or null(float)obrigatório

O valor pago nesta parcela.

Exemplo: 8000
outstanding_balancenumber or null(float)obrigatório

O valor restante a ser pago.

Exemplo: 10877.84
payrollobject or nullobrigatório

Detalhes sobre o pagamento da folha de pagamento. Aplicável apenas para faturas de folha de pagamento.

daysinteger or null(int32)obrigatório

O número de dias cobertos pelo pagamento.

Exemplo: 30
typestring or nullobrigatório

O tipo de folha de pagamento, conforme definido pela entidade legal do país.

Exemplo: "O"
amountnumber(float)obrigatório

O valor total do pagamento da folha de pagamento.

Exemplo: 20400.1
versionstringobrigatório

A versão do objeto de folha de pagamento.

Exemplo: "1.2"
date_fromstring or null(date)obrigatório

A data de início do período de pagamento, no formato YYYY-MM-DD.

Exemplo: "2018-07-01"
date_tostring or null(date)obrigatório

A data de término do período de pagamento, no formato YYYY-MM-DD.

Exemplo: "2018-07-31"
collected_atstring(date-time)

O carimbo de data/hora ISO-8601 quando o ponto de dados foi coletado.

Exemplo: "2022-02-09T08:45:50.406032Z"
payment_datestring(date)obrigatório

A data de pagamento, no formato YYYY-MM-DD.

Exemplo: "2018-07-16"
periodicitystring or null

Com que frequência o pagamento da folha de pagamento é realizado.

Para o SAT do México, retornamos um dos seguintes valores:

  • DAILY
  • WEEKLY
  • TENTH_DAY
  • FOURTEENTH_DAY
  • FIFTEENTH_DAY
  • MONTHLY
  • BIMONTHLY
  • PER_TASK
  • COMMISSION
  • ONE_OFF
  • OTHER_PERIODICITY
Enum"DAILY""WEEKLY""TENTH_DAY""FOURTEENTH_DAY""FIFTEENTH_DAY""MONTHLY""BIMONTHLY""PER_TASK""COMMISSION""ONE_OFF"
Exemplo: "MONTHLY"
earnings_breakdownArray of objects or null or null

Uma análise detalhada dos ganhos para o pagamento da folha de pagamento.

tax_deductionsArray of objects or null or null

Uma análise das deduções fiscais no pagamento da folha de pagamento.

other_paymentsArray of objects or null or null

Uma análise detalhada de outros pagamentos para a folha de pagamento.

foliostring or null

O número de controle interno que o contribuinte atribui à nota fiscal.

Exemplo: "26"
export_typestring or null

O tipo de exportação da fatura, conforme definido pela entidade legal no país. Para mais informações, consulte nosso artigo de referência do catálogo SAT.

Exemplo: "01"
xmlstring or null

XML do documento da fatura.

warningsobject or null

Objeto contendo informações sobre quaisquer avisos relacionados a esta fatura.

payment_type_descriptionstring or nullObsoletoobrigatório

Este campo foi descontinuado. Para mais informações sobre a Belvo e descontinuação, consulte nossa explicação sobre Campos descontinuados.

Exemplo: null
payment_method_descriptionstring or nullObsoleto

Este campo foi descontinuado. Para mais informações sobre a Belvo e descontinuação, consulte nossa explicação sobre Campos descontinuados.

A descrição do método de pagamento utilizado para esta fatura.

Exemplo: null
sender_blacklist_statusstring or nullObsoleto

Este campo foi descontinuado. Para mais informações sobre a Belvo e descontinuação, consulte nossa explicação sobre Campos descontinuados. Por favor, use sender_tax_fraud_status em vez disso.

Exemplo: null
receiver_blacklist_statusstring or nullObsoleto

Este campo foi descontinuado. Para mais informações sobre a Belvo e descontinuação, consulte nossa explicação sobre Campos descontinuados. Por favor, use receiver_tax_fraud_status em vez disso.

Exemplo: null
{ "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d", "link": "30cb4806-6e00-48a4-91c9-ca55968576c8", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:45:50.406032Z", "invoice_identification": "A1A1A1A1-2B2B-3C33-D44D-555555E55EE", "invoice_date": "2019-12-01", "status": "Vigente", "invoice_type": "Ingreso", "type": "INFLOW", "tax_details": { "total_tax_retained": 194.27, "total_tax_transferred": 150.4, "retained_taxes": [], "transferred_taxes": [] }, "sender_id": "AAA111111AA11", "sender_fiscal_regime": "601", "sender_name": "ACME CORP", "sender_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "receiver_id": "BBB222222BB22", "receiver_postal_code": "11560", "receiver_fiscal_regime": "601", "receiver_name": "BELVO CORP", "receiver_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "cancelation_status": "string", "cancelation_update_date": "2019-12-02", "certification_date": "2019-12-01", "certification_authority": "CCC333333CC33", "payment_type": "99", "payment_type_description": null, "payment_method": "PUE", "payment_method_description": null, "usage": "P01", "version": "3.3", "place_of_issue": "01165", "invoice_details": [ {} ], "currency": "MXN", "subtotal_amount": 400, "exchange_rate": 0.052, "tax_amount": 64, "discount_amount": 10, "total_amount": 454, "related_invoices": [ {} ], "payments": [ {} ], "payroll": { "days": 30, "type": "O", "amount": 20400.1, "version": "1.2", "date_from": "2018-07-01", "date_to": "2018-07-31", "collected_at": "2022-02-09T08:45:50.406032Z", "payment_date": "2018-07-16", "periodicity": "MONTHLY", "earnings_breakdown": [], "tax_deductions": [], "other_payments": [] }, "folio": "26", "export_type": "01", "xml": "string", "warnings": { "code": "sat_xml_limit_reached", "message": "The daily limit for XML downloads set by SAT was reached so this invoice\nmight be missing data. Please check https://tinyurl.com/yydzhy5d for more\ninformation on this error.\n" }, "sender_blacklist_status": null, "receiver_blacklist_status": null }

Listar faturas

Requisição

▶️ Uso

Com o método Listar Faturas, você pode:

  1. Listar faturas relacionadas a um link.id específico (usando o parâmetro de consulta link).
  2. Obter os detalhes de um invoice.id específico (usando o parâmetro de consulta id).
  3. [Não Recomendado] Listar todas as faturas relacionadas à sua conta Belvo (sem usar nenhum parâmetro de consulta).

📖 Paginação

Este método retorna uma resposta paginada (padrão: 100 itens por página). Você pode usar o parâmetro de consulta page_size para aumentar o número de itens retornados até um máximo de 1000 itens. Você pode usar o parâmetro de consulta page para navegar pelos resultados. Para mais detalhes sobre como navegar pelas respostas paginadas da Belvo, consulte nosso artigo Dicas de Paginação.

🔦 Filtrando Respostas

Consulte a lista de consultas abaixo para ver uma lista de campos pelos quais você pode filtrar suas respostas. Para mais informações sobre como usar filtros, veja nosso artigo Filtrando respostas.

🚨 Campos Obsoletos

Este recurso pode retornar campos obsoletos. Na documentação de resposta, você pode ver que um campo foi marcado como obsoleto. Isso significa que este campo não é mais mantido pela equipe da Belvo. Você ainda pode receber dados para este campo dependendo da instituição, no entanto, não deve confiar neste campo.

Security
basicAuth
Consulta
linkstring(uuid)

O link.id pelo qual você deseja filtrar.

ℹ️ Recomendamos fortemente adicionar o filtro link.id para melhorar seu desempenho.

Exemplo: link=8848bd0c-9c7e-4f53-a732-ec896b11d4c4
pageinteger(int32)>= 1

Um número de página dentro do conjunto de resultados paginados.

Exemplo: page=1
page_sizeinteger(int32)[ 1 .. 1000 ]

Indica quantos resultados retornar por página. Por padrão, retornamos 100 resultados por página.

ℹ️ O número mínimo de resultados retornados por página é 1 e o máximo é 1000. Se você inserir um valor maior que 1000, nossa API usará o valor máximo por padrão (1000).

Padrão 100
Exemplo: page_size=100
link__inArray of strings(uuid)

Retorne resultados apenas para esses link.ids.

Exemplo: link__in=5722d0ba-69d7-42dc-8ff5-33767b83c5d6
omitstring

Omitir certos campos de serem retornados na resposta. Para mais informações, consulte nosso artigo Filtrando respostas no DevPortal.

fieldsstring

Retorne apenas os campos especificados na resposta. Para mais informações, consulte nosso artigo no DevPortal Filtrando respostas.

idstring(uuid)

Retorne informações apenas para este recurso id.

Exemplo: id=24ccab1d-3a86-4136-a6eb-e04bf52b356f
id__inArray of strings(uuid)

Retorne informações para esses ids de recurso.

Exemplo: id__in=6b3dea0f-be29-49d1-aabe-1a6d588642e6
created_atstring(date)

Retorne itens que foram atualizados pela última vez no banco de dados da Belvo nesta data (no formato YYYY-MM-DD).

Exemplo: created_at=2022-05-05
created_at__gtstring(date)

Retorne itens que foram atualizados pela última vez no banco de dados da Belvo após esta data (no formato YYYY-MM-DD).

Exemplo: created_at__gt=2022-05-05
created_at__gtestring(date)

Retorne itens que foram atualizados pela última vez no banco de dados da Belvo após ou nesta data (no formato YYYY-MM-DD).

Exemplo: created_at__gte=2022-05-04
created_at__ltstring(date)

Retorne itens que foram atualizados pela última vez no banco de dados da Belvo antes desta data (no formato YYYY-MM-DD).

Exemplo: created_at__lt=2022-04-01
created_at__ltestring(date)

Retorne itens que foram atualizados pela última vez no banco de dados da Belvo antes ou na data especificada (no formato YYYY-MM-DD).

Exemplo: created_at__lte=2022-03-30
created_at__rangeArray of strings(date)<= 2 items

Retorne contas que foram atualizadas pela última vez no banco de dados do Belvo entre duas datas (no formato YYYY-MM-DD).

Exemplo: created_at__range=2022-03-03
invoice_datestring(date)

Retornar faturas emitidas exatamente nesta data (YYYY-MM-DD).

Exemplo: invoice_date=2022-05-05
invoice_date__ltstring(date)

Retornar saldos emitidos antes desta data (YYYY-MM-DD).

Exemplo: invoice_date__lt=2022-03-02
invoice_date__ltestring(date)

Retornar saldos emitidos nesta data ou antes (YYYY-MM-DD).

Exemplo: invoice_date__lte=2022-03-01
invoice_date__gtstring(date)

Retorne faturas emitidas após esta data (YYYY-MM-DD).

Exemplo: invoice_date__gt=2022-05-06
invoice_date__gtestring(date)

Retornar faturas emitidas nesta data ou posteriormente (YYYY-MM-DD)

Exemplo: invoice_date__gte=2022-05-04
invoice_date__rangeArray of strings(date)<= 2 items

Retornar faturas emitidas dentro deste intervalo de datas (YYYY-MM-DD).

Exemplo: invoice_date__range=2022-05-06
invoice_identificationstring

Retorne uma fatura com este ID (conforme fornecido pela instituição).

Exemplo: invoice_identification=862B9918-3K6H-4E0B-NAI9-2BE2D833B840
invoice_identification__inArray of strings

Retorne as faturas com estes IDs (conforme fornecido pela instituição).

Exemplo: invoice_identification__in=992B9918-3G6H-4E0B-DAI9-2BE2D833B833
statusstring

Retorne faturas com este status. Pode ser Vigente (válido) ou Cancelado (cancelado).

Exemplo: status=Vigente
status__inArray of strings

Retorne faturas com estes status. Pode ser Vigente (válido) ou Cancelado (cancelado).

Exemplo: status__in=Cancelado
typestring

Retorne faturas deste tipo. Pode ser OUTFLOW ou INFLOW.

Enum"OUTFLOW""INFLOW"
Exemplo: type=OUTFLOW
type__inArray of strings

Retorne faturas desses tipos. Pode ser OUTFLOW ou INFLOW.

Itens Enum"OUTFLOW""INFLOW"
Exemplo: type__in=OUTFLOW
total_amountnumber(float)^\d{1,15}\.\d{2,4}$

Retornar faturas que correspondam exatamente a este valor.

Exemplo: total_amount=1000.02
total_amount__ltnumber(float)^\d{1,15}\.\d{2,4}$

Retornar faturas menores que este valor.

Exemplo: total_amount__lt=540.02
total_amount__ltenumber(float)^\d{1,15}\.\d{2,4}$

Retornar faturas menores ou iguais a este valor.

Exemplo: total_amount__lte=541.02
total_amount__gtnumber(float)^\d{1,15}\.\d{2,4}$

Retornar faturas maiores que este valor.

Exemplo: total_amount__gt=520.02
total_amount__gtenumber(float)^\d{1,15}\.\d{2,4}$

Retornar faturas maiores ou iguais a este valor.

Exemplo: total_amount__gte=519.02
total_amount__rangeArray of numbers(float)<= 2 items

Retornar faturas entre esses dois valores.

Exemplo: total_amount__range=541.02
curl -i -X GET \
  -u <username>:<password> \
  'https://developers.belvo.com/_mock/pt-br/apis/belvoopenapispec/api/invoices/?created_at=2022-05-05&created_at__gt=2022-05-05&created_at__gte=2022-05-04&created_at__lt=2022-04-01&created_at__lte=2022-03-30&created_at__range=2022-03-03&fields=string&id=24ccab1d-3a86-4136-a6eb-e04bf52b356f&id__in=6b3dea0f-be29-49d1-aabe-1a6d588642e6&invoice_date=2022-05-05&invoice_date__gt=2022-05-06&invoice_date__gte=2022-05-04&invoice_date__lt=2022-03-02&invoice_date__lte=2022-03-01&invoice_date__range=2022-05-06&invoice_identification=862B9918-3K6H-4E0B-NAI9-2BE2D833B840&invoice_identification__in=992B9918-3G6H-4E0B-DAI9-2BE2D833B833&link=8848bd0c-9c7e-4f53-a732-ec896b11d4c4&link__in=5722d0ba-69d7-42dc-8ff5-33767b83c5d6&omit=string&page=1&page_size=100&status=Vigente&status__in=Cancelado&total_amount=1000.02&total_amount__gt=520.02&total_amount__gte=519.02&total_amount__lt=540.02&total_amount__lte=541.02&total_amount__range=541.02&type=OUTFLOW&type__in=OUTFLOW'

Respostas

Ok

Corpoapplication/json
countinteger(int32)

O número total de resultados na sua conta Belvo.

Exemplo: 130
nextstring or null(uri)

A URL para a próxima página de resultados. Cada página consiste em até 100 itens. Se não houver resultados suficientes para uma página adicional, o valor será null.

Em nosso exemplo de documentação, usamos {endpoint} como um valor de espaço reservado. Em produção, esse valor será substituído pelo endpoint real que você está usando atualmente (por exemplo, accounts ou owners).

Exemplo: "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2"
previousstring or null(uri)

A URL para a página anterior de resultados. Se não houver uma página anterior, o valor será null.

Exemplo: null
resultsArray of objects

Array de objetos de invoice.

Resposta
application/json

Exemplo de uma fatura do tipo Igreso.

{ "count": 110, "next": "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2", "previous": null, "results": [ {} ] }

Recuperar faturas para um link

Requisição

Recupere informações de faturas a partir de um link fiscal específico.

📘 Informação

Você pode solicitar até um ano (365 dias) de faturas por solicitação. Se precisar de faturas por mais de um ano, basta fazer outra solicitação.

🚧 Aviso

Este recurso pode retornar campos obsoletos. Por favor, verifique a documentação da resposta para mais informações.

Security
basicAuth
Consulta
omitstring

Omitir certos campos de serem retornados na resposta. Para mais informações, consulte nosso artigo Filtrando respostas no DevPortal.

fieldsstring

Retorne apenas os campos especificados na resposta. Para mais informações, consulte nosso artigo no DevPortal Filtrando respostas.

Cabeçalhos
X-Belvo-Request-Modestring

Parâmetro de cabeçalho recomendado para tornar sua solicitação POST assíncrona (evitando timeouts e melhorando o fluxo de dados).

Quando você faz uma solicitação assíncrona, a Belvo responde com um payload 202 - Accepted, incluindo o request_id. Assim que tivermos recuperado as informações solicitadas, você receberá um webhook com o link e os IDs de solicitação.

Valor"async"
Exemplo: async
Corpoapplication/jsonobrigatório
linkstring(uuid)obrigatório

O link.id para o qual você deseja recuperar informações.

Exemplo: "c81a1dea-6dd6-4999-8b9f-541ee8197058"
date_fromstring(date)= 10 characters^\d{4}-\d{2}-\d{2}$obrigatório

A data a partir da qual você deseja começar a obter dados, no formato YYYY-MM-DD.

⚠️ O valor de date_from não pode ser maior que date_to.

Exemplo: "2020-08-05"
date_tostring(date)= 10 characters^\d{4}-\d{2}-\d{2}$obrigatório

A data em que você deseja parar de receber dados, no formato YYYY-MM-DD.

⚠️ O valor de date_to não pode ser maior que a data de hoje (ou seja, não são permitidas datas futuras).

Exemplo: "2020-10-05"
typestring or nullobrigatório

A direção da fatura (do ponto de vista do proprietário do Link).

  • OUTFLOW indica uma fatura enviada.
  • INFLOW indica uma fatura recebida.
Enum"OUTFLOW""INFLOW"null
Exemplo: "INFLOW"
attach_xmlboolean

Quando definido como true, você receberá a fatura XML na resposta.

Padrão false
Exemplo: false
save_databoolean

Indica se os dados devem ou não ser persistidos no Belvo. Por padrão, isso é definido como true e retornamos uma resposta 201 Created.

Quando definido como false, os dados não serão persistidos e retornamos uma resposta 200 OK.

Padrão true
Exemplo: true
curl -i -X POST \
  -u <username>:<password> \
  'https://developers.belvo.com/_mock/pt-br/apis/belvoopenapispec/api/invoices/?fields=string&omit=string' \
  -H 'Content-Type: application/json' \
  -H 'X-Belvo-Request-Mode: async' \
  -d '{
    "link": "c81a1dea-6dd6-4999-8b9f-541ee8197058",
    "date_from": "2020-08-05",
    "date_to": "2020-10-05",
    "type": "INFLOW",
    "attach_xml": false,
    "save_data": true
  }'

Respostas

Ok (quando save_data=false)

Corpoapplication/jsonArray [
idstring(uuid)

Identificador único da Belvo para o item atual.

Exemplo: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"
linkstring or null(uuid)

O link.id ao qual os dados pertencem.

Exemplo: "30cb4806-6e00-48a4-91c9-ca55968576c8"
collected_atstring(date-time)obrigatório

O carimbo de data/hora ISO-8601 quando o ponto de dados foi coletado.

Exemplo: "2022-02-09T08:45:50.406032Z"
created_atstring(date-time)

O carimbo de data e hora ISO-8601 de quando o ponto de dados foi criado no banco de dados da Belvo.

Exemplo: "2022-02-09T08:45:50.406032Z"
invoice_identificationstring or nullobrigatório

O ID único da instituição fiscal para a fatura.

Exemplo: "A1A1A1A1-2B2B-3C33-D44D-555555E55EE"
invoice_datestring or nullobrigatório

A data da fatura, no formato YYYY-MM-DD.

Exemplo: "2019-12-01"
statusstring or nullobrigatório

O status da fatura. Pode ser Vigente (válido) ou Cancelado (cancelado).

Exemplo: "Vigente"
invoice_typestring or nullobrigatório

A classificação da fatura pela instituição fiscal.

Para o SAT do México, retornamos um dos seguintes valores:

  • Egreso
  • Ingreso
  • Nómina
  • Pago
  • Traslado
Enum"Egreso""Ingreso""Nómina""Pago""Traslado"
Exemplo: "Ingreso"
typestring or nullobrigatório

A direção da fatura (do ponto de vista do proprietário do Link).

  • OUTFLOW indica uma fatura enviada.
  • INFLOW indica uma fatura recebida.
Enum"OUTFLOW""INFLOW"null
Exemplo: "INFLOW"
tax_detailsobject

Informações gerais sobre os impostos da fatura.

sender_idstring or nullobrigatório

O ID fiscal do remetente da fatura

Exemplo: "AAA111111AA11"
sender_fiscal_regimestring or null

O regime tributário do remetente, conforme definido pela pessoa jurídica no país.

Exemplo: "601"
sender_namestring or nullobrigatório

O nome do remetente da fatura.

Exemplo: "ACME CORP"
sender_tax_fraud_statusstring or null

Indica se o remetente está ou não na lista de fraude fiscal do SAT por ter enviado dados incorretos, ter pagamentos pendentes ou ter realizado negócios que violam os regulamentos da instituição fiscal.

O SAT atualiza a lista de fraude fiscal a cada três meses.

Para mais informações sobre os motivos pelos quais um contribuinte pode ser incluído na lista de fraude fiscal, consulte o Artigo 69 e o Artigo 69-B do Código Fiscal da Federação do México.

Os status possíveis são:

  • INVESTIGATING
    A instituição fiscal identificou irregularidades e abriu uma investigação sobre o contribuinte.
  • DISMISSED
    A instituição fiscal investigou o contribuinte e o declarou inocente.
  • CONFIRMED
    A instituição fiscal confirmou que o contribuinte é culpado.
  • OVERTURNED
    A instituição fiscal reavaliou um contribuinte previamente confirmado e, com base em novas evidências, retirou o contribuinte da lista de fraude fiscal.
  • NO_TAX_FRAUD_STATUS
    O receptor ou remetente não é encontrado na lista (ou seja, está em conformidade com os regulamentos da instituição fiscal).
Exemplo: "NO_TAX_FRAUD_STATUS"
receiver_idstring or nullobrigatório

O ID fiscal do destinatário da fatura.

Exemplo: "BBB222222BB22"
receiver_postal_codestring

O código postal do destinatário.

Exemplo: "11560"
receiver_fiscal_regimestring or null

O regime tributário do recebedor, conforme definido pela pessoa jurídica no país.

Exemplo: "601"
receiver_namestring or nullobrigatório

O nome do destinatário da fatura.

Exemplo: "BELVO CORP"
receiver_tax_fraud_statusstring or null

Indica se o destinatário está ou não na lista de fraude fiscal do SAT por ter enviado dados incorretos, ter pagamentos pendentes ou ter realizado negócios que violam os regulamentos da instituição fiscal.

O SAT atualiza a lista de fraude fiscal a cada três meses.

Para mais informações sobre os motivos pelos quais um contribuinte pode ser incluído na lista de fraude fiscal, consulte o Artigo 69 e o Artigo 69-B do Código Fiscal da Federação do México.

Os status possíveis são:

  • INVESTIGATING
    A instituição fiscal identificou irregularidades e abriu uma investigação sobre o contribuinte.
  • DISMISSED
    A instituição fiscal investigou o contribuinte e o declarou inocente.
  • CONFIRMED
    A instituição fiscal confirmou que o contribuinte é culpado.
  • OVERTURNED
    A instituição fiscal reavaliou um contribuinte previamente confirmado e, com base em novas evidências, retirou o contribuinte da lista de fraude fiscal.
  • NO_TAX_FRAUD_STATUS
    O destinatário ou remetente não é encontrado na lista (ou seja, está em conformidade com os regulamentos da instituição fiscal).
Exemplo: "NO_TAX_FRAUD_STATUS"
cancelation_statusstring or nullobrigatório

Se a fatura for cancelada, este campo indica o status do cancelamento.

cancelation_update_datestring or null(date)obrigatório

A data do cancelamento da fatura, no formato YYYY-MM-DD.

Exemplo: "2019-12-02"
certification_datestring or null(date)obrigatório

A data da certificação fiscal, no formato YYYY-MM-DD.

Exemplo: "2019-12-01"
certification_authoritystring or nullobrigatório

O ID fiscal do provedor de certificação.

Exemplo: "CCC333333CC33"
payment_typestring or nullobrigatório

O código do tipo de pagamento usado para esta fatura, conforme definido pela entidade legal do país.

Exemplo: "99"
payment_methodstring or null

O código do método de pagamento usado para esta fatura, conforme definido pela entidade legal do país.

Enum"PUE""PPD"null
Exemplo: "PUE"
usagestring or null

O código de uso da fatura, conforme definido pela entidade legal do país.

Exemplo: "P01"
versionstring or null

A versão CFDI da fatura.

Exemplo: "3.3"
place_of_issuestring or null

O código postal de onde a fatura foi emitida.

Exemplo: "01165"
invoice_detailsArray of objectsobrigatório

Uma lista de descrições para cada item (produto comprado ou serviço prestado) na fatura.

collected_atstring(date-time)

O carimbo de data/hora ISO-8601 quando o ponto de dados foi coletado.

Exemplo: "2022-02-09T08:45:50.406032Z"
descriptionstring or nullobrigatório

A descrição do item da fatura (uma fatura pode ter um ou mais itens).

Exemplo: "December 2019 accounting fees"
product_identificationstring or nullobrigatório

O código de identificação do produto ou serviço, conforme definido pela entidade legal no país.\n- \U0001F1F2\U0001F1FD México.

Exemplo: "84101600"
quantitynumber or null(float)obrigatório

A quantidade deste item da fatura.

Exemplo: 10
unit_codestring or nullobrigatório

A unidade de medida, conforme definida pela entidade legal no país. \n- \U0001F1F2\U0001F1FD México referência do catálogo SAT.

Exemplo: "E48"
unit_descriptionstring or nullobrigatório

A descrição do item, conforme definido pela entidade legal no país.\n- \U0001F1F2\U0001F1FD México referência do catálogo SAT.

Exemplo: "Unidad de servicio"
unit_amountnumber or null(float)obrigatório

O preço de um único item.

Exemplo: 200
tax_typestring or null

O tipo de imposto do item.

Exemplo: null
pre_tax_amountnumber or null(float)obrigatório

O preço total deste item antes da aplicação de impostos é (quantity x unit_amount).

Exemplo: 400
tax_percentagenumber or null(float)obrigatório

A porcentagem de imposto a ser aplicada.

Exemplo: 16
tax_amountnumber or null(float)obrigatório

O valor do imposto para este item da fatura (pre_tax_amount x tax_percentage).

Exemplo: 64
total_amountnumber or null(float)obrigatório

O preço total para este item da fatura (pre_tax_amount + tax_amount).

Exemplo: 464
retained_taxesArray of objects

O imposto retido no item da fatura.

transferred_taxesArray of objects

Os impostos transferidos relacionados à fatura.

currencystring or nullobrigatório

A moeda da fatura. Por exemplo:

  • 🇧🇷 BRL (Real Brasileiro)
  • 🇨🇴 COP (Peso Colombiano)
  • 🇲🇽 MXN (Peso Mexicano)
  • 🇺🇸 USD (Dólar dos Estados Unidos)
Exemplo: "MXN"
subtotal_amountnumber or null(float)obrigatório

O valor antes dos impostos desta fatura (soma do pre_tax_amount de cada item).

Exemplo: 400
exchange_ratenumber or null(float)obrigatório

A taxa de câmbio utilizada nesta fatura para a moeda.

Exemplo: 0.052
tax_amountnumber or null(float)obrigatório

O valor do imposto para esta fatura (soma do tax_amount de cada item).

Exemplo: 64
discount_amountnumber or null(float)obrigatório

O valor total descontado nesta fatura.

Exemplo: 10
total_amountnumber or null(float)obrigatório

O valor total da fatura (subtotal_amount + tax_amount - discount_amount)

Exemplo: 454
related_invoicesArray of objects

Uma lista de faturas relacionadas.

paymentsArray of objectsobrigatório

Uma lista detalhando todos os pagamentos de faturas.

datestring or null(date-time)obrigatório

Carimbo de data/hora ISO-8601 quando o pagamento foi realizado.

Exemplo: "2020-03-17T12:00:00.000Z"
payment_typestring or nullobrigatório

Código do tipo de pagamento usado para esta fatura, conforme definido pela entidade legal do país.

Exemplo: "03"
currencystring or nullobrigatório

A moeda do pagamento. Por exemplo:

  • 🇧🇷 BRL (Real Brasileiro)
  • 🇨🇴 COP (Peso Colombiano)
  • 🇲🇽 MXN (Peso Mexicano)

Por favor, note que outras moedas além das listadas acima podem ser retornadas.

Exemplo: "BRL"
exchange_ratestring or nullobrigatório

A taxa de câmbio de currency para MXN no momento em que o pagamento foi realizado.

Exemplo: "3.75"
amountnumber or null(float)obrigatório

O valor da fatura, na moeda da fatura original.

Exemplo: 8000.5
operation_numberstring or nullobrigatório

O identificador interno da instituição fiscal para a operação.

Exemplo: "831840"
beneficiary_rfcstring or null

O ID fiscal do beneficiário do pagamento.

Exemplo: "BNM840515VB1"
beneficiary_account_numberstring or nullobrigatório

O número da conta bancária do beneficiário do pagamento.

Exemplo: "12343453245633"
payer_rfcstring or nullobrigatório

O ID fiscal do emissor do pagamento.

Exemplo: "BKJM840515VB1"
payer_account_numberstring or nullobrigatório

O número da conta bancária do emissor do pagamento.

Exemplo: "13343663245699"
payer_bank_namestring or nullobrigatório

A instituição bancária que foi utilizada pelo emissor do pagamento.

Exemplo: "CITI BANAMEX"
related_documentsArray of objectsobrigatório

Uma lista de todas as faturas diferidas relacionadas afetadas pelo pagamento.

invoice_identificationstring or nullobrigatório

O ID exclusivo da instituição fiscal para a fatura diferida relacionada.

Exemplo: "7EE015F3-6311-11EA-B02A-00155D014007"
currencystring or nullobrigatório

A moeda da fatura relacionada. Por exemplo:

  • 🇧🇷 BRL (Real Brasileiro)
  • 🇨🇴 COP (Peso Colombiano)
  • 🇲🇽 MXN (Peso Mexicano)

Por favor, note que outras moedas além das listadas acima podem ser retornadas.

Exemplo: "MXN"
payment_methodstring or nullobrigatório

O método de pagamento da fatura relacionada.

Exemplo: "PPD"
partiality_numberinteger(int32)

O número da parcela de pagamento.

Exemplo: 1
previous_balancenumber or null(float)obrigatório

O valor da fatura antes do pagamento.

Exemplo: 18877.84
amount_paidnumber or null(float)obrigatório

O valor pago nesta parcela.

Exemplo: 8000
outstanding_balancenumber or null(float)obrigatório

O valor restante a ser pago.

Exemplo: 10877.84
payrollobject or nullobrigatório

Detalhes sobre o pagamento da folha de pagamento. Aplicável apenas para faturas de folha de pagamento.

daysinteger or null(int32)obrigatório

O número de dias cobertos pelo pagamento.

Exemplo: 30
typestring or nullobrigatório

O tipo de folha de pagamento, conforme definido pela entidade legal do país.

Exemplo: "O"
amountnumber(float)obrigatório

O valor total do pagamento da folha de pagamento.

Exemplo: 20400.1
versionstringobrigatório

A versão do objeto de folha de pagamento.

Exemplo: "1.2"
date_fromstring or null(date)obrigatório

A data de início do período de pagamento, no formato YYYY-MM-DD.

Exemplo: "2018-07-01"
date_tostring or null(date)obrigatório

A data de término do período de pagamento, no formato YYYY-MM-DD.

Exemplo: "2018-07-31"
collected_atstring(date-time)

O carimbo de data/hora ISO-8601 quando o ponto de dados foi coletado.

Exemplo: "2022-02-09T08:45:50.406032Z"
payment_datestring(date)obrigatório

A data de pagamento, no formato YYYY-MM-DD.

Exemplo: "2018-07-16"
periodicitystring or null

Com que frequência o pagamento da folha de pagamento é realizado.

Para o SAT do México, retornamos um dos seguintes valores:

  • DAILY
  • WEEKLY
  • TENTH_DAY
  • FOURTEENTH_DAY
  • FIFTEENTH_DAY
  • MONTHLY
  • BIMONTHLY
  • PER_TASK
  • COMMISSION
  • ONE_OFF
  • OTHER_PERIODICITY
Enum"DAILY""WEEKLY""TENTH_DAY""FOURTEENTH_DAY""FIFTEENTH_DAY""MONTHLY""BIMONTHLY""PER_TASK""COMMISSION""ONE_OFF"
Exemplo: "MONTHLY"
earnings_breakdownArray of objects or null or null

Uma análise detalhada dos ganhos para o pagamento da folha de pagamento.

tax_deductionsArray of objects or null or null

Uma análise das deduções fiscais no pagamento da folha de pagamento.

other_paymentsArray of objects or null or null

Uma análise detalhada de outros pagamentos para a folha de pagamento.

foliostring or null

O número de controle interno que o contribuinte atribui à nota fiscal.

Exemplo: "26"
export_typestring or null

O tipo de exportação da fatura, conforme definido pela entidade legal no país. Para mais informações, consulte nosso artigo de referência do catálogo SAT.

Exemplo: "01"
xmlstring or null

XML do documento da fatura.

warningsobject or null

Objeto contendo informações sobre quaisquer avisos relacionados a esta fatura.

payment_type_descriptionstring or nullObsoletoobrigatório

Este campo foi descontinuado. Para mais informações sobre a Belvo e descontinuação, consulte nossa explicação sobre Campos descontinuados.

Exemplo: null
payment_method_descriptionstring or nullObsoleto

Este campo foi descontinuado. Para mais informações sobre a Belvo e descontinuação, consulte nossa explicação sobre Campos descontinuados.

A descrição do método de pagamento utilizado para esta fatura.

Exemplo: null
sender_blacklist_statusstring or nullObsoleto

Este campo foi descontinuado. Para mais informações sobre a Belvo e descontinuação, consulte nossa explicação sobre Campos descontinuados. Por favor, use sender_tax_fraud_status em vez disso.

Exemplo: null
receiver_blacklist_statusstring or nullObsoleto

Este campo foi descontinuado. Para mais informações sobre a Belvo e descontinuação, consulte nossa explicação sobre Campos descontinuados. Por favor, use receiver_tax_fraud_status em vez disso.

Exemplo: null
]
Resposta
application/json

Exemplo de uma fatura do tipo Igreso.

[ { "id": "90d90e38-0087-4b6d-b6dc-94ea561bb9cb", "link": "1bd948f7-245d-4313-b604-34d1044cb908", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "invoice_identification": "862B9918-3K6H-4E0B-NAI9-2BE2D833B840", "invoice_date": "2020-12-24", "status": "Vigente", "invoice_type": "Ingreso", "type": "OUTFLOW", "sender_id": "GHTF980303F7", "sender_name": "Roberto Martinez Diaz", "sender_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "receiver_id": "MNMK3203409H1", "receiver_name": "ACNE SA DE CV", "receiver_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "cancelation_status": null, "cancelation_update_date": null, "certification_date": "2020-12-24", "certification_authority": "FGV330542BG6", "payment_type": "04", "payment_type_description": null, "payment_method": "PUE", "usage": "G03", "place_of_issue": "11000", "version": "3.3", "invoice_details": [], "currency": "MXN", "subtotal_amount": 25, "exchange_rate": 1, "tax_amount": 4, "discount_amount": 0, "total_amount": 29, "payments": [], "payroll": null, "folio": "28", "xml": "=XML-STRING=", "warnings": {} } ]

Tax compliance status

Operações

Tax returns

Operações

Tax retentions

Operações

Tax status

Operações

Financial Statements

Operações

Invoices Chile

Operações

Tax Status Chile

Operações

Debt Reports Chile

Operações

Incomes

Use o endpoint Incomes para obter insights sobre as fontes de renda de uma conta nos últimos 365 dias. O endpoint é particularmente útil quando você deseja verificar a renda de uma pessoa.

📘 Info

O recurso incomes está disponível apenas para contas Corrente e Poupança associadas a links bancários.

Operações

Recurring Expenses

A API de Despesas Recorrentes da Belvo permite que você identifique os pagamentos regulares de um usuário para serviços de assinatura, como Netflix ou assinaturas de academia, bem como pagamentos de serviços públicos, como contas de eletricidade ou telefone. Nós retornamos informações de até 365 dias.

📘 Informação

O recurso de despesas recorrentes está disponível apenas para contas Corrente, Poupança e de Cartão de Crédito associadas a links bancários.

Operações

Risk Insights

Operações

Employment Metrics

Operações

Payment Institutions (Brazil)

Uma instituição de pagamento é uma entidade da qual a Belvo pode acessar informações. Você pode ver uma lista completa de instituições disponíveis para pagamentos fazendo uma solicitação de List para este endpoint.

Operações

Customers (Brazil)

Um customer é o pagador que vai transferir fundos para sua conta bancária. Você precisa criar um customer para receber pagamentos de entrada na conta bancária da sua organização.

Operações

Bank Accounts (Brazil)

Para receber pagamentos de entrada na conta bancária da sua organização, você deve registrar as contas bancárias (individuais e empresariais) usando a Payments API da Belvo.

  • Contas bancárias individuais devem ser criadas para cada pagador (seu cliente).
  • Contas bancárias empresariais precisam ser criadas para o beneficiário do pagamento (sua organização).
Operações

Payment Intents (Brazil)

Um payment intent é um ponto único de acesso para criar pagamentos usando qualquer método de pagamento oferecido pela Belvo.

Um payment intent captura todas as informações de pagamento (como o valor a ser cobrado, a descrição do pagamento, o provedor, etc.) e guia seus clientes através do fluxo de pagamento.

Nota: Para instituições que exigem o username_type no array form_fields, você deve enviar esse valor na sua solicitação PATCH.

Operações

Payment Authorizations (Brazil)

Uma Autorização de Pagamento é o consentimento que seu usuário dá para que você debite dinheiro de suas contas. Você precisa realizar uma Autorização de Pagamento por ‘contrato’ (por exemplo, se sua empresa fornece tanto eletricidade quanto água, mas elas são cobradas separadamente, então você criará duas Autorizações de Pagamento separadas).

Assim que o usuário confirmar a autorização, você precisará escutar um webhook PAYMENT_AUTHORIZATION com o status definido como AUTHORIZED. Assim que você receber esse webhook, o processo de autorização estará completo, e você poderá cobrar seu usuário.

O que é uma cobrança?

Uma cobrança representa o pagamento individual (débito) que seu cliente fará.

Cabeçalho de Versão

O recurso de Autorização de Pagamento requer que você envie o cabeçalho X-Belvo-API-Resource-Version configurado para Payments-BR.V2.

Operações

Biometric Pix Widget Access Token (Brazil)

Use as solicitações de Token do Biometric Pix Widget para criar um token de acesso para Pagamentos Biométricos.

Operações

Enrollments (Brazil)

Operações

Payment Transactions (Brazil)

Cada vez que você recebe um pagamento de entrada de um cliente, uma transação é criada no banco de dados da Belvo.

Você pode usar o recurso de Transações de Pagamento para obter informações úteis sobre uma transação, bem como a cobrança específica associada a ela.

Operações