Cobranças com vencimento

O conjunto de endpoints a seguir é responsável pela gestão de cobranças com vencimento. As cobranças, no contexto da API Pix, representam uma transação financeira entre um pagador e um recebedor, cuja forma de pagamento é o Pix.

Criar cobrança com vencimento

Endpoint para cadastrar uma cobrança com vencimento e um identificador de transação (txid).

PUT /v2/cobv/:txid

Requer autorização para o escopo: cobv.write

Requisição

Exemplo 1

{
  "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."
}

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"
        }
      ]
    }
  },
  "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

{
  "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."
}

🔴 400

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"
    }
  ]
}

🔴 403

{
  "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."
}

🔴 404

{
  "type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
  "title": "Não Encontrado",
  "status": 404,
  "detail": "Entidade não encontrada."
}

🔴 503

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

Requer autorização para o escopo: cobv.write

Requisição

Exemplo 1

{
  "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."
}

Exemplo 2

{
  "valor": {
    "original": "567.89"
  },
  "solicitacaoPagador": "Informar cartão fidelidade"
}

Exemplo 3

{
  "status": "REMOVIDA_PELO_USUARIO_RECEBEDOR"
}

Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

🟢 200

{
  "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."
}

🔴 400

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

🔴 403

{
  "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."
}

🔴 404

{
  "type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
  "title": "Não Encontrado",
  "status": 404,
  "detail": "Entidade não encontrada."
}

🔴 503

{
  "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

Requer autorização para o escopo: 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 param revisao. 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

{
  "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."
}

🔴 403

{
  "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."
}

🔴 404

{
  "type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
  "title": "Não Encontrado",
  "status": 404,
  "detail": "Entidade não encontrada."
}

🔴 503

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

Requer autorização para o escopo: 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 datas inicio e fim) e o formato em que esses parâmetros devem ser repassados.

/v2/cob?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

{
  "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"
      }
    },
    {
      "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"
      }
    }
  ]
}

🔴 403

{
  "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."
}

🔴 503

{
  "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."
}