Pular para o conteúdo principal

Cobranças em Lote

O conjunto de endpoints a seguir é responsável pela gestão de cobranças em lote. 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.


Cobranças com vencimento em lote​

Reúne endpoints destinados a lidar com gerenciamento de cobranças com vencimento em lote.

Criar/Alterar lote de cobranças com vencimento​

Endpoint utilizado para criar ou alterar um lote de cobranças com vencimento.

Informação

Uma solicitação de criação de cobrança com status "EM_PROCESSAMENTO" ou "NEGADA" está associada a uma cobrança não existe de fato, portanto não será listada em GET /cobv ou GET /cobv/:txid.

Uma cobrança, uma vez criada via PUT /cobv/:txid, não pode ser associada a um lote posteriormente.

Uma cobrança, uma vez criada via PUT /lotecobv/:id, não pode ser associada a um novo lote posteriormente.

A criação do lote deve conter pelo menos 1 cobrança e no máximo 1000.


Dica

Após a geração da cobrança em lote, você pode utilizar o endpoint de Consultar lista de cobranças com vencimento, informado o parâmetro loteCobvId para retornar as informações do lote.


PUT /v2/lotecobv/:id
Requer autorização para o escopo: lotecobv.read


Para o caso de uso de alteração de cobranças, o array a ser atribuído na requisicão deve ser composto pelas exatas requisições de criação de cobranças que constaram no array atribuído na requisição originária.

Não se pode utilizar este endpoint para alterar um lote de cobranças com vencimento agregando ou removendo cobranças já existentes dentro do conjunto de cobranças criadas na requisição originária do lote.

Em outras palavras, se originalmente criou-se um lote, por exemplo, com as cobranças [a, b e c], não se pode alterar esse conjunto de cobranças original que o lote representa para [a, b, c, d], ou para [a, b]. Por outro lado, pode-se alterar, em lote as cobranças [a, b, c], conforme originalmente constam na requisição originária do lote.


Requisição

{
  "descricao": "Cobranças dos alunos do turno vespertino",
  "cobsv": [
    {
      "calendario": {
          "dataDeVencimento": "2020-12-31",
          "validadeAposVencimento": 30
      },
      "txid": "fb2761260e554ad593c7226beb5cb650",
      "devedor": {
          "cpf": "08577095428",
          "nome": "João Souza"
      },
      "valor": {
          "original": "100.00"
      },
      "chave": "7c084cd4-54af-4172-a516-a7d1a12b75cc",
      "solicitacaoPagador": "Informar matrícula"
      },
      {
      "calendario": {
          "dataDeVencimento": "2020-12-31",
          "validadeAposVencimento": 30
      },
      "txid": "7978c0c97ea847e78e8849634473c1f1",
      "devedor": {
          "cpf": "15311295449",
          "nome": "Manoel Silva"
      },
      "valor": {
          "original": "100.00"
      },
      "chave": "7c084cd4-54af-4172-a516-a7d1a12b75cc",
      "solicitacaoPagador": "Informar matrícula"
    }
  ]
}

Respostas

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

Lote de cobranças com vencimento solicitado para criação.

Revisar cobranças específicas de um lote​

Endpoint utilizado para revisar cobranças específicas dentro de um lote de cobranças com vencimento.

Informação

A diferença deste endpoint para o endpoint PUT correlato é que este endpoint admite um array cobsv com menos solicitações de criação ou alteração de cobranças do que o array atribuído na requisição originária do lote.

Não se pode, entretanto, utilizar esse endpoint para agregar ou remover solicitações de alteração ou criação de cobranças conforme constam na requisição originária do lote.


PATCH /v2/lotecobv/:id
Requer autorização para o escopo: lotecobv.read


Requisição

{
  "cobsv": [
    {
      "calendario": {
        "dataDeVencimento": "2020-01-10"
      },
      "txid": "fb2761260e554ad593c7226beb5cb650",
      "valor": {
        "original": "110.00"
      }
    },
    {
      "calendario": {
        "dataDeVencimento": "2020-01-10"
      },
      "txid": "7978c0c97ea847e78e8849634473c1f1",
      "valor": {
        "original": "110.00"
      }
    }
  ]
}


Respostas

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

Solicitação de revisão do Lote de cobranças encaminhada para processamento.

Consultar lote de cobranças com vencimento.​

Endpoint para consultar um lote específico de cobranças com vencimento.

GET /v2/lotecobv/:id
Requer autorização para o escopo: lotecobv.write


Respostas

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

{
  "descricao": "Cobranças dos alunos do turno vespertino",
  "criacao": "2020-11-01T20:15:00.358Z",
  "cobsv": [
    {
      "criacao": "2020-11-01T20:15:00.358Z",
      "txid": "fb2761260e554ad593c7226beb5cb650",
      "status": "CRIADA"
    },
    {
      "txid": "7978c0c97ea847e78e8849634473c1f1",
      "status": "NEGADA",
      "problema": {
        "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"
          }
        ]
      }
    }
  ]
}

Consultar lista de lotes 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/lotecobv
Requer autorização para o escopo: lotecobv.write


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/lotecobv?inicio=2023-01-01T16:01:35Z&fim=2023-12-30T16:01:35Z

Respostas

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

{
  "parametros": {
    "inicio": "2020-01-01T00:00:00Z",
    "fim": "2020-12-01T23:59:59Z",
    "paginacao": {
      "paginaAtual": 0,
      "itensPorPagina": 100,
      "quantidadeDePaginas": 1,
      "quantidadeTotalDeItens": 2
    }
  },
  "lotes": [
    {
      "$ref": "openapi.yaml#/components/examples/loteCobVResponse1/value"
    },
    {
      "$ref": "openapi.yaml#/components/examples/loteCobVResponse2/value"
    }
  ]
}
Última atualização em