Skip to main content

Batch charges

The following set of endpoints is responsible for managing batch charges.


Create batch of due charges​

Endpoint used to create a batch of due charges (lotecobv) for mass processing.

Batch Characteristics:
  • Asynchronous processing: The batch is processed in the background
  • Custom ID: Unique identifier provided by the PSP
  • Multiple charges: Up to 1000 charges per batch
  • Individual validation: Each charge is validated separately
  • Batch status: Monitoring of the processing
Advantages of Batch Processing:
  • Efficiency: Processes multiple charges at once
  • Performance: Reduces overhead from multiple individual requests
  • Control: Centralized monitoring of processing
  • Partial atomicity: Valid charges are created even if others fail
Processing Flow:
  • 1. Submission: Batch is sent for processing
  • 2. Validation: Each charge is validated individually
  • 3. Processing: Valid charges are created
  • 4. Result: Detailed status of each charge in the batch
Validations per Charge:
  • All validations applicable to individual charges
  • Unique TxId within the batch and globally
  • Complete required data for each charge
Important!

Processing is asynchronous. Use the query endpoint to check the status.


PUT /v1/lotecobv/:id
Requires authorization for the scope: lotecobv.ind.read


Request

{
    "customId": 123,
    "description": "Lote de faturas de dezembro 2023",
    "datedCharges": [
      {
        "txid": "fb2761260e054c7a94fb7b7b01",
        "calendario": {
          "dataDeVencimento": "2023-12-31",
          "validadeAposVencimento": 30
        },
        "devedor": {
          "nome": "João Silva Santos",
          "cpf": "12345678901",
          "logradouro": "Rua das Flores, 123",
          "cidade": "São Paulo",
          "uf": "SP",
          "cep": "01234567"
        },
        "recebedor": {
          "nome": "Empresa XYZ Ltda",
          "cnpj": "98765432000123",
          "logradouro": "Av. Paulista, 1000",
          "cidade": "São Paulo",
          "uf": "SP",
          "cep": "01310100"
        },
        "valor": {
          "original": "100.50"
        },
        "chave": "+5561988887777",
        "solicitacaoPagador": "Fatura #001 do lote",
        "infoAdicionais": [
          {
            "nome": "Lote",
            "valor": "123"
          }
        ]
      },
      {
        "txid": "fb2761260e054c7a94fb7b7b02",
        "calendario": {
          "dataDeVencimento": "2023-12-31",
          "validadeAposVencimento": 30
        },
        "devedor": {
          "nome": "Maria Silva",
          "cpf": "98765432100",
          "logradouro": "Av. Brasil, 456",
          "cidade": "Rio de Janeiro",
          "uf": "RJ",
          "cep": "20040020"
        },
        "recebedor": {
          "nome": "Empresa XYZ Ltda",
          "cnpj": "98765432000123",
          "logradouro": "Av. Paulista, 1000",
          "cidade": "São Paulo",
          "uf": "SP",
          "cep": "01310100"
        },
        "valor": {
          "original": "250.00",
          "juros": {
            "modalidade": 2,
            "valorPerc": "0.033"
          },
          "multa": {
            "modalidade": 2,
            "valorPerc": "2.00"
          }
        },
        "chave": "[email protected]",
        "solicitacaoPagador": "Fatura #002 do lote"
      }
    ]
}

Responses

The responses below represent Success(202) from the consumption.

{
  "loteCobvId": 123,
  "status": "EM_PROCESSAMENTO",
  "customId": 123,
  "description": "Lote de faturas de dezembro 2023",
  "quantidadeCobrancas": 2,
  "criadoEm": "2023-10-15T14:30:00Z"
  }

Get batch of due charges​

Endpoint to retrieve detailed information of a specific batch and the processing status of its charges.

Use Cases:
  • Monitoring: Track the progress of processing
  • Auditing: Verify successfully created charges
  • Correction: Identify charges with errors for reprocessing
  • Reconciliation: Validate that all charges were processed
GET /v1/lotecobv/:id
Requires authorization for the scope: lotecobv.ind.read


Responses

The responses below represent Success(200) and failures/errors from consumption.

