Referência: rec, cobr e webhooks de recorrência

Resposta rápida: Pix Automático usa /rec e /solicrec para o mandato, /cobr por ciclo, /locrec para payload próprio e /webhookrec e /webhookcobr para eventos; cada recurso exige seu escopo na credencial (rec.write, cobr.write, webhookrec.write, ...).

Endpoints

Método	Path	Uso	Escopo
POST	/rec	Criar recorrência	rec.write
GET	/rec/{idRec}	Consultar recorrência; ?txid= compõe o QR com uma cobrança	rec.read
PATCH	/rec/{idRec}	Revisar recorrência	rec.write
GET	/rec/{recUrlAccessToken}	Recuperar o payload JSON da recorrência	—
POST	/solicrec	Criar solicitação de confirmação	solicrec.write
GET	/solicrec/{idSolicRec}	Consultar solicitação	solicrec.read
PATCH	/solicrec/{idSolicRec}	Revisar solicitação	solicrec.write
PUT	/cobr/{txid}	Criar cobrança recorrente	cobr.write
GET	/cobr/{txid}	Consultar cobrança recorrente	cobr.read
PATCH	/cobr/{txid}	Revisar cobrança recorrente	cobr.write
POST	/cobr/{txid}/retentativa/{data}	Solicitar retentativa	cobr.write
POST	/locrec	Criar location do payload	payloadlocationrec.write
GET	/locrec/{id}	Recuperar location	payloadlocationrec.read
DELETE	/locrec/{id}/idRec	Desvincular recorrência da location	payloadlocationrec.write
PUT	/webhookrec	Configurar webhook do mandato	webhookrec.write
GET	/webhookrec	Exibir webhook do mandato	webhookrec.read
DELETE	/webhookrec	Cancelar webhook do mandato	webhookrec.write
PUT	/webhookcobr	Configurar webhook dos ciclos	webhookcobr.write
GET	/webhookcobr	Exibir webhook dos ciclos	webhookcobr.read
DELETE	/webhookcobr	Cancelar webhook dos ciclos	webhookcobr.write

Os webhooks de recorrência não levam chave no path e são independentes do PUT /webhook/{chave} da cobrança imediata.

Lembre que escopo é propriedade da credencial: não se manda scope no token (auth). Recurso respondendo 403 com token válido significa escopo ausente na credencial — o caminho é o banco, não o código.

Corpo mínimo

POST /rec:

Campo	Nota
vinculo.contrato, vinculo.objeto, vinculo.devedor	O que o pagador vê como o "porquê" da autorização
calendario.dataInicial, dataFinal, periodicidade	SEMANAL, MENSAL, TRIMESTRAL, SEMESTRAL, ANUAL
valor.valorRec	Valor de referência do mandato
politicaRetentativa	NAO_PERMITE ou PERMITE_3R_7D
ativacao.dadosJornada.txid	Jornada 1: a cobrança que carrega a autorização
loc	Location do payload próprio (/locrec), necessária para o QR composto

PUT /cobr/{txid}:

Campo	Nota
idRec	Amarra o ciclo ao mandato
calendario.dataDeVencimento	Um ciclo por vencimento
valor.original	Valor efetivo do ciclo
ajusteDiaUtil	Move vencimento em dia não útil
infoAdicional, devedor, recebedor	Complementos

O QR composto (dadosQR)

O BR Code da ativação sai da leitura da recorrência, nunca da criação:

Requisição	dadosQR.jornada	Conteúdo
GET /rec/{idRec}	JORNADA_2	QR da recorrência
GET /rec/{idRec}?txid={cob}	JORNADA_3	QR da cobrança imediata + recorrência
GET /rec/{idRec}?txid={cobv}	JORNADA_4	QR da cobrança com vencimento + recorrência

Os dois campos (jornada e pixCopiaECola) só aparecem quando as location necessárias estão preenchidas — na recorrência sempre, e na cobrança também nas jornadas 3 e 4. A Jornada 1 não está no enum: ela não tem QR próprio, a autorização viaja na cobrança existente.

Status

Recurso	Valores observados
rec	CRIADA, APROVADA / CONFIRMADA, REJEITADA, CANCELADA, EXPIRADA
solicrec	CRIADA, ENVIADA, RECEBIDA (cancelável só nesses)
cobr	ATIVA, CONCLUÍDA, REJEITADA, CANCELADA

Regras de transição que a API impõe e que costumam pegar quem está implementando:

• rec.loc, calendario.dataInicial e vinculo.devedor.nome só mudam enquanto o status for CRIADA.
• rec.dadosJornada.txid não muda depois de REJEITADA ou CANCELADA.
• Não se cria uma segunda cobr para o mesmo idRec com vencimento no mesmo ciclo enquanto a anterior não estiver REJEITADA ou CANCELADA.
• O txid citado em dadosJornada tem de ser de cobrança do mesmo recebedor da recorrência.

Contrato

OpenAPI BACEN — a recorrência existe a partir da linha de versões 2.10; a 2.9 não a define. Este pack não reespecifica schemas completos: campos opcionais, formatos e enums exaustivos ficam no YAML.

Notas Modobank

• O produto vem habilitado por padrão nas contas; o que gate é o escopo da credencial.
• Não há simulação de recorrência em homologação: mandato e débito só se provam em produção. Planeje o primeiro teste com valor baixo e conta própria.
• Snippets: snippets/curl/create-rec.sh, snippets/curl/create-cobr.sh, snippets/curl/register-webhookrec.sh.