Pular para o conteúdo
Vintém

Criar cobrança com vencimento

PUT
/cobv/{txid}
curl --request PUT \
  --url http://localhost:8080/cobv/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "calendario": { "dataDeVencimento": "2026-04-15", "validadeAposVencimento": 30 }, "devedor": { "cpf": "example", "cnpj": "example", "nome": "example", "email": "example", "logradouro": "example", "cidade": "example", "uf": "example", "cep": "example" }, "loc": { "id": 1 }, "valor": { "original": "10.50", "multa": { "modalidade": 1, "valorPerc": "10.50" }, "juros": { "modalidade": 1, "valorPerc": "10.50" }, "abatimento": { "modalidade": 1, "valorPerc": "10.50" }, "desconto": { "modalidade": 1, "descontoDataFixa": [ { "data": "2026-04-15", "valorPerc": "10.50" } ], "valorPerc": "10.50" } }, "chave": "example", "solicitacaoPagador": "example", "infoAdicionais": [ { "nome": "example", "valor": "example" } ] }'

Authorizations

Seção intitulada “Authorizations”

Parameters

Seção intitulada “Parameters”

Path Parameters

Seção intitulada “Path Parameters”
txid
required
string
/^[a-zA-Z0-9]{26,35}$/

Header Parameters

Seção intitulada “Header Parameters”
Idempotency-Key
string
>= 1 characters <= 255 characters

Reenvio com a mesma chave em até 24 h devolve a resposta original (RN-11).

Request Bodyrequired

Seção intitulada “Request Bodyrequired”
Media typeapplication/json
object
calendario
required
object
dataDeVencimento
required
string format: date
validadeAposVencimento

Dias corridos após o vencimento em que ainda pode ser paga.

integer format: int32
default: 30
devedor
required
object
cpf
string
/^\d{11}$/
cnpj

Aceita o CNPJ alfanumérico.

string
/^[0-9A-Z]{14}$/
nome
required
string
<= 200 characters
email
string
logradouro
string
<= 200 characters
cidade
string
<= 200 characters
uf
string
<= 2 characters
cep
string
<= 8 characters
loc
object
id
integer format: int64
valor
required
object
original
required
string
/^\d{1,10}\.\d{2}$/

Example 

10.50
multa
object
modalidade
required

1 valor fixo, 2 percentual.

integer format: int32
>= 1 <= 2
valorPerc
required
string
/^\d{1,10}\.\d{2}$/

Example 

10.50
juros
object
modalidade
required
integer format: int32
>= 1 <= 8
valorPerc
required
string
/^\d{1,10}\.\d{2}$/

Example 

10.50
abatimento
object
modalidade
required
integer format: int32
>= 1 <= 2
valorPerc
required
string
/^\d{1,10}\.\d{2}$/

Example 

10.50
desconto

Use descontoDataFixa (modalidades 1 e 2) ou valorPerc (3 a 6), nunca os dois.

object
modalidade
required
integer format: int32
>= 1 <= 6
descontoDataFixa
Array<object>
>= 1 items <= 3 items
object
data
required
string format: date
valorPerc
required
string
/^\d{1,10}\.\d{2}$/

Example 

10.50
valorPerc
string
/^\d{1,10}\.\d{2}$/

Example 

10.50
chave
required

Chave Pix do recebedor (telefone, e-mail, CPF/CNPJ ou EVP).

string
<= 77 characters
solicitacaoPagador
string
<= 140 characters
infoAdicionais
Array<object>
<= 50 items
object
nome
required
string
<= 50 characters
valor
required
string
<= 200 characters

Responses

Seção intitulada “Responses”

201

Seção intitulada “201”

Cobrança criada.

Media typeapplication/json
object
calendario
required
object
dataDeVencimento
required
string format: date
validadeAposVencimento

Dias corridos após o vencimento em que ainda pode ser paga.

integer format: int32
default: 30
criacao
required
string format: date-time
txid
required
string
/^[a-zA-Z0-9]{26,35}$/
revisao
required
integer format: int32
devedor
required
object
cpf
string
/^\d{11}$/
cnpj

Aceita o CNPJ alfanumérico.

string
/^[0-9A-Z]{14}$/
nome
required
string
<= 200 characters
email
string
logradouro
string
<= 200 characters
cidade
string
<= 200 characters
uf
string
<= 2 characters
cep
string
<= 8 characters
recebedor
object
cpf
string
/^\d{11}$/
cnpj

Aceita o CNPJ alfanumérico.

string
/^[0-9A-Z]{14}$/
nome
string
nomeFantasia
string
logradouro
string
cidade
string
uf
string
cep
string
loc
object
id
required
integer format: int64
location
string
tipoCob
string
Allowed values: cob cobv
criacao
string format: date-time
status
required
string
Allowed values: ATIVA CONCLUIDA REMOVIDA_PELO_USUARIO_RECEBEDOR REMOVIDA_PELO_PSP
valor
required
object
original
required
string
/^\d{1,10}\.\d{2}$/
multa
object
modalidade
required

1 valor fixo, 2 percentual.

integer format: int32
>= 1 <= 2
valorPerc
required
string
/^\d{1,10}\.\d{2}$/
juros
object
modalidade
required
integer format: int32
>= 1 <= 8
valorPerc
required
string
/^\d{1,10}\.\d{2}$/
abatimento
object
modalidade
required
integer format: int32
>= 1 <= 2
valorPerc
required
string
/^\d{1,10}\.\d{2}$/
desconto

Use descontoDataFixa (modalidades 1 e 2) ou valorPerc (3 a 6), nunca os dois.

object
modalidade
required
integer format: int32
>= 1 <= 6
descontoDataFixa
Array<object>
>= 1 items <= 3 items
object
data
required
string format: date
valorPerc
required
string
/^\d{1,10}\.\d{2}$/
valorPerc
string
/^\d{1,10}\.\d{2}$/
chave
required

Chave Pix do recebedor (telefone, e-mail, CPF/CNPJ ou EVP).

string
<= 77 characters
solicitacaoPagador
string
infoAdicionais
Array<object>
object
nome
required
string
<= 50 characters
valor
required
string
<= 200 characters
pixCopiaECola
string
<= 512 characters

Example 

{
  "calendario": {
    "validadeAposVencimento": 30
  },
  "loc": {
    "tipoCob": "cob"
  },
  "status": "ATIVA",
  "valor": {
    "original": "10.50",
    "multa": {
      "valorPerc": "10.50"
    },
    "juros": {
      "valorPerc": "10.50"
    },
    "abatimento": {
      "valorPerc": "10.50"
    },
    "desconto": {
      "descontoDataFixa": [
        {
          "valorPerc": "10.50"
        }
      ],
      "valorPerc": "10.50"
    }
  }
}

400

Seção intitulada “400”

Requisição fora do formato ou violando uma regra de negócio.

Media typeapplication/problem+json

Erro no formato da spec do BCB (RFC 7807).

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
correlationId
string
violacoes
Array<object>
object
razao
string
propriedade
string
valor
string

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "correlationId": "example",
  "violacoes": [
    {
      "razao": "example",
      "propriedade": "example",
      "valor": "example"
    }
  ]
}

401

Seção intitulada “401”

API key ausente ou inválida.

Media typeapplication/problem+json

Erro no formato da spec do BCB (RFC 7807).

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
correlationId
string
violacoes
Array<object>
object
razao
string
propriedade
string
valor
string

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "correlationId": "example",
  "violacoes": [
    {
      "razao": "example",
      "propriedade": "example",
      "valor": "example"
    }
  ]
}

403

Seção intitulada “403”

A API key não tem o escopo necessário.

Media typeapplication/problem+json

Erro no formato da spec do BCB (RFC 7807).

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
correlationId
string
violacoes
Array<object>
object
razao
string
propriedade
string
valor
string

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "correlationId": "example",
  "violacoes": [
    {
      "razao": "example",
      "propriedade": "example",
      "valor": "example"
    }
  ]
}

409

Seção intitulada “409”

Txid já existe, revisão desatualizada, ou Idempotency-Key reutilizada com outro payload.

Media typeapplication/problem+json

Erro no formato da spec do BCB (RFC 7807).

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
correlationId
string
violacoes
Array<object>
object
razao
string
propriedade
string
valor
string

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "correlationId": "example",
  "violacoes": [
    {
      "razao": "example",
      "propriedade": "example",
      "valor": "example"
    }
  ]
}

501

Seção intitulada “501”

O PSP da conta não oferece essa capacidade (RN-50).

Media typeapplication/problem+json

Erro no formato da spec do BCB (RFC 7807).

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
correlationId
string
violacoes
Array<object>
object
razao
string
propriedade
string
valor
string

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "correlationId": "example",
  "violacoes": [
    {
      "razao": "example",
      "propriedade": "example",
      "valor": "example"
    }
  ]
}

default

Seção intitulada “default”

Qualquer outro erro, sempre como Problema. Os mais comuns: 502 quando o banco recusa ou falha (PSPIndisponivel) e 500 para erro interno.

Media typeapplication/problem+json

Erro no formato da spec do BCB (RFC 7807).

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
correlationId
string
violacoes
Array<object>
object
razao
string
propriedade
string
valor
string

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "correlationId": "example",
  "violacoes": [
    {
      "razao": "example",
      "propriedade": "example",
      "valor": "example"
    }
  ]
}