// Batch processed successfully
{
  "loteCobvId": 123,
  "customId": 123,
  "description": "Lote de faturas de dezembro 2023",
  "status": "PROCESSADO",
  "criadoEm": "2023-10-15T14:30:00Z",
  "processadoEm": "2023-10-15T14:35:00Z",
  "estatisticas": {
    "total": 3,
    "processadas": 3,
    "criadas": 2,
    "comErro": 1,
    "pendentes": 0
  },
  "cobrancas": [
    {
      "txid": "fb2761260e054c7a94fb7b7b01",
      "status": "CRIADA",
      "criadaEm": "2023-10-15T14:32:00Z",
      "cobranca": {
        "txid": "fb2761260e054c7a94fb7b7b01",
        "status": "ATIVA",
        "valor": {
          "original": "100.50"
        },
        "loc": {
          "id": 789,
          "location": "pix.example.com/qr/v2/cobv/fb2761260e054c7a94fb7b7b01"
        }
      }
    },
    {
      "txid": "fb2761260e054c7a94fb7b7b02",
      "status": "CRIADA",
      "criadaEm": "2023-10-15T14:33:00Z",
      "cobranca": {
        "txid": "fb2761260e054c7a94fb7b7b02",
        "status": "ATIVA",
        "valor": {
          "original": "250.00"
        },
        "loc": {
          "id": 790,
          "location": "pix.example.com/qr/v2/cobv/fb2761260e054c7a94fb7b7b02"
        }
      }
    },
    {
      "txid": "fb2761260e054c7a94fb7b7b03",
      "status": "ERRO",
      "erro": {
        "codigo": "INVALID_CPF",
        "mensagem": "CPF informado é inválido",
        "detalhes": [
          "CPF deve conter 11 dígitos",
          "CPF não pode estar em branco"
        ]
      }
    }
  ]
}

Review specific charges in a batch​

Endpoint used to review specific charges within a due-date charge batch.

PATCH /v1/lotecobv/:id
Requires authorization for the scope: lotecobv.ind.read


Request

{
  "customId": 123,
  "description": "Lote de faturas de dezembro 2023",
  "datedCharges": [
    {
      "txid": "fb2761260e054c7a94fb7b7b01",
      "calendario": {
        "dataDeVencimento": "2023-12-31",
        "validadeAposVencimento": 30
      },
      "devedor": {
        "nome": "João Silva Santos",
        "cpf": "12345678901",
        "logradouro": "Rua das Flores, 123",
        "cidade": "São Paulo",
        "uf": "SP",
        "cep": "01234567"
      },
      "recebedor": {
        "nome": "Empresa XYZ Ltda",
        "cnpj": "98765432000123",
        "logradouro": "Av. Paulista, 1000",
        "cidade": "São Paulo",
        "uf": "SP",
        "cep": "01310100"
      },
      "valor": {
        "original": "100.50"
      },
      "chave": "+5561988887777",
      "solicitacaoPagador": "Fatura #001 do lote",
      "infoAdicionais": [
        {
          "nome": "Lote",
          "valor": "123"
        }
      ]
    },
    {
      "txid": "fb2761260e054c7a94fb7b7b02",
      "calendario": {
        "dataDeVencimento": "2023-12-31",
        "validadeAposVencimento": 30
      },
      "devedor": {
        "nome": "Maria Silva",
        "cpf": "98765432100",
        "logradouro": "Av. Brasil, 456",
        "cidade": "Rio de Janeiro",
        "uf": "RJ",
        "cep": "20040020"
      },
      "recebedor": {
        "nome": "Empresa XYZ Ltda",
        "cnpj": "98765432000123",
        "logradouro": "Av. Paulista, 1000",
        "cidade": "São Paulo",
        "uf": "SP",
        "cep": "01310100"
      },
      "valor": {
        "original": "250.00",
        "juros": {
          "modalidade": 2,
          "valorPerc": "0.033"
        },
        "multa": {
          "modalidade": 2,
          "valorPerc": "2.00"
        }
      },
      "chave": "[email protected]",
      "solicitacaoPagador": "Fatura #002 do lote"
    }
  ]
}

Responses

The responses below represent Success(202) from the consumption.

{
  "loteCobvId": 123,
  "status": "EM_PROCESSAMENTO",
  "customId": 123,
  "description": "Lote de faturas de dezembro 2023",
  "quantidadeCobrancas": 2,
  "criadoEm": "2023-10-15T14:30:00Z"
}

List batch charges​

Endpoint to retrieve a paginated list of due-date charge batches created by the PSP.

Information per Batch:
  • Identification: Batch ID and custom ID
  • Status: Current processing state
  • Statistics: Summary of charges processing
  • Dates: Creation and processing completion dates
  • Description: Description provided at creation
Use Cases:
  • Monitoring: Track all batches in processing
  • Audit: Check history of processed batches
  • Reconciliation: Validate processing of multiple batches
GET /v1/lotecobv
Requires authorization for the scope: lotecobv.ind.write


Request

The code snippet below illustrates using the endpoint with the minimum required parameters (the inicio and fim date range) and the format for these parameters.

/v1/lotecobv?inicio=2023-01-01T16:01:35Z&fim=2023-12-30T16:01:35Z

Responses

The responses below represent Success(200) from the consumption.

{
  "parametros": {
    "inicio": "2023-10-01T00:00:00Z",
    "fim": "2023-10-31T23:59:59Z",
    "paginacao": {
      "paginaAtual": 0,
      "itensPorPagina": 100,
      "quantidadeDePaginas": 1,
      "quantidadeTotalDeItens": 3
    }
  },
  "lotes": [
    {
      "id": 123,
      "description": "Lote de faturas de dezembro 2023",
      "cobsv": {
        "criacao": "2023-10-15T14:30:00Z",
        "txid": "2023-10-15T14:35:00Z",
        "status": "PROCESSADO"
      }
    }
  ]
}
Last updated on