Material de Apoio para utilização das APIs
Está página tem como objetivo explicar melhor a utilização das APIs da Integração bem como responder a perguntas frequentes
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.
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. 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. 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:
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.
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.
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.
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 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. 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. 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.
Last updated