Criar cobrança recorrente com txid gerado pelo Vintém

POST

/cobr

const url = 'http://localhost:8080/cobr';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'example',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"idRec":"example","calendario":{"dataDeVencimento":"2026-04-15"},"valor":{"original":"10.50"},"ajusteDiaUtil":true,"infoAdicional":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url http://localhost:8080/cobr \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "idRec": "example", "calendario": { "dataDeVencimento": "2026-04-15" }, "valor": { "original": "10.50" }, "ajusteDiaUtil": true, "infoAdicional": "example" }'

A recorrência precisa estar APROVADA e o vencimento, de 2 a 10 dias corridos à frente (RN-42). Um ciclo tem uma cobrança só.

Authorizations

apiKey

Parameters

Header Parameters

Idempotency-Key

required

string

>= 1 characters <= 255 characters

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

Request Body^required

application/json

object

idRec

required

Identificador da recorrência, gerado pelo PSP (R + R/N + ISPB + AAAAMMDD + 11 caracteres).

string

/^R[RN][0-9A-Z]{8}[0-9]{8}[a-zA-Z0-9]{11}$/

calendario

required

object

dataDeVencimento

required

Data prevista de liquidação, de 2 a 10 dias corridos à frente (RN-42).

string format: date

valor

required

object

original

required

string

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

Example

10.50

ajusteDiaUtil

Leva a liquidação para o próximo dia útil se o vencimento cair num dia não útil.

boolean

default: true

infoAdicional

string

<= 140 characters

Responses

201

Cobrança recorrente criada.

application/json

object

idRec

required

Identificador da recorrência, gerado pelo PSP (R + R/N + ISPB + AAAAMMDD + 11 caracteres).

string

/^R[RN][0-9A-Z]{8}[0-9]{8}[a-zA-Z0-9]{11}$/

calendario

required

object

dataDeVencimento

required

Data prevista de liquidação, de 2 a 10 dias corridos à frente (RN-42).

string format: date

valor

required

object

original

required

string

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

ajusteDiaUtil

required

Leva a liquidação para o próximo dia útil se o vencimento cair num dia não útil.

boolean

default: true

infoAdicional

string

<= 140 characters

txid

required

string

/^[a-zA-Z0-9]{26,35}$/

status

required

string

Allowed values: CRIADA ATIVA CONCLUIDA EXPIRADA REJEITADA CANCELADA

tentativas

required

Array<object>

object

dataLiquidacao

required

string format: date

tipo

required

string

Allowed values: AGND NTAG RIFL

status

required

string

Allowed values: SOLICITADA AGENDADA PAGA CANCELADA REJEITADA EXPIRADA

endToEndId

string

motivoRejeicao

string

motivoEncerramento

Código e descrição da rejeição ou do cancelamento.

string

Example

{
  "valor": {
    "original": "10.50"
  },
  "ajusteDiaUtil": true,
  "status": "CRIADA",
  "tentativas": [
    {
      "tipo": "AGND",
      "status": "SOLICITADA"
    }
  ]
}

400

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

application/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

API key ausente ou inválida.

application/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

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

application/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"
    }
  ]
}

404

Recurso não encontrado.

application/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

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

application/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

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

application/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

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

application/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"
    }
  ]
}

Criar cobrança recorrente com txid gerado pelo Vintém

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Example

Responses

201

Example

400

Example generated

401

Example generated

403

Example generated

404

Example generated

409

Example generated

501

Example generated

default

Example generated

Request Body^required

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated