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:

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

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.