Pular para o conteúdo
Vintém

Criar recorrência de Pix Automático

POST
/rec
curl --request POST \
  --url http://localhost:8080/rec \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "vinculo": { "objeto": "example", "contrato": "example", "devedor": { "cpf": "example", "cnpj": "example", "nome": "example" } }, "calendario": { "dataInicial": "2026-04-15", "dataFinal": "2026-04-15", "periodicidade": "SEMANAL" }, "valor": { "valorRec": "10.50", "valorMinimoRecebedor": "10.50" }, "politicaRetentativa": "NAO_PERMITE" }'

O idRec é gerado pelo PSP da conta. Exige API key restrita a uma conta. Responde 501 se o banco da conta não oferece Pix Automático.

Authorizations

Seção intitulada “Authorizations”

Parameters

Seção intitulada “Parameters”

Header Parameters

Seção intitulada “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 Bodyrequired

Seção intitulada “Request Bodyrequired”
Media typeapplication/json
object
vinculo
required
object
objeto
string
<= 35 characters
contrato
required
string
>= 1 characters <= 35 characters
devedor
required

Pessoa física (cpf) ou jurídica (cnpj). Informe um dos dois.

object
cpf
string
/^\d{11}$/
cnpj

Aceita o CNPJ alfanumérico.

string
/^[0-9A-Z]{14}$/
nome
required
string
<= 200 characters
calendario
required
object
dataInicial
required
string format: date
dataFinal
string format: date
periodicidade
required
string
Allowed values: SEMANAL MENSAL TRIMESTRAL SEMESTRAL ANUAL
valor

ValorRec fixa o valor de toda cobrança. Sem ele, o valor varia, e o pagador define um máximo na autorização; valorMinimoRecebedor é o piso desse máximo. Os dois são excludentes (RN-40).

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

Example 

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

Example 

10.50
politicaRetentativa
required
string
Allowed values: NAO_PERMITE PERMITE_3R_7D

Responses

Seção intitulada “Responses”

201

Seção intitulada “201”

Recorrência criada, com status CRIADA.

Media typeapplication/json
object
vinculo
required
object
objeto
string
<= 35 characters
contrato
required
string
>= 1 characters <= 35 characters
devedor
required

Pessoa física (cpf) ou jurídica (cnpj). Informe um dos dois.

object
cpf
string
/^\d{11}$/
cnpj

Aceita o CNPJ alfanumérico.

string
/^[0-9A-Z]{14}$/
nome
required
string
<= 200 characters
calendario
required
object
dataInicial
required
string format: date
dataFinal
string format: date
periodicidade
required
string
Allowed values: SEMANAL MENSAL TRIMESTRAL SEMESTRAL ANUAL
valor

ValorRec fixa o valor de toda cobrança. Sem ele, o valor varia, e o pagador define um máximo na autorização; valorMinimoRecebedor é o piso desse máximo. Os dois são excludentes (RN-40).

object
valorRec
string
/^\d{1,10}\.\d{2}$/
valorMinimoRecebedor
string
/^\d{1,10}\.\d{2}$/
politicaRetentativa
required
string
Allowed values: NAO_PERMITE PERMITE_3R_7D
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}$/
status
required
string
Allowed values: CRIADA APROVADA REJEITADA EXPIRADA CANCELADA
motivoRejeicao
string

Example 

{
  "calendario": {
    "periodicidade": "SEMANAL"
  },
  "valor": {
    "valorRec": "10.50",
    "valorMinimoRecebedor": "10.50"
  },
  "politicaRetentativa": "NAO_PERMITE",
  "status": "CRIADA"
}

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

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