Pular para o conteúdo principal

Lote de cobranças

O conjunto de endpoints a seguir é responsável pela gestão de cobranças em lote.


Criar lote de cobranças com vencimento​

Endpoint utilizado para criar lote de cobranças com vencimento (lotecobv) para processamento em massa.

Características do Lote:
  • Processamento assíncrono: O lote é processado em background
  • ID customizado Identificador único fornecido pelo PSP
  • Múltiplas cobranças: Até 1000 cobranças por lote
  • Validação individual: Cada cobrança é validada separadamente
  • Status do lote: Acompanhamento do processamento
Vantagens do Processamento em Lote:
  • Eficiência: Processa múltiplas cobranças de uma vez
  • Performance Reduz overhead de múltiplas requisições individuais
  • Controle: Acompanhamento centralizado do processamento
  • Atomicidade parcial: Cobranças válidas são criadas mesmo se outras falharem
Fluxo do Processamento:
  • 1. Envio: Lote é enviado para processamento
  • 2. Validação: Cada cobrança é validada individualmente
  • 3. Processamento: Cobranças válidas são criadas
  • 4. Resultado: Status detalhado de cada cobrança no lote
Validações por Cobrança:
  • Todas as validações aplicáveis às cobranças individuais
  • TxId único dentro do lote e globalmente
  • Dados obrigatórios completos para cada cobrança
Importante!

O processamento é assíncrono. Use o endpoint de consulta para verificar o status.


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


Requisição

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

Respostas

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

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

Consultar lote de cobranças​

Endpoint para recuperar informações detalhadas de um lote específico e o status do processamento de suas cobranças.

Casos de Uso:
  • Monitoramento: Acompanhar progresso do processamento
  • Auditoria: Verificar cobranças criadas com sucesso
  • Correção: Identificar cobranças com erro para reprocessamento
  • Reconciliação: Validar que todas as cobranças foram processadas
GET /v1/lotecobv/:id
Requer autorização para o escopo: lotecobv.ind.read


Respostas

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

// Lote processado com sucesso
{
  "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"
        ]
      }
    }
  ]
}

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.

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


Requisição

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

Respostas

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

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

Listar lotes de cobranças​

Endpoint para recuperar uma lista paginada de lotes de cobranças com vencimento criados pelo PSP.

Informações por Lote:
  • Identificação: ID do lote e ID customizado
  • Status: Estado atual do processamento
  • Estatísticas: Resumo do processamento das cobranças
  • Datas: Criação e conclusão do processamento
  • Descrição: Descrição fornecida na criação
Casos de Uso:
  • Monitoramento: Acompanhar todos os lotes em processamento
  • Auditoria: Verificar histórico de lotes processados
  • Reconciliação: Validar processamento de múltiplos lotes
GET /v1/lotecobv
Requer autorização para o escopo: lotecobv.ind.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.

/v1/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": "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"
      }
    }
  ]
}
Última atualização em