> For the complete documentation index, see [llms.txt](https://integracao.useblu.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://integracao.useblu.com.br/fornecedores-apis/material-de-apoio-para-utilizacao-das-apis.md).
# Material de Apoio para utilização das APIs
### Enviar Cobrança
Esta API tem como objetivo enviar uma cobrança para ser registrada no Portal Blu.\
Neste ponto, é determinado através do campo *billing\_later*. se a cobrança será com ou sem faturamento:
* Com faturamento → billing\_later: true
* Sem faturamento → billing\_later: false
A operação ocorrendo com sucesso deve ser retornado o **status 1 - Aguardando aprovação** e aguardar o cobrado aprovar a cobrança.
### Consultar Cobrança
A API tem como principais funções:
#### 1. Consultar se houve mudança de status na cobrança:
Devem ser verificados os campo *status* e *status\_code* para saber se houve alteração.\
Os status possíveis estão [aqui.](https://integracao.useblu.com.br/sobre-apis-1)
#### 2. Consultar se o calendário de pagamento da cobrança foi gerado (PagBlu) ou se o pagamento "À Vista" foi realizado:
O campo *installments\_of\_charger* é populado a partir do momento que o calendário de pagamento é emitido pela Blu:
* Cobrança **com faturamento** → Após o envio do faturamento o calendário de pagamento é gerado.
* Cobrança **sem faturamento** → No momento em que o cobrado aprova a cobrança o calendário de pagamento é gerado.
* Cobrança **À Vista** → No momento em que o cobrado aprova a cobrança uma parcela com o valor total da cobrança aparece no campo.
#### 3. Verificar o *charger\_kind* que pode ser default ou on\_time.
Default se refere ao pagamento do tipo PagBlu (parcelado) e on\_time que tratará de pagamentos À Vista.
#### 4. Validação de valores de desconto pelo visão de cobrador (fornecedor) e cobrado (lojista):
* **Cobrador** → Os campos *charger\_increase\_or\_discount\_rate*, *charger\_increase\_or\_discount*, *charger\_value* se referem ao percentual de desconto, valor do desconto e valor total a ser recebido pelo cobrador.
* **Cobrado** → Os campos *increase\_or\_discount\_rate*, *increase\_or\_discount*, *value* se referem ao percentual de desconto, valor do desconto e valor total que foi pago pelo cobrado.\
Existem casos em que o desconto dado ao cobrado é diferente do desconto aplicado ao cobrador por conta do modelo de recebimento escolhido pelo cobrador. Neste caso, para ter o valor exato do valor cobrado pela escolha do modelo de recebimento deve ser feita a diferença entre os campos do cobrado e cobrador. Em caso de dúvidas consulte o Time de Integração para maiores esclarecimentos.
### Cancelar Cobrança
Esta API permite que o cobrador cancele a cobrança antes que o cobrado a aceite. Ou seja, a cobrança deve estar em **status 1 - Aguardando Aprovação** ou **status 2 - Aprovado, aguardando o valor total para pagamento automático** para que seja possível cancelar a cobrança.
Após o cancelamento da cobrança ela passará a ter **status 4 - Pagamento cancelado**.
Vale frisar que quando uma cobrança é cancelada pelo cobrador ou rejeitada pelo cobrado é possível utilizar o mesmo *document\_number* em uma nova cobrança.
### Enviar Faturamento
Esta API é utilizada em cobranças com o parâmetro *billing\_later: true* para que o faturamento seja enviado para a Blu e o calendário de pagamento gerado.\
O envio do faturamento só pode ser feito quando a cobrança já foi aprovada pelo cobrado e encontra-se em **status 8 - Pagamento aguardando faturamento ou cancelamento de nota** e deve:
* Possuir data do dia atual ou futura.
* Ter valor menor ou igual ao valor da cobrança.
* Cada faturamento de cobrança enviado deve ter um nome de Nota Fiscal único.
Para verificar se o faturamento foi registrado corretamente deve ser utilizada a API de *Consultar Cobrança* no campo *installments\_of\_charger.*\
Após o envio de um faturamento total a cobrança permanece em **status 8** por mais 24h e então o status é alterado para **status 3 - Pagamento realizado**.\
\&#xNAN;*Atualização: Em 15/11/2024 o tempo de permanência de uma cobrança totalmente faturada em status 8 passou de 72h para 24h.*
### Cancelar Faturamento
A API de *Cancelar Faturamento* é utilizada em cobranças com com o parâmetro *billing\_later: true* e permite cancelar um faturamento que tenha sido enviado há menos de 24h de uma cobrança que ainda encontre-se em **status 8 - Pagamento aguardando faturamento ou cancelamento de nota**.
Após o cancelamento do faturamento o saldo volta a estar *Aguardando faturamento* e o calendário de pagamento gerado é extinto.\
\&#xNAN;*Atualização: Em 15/11/2024 o tempo de permanência de uma cobrança totalmente faturada em status 8 passou de 72h para 24h.*
### Enviar Devolução
Esta API é utilizada em cobranças com o parâmetro *billing\_later: true e* em três situações:
1. Quando deseja-se devolver o valor total ao cobrado e não faturar nenhuma nota. Neste caso após a devolução a cobrança irá para **status 9 - Pagamento devolvido**.
2. Quando a cobrança foi parcialmente faturada e deseja-se devolver o valor restante para o cobrado. Neste caso após a devolução irá para **status 3 - Pagamento realizado**.
3. Quando há um valor residual de centavos e a cobrança não passa para **status 3** após 24h. Após a devolução a cobrança irá para **status 3 - Pagamento realizado**.
4. Quando a cobrança está totalmente faturada e deseja-se que ela mude para o **status 3 - Pagamento realizado** de maneira imediata sem aguardar as 24h que possibilitam o cancelamento do faturamento.
Em todos os casos o valor é devolvido para a Conta Blu do cobrado no momento em que a devolução é enviada.
Vale frisar que não é possível determinar o valor da devolução. Todo o valor Aguardando faturamento, ou seja, sem Nota Fiscal e calendário de pagamento associados será devolvido para o cobrado.
Após o envio da devolução a cobrança é finalizada, entrando nos status finais 3 ou 9.
*Atualização: Em 15/11/2024 o tempo de permanencia de uma cobrança totalmente faturada em status 8 passou de 72h para 24h.*
### Consultar Conciliação Financeira
A API de *Consultar Conciliação Financeira* possibilita consultar todos os pagamentos feitos pela Blu em D-1 ou anterior, ou seja, deve-se sempre consultar no mínimo o dia anterior ao atual. A consulta deve ocorrer sempre **após às 9h**, caso contrários os dados de D-1 podem ainda não estar disponíveis e retorno ser erroneamente “Nenhuma informação encontrada para os dados informados.".\
As movimentações mostradas pela API são:
* Recebimento de Parcelas PagBlu.
* Recebimento de cobranças À Vista.
* Antecipações financeiras provenientes de cobranças.
Vale frisar que em movimentações de baixa parcial de parcelas advindas de antecipações financeiras o valor proporcional da taxa de inadimplência e a taxa de antecipação são exibidas em cada uma das parcelas.
### Auxiliar: Verifica Lojista/Criado Blu
A API de *Verifica Lojista/Criado Blu* pode ser acessada no [link](https://integracao.useblu.com.br/sobre-apis/auxiliares) e tem como objetivo verificar se um cobrado possui conta Blu.\
Vale frisar que essa API não deve ser utilizada em massa e sim pontualmente no cadastro do cliente.
##
## Perguntas Frequentes
Como acesso o ambiente de Homologação da Blu?
O Ambiente de Homologação é uma replica do ambiente de Produção em que os testes da Integração podem ser feitos. As APIs utilizadas são cópias de produção com a adição de *-hlg* em sua url, como descrito na [documentação técnica](https://integracao.useblu.com.br/sobre-apis-1). O time de Integração fornecerá um token de Homologação para o CNPJ desejado, que será o cobrador (fornecedor) bem como um cliente do ambiente que atuará como cobrado (lojista).\
Para acessar o ambiente solicite as credenciais para o time de Integração e em seguida busque seus clientes designados utilizando *control+f*.
Como o cobrado (lojista) aprova uma cobrança?
No ambiente de **Homologação**, ou seja, no ambiente de testes que replica Produção é possível atuar como cobrador (fornecedor) e cobrado (lojista). No momento em que o token de Homologação é liberado pelo time de Integração é também informado o cliente que será utilizado como cobrado. Deve-se localizar o cobrado utilizando *control+f*, localizar a cobrança que deseja e aprová-la em uma das modalidades disponíveis.
No ambiente de **Produção** o cobrador (fornecedor) não possui nenhuma ação quanto a aprovação de uma cobrança. O cobrado (lojista) deve acessar sua conta no Portal Blu e aprovar a cobrança, assim que essa ação for realizada será possível ver pela API *Consultar Cobrança* que o status da mesma saiu de **status 1 - Aguardando aprovação.**
Quando posso reutilizar um document_number (número do pedido/cobrança)?
O *document\_number* é o "nome" do pedido/cobrança e ajuda a identificá-la em conjunto com o uuid.\
Existem três casos em que é permitido reutilizar o *document\_number*: \
\- Quando a cobrança original está em status **4 - Pagamento cancelado**.\
\- Quando a cobrança original está em status **5 - Pagamento rejeitado**.\
\- Quando a cobrança original está em status **9 - Pagamento devolvido**, ou seja, foi teve seu valor totalmente devolvido ao lojista.\
Em qualquer outro status **não** é possível reutilizar o *document\_number*.
Quanto tempo leva para uma cobrança sair do status 8 - Pagamento aguardando faturamento ou cancelamento de nota e ir para o status 3 - Pagamento confirmado?
Após o envio do faturamento a cobrança fica ainda em status 8 por 24 horas (1 dia) para possibilitar o cancelamento da nota. Após esse período ela irá automaticamente para o status 3, em caso de faturamento total.\
\&#xNAN;*Atualização: Em 15/11/2024 o tempo de permanência de uma cobrança totalmente faturada em status 8 passou de 72h para 24h.*
Quais são os status finais e quando eles ocorrem?
Status final é um status onde a cobrança é vista como encerrada pela Blu, sendo eles:\
**Status 3 - Pagamento realizado**: Quando a cobrança foi paga ou está com o calendário de pagamento no valor total de mesma gerado.
**Status 4 - Pagamento cancelado**: Quando o fornecedor cancela a cobrança antes da aprovação do cobrado (lojista).
**Status 5 - Pagamento rejeitado**: Quando o cobrado (lojista) rejeita a cobrança.
**Status 9 - Pagamento devolvido**: Quando o valor total da cobrança é devolvido para o cobrado (lojista).
O que acontece se o cobrado (lojista) não possuir todo o valor da cobrança em saldo?
Caso o cobrado (lojista) não possua o saldo a cobrança irá para **status 2 - Aprovado, aguardando o valor total para pagamento automático** e a Blu garante que assim que o lojista tiver saldo ele vai diretamente para o pagamento da cobrança em questão. Esta situação pode ser simulada no ambiente de Homologação.
O que é o status 10 - Aguardando Antecipação?
O **status 10 - Aguardando Antecipação** é um status interno da Blu que pode aparecer no retorno de uma chamada de API, principalmente no ambiente de Homologação. Em produção ele é quase instantâneo e na próxima consulta a cobrança já estará no status esperado. O ERP deve ser preparar para receber esse status, mas o mesmo é apenas transitório.
É possível forçar que uma cobrança em status 8 vá para status 3 em menos de 24 horas?
Sim, essa operação é possível utilizando a API de *Enviar Devolução*. Deve-se atentar para algumas situações antes de realizar o envio da devolução e forçar o encerramento precoce do faturamento:
* Se houver algum saldo Aguardando faturamento o dinheiro será devolvido para o cobrador (lojista).
* Não será possível cancelar faturamento ou adicionar outro faturamento à cobrança após o envio da devolução, pois a cobrança irá para **status 3 - Pagamento realizado** um dos status finais da cobrança.
*Atualização: Em 15/11/2024 o tempo de permanência de uma cobrança totalmente faturada em status 8 passou de 72h para 24h.*
###
Para que utilizo o uuid que é retornado ao enviar um faturamento?
As APIs da Integração são preparadas para o cenário de mais de um faturamento ser enviado por cobrança, assim o uuid de faturamento é utilizado para identificar na API de *Consultar Cobrança* no campo de *installments\_of\_charger* qual parcela é referente a qual faturamento. Para isso o uuid do faturamento é exibido no campo *payment\_plan\_uuid* em todas as parcelas relacionadas ao mesmo faturamento.
O que seria o campo payment_id na API de Consultar Conciliação Financeira?
O campo *payment\_id* é preenchido com o campo *id* que está dentro de cada parcela da API *Consultar Cobrança*, ou seja, ele identifica a parcela que está sendo paga.
O que seria o campo transaction_id na API de Consultar Conciliação Financeira?
As APIs da Integração tentam prever a maioria dos cenários realizados no dia a dia da operação de um fornecedor. Assim, prevendo que havendo uma Antecipação de Recebíveis pode ocorrer o pagamento parcial de uma parcela, caracterizada pelo *payment\_id*, e posteriormente outro pagamento do montante restante do valor da parcela. Para este caso em que uma mesma parcela possui pagamento em duas ou mais etapas deve-se olhar o campo *transaction\_id* para diferenciar as transações de pagamento.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://integracao.useblu.com.br/fornecedores-apis/material-de-apoio-para-utilizacao-das-apis.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.