APIs PagBlu v1

Este conjunto de APIs PagBlu não conta com HTTP Status, tratando-se da versão anterior a APIs PagBlu com HTTP Status. O time de integração da Blu recomenda que seja utilizada o conjunto de APIs mais recente. Como diversos fornecedores ainda as utilizam sua documentação e collection ainda encontram-se disponíveis.

Estrutura do Pedido/Cobrança

Todo pedido/cobrança Blu possui uma estrutura de dados comum. Os campos aqui descritos podem estar presentes de forma parcial ou total nas chamadas de APIs listadas abaixo, conforme o escopo da requisição. Para facilitar o entendimento das informações de um pedido/cobrança, apresentamos a seguinte relação de campos:

Campo	Data Type	Descrição
document_number	string	Número do pedido/cobrança
uuid	string	Identificador único do pedido/cobrança na Blu
billing_later	boolean	Pedido/cobrança aguarda (true) ou não (false) o faturamento
charger	string	CNPJ/CPF do fornecedor/cobrador
charged	string	CNPJ/CPF do lojista/cobrado
status	string	Situação do pedido/cobrança
status_code	integer	Código da situação do pedido/cobrança (conforme tabela)
message	string	Mensagem de retorno da operação
kind	string	Forma de pagamento (conforme tabela)
charger_kind	string	Condição de pagamento (conforme tabela)
scheduled_at	string	Data de agendamento (para pedidos/cobranças com prazo, ex.: Antecipação ZERO + Prazo (Descontinuado)e Boleto Blu
increase_or_discount_rate	decimal	Taxa de acréscimo ou desconto no pedido/cobrança
increase_or_discount	decimal	Valor de acréscimo ou desconto no pedido/cobrança
value	string	Valor do pedido/cobrança
charger_increase_or_discount_rate	string	Percentual de desconto ao fornecedor/cobrador
charger_increase_or_discount	string	Valor de desconto ao fornecedor/cobrador
charger_value	string	Valor disponível ao fornecedor/cobrador
installments_of_charger	array	Relação de pagamentos ao fornecedor/cobrador
gross_value	string	Valor bruto da parcela do pedido/cobrança
net_value	string	Valor líquido da parcela do pedido/cobrança
rate_value	string	Valor de desconto da parcela do pedido/cobrança
tax_rate	string	Percentual de desconto da parcela do pedido/cobrança
advances_rate_value	string	Taxa de antecipação da parcela do pedido/cobrança

Relação de status_code de Pedido/Cobrança

A seguir são listados os códigos de situação que um pedido/cobrança pode se encontrar dentro da Blu.

Status Code	Descrição
1	Aguardando aprovação
2	Aprovado, aguardando o valor total para pagamento automático
3	Pagamento realizado
4	Pagamento cancelado
5	Pagamento rejeitado
6	Agendamento aprovado para o dia AAAA-MM-DD
7	Em processamento
8	Pagamento aguardando faturamento ou cancelamento de nota
9	Pagamento devolvido
10	Aguardando Antecipação

Acessando as APIs

As funcionalidades listadas abaixo devem ser acessadas através dos seguintes endereços:

Homologação: https://api-hlg.blu.com.br/b2b

Produção: https://api.blu.com.br/b2b

Enviar Cobrança

POST /payment-collections

Realiza o envio de pedidos/cobranças para o portal da Blu.

Headers

Name	Type	Description
Authorization	string	Bearer token

Request Body

Name	Type	Description
blu_billet_days	string	(Descontinuado) Número de dias de carência para o Boleto Blu¹.
blu_billet	boolean	(Descontinuado) Indica se o pedido/cobrança terá a opção de pagamento Boleto Blu¹.
representative_cpf_cnpj	string	CNPJ/CPF do representante comercial.
document_number	string	Número do pedido/cobrança.
charged	string	CNPJ/CPF do lojista/cobrado.
value	string	Valor do pedido/cobrança.
scheduled_at	string	Data de agendamento de pedido/cobrança².
billing_later	boolean	Indica se haverá faturamento³ (true) ou se o pagamento deverá ocorrer no momento da aprovação do pedido/cobrança pelo lojista/cobrado (false).

200

OK

{
    "uuid": "<identificador-único>",
    "document_number": "XXXX-XX",
    "charged": "000.000.000-00"
    "message": "Cobrança criada com sucesso, mas não pode ser aprovada via API, porque o cliente ainda não permitiu efetuar aprovação automática. Para efetuar a permissão é necessário que o cliente cobrado autorize esse tipo de ação no dashboard na própria cobrança efetuada",
    "status": "Aguardando aprovação",
    "status_code": 1
}

NOK

{
    "message": "Usuário não encontrado para o token informado."
}

Reenvio

{
    "message": "A validação falhou: Chave única já existe uma cobrança com essa business_key, UUID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
}

Exemplos de chamada

Exemplo Body

{
    ("blu_billet_days" : null,) => deprecated
    ("blu_billet" : false,) => deprecated
    "representative_cpf_cnpj" : "000.000.000-00",
    "document_number" : "XXXX-XX",
    "charged" : "000.000.000-00",
    "value" : "0.00",
    "scheduled_at" : "AAAA-MM-DD",
    "billing_later" : true
}

cURL

curl --location --request POST 'https://api-hlg.blu.com.br/b2b/payment-collections' \
--header 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--data-raw '{
	("blu_billet_days" : null,) => deprecated
	("blu_billet" : false,) => deprecated
	"representative_cpf_cnpj" : "000.000.000-00",
	"document_number" : "XXXX-XX",
	"charged" : "000.000.000-00",
	"value" : "0.00",
	"scheduled_at" : "AAAA-MM-DD",
	"billing_later" : true
}'

NodeJS

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://api-hlg.blu.com.br/b2b/payment-collections',
  'headers': {
    'Authorization': 'Bearer XXXXXXXXXXXXXXXXXXXXXXX',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({("blu_billet_days":null,)=>deprecated("blu_billet":false,)=>deprecated"representative_cpf_cnpj":"000.000.000-00","document_number":"XXXX-XX","charged":"000.000.000-00","value":"0.00","scheduled_at":"AAAA-MM-DD","billing_later":true})

};
request(options, function (error, response) { 
  if (error) throw new Error(error);
  console.log(response.body);
});

Confira a relação de "status_code" nesta sessão.

(Descontinuado) ¹ Para saber mais sobre o Boleto Blu, acesse Pedidos/Cobranças.

² Ao definir uma data de agendamento para o seu pedido/cobrança, você estará concedendo ao lojista/cobrado a possibilidade de realizar o pagamento em uma data futura, data essa que foi estipulada no campo data de agendamento. Utilizando-se de tal opção, somente as formas de pagamento com prazo, Antecipação ZERO + Prazo e Boleto Blu,(Descontinuado) estarão habilitadas para seleção pelo lojista/cobrado, sendo que o Antecipação ZERO + Prazo utilizará da data de agendamento como prazo e o Boleto Blu, caso esteja assinalado para uso("blu_billet": true), utilizará o número de dias de carência.(Descontinuado) Para saber mais sobre pedidos/cobranças e seus meios e formas de pagamento acesse

³ No modelo de faturamento ("billing_later": true), após o pedido/cobrança ser aprovada pelo lojista/cobrado, o valor do pedido/cobrança já é retirado do saldo do lojista/cobrado, ficando este empenhado em um modo de espera, aguardando a realização do faturamento (envio de notas fiscais ou documentos comprobatórios) para então gerar o calendário de pagamentos ou então efetivamente efetuar o pagamento ao fornecedor/cobrador, variando de acordo com o valor informado no faturamento, como também pela a forma e condição de pagamento acordada entre o fornecedor/cobrador e a Blu.

Consultar Cobrança

GET /payment-collections/{uuid}

Consulta a situação de uma cobrança.

Path Parameters

Name	Type	Description
uuid	string	Identificador único do pedido/cobrança.

Headers

Name	Type	Description
Authorization	string	Bearer token.

200

OK

{
    "uuid": "<identificador-único>",
    "billing_later": true,
    "document_number": "",
    "charger": "000.000.000-00",
    "charged": "00.000.000/0000-00",
    "status": "Aguardando aprovação",
    "statusCode": 1,
    "kind": "payment_collection",
    "charger_kind": "default",
    "charger_increase_or_discount_rate": "0.0",
    "charger_increase_or_discount": "0.0",
    "charger_value": "0.0"
    "scheduled_at": "",
    "increase_or_discount_rate": "0.0",
    "increase_or_discount": "0.0",
    "value": "0.0",
    "installments_of_charger": [{}]
}

NOK

{
    "message": "Nenhuma cobrança encontrada para o identificador informado."
}

Exemplo de chamada:

cURL

curl --location --request GET 'https://api-hlg.blu.com.br/b2b/payment-collections/{uuid}' \
--header 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXX'

NodeJs

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://api-hlg.blu.com.br/b2b/payment-collections/{uuid}',
  'headers': {
    'Authorization': 'Bearer XXXXXXXXXXXXXXXXXXXXXXX'
  }
};
request(options, function (error, response) { 
  if (error) throw new Error(error);
  console.log(response.body);
});

Confira a relação de "status_code" nesta sessão.

Cancelar Cobrança

DELETE /payment-collections/{uuid}

Realiza o cancelamento de um pedido/cobrança, caso este ainda não tenha sido aprovado ("status_code": 1), esteja aguardando saldo para efetuar o pagamento ("status_code": 2) ou ainda esteja aprovado, aguardando pagamento agendado ("status_code": 6).

Path Parameters

Name	Type	Description
uuid	string	Identificador único do pedido/cobrança.

Headers

Name	Type	Description
Authorization	string	Bearer token.

200 Solicitação de cancelamento em processamento.

OK

{
    "uuid": "<identificador-único>",
    "document_number": "",
    "charger": "000.000.000-00",
    "charged": "00.000.000/0000-00",
    "message": "Pagamento cancelado com sucesso!"
}

NOK

{
    "uuid": "<identificador-único>",
    "document_number": "",
    "charger": "000.000.000-00",
    "charged": "00.000.000/0000-00",
    "message": "Cobrança encontra-se em status 'Pagamento confirmado' e não pode ser cancelada."
}

Exemplo de chamada:

cURL

curl --location --request DELETE 'https://api-hlg.blu.com.br/b2b/payment-collections/{uuid}' \
--header 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXX'

NodeJS

var request = require('request');
var options = {
  'method': 'DELETE',
  'url': 'https://api-hlg.blu.com.br/b2b/payment-collections/{uuid}',
  'headers': {
    'Authorization': 'Bearer XXXXXXXXXXXXXXXXXXXXXXX'
  }
};
request(options, function (error, response) { 
  if (error) throw new Error(error);
  console.log(response.body);
});

Enviar Faturamento

POST /payment-collections/{uuid}/payment-plans

Permite o envio de informações relacionadas ao faturamento de um pedido/cobrança específica. Após o envio dessas informações, na API GET Consultar Cobrança, nos dados da "installments_of_charger", será possível consultar todos os dados dos pagamentos. O faturamento de um pedido/cobrança somente poderá ser realizando se este foi criado com a opção de faturamento ("billing_later": true), já encontra-se aprovado e não esteja pago ("status_code": 8).

Path Parameters

Name	Type	Description
uuid	string	Identificador único do pedido/cobrança

Headers

Name	Type	Description
Authorization	string	Bearer token.

Request Body

Name	Type	Description
type	string	Tipo do documento (nota fiscal, boleto, título).
key	string	Chave de autorização da nota fiscal.
invoice_number	string	Número do documento (nota fiscal, boleto, título).
value	string	Valor do documento.
date	string	Data de envio dos dados do faturamento ou vencimento do documento.

200 Solicitação de faturamento em processamento.

OK

{
    "uuid": "<identificador-único>",
    "invoice_number": "XXXXXX-XXXXXX-XXXXX",
    "value": "0.00",
    "date": "aaaa-mm-dd",    
    "message": "Faturamento registrado com sucesso."
}

NOK

{
    "message": "Nenhuma cobrança encontrada para os dados informados."
}

Exemplo de chamada:

Exemplo Body

{
    "payment_plans": {
        "type": "",
        "key": "",
        "invoice_number": "XXXXXX-XXXXXX-XXXXX",
        "value": "0.00",
        "date": "aaaa-mm-dd"
    }
}

cURL

curl --location --request POST 'https://api-hlg.blu.com.br/b2b/payment-collections/{uuid}/payment-plans' \
--header 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--data-raw '{
    "payment_plans":{
       "type": "",
       "key": "",
       "value": "0.00",
       "invoice_number": "XXXXXX-XXXXXX-XXXXX",
       "date": "AAAA-MM-DD"
    }
}'

NodeJs

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://api-hlg.blu.com.br/b2b/payment-collections/{uuid}/payment-plans',
  'headers': {
    'Authorization': 'Bearer XXXXXXXXXXXXXXXXXXXXXXX',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({"payment_plans":{"type":"","key":"","value":"0.00","invoice_number":"XXXXXX-XXXXXX-XXXXX","date":"AAAA-MM-DD"}})

};
request(options, function (error, response) { 
  if (error) throw new Error(error);
  console.log(response.body);
});

Cancelar Faturamento

DELETE /payment-collections/{uuid}/payment-plans/{payment_plan_uuid}

Permite realizar o cancelamento do faturamento de um pedido/cobrança. O cancelamento de um faturamento somente poderá ser realizado em pedidos/cobranças que já estejam aprovados e ainda não estejam pagos ("status_code": 8).

Path Parameters

Name	Type	Description
uuid	string	Identificador único do pedido/cobrança.
payment_plan_uuid	string	Identificador único do faturamento.

Headers

Name	Type	Description
Authorization	string	Bearer token.

200 Solicitação de cancelamento de fatura em processamento.

OK

{
    "uuid": "<uuid-do-pedido/cobrança>",
    "document_number": "",
    "charger": "00000000000",
    "value": "0.00",
    "message": "Nota xxxxxxxxxx-xxxxxxx-xxxxxx-xxxxx-xxxxxxxxxx será cancelada. Invoice_number: Número-Faturamento. O valor recebido será devolvido e voltará para o saldo a faturar."
}

NOK

{
    "uuid": "<uuid-do-pedido/cobrança>",
    "document_number": "",
    "charger": "000000000000",
    "value": "0.00",
    "message": "A Cobrança encontra-se em status 3 - Pagamento confirmado - Não é possível cancelar o faturamento de uma cobrança no status 3 - Pagamento confirmado"
}

Exemplo de chamada:

cURL

curl --location --request DELETE 'https://api-hlg.blu.com.br/b2b/payment-collections/{uuid}/payment-plans/{payment_plan_uuid}' \
--header 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXX'

NodeJs

var request = require('request');
var options = {
  'method': 'DELETE',
  'url': 'https://api-hlg.blu.com.br/b2b/payment-collections/{uuid}/payment-plans/{payment_plan_uuid}',
  'headers': {
    'Authorization': 'Bearer XXXXXXXXXXXXXXXXXXXXXXX'
  }
};
request(options, function (error, response) { 
  if (error) throw new Error(error);
  console.log(response.body);
});

Enviar Devolução

POST /payment-collections/{uuid}/refund

Permite realizar a devolução do valor empenhado para o pagamento do pedido/cobrança ao lojista/cobrado. A devolução parcial ou total de um pedido/cobrança, somente poderá ser realizada se este encontra-se aprovado e ainda não esteja pago ("status_code": 8).

Path Parameters

Name	Type	Description
uuid	string	Identificador único do pedido/cobrança.

Headers

Name	Type	Description
Authorization	string	Bearer token.

200

OK

{
    "uuid": "<identificador-único>",
    "document_number": "",
    "charger": "00000000000",
    "value": "0.00",
    "message": "Faturamento será finalizado, o valor remanescente será devolvido ao cobrado"
}

NOK

{
    "uuid": "<identificador-único>",
    "document_number": "",
    "charger": "00000000000",
    "value": "0.00    ",
    "message": "Cobrança encontra-se em status 'Pagamento confirmado' e saldo à faturar não pode ser devolvido"
}

cURL

curl --location --request POST 'https://api-hlg.blu.com.br/b2b/payment-collections/{uuid}/refund' \
--header 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXX'

NodeJs

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://api-hlg.blu.com.br/b2b/payment-collections/{uuid}/refund',
  'headers': {
    'Authorization': 'Bearer XXXXXXXXXXXXXXXXXXXXXXX'
  }
};
request(options, function (error, response) { 
  if (error) throw new Error(error);
  console.log(response.body);
});

Consultar Conciliação Financeira

GET /payment-collections/reconciliation

Retorna a conciliação financeira, ou seja, todos os pagamentos efetuados na determinada data ("date": "aaaa-mm-dd"); e ou determinado pedido/cobrança ("document_number": "xxx-xx"); e ou determinado número de documento de faturamento ("invoice_number": "xxxx-xxxx-xxxx"), que foram enviados para a consulta. Caso não seja informado nenhum dos parâmetros, será retornado todos os pagamentos efetuados na data do dia da consulta menos um, ou seja D-1. É importante salientar que, a consulta sempre será ao passado, considerando o dia atual menos um (D-1) em diante.

Query Parameters

Name	Type	Description
document_number	string	Número do pedido/cobrança.
invoice_number	string	Número do documento de faturamento.
date	string	Data do pagamento. Formato AAAA-MM-DD.

Headers

Name	Type	Description
Authorization	string	Bearer token.

200

OK

[
    {
        "payment_id": "<identificador-parcela>",
        "transaction_id": "<identificador-transacao>",
        "document_number": "XXXX-XX",
        "invoice_number": "XXXXXX-XXXXXX-XXXXX",
        "charged": "000.000.000-00",
        "date": "aaaa-mm-dd"
        "value": "0.00",
        "monetary_paidout": "0.00",
        "monetary_anticipation": "0.00",
        "standard_rate_value": "0.00"
    }
]

NOK

{
    "message": "Nenhuma informação encontrada para os dados informados."
}

Exemplo de chamada:

cURL

curl --location --request GET 'https://api-hlg.blu.com.br/b2b/payment-collections/reconciliation?document_number=XXXX-XX&date=AAAA-MM-DD&invoice_number=XXXXXX-XXXXXX-XXXXX' \
--header 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXX'

NodeJs

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://api-hlg.blu.com.br/b2b/payment-collections/reconciliation?document_number=XXXX-XX&date=AAAA-MM-DD&invoice_number=XXXXXX-XXXXXX-XXXXX',
  'headers': {
    'Authorization': 'Bearer XXXXXXXXXXXXXXXXXXXXXXX'
  }
};
request(options, function (error, response) { 
  if (error) throw new Error(error);
  console.log(response.body);
});

Descrição dos campos de retorno da conciliação financeira

Campo	Data Type	Descrição
payment_id	string	Identificador único da parcela.
transaction_id	string	Identificador único da transação.
invoice_number	string	Número do documento de faturamento.
charged	string	CNPJ/CPF do lojista/cobrado.
date	string	Data do pagamento.
value	string	Valor bruto da parcela.
monetary_paidout	string	Valor líquido da parcela.
monetary_anticipation	string	Valor pago pela antecipação.
standart_rate_value	string	Valor pago pelo seguro inadimplência.

Download Collection Postman (pacote de APIs)

Segue abaixo o link para download da coleção de APIs no Postman.

5KB

BLU B2B.postman_collection.json