Lote de Cobrancas

Gerencie lotes de cobrancas com vencimento (lotecobv). Permite criar e consultar multiplas cobrancas em uma unica requisicao.

Nao e possivel adicionar ou remover cobrancas de lotes existentes. Cobrancas criadas individualmente via /cobv nao podem ser adicionadas a lotes posteriormente. Para alterar cobrancas dentro de um lote, utilize o endpoint PATCH /lotecobv/{id}.

Criar Lote de Cobranças

PUT/lotecobv/{id}

Cria ou substitui um lote de cobrancas com vencimento. O id do lote e definido pelo cliente.

Base URL: https://api.pix.basspago.com.br

Headers

Header	Valor	Descricao
`Content-Type`	application/json	Tipo do conteudo da requisicao
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2

Parametros de Rota

Nome	Tipo	Descricao
`id`	string	Identificador do lote definido pelo cliente

Parametros do Body

Nome	Tipo	Obrigatorio	Descricao
`descricao`	string	Opcional	Descricao do lote de cobrancas
`cobsv`	array	Obrigatorio	Array de cobrancas com vencimento. Cada item segue a mesma estrutura do body de PUT /cobv/{txid}, incluindo txid, calendario, devedor, valor e chave.
`cobsv[].txid`	string	Obrigatorio	Identificador unico da cobranca dentro do lote (26-35 caracteres alfanumericos)
`cobsv[].calendario.dataDeVencimento`	string	Obrigatorio	Data de vencimento da cobranca (formato YYYY-MM-DD)
`cobsv[].calendario.validadeAposVencimento`	integer	Opcional	Dias de validade apos o vencimento
`cobsv[].devedor.cpf`	string	Opcional	CPF do devedor (usar cpf OU cnpj)
`cobsv[].devedor.cnpj`	string	Opcional	CNPJ do devedor (usar cpf OU cnpj)
`cobsv[].devedor.nome`	string	Obrigatorio	Nome do devedor
`cobsv[].valor.original`	string	Obrigatorio	Valor da cobranca em BRL (ex: "100.00")
`cobsv[].chave`	string	Obrigatorio	Chave Pix cadastrada na conta

Exemplo de Request

{
  "descricao": "Lote de cobrancas mensais",
  "cobsv": [
    {
      "txid": "abcdefghijklmnopqrstuvwxyz01",
      "calendario": {
        "dataDeVencimento": "2025-02-15",
        "validadeAposVencimento": 30
      },
      "devedor": {
        "cpf": "12345678909",
        "nome": "Fulano de Tal"
      },
      "valor": {
        "original": "100.00"
      },
      "chave": "sua-chave-pix@example.com",
      "solicitacaoPagador": "Fatura #001"
    },
    {
      "txid": "abcdefghijklmnopqrstuvwxyz02",
      "calendario": {
        "dataDeVencimento": "2025-02-15",
        "validadeAposVencimento": 30
      },
      "devedor": {
        "cnpj": "11222333000181",
        "nome": "Empresa ABC Ltda"
      },
      "valor": {
        "original": "250.00"
      },
      "chave": "sua-chave-pix@example.com",
      "solicitacaoPagador": "Fatura #002"
    }
  ]
}

Exemplo de Response

{
  "descricao": "Lote de cobrancas mensais",
  "criacao": "2025-01-15T10: 30: 00.000Z",
  "cobsv": [
    {
      "txid": "abcdefghijklmnopqrstuvwxyz01",
      "status": "CRIADA",
      "problema": null
    },
    {
      "txid": "abcdefghijklmnopqrstuvwxyz02",
      "status": "CRIADA",
      "problema": null
    }
  ]
}

Exemplos de Codigo

curl -X PUT https://api.pix.basspago.com.br/lotecobv/1001 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "descricao": "Lote de cobrancas mensais",
    "cobsv": [
      {
        "txid": "abcdefghijklmnopqrstuvwxyz01",
        "calendario": {
          "dataDeVencimento": "2025-02-15",
          "validadeAposVencimento": 30
        },
        "devedor": {
          "cpf": "12345678909",
          "nome": "Fulano de Tal"
        },
        "valor": {
          "original": "100.00"
        },
        "chave": "sua-chave-pix@example.com",
        "solicitacaoPagador": "Fatura #001"
      },
      {
        "txid": "abcdefghijklmnopqrstuvwxyz02",
        "calendario": {
          "dataDeVencimento": "2025-02-15",
          "validadeAposVencimento": 30
        },
        "devedor": {
          "cnpj": "11222333000181",
          "nome": "Empresa ABC Ltda"
        },
        "valor": {
          "original": "250.00"
        },
        "chave": "sua-chave-pix@example.com",
        "solicitacaoPagador": "Fatura #002"
      }
    ]
  }'

Revisar Cobranças do Lote

PATCH/lotecobv/{id}

Permite revisar cobrancas especificas dentro de um lote. Nao e possivel adicionar ou remover cobrancas, apenas alterar as existentes.

Base URL: https://api.pix.basspago.com.br

Headers

Header	Valor	Descricao
`Content-Type`	application/json	Tipo do conteudo da requisicao
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2

Parametros de Rota

Nome	Tipo	Descricao
`id`	string	Identificador do lote a ser atualizado

Parametros do Body

Nome	Tipo	Obrigatorio	Descricao
`cobsv`	array	Obrigatorio	Array de cobrancas a serem revisadas (deve incluir o txid de cada cobranca existente no lote)

Exemplo de Request

{
  "cobsv": [
    {
      "txid": "abcdefghijklmnopqrstuvwxyz01",
      "valor": {
        "original": "120.00"
      }
    }
  ]
}

Exemplo de Response

{
  "descricao": "Lote de cobrancas mensais",
  "criacao": "2025-01-15T10: 30: 00.000Z",
  "cobsv": [
    {
      "txid": "abcdefghijklmnopqrstuvwxyz01",
      "status": "CRIADA",
      "problema": null
    },
    {
      "txid": "abcdefghijklmnopqrstuvwxyz02",
      "status": "CRIADA",
      "problema": null
    }
  ]
}

Exemplos de Codigo

curl -X PATCH https://api.pix.basspago.com.br/lotecobv/1001 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "cobsv": [
      {
        "txid": "abcdefghijklmnopqrstuvwxyz01",
        "valor": {
          "original": "120.00"
        }
      }
    ]
  }'

Consultar Lote

GET/lotecobv/{id}

Consulta um lote de cobrancas especifico pelo identificador.

Base URL: https://api.pix.basspago.com.br

Headers

Header	Valor	Descricao
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2

Parametros de Rota

Nome	Tipo	Descricao
`id`	string	Identificador do lote a ser consultado

Exemplo de Response

{
  "descricao": "Lote de cobrancas mensais",
  "criacao": "2025-01-15T10: 30: 00.000Z",
  "cobsv": [
    {
      "txid": "abcdefghijklmnopqrstuvwxyz01",
      "criacao": "2025-01-15T10: 30: 00.000Z",
      "status": "ATIVA",
      "devedor": {
        "cpf": "12345678909",
        "nome": "Fulano de Tal"
      },
      "valor": {
        "original": "100.00"
      }
    },
    {
      "txid": "abcdefghijklmnopqrstuvwxyz02",
      "criacao": "2025-01-15T10: 30: 00.000Z",
      "status": "ATIVA",
      "devedor": {
        "cnpj": "11222333000181",
        "nome": "Empresa ABC Ltda"
      },
      "valor": {
        "original": "250.00"
      }
    }
  ]
}

Exemplos de Codigo

curl -X GET https://api.pix.basspago.com.br/lotecobv/1001 \
  -H "Authorization: Bearer {access_token}"

Listar Lotes

GET/lotecobv

Lista todos os lotes de cobrancas, com suporte a paginacao e filtro por periodo.

Base URL: https://api.pix.basspago.com.br

Headers

Header	Valor	Descricao
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2

Parametros de Query

Nome	Tipo	Obrigatorio	Descricao
`inicio`	string	Obrigatorio	Data/hora inicial do periodo de consulta (formato RFC 3339, ex: 2025-01-01T00:00:00Z)
`fim`	string	Obrigatorio	Data/hora final do periodo de consulta (formato RFC 3339, ex: 2025-01-31T23:59:59Z)
`paginacao.paginaAtual`	integer	Opcional	Numero da pagina atual para paginacao (inicia em 0)
`paginacao.itensPorPagina`	integer	Opcional	Quantidade de itens por pagina (1 a 1000)

Exemplo de Response

{
  "parametros": {
    "inicio": "2025-01-01T00: 00:00Z",
    "fim": "2025-01-31T23: 59:59Z",
    "paginacao": {
      "paginaAtual": 0,
      "itensPorPagina": 100,
      "quantidadeDePaginas": 1,
      "quantidadeTotalDeItens": 1
    }
  },
  "lotes": [
    {
      "id": 1001,
      "descricao": "Lote de cobrancas mensais",
      "criacao": "2025-01-15T10: 30: 00.000Z",
      "quantidadeCobrancas": 2
    }
  ]
}

Exemplos de Codigo

curl -X GET "https://api.pix.basspago.com.br/lotecobv?inicio=2025-01-01T00:00:00Z&fim=2025-01-31T23:59:59Z&paginacao.paginaAtual=0&paginacao.itensPorPagina=100" \
  -H "Authorization: Bearer {access_token}"