Cobranças com vencimento

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

Criar cobrança com vencimento (cobv)

Endpoint para criar uma cobrança com vencimento (cobv) com TxId específico fornecido pelo PSP.

Características da Cobrança com vencimento (Cobv):

Data de vencimento obrigatória: Define quando a cobrança vence
Pagamento flexível: Pode ser paga antes, durante ou após vencimento
Juros e multa: Configuráveis para pagamentos em atraso
Desconto: Configurável para pagamentos antecipados
Abatimento: Redução no valor original
Endereço completo: Devedor e recebedor com endereço obrigatório

Diferenças entre Cob e Cobv:

Característica	Cob (Imediata)	Cobv (Com Vencimento)
Vencimento	❌ Não tem	✅ Obrigatório
Pagamento	Imediato	Pode ser futuro
Juros/Multa	❌ Não permite	✅ Configurável
Abatimento	❌ Não permite	✅ Configurável
Desconto	❌ Não permite	✅ Configurável
Endereço devedor	❌ Opcional básico	✅ Obrigatório completo

Modalidades de Juros/Multa/Abatimento:

1: Valor fixo
2: Percentual

Modalidades de Desconto:

1: Valor fixo até data específica
2: Percentual até data específica
3: Valor fixo por dia de antecipação
4: Percentual por dia de antecipação
5: Valor fixo por dia útil de antecipação
6: Percentual por dia útil de antecipação

Validações:

Data de vencimento: Deve ser no futuro
Endereços: Devedor e recebedor obrigatórios e completos
CPF/CNPJ: Devem ser válidos e não bloqueados
Valores: Juros, multa, desconto devem ser positivos

PUT /v1/cobv/:txid

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

Requisição

Cobrança simples com vencimento
Cobrança completa com juros e desconto

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

{
  "calendario": {
    "dataDeVencimento": "2023-12-31",
    "validadeAposVencimento": 30
  },
  "devedor": {
    "nome": "João Silva Santos",
    "cpf": "12345678901",
    "email": "[email protected]",
    "logradouro": "Rua das Flores, 123, Apto 45",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "01234567"
  },
  "recebedor": {
    "nome": "Empresa XYZ Ltda",
    "cnpj": "98765432000123",
    "email": "[email protected]",
    "logradouro": "Av. Paulista, 1000, Sala 100",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "01310100"
  },
  "valor": {
    "original": "500.00",
    "juros": {
      "modalidade": 2,
      "valorPerc": "0.033"
    },
    "multa": {
      "modalidade": 2,
      "valorPerc": "2.00"
    },
    "desconto": {
      "modalidade": 1,
      "descontoDataFixa": [
        {
          "data": "2023-12-25",
          "valorPerc": "25.00"
        },
        {
          "data": "2023-12-28",
          "valorPerc": "10.00"
        }
      ]
    }
  },
  "chave": "[email protected]",
  "solicitacaoPagador": "Fatura #123 - Desconto até 25/12",
  "infoAdicionais": [
    {
      "nome": "Fatura",
      "valor": "#123"
    },
    {
      "nome": "Referência",
      "valor": "DEZ/2023"
    }
  ]
}

Respostas

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

{
  "calendario": {
    "criacao": "2023-10-15T14:30:00Z",
    "dataDeVencimento": "2023-12-31",
    "validadeAposVencimento": 30
  },
  "txid": "fb2761260e054c7a94fb7b7b",
  "revisao": 0,
  "loc": {
    "id": 789,
    "location": "pix.example.com/qr/v2/cobv/fb2761260e054c7a94fb7b7b",
    "tipoCob": "cobv"
  },
  "location": "pix.example.com/qr/v2/cobv/fb2761260e054c7a94fb7b7b",
  "status": "ATIVA",
  "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",
  "pixCopiaECola": "00020101021226580014BR.GOV.BCB.PIX0136123e4567-e89b-12d3-a456-426655440000520400005303986540510.005802BR5913Fulano de Tal6008BRASILIA62070503***630445CC"
}

{
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "error": {
    "status": 400,
    "title": "Bad Request",
    "detail": "Data de vencimento deve ser no futuro"
  }
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Unauthorized",
    "detail": "Token de acesso inválido ou expirado",
    "status": 401
  }
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Forbidden",
    "detail": "Acesso negado",
    "status": 403
  }
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "InternalServerError",
    "detail": "Erro interno do servidor",
    "status": 500
  }
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "ServiceUnavailable",
    "detail": "Serviço temporariamente indisponível",
    "status": 503
  }
}

Consultar cobrança com vencimento

Endpoint para recuperar informações detalhadas de uma cobrança com vencimento específica através do seu txid.

Cálculo de Valores:

O sistema retorna os valores configurados (juros, multa, desconto) mas não calcula o valor final. O cálculo do valor a ser pago é feito no momento do pagamento baseado na data.

Casos de Uso:

Verificar vencimento: Conferir se a cobrança está vencida
Obter QR Code: Para disponibilizar ao pagador
Auditoria: Acompanhar histórico de modificações
Validar configurações: Conferir juros, multas e descontos

GET /v1/cobv/:txid

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

Requisição

A requisição enviada para esse endpoint não precisa de um body, apenas os cabeçalhos de autorização OAuth, parâmetros e o certificado da conta.

Respostas

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

//Cobrança ativa com vencimento
{
  "calendario": {
    "criacao": "2023-10-15T14:30:00Z",
    "dataDeVencimento": "2023-12-31",
    "validadeAposVencimento": 30
  },
  "txid": "fb2761260e054c7a94fb7b7b",
  "revisao": 0,
  "loc": {
    "id": 789,
    "location": "pix.example.com/qr/v2/cobv/fb2761260e054c7a94fb7b7b",
    "tipoCob": "cobv",
    "criacao": "2023-10-15T14:30:00Z"
  },
  "status": "ATIVA",
  "devedor": {
    "nome": "João Silva Santos",
    "cpf": "12345678901",
    "email": "[email protected]",
    "logradouro": "Rua das Flores, 123, Apto 45",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "01234567"
  },
  "recebedor": {
    "nome": "Empresa XYZ Ltda",
    "cnpj": "98765432000123",
    "email": "[email protected]",
    "logradouro": "Av. Paulista, 1000, Sala 100",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "01310100"
  },
  "valor": {
    "original": "500.00",
    "juros": {
      "modalidade": 2,
      "valorPerc": "0.033"
    },
    "multa": {
      "modalidade": 2,
      "valorPerc": "2.00"
    },
    "desconto": {
      "modalidade": 1,
      "descontoDataFixa": [
        {
          "data": "2023-12-25",
          "valorPerc": "25.00"
        },
        {
          "data": "2023-12-28",
          "valorPerc": "10.00"
        }
      ]
    }
  },
  "chave": "+5561988887777",
  "solicitacaoPagador": "Fatura #123 - Desconto até 25/12",
  "infoAdicionais": [
    {
      "nome": "Fatura",
      "valor": "#123"
    },
    {
      "nome": "Referência",
      "valor": "DEZ/2023"
    }
  ],
  "pixCopiaECola": "00020101021226580014BR.GOV.BCB.PIX0136123e4567-e89b-12d3-a456-426655440000520400005303986540510.005802BR5913Fulano de Tal6008BRASILIA62070503***630445CC"
}

//Cobrança concluída
{
  "calendario": {
    "criacao": "2023-10-15T14:30:00Z",
    "dataDeVencimento": "2023-12-31",
    "validadeAposVencimento": 30
  },
  "txid": "fb2761260e054c7a94fb7b7b",
  "revisao": 0,
  "loc": {
    "id": 789,
    "location": "pix.example.com/qr/v2/cobv/fb2761260e054c7a94fb7b7b",
    "tipoCob": "cobv",
    "criacao": "2023-10-15T14:30:00Z"
  },
  "status": "CONCLUIDA",
  "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": "500.00"
  },
  "chave": "+5561988887777",
  "pixCopiaECola": "00020101021226580014BR.GOV.BCB.PIX0136123e4567-e89b-12d3-a456-426655440000520400005303986540510.005802BR5913Fulano de Tal6008BRASILIA62070503***630445CC"
}

{
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "error": {
    "status": 400,
    "title": "Bad Request",
    "detail": "TxId deve ter entre 26 e 35 caracteres alfanuméricos"
  }
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Unauthorized",
    "detail": "Token de acesso inválido ou expirado",
    "status": 401
  }
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Forbidden",
    "detail": "Acesso negado",
    "status": 403
  }
}

{
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "error": {
    "status": 404,
    "title": "Not Found",
    "detail": "Cobrança com vencimento com o txid informado não foi encontrada"
  }
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "InternalServerError",
    "detail": "Erro interno do servidor",
    "status": 500
  }
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "ServiceUnavailable",
    "detail": "Serviço temporariamente indisponível",
    "status": 503
  }
}

Atualizar cobrança com vencimento

Endpoint para atualizar informações de uma cobrança com vencimento (cobv) existente.

Restrições:

Status: Apenas cobranças com status ATIVA podem ser atualizadas
Data de vencimento: Não pode ser alterado após criação
Chave: Não pode ser alterada após criação
TxId: Não pode ser alterado

Validações Especiais:

Endereços: Devedor e recebedor devem ter endereço completo
Data de vencimento: Se for no passado, a cobrança pode estar vencida mas ainda ser atualizável
Valores: Juros, multa, desconto devem seguir as modalidades corretas
CPF/CNPJ: Se alterado, deve ser válido e não bloqueado

Comportamentos:

Revisão: Incrementa automaticamente a cada atualização
QR Code: É regenerado com as novas informações
Modalidades: Alterações nas modalidades de juros/multa/desconto são permitidas

Importante!

Após a atualização, um novo QR Code será gerado. QR Codes anteriores podem não funcionar.

PATCH /v1/cobv/:txid

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

Requisição

Atualizar valores e juros
Atualizar dados do devedor
Atualização completa

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

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

{
  "status": "REMOVIDA_PELO_USUARIO_RECEBEDOR"
}

Respostas

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

{
  "calendario": {
    "criacao": "2023-10-15T14:30:00Z",
    "dataDeVencimento": "2023-12-31",
    "validadeAposVencimento": 30
  },
  "txid": "fb2761260e054c7a94fb7b7b",
  "revisao": 0,
  "loc": {
    "id": 789,
    "location": "pix.example.com/qr/v2/cobv/fb2761260e054c7a94fb7b7b",
    "tipoCob": "cobv"
  },
  "location": "pix.example.com/qr/v2/cobv/fb2761260e054c7a94fb7b7b",
  "status": "ATIVA",
  "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",
  "pixCopiaECola": "00020101021226580014BR.GOV.BCB.PIX0136123e4567-e89b-12d3-a456-426655440000520400005303986540510.005802BR5913Fulano de Tal6008BRASILIA62070503***630445CC"
}

{
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "error": {
    "status": 400,
    "title": "Bad Request",
    "detail": "Data de vencimento deve ser no futuro"
  }
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Unauthorized",
    "detail": "Token de acesso inválido ou expirado",
    "status": 401
  }
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Forbidden",
    "detail": "Acesso negado",
    "status": 403
  }
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "InternalServerError",
    "detail": "Erro interno do servidor",
    "status": 500
  }
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "ServiceUnavailable",
    "detail": "Serviço temporariamente indisponível",
    "status": 503
  }
}

Listar cobranças com vencimento

Endpoint para recuperar uma lista paginada de cobranças com vencimento (cobv) criadas pelo PSP.

GET /v1/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.

/v1/cobv?inicio=2020-10-22T16:01:35Z&fim=2020-11-30T20:10:00Z

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": 2
    }
  },
  "cobvs": [
    {
      "calendario": {
        "criacao": "2023-10-15T14:30:00Z",
        "dataDeVencimento": "2023-12-31",
        "validadeAposVencimento": 30
      },
      "txid": "fb2761260e054c7a94fb7b7b",
      "revisao": 0,
      "loc": {
        "id": 789,
        "location": "pix.example.com/qr/v2/cobv/fb2761260e054c7a94fb7b7b",
        "tipoCob": "cobv"
      },
      "location": "pix.example.com/qr/v2/cobv/fb2761260e054c7a94fb7b7b",
      "status": "ATIVA",
      "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": "500.00",
        "juros": {
          "modalidade": 2,
          "valorPerc": "0.033"
        },
        "multa": {
          "modalidade": 2,
          "valorPerc": "2.00"
        },
        "desconto": {
          "modalidade": 1,
          "descontoDataFixa": [
            {
              "data": "2023-12-25",
              "valorPerc": "25.00"
            }
          ]
        }
      },
      "chave": "+5561988887777",
      "solicitacaoPagador": "Fatura #123 - Desconto até 25/12",
      "infoAdicionais": [
        {
          "nome": "Fatura",
          "valor": "#123"
        }
      ]
    },
    {
      "calendario": {
        "criacao": "2023-10-16T09:15:00Z",
        "dataDeVencimento": "2024-01-15",
        "validadeAposVencimento": 15
      },
      "txid": "ac3849f6b2d54e8a95fb1b2c",
      "revisao": 0,
      "loc": {
        "id": 790,
        "location": "pix.example.com/qr/v2/cobv/ac3849f6b2d54e8a95fb1b2c",
        "tipoCob": "cobv"
      },
      "status": "CONCLUIDA",
      "devedor": {
        "nome": "Maria Silva",
        "cpf": "98765432100",
        "logradouro": "Av. Brasil, 456",
        "cidade": "Rio de Janeiro",
        "uf": "RJ",
        "cep": "20040020"
      },
      "recebedor": {
        "nome": "Loja ABC Ltda",
        "cnpj": "11223344000156",
        "logradouro": "Rua Comercial, 789",
        "cidade": "Rio de Janeiro",
        "uf": "RJ",
        "cep": "20050030"
      },
      "valor": {
        "original": "250.00"
      },
      "chave": "[email protected]"
    }
  ]
}

{
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "error": {
    "status": 400,
    "title": "Bad Request",
    "detail": "Data de início deve ser anterior à data de fim"
  }
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Unauthorized",
    "detail": "Token de acesso inválido ou expirado",
    "status": 401
  }
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Forbidden",
    "detail": "Acesso negado",
    "status": 403
  }
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "InternalServerError",
    "detail": "Erro interno do servidor",
    "status": 500
  }
}

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "ServiceUnavailable",
    "detail": "Serviço temporariamente indisponível",
    "status": 503
  }
}

Cobranças com vencimento

Criar cobrança com vencimento (cobv)​

Consultar cobrança com vencimento​

Atualizar cobrança com vencimento​

Listar cobranças com vencimento​

Criar cobrança com vencimento (cobv)

Consultar cobrança com vencimento

Atualizar cobrança com vencimento

Listar cobranças com vencimento