Cobranças com vencimento
Para testar os endpoints de cobrança Pix Cobv em ambiente de homologação, é possível simular todos os status retornados pela nossa API e webhook.
Cobranças com valor entre R$ 0.01 à R$ 10.00 são confirmadas, e você receberá a informação via Webhook.
Cobranças com valor acima de R$ 10.00 permanecem ativas, sem confirmação, e não há webhook nesses casos.
Criar cobrança com vencimento
Endpoint para cadastrar uma cobrança com vencimento e um identificador de transação (txid
).
PUT /v2/cobv/:txid
cobv.write
Requisição
- Exemplo 1
- Exemplo 2 (loc)
{
"calendario": {
"dataDeVencimento": "2022-12-01",
"validadeAposVencimento": 30
},
"devedor": {
"logradouro": "Alameda Souza, Numero 80, Bairro Braz",
"cidade": "Recife",
"uf": "PE",
"cep": "70011750",
"cpf": "12345678909",
"nome": "Francisco da Silva"
},
"valor": {
"original": "123.45",
"multa": {
"modalidade": 2,
"valorPerc": "15.00"
},
"juros": {
"modalidade": 2,
"valorPerc": "2.00"
},
"desconto": {
"modalidade": 1,
"descontoDataFixa": [
{
"data": "2022-11-30",
"valorPerc": "30.00"
}
]
}
},
"chave": "5f84a4c5-c5cb-4599-9f13-7eb4d419dacc",
"solicitacaoPagador": "Cobrança dos serviços prestados."
}
{
"calendario": {
"dataDeVencimento": "2022-12-01",
"validadeAposVencimento": 30
},
"devedor": {
"logradouro": "Alameda Souza, Numero 80, Bairro Braz",
"cidade": "Recife",
"uf": "PE",
"cep": "70011750",
"cpf": "12345678909",
"nome": "Francisco da Silva"
},
"valor": {
"original": "123.45",
"multa": {
"modalidade": 2,
"valorPerc": "15.00"
},
"juros": {
"modalidade": 2,
"valorPerc": "2.00"
},
"desconto": {
"modalidade": 1,
"descontoDataFixa": [
{
"data": "2022-11-30",
"valorPerc": "30.00"
}
]
}
},
"loc": {
"id": 1
},
"chave": "5f84a4c5-c5cb-4599-9f13-7eb4d419dacc",
"solicitacaoPagador": "Cobrança dos serviços prestados."
}
Respostas
As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.
- 🟢 201
- 🔴 400
- 🔴 403
- 🔴 404
- 🔴 503
{
"calendario": {
"criacao": "2020-09-09T20:15:00.358Z",
"dataDeVencimento": "2020-12-31",
"validadeAposVencimento": 30
},
"txid": "7978c0c97ea847e78e8849634473c1f1",
"revisao": 0,
"loc": {
"id": 789,
"location": "pix.example.com/qr/c2/cobv/9d36b84fc70b478fb95c12729b90ca25",
"tipoCob": "cobv"
},
"status": "ATIVA",
"devedor": {
"logradouro": "Alameda Souza, Numero 80, Bairro Braz",
"cidade": "Recife",
"uf": "PE",
"cep": "70011750",
"cpf": "12345678909",
"nome": "Francisco da Silva"
},
"recebedor": {
"logradouro": "Rua 15 Numero 1200, Bairro São Luiz",
"cidade": "São Paulo",
"uf": "SP",
"cep": "70800100",
"cnpj": "56989000019533",
"nome": "Empresa de Logística SA"
},
"valor": {
"original": "123.45"
},
"chave": "5f84a4c5-c5cb-4599-9f13-7eb4d419dacc",
"solicitacaoPagador": "Cobrança dos serviços prestados.",
"pixCopiaECola": "00020101021226880014BR.GOV.BCB.PIX2116qrcodespix.sejaefi.com.br/v2/cobv/c24c8d65fd024836bc7bac75d5c4002f5204000053039865802BR5905EFISA6008SAOPAULO62070503***6304C225"
}
InvalidOperationError
{
"type": "https://pix.bcb.gov.br/api/v2/error/CobVOperacaoInvalida",
"title": "Cobrança inválida.",
"status": 400,
"detail": "A requisição que busca alterar ou criar uma cobrança com vencimento não respeita o _schema_ ou está semanticamente errada.",
"violacoes": [
{
"razao": "O objeto cobv.devedor não respeita o _schema_.",
"propriedade": "cobv.devedor"
}
]
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/AcessoNegado",
"title": "Acesso Negado",
"status": 403,
"detail": "Requisição de participante autenticado que viola alguma regra de autorização."
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
"title": "Não Encontrado",
"status": 404,
"detail": "Entidade não encontrada."
}
ApplicationError
{
"type": "https://pix.bcb.gov.br/api/v2/error/ServicoIndisponivel",
"title": "Serviço Indisponível",
"status": 503,
"detail": "Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento."
}
Revisar cobrança com vencimento
Endpoint para revisar (modificar) uma cobrança a partir do seu txid
.
PATCH /v2/cobv/:txid
cobv.write
Requisição
- Exemplo 1
- Exemplo 2
- Exemplo 3
{
"loc": {
"id": 789
},
"devedor": {
"logradouro": "Alameda Souza, Numero 80, Bairro Braz",
"cidade": "Recife",
"uf": "PE",
"cep": "70011750",
"cpf": "12345678909",
"nome": "Francisco da Silva"
},
"valor": {
"original": "123.45"
},
"solicitacaoPagador": "Cobrança dos serviços prestados."
}
{
"valor": {
"original": "567.89"
},
"solicitacaoPagador": "Informar cartão fidelidade"
}
{
"status": "REMOVIDA_PELO_USUARIO_RECEBEDOR"
}
Respostas
As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.
- 🟢 200
- 🔴 400
- 🔴 403
- 🔴 404
- 🔴 503
{
"calendario": {
"criacao": "2020-09-09T20:15:00.358Z",
"dataDeVencimento": "2020-12-31",
"validadeAposVencimento": 30
},
"txid": "7978c0c97ea847e78e8849634473c1f1",
"revisao": 0,
"loc": {
"id": 789,
"location": "pix.example.com/qr/c2/cobv/9d36b84fc70b478fb95c12729b90ca25",
"tipoCob": "cobv"
},
"status": "ATIVA",
"devedor": {
"logradouro": "Alameda Souza, Numero 80, Bairro Braz",
"cidade": "Recife",
"uf": "PE",
"cep": "70011750",
"cpf": "12345678909",
"nome": "Francisco da Silva"
},
"recebedor": {
"logradouro": "Rua 15 Numero 1200, Bairro São Luiz",
"cidade": "São Paulo",
"uf": "SP",
"cep": "70800100",
"cnpj": "56989000019533",
"nome": "Empresa de Logística SA"
},
"valor": {
"original": "123.45"
},
"chave": "5f84a4c5-c5cb-4599-9f13-7eb4d419dacc",
"solicitacaoPagador": "Cobrança dos serviços prestados.",
"pixCopiaECola": "00020101021226880014BR.GOV.BCB.PIX2116qrcodespix.sejaefi.com.br/v2/cobv/c24c8d65fd024836bc7bac75d5c4002f5204000053039865802BR5905EFISA6008SAOPAULO62070503***6304C225"
}
UnknownRegisterError
{
"type": "https://pix.bcb.gov.br/api/v2/error/CobVOperacaoInvalida",
"title": "Operação inválida.",
"status": 400,
"detail": "Cobrança não encontra-se mais com o status ATIVA, somente cobranças ativas podem ser revisadas."
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/AcessoNegado",
"title": "Acesso Negado",
"status": 403,
"detail": "Requisição de participante autenticado que viola alguma regra de autorização."
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
"title": "Não Encontrado",
"status": 404,
"detail": "Entidade não encontrada."
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/ServicoIndisponivel",
"title": "Serviço Indisponível",
"status": 503,
"detail": "Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento."
}
Consultar cobrança com vencimento
Endpoint para consultar uma cobrança com vencimento a partir do txid.
GET /v2/cobv/:txid
cobv.read
Requisição
Também é possível consultar informações de uma revisão específica de uma cobrança. Para isso é necessário informar o query paramrevisao
. Exemplo: /v2/cobv/:txid/?revisao=1
. Quando o parâmetro não é informado, a revisão mais recente é retornada como padrão.Respostas
As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.
- 🟢 200
- 🔴 403
- 🔴 404
- 🔴 503
{
"calendario": {
"criacao": "2020-09-09T20:15:00.358Z",
"dataDeVencimento": "2020-12-31",
"validadeAposVencimento": 30
},
"txid": "7978c0c97ea847e78e8849634473c1f1",
"revisao": 0,
"loc": {
"id": 789,
"location": "pix.example.com/qr/c2/cobv/9d36b84fc70b478fb95c12729b90ca25",
"tipoCob": "cobv"
},
"status": "ATIVA",
"devedor": {
"logradouro": "Alameda Souza, Numero 80, Bairro Braz",
"cidade": "Recife",
"uf": "PE",
"cep": "70011750",
"cpf": "12345678909",
"nome": "Francisco da Silva"
},
"recebedor": {
"logradouro": "Rua 15 Numero 1200, Bairro São Luiz",
"cidade": "São Paulo",
"uf": "SP",
"cep": "70800100",
"cnpj": "56989000019533",
"nome": "Empresa de Logística SA"
},
"valor": {
"original": "123.45"
},
"chave": "5f84a4c5-c5cb-4599-9f13-7eb4d419dacc",
"solicitacaoPagador": "Cobrança dos serviços prestados.",
"pixCopiaECola": "00020101021226880014BR.GOV.BCB.PIX2116qrcodespix.sejaefi.com.br/v2/cobv/c24c8d65fd024836bc7bac75d5c4002f5204000053039865802BR5905EFISA6008SAOPAULO62070503***6304C225"
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/AcessoNegado",
"title": "Acesso Negado",
"status": 403,
"detail": "Requisição de participante autenticado que viola alguma regra de autorização."
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
"title": "Não Encontrado",
"status": 404,
"detail": "Entidade não encontrada."
}
UnknownRegisterError
{
"type": "https://pix.bcb.gov.br/api/v2/error/ServicoIndisponivel",
"title": "Serviço Indisponível",
"status": 503,
"detail": "Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento."
}
Consultar lista de cobranças com vencimento
Endpoint para consultar cobranças com vencimento através de parâmetros como início, fim, cpf, cnpj e status.
GET /v2/cobv
cobv.read
Requisição
O trecho de código abaixo ilustra o consumo do endpoint em uma requisição com o mínimo de parâmetros possível (o intervalo de datasinicio
e fim
) e o formato em que esses parâmetros devem ser repassados./v2/cobv?inicio=2020-10-22T16:01:35Z&fim=2020-11-30T20:10:00Z
Respostas
As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.
- 🟢 200
- 🔴 403
- 🔴 503
{
"parametros": {
"inicio": "2022-01-01T23:59:59.000Z",
"fim": "2022-12-31T23:59:59.000Z",
"paginacao": {
"paginaAtual": 0,
"itensPorPagina": 100,
"quantidadeDePaginas": 1,
"quantidadeTotalDeItens": 13
}
},
"cobs": [
{
"calendario": {
"criacao": "2022-11-12T18:32:10.000Z",
"dataDeVencimento": "2090-12-31",
"validadeAposVencimento": 90
},
"txid": "31a0baG77448041d64352h4523459",
"revisao": 1,
"status": "ATIVA",
"devedor": {
"nome": "Empreendimentos",
"cnpj": "53747188000100"
},
"recebedor": {
"logradouro": "Rua 15 Numero 1200, Bairro São Luiz",
"cidade": "São Paulo",
"uf": "SP",
"cep": "70800100",
"cnpj": "56989000019533",
"nome": "Empresa de Logística SA"
},
"valor": {
"original": "123.45",
"juros": {
"modalidade": 2,
"valorPerc": "0.30"
},
"multa": {
"modalidade": 2,
"valorPerc": "2.00"
},
"desconto": {
"modalidade": 1,
"descontoDataFixa": [
{
"data": "2022-10-15",
"valorPerc": "30.00"
}
]
}
},
"chave": "5f84a6c5-c5cb-4569-9f13-7eb4d410dacc",
"solicitacaoPagador": "Cobrança dos serviços prestados.",
"infoAdicionais": [
{
"nome": "Campo 1",
"valor": "Informação Adicional1"
},
{
"nome": "Campo 2",
"valor": "Informação Adicional2"
}
],
"loc": {
"id": 220,
"location": "qrcodes-pix.gerencianet.com.br/v2/cobv/ba942520ab0746cfae2858d9afe485fd0",
"tipoCob": "cobv",
"criacao": "2022-11-12T18:32:10.000Z"
},
"pixCopiaECola": "00020101021226880014BR.GOV.BCB.PIX2116qrcodespix.sejaefi.com.br/v2/cobv/c24c8d65fd024836bc7bac75d5c4002f5204000053039865802BR5905EFISA6008SAOPAULO62070503***6304C2"
},
{
"calendario": {
"criacao": "2022-10-27T17:30:59.000Z",
"dataDeVencimento": "2022-12-31",
"validadeAposVencimento": 30
},
"txid": "7976c0c97ea847578e8845634473c1f2",
"revisao": 0,
"status": "ATIVA",
"devedor": {
"logradouro": "Alameda Souza, Numero 80, Bairro Braz",
"cidade": "Recife",
"uf": "PE",
"cep": "70011750",
"cpf": "12345678909",
"nome": "Francisco da Silva"
},
"recebedor": {
"logradouro": "Rua 15 Numero 1200, Bairro São Luiz",
"cidade": "São Paulo",
"uf": "SP",
"cep": "70800100",
"cnpj": "56989000019533",
"nome": "Empresa de Logística SA"
},
"valor": {
"original": "100.00",
"juros": {
"modalidade": 1,
"valorPerc": "0.25"
},
"multa": {
"modalidade": 2,
"valorPerc": "2.00"
},
"abatimento": {
"modalidade": 1,
"valorPerc": "5.00"
},
"desconto": {
"modalidade": 3,
"valorPerc": "1.00"
}
},
"chave": "5f84a6c5-c5cb-4569-9f13-7eb4d410dacc",
"solicitacaoPagador": "Informe o número ou identificador do pedido.",
"loc": {
"id": 215,
"location": "qrcodes-pix.gerencianet.com.br/v2/cobv/68ae6f11868040ce980d6803ff6d904d",
"tipoCob": "cobv",
"criacao": "2022-10-27T17:30:59.000Z"
},
"pixCopiaECola": "00020101021226880014BR.GOV.BCB.PIX2116qrcodespix.sejaefi.com.br/v2/cobv/c24c8d65fd024836bc7bac75d5c4002f5204000053039865802BR5905EFISA6008SAOPAULO62070503***6304C2",
}
]
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/AcessoNegado",
"title": "Acesso Negado",
"status": 403,
"detail": "Requisição de participante autenticado que viola alguma regra de autorização."
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/ServicoIndisponivel",
"title": "Serviço Indisponível",
"status": 503,
"detail": "Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento."
}