Geração de cobrança avulsa por API

Plano e recursos necessários

Você precisa de API habilitada, do utilitário Integrações Externas ativo e dos escopos de clientes e cobranças descritos neste guia. O Starter oferece 100 requisições por mês para testes. O pagamento da cobrança usa a URL retornada pela API; não é o checkout público de contratação de planos. NFS-e exige um plano com o recurso fiscal.

Confira os requisitos por tipo de integração e compare os planos disponíveis.

O problema resolvido

Seu sistema origina a venda; o RecoPay conduz a cobrança

Use este fluxo para pedidos, serviços adicionais, taxas ou qualquer valor pontual que precise virar uma cobrança dentro de um cliente. O sistema de origem informa os dados comerciais mínimos e guarda o identificador devolvido.

Contrato isolado

A cobrança avulsa não cria assinatura, consumo ou componente por uso. Ela usa somente o utilitário Integrações Externas e os escopos concedidos à chave.

Sistema integrador

Protege a chave no backend.
Identifica o cliente e a venda.
Preserva a chave idempotente.
Guarda o ID e consulta o status.

RecoPay

Isola os dados por empresa e escopo.
Ajusta o vencimento para dia útil.
Aplica a retenção fiscal configurada.
Entrega checkout, conciliação e histórico.

Configuração no painel

Pré-requisitos

Entre no RecoPay com um usuário autorizado a gerenciar utilitários e chaves.
Ative o utilitário Integrações Externas.
Abra o utilitário, crie uma chave nomeada para o sistema consumidor e selecione somente os escopos necessários.
Copie o segredo exibido uma única vez e armazene-o em cofre de segredos ou configuração protegida do backend.
Defina uma referência idempotente estável para cada criação lógica.

Nunca coloque a chave no navegador

As rotas de integração são servidor a servidor. JavaScript público, aplicativo distribuído e repositório Git não são locais seguros para o segredo.

Roadmap literal

Fluxo completo de implementação

Localize o cliente pelo documento

Consulte CPF ou CNPJ antes de criar um novo cadastro.

Crie o cliente somente quando necessário

Se a consulta retornar 404, envie o cadastro com uma chave idempotente própria.

Crie a cobrança avulsa

Informe cliente, descrição, valor e vencimento; preserve a mesma chave em retries.

Guarde o ID e a URL de pagamento

Use a URL retornada para encaminhar o cliente ao checkout oficial.

Acompanhe ou cancele explicitamente

Consulte o status nativo do RecoPay e cancele somente quando sua regra de negócio exigir.

Obrigatório em todas as chamadas

Autentique toda rota de integração com Bearer

Toda chamada para uma rota iniciada por /integracoes, inclusive GET, deve levar a chave no header Authorization. Sem esse header a API não executa a operação.

Header obrigatório

Authorization: Bearer SUA_CHAVE

Bearer autentica; Idempotency-Key não autentica

Nos comandos de criação você enviará os dois headers. A chave idempotente evita duplicidade, mas nunca substitui a credencial Bearer.

Para o fluxo completo, conceda os cinco escopos abaixo; se o sistema apenas consulta, remova os escopos de escrita e cancelamento.

Escopo	Permite
`clientes:ler`	Localizar cliente pelo documento.
`clientes:escrever`	Criar cliente ativo.
`cobrancas:escrever`	Criar cobrança avulsa.
`cobrancas:ler`	Consultar a cobrança criada pela integração.
`cobrancas:cancelar`	Cancelar explicitamente a cobrança elegível.

Uma chave ausente, inválida ou revogada retorna 401. Uma chave válida sem o escopo exigido retorna 403.

Obrigatória somente ao criar

Use uma Idempotency-Key por criação lógica

A Idempotency-Key é obrigatória ao criar um cliente ou uma cobrança. Gere-a antes da primeira tentativa, salve-a no sistema de origem e reutilize-a somente se precisar repetir exatamente aquela criação.

Endpoint	Bearer	Idempotency-Key
`GET /integracoes/clientes/por-documento/{documento}`	Obrigatório	Não usar
`POST /integracoes/clientes`	Obrigatório	Obrigatória
`POST /integracoes/clientes/{clienteId}/cobrancas`	Obrigatório	Obrigatória
`GET /integracoes/cobrancas/{cobrancaId}`	Obrigatório	Não usar
`POST /integracoes/cobrancas/{cobrancaId}/cancelamento`	Obrigatório	Não usar; o cancelamento já é idempotente

Use até 120 caracteres formados por letras, números, ponto, hífen, underline ou dois-pontos. Exemplos: cliente:erp-4821:01J6M7K8N9 e cobranca:pedido-879:01J6M7K8P0.

Situação	O que enviar	Resultado
Primeira tentativa	Nova chave + payload	`201` e `repetido: false`
Timeout ou resposta perdida	Mesma chave + mesmo payload	`200`, mesmo recurso e `repetido: true`
Chave reutilizada por engano	Mesma chave + payload diferente	`409`; nada novo é criado
Novo cliente ou nova cobrança	Nova chave + novo payload	Uma nova criação é processada

A chave pertence à operação, não à requisição HTTP

Se uma tentativa falhar sem resposta conclusiva, não gere outra chave: repita a mesma. Gere uma nova chave apenas quando a intenção for criar outro recurso.

Etapas 1 e 2

Localize ou crie o cliente

GET/integracoes/clientes/por-documento/{documento}

cURL · localizar cliente

curl --request GET \
  --url https://api.recopay.com.br/integracoes/clientes/por-documento/12345678000190 \
  --header "Authorization: Bearer SUA_CHAVE" \
  --header "Accept: application/json"

HTTP 200 · cliente localizado

{
  "id": 20,
  "tipoPessoa": "juridica",
  "nomeRazaoSocial": "Empresa Exemplo LTDA",
  "nomeFantasia": "Empresa Exemplo",
  "documento": "12345678000190",
  "email": "[email protected]",
  "telefone": "11999999999",
  "status": "ativo",
  "dataCriacao": "2026-08-25T09:30:00",
  "repetido": false
}

Se o status for inativo, interrompa o fluxo e resolva o cadastro no RecoPay. A API não reativa clientes silenciosamente.

POST/integracoes/clientes

cURL · criar cliente

curl --request POST \
  --url https://api.recopay.com.br/integracoes/clientes \
  --header "Authorization: Bearer SUA_CHAVE" \
  --header "Idempotency-Key: cliente-erp-4821" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "tipoPessoa": "juridica",
    "nomeRazaoSocial": "Empresa Exemplo LTDA",
    "nomeFantasia": "Empresa Exemplo",
    "documento": "12345678000190",
    "email": "[email protected]",
    "telefone": "11999999999",
    "nfseModoEmissao": "manual",
    "endereco": {
      "logradouro": "Praca da Se",
      "numero": "100",
      "bairro": "Se",
      "cep": "01001000",
      "municipio": "Sao Paulo",
      "uf": "SP",
      "codigoMunicipioIbge": "3550308"
    }
  }'

A primeira criação retorna 201. O retry com a mesma chave e o mesmo payload retorna 200 e repetido: true. Documento já cadastrado com outra chave retorna 409; consulte-o em vez de duplicar.

Etapa 3

Crie a cobrança avulsa

POST/integracoes/clientes/{clienteId}/cobrancas

cURL · criar cobrança

curl --request POST \
  --url https://api.recopay.com.br/integracoes/clientes/20/cobrancas \
  --header "Authorization: Bearer SUA_CHAVE" \
  --header "Idempotency-Key: pedido-erp-879" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "descricao": "Servico adicional de implantacao",
    "valorOriginal": 350.00,
    "dataVencimento": "2026-08-31",
    "competenciaReferencia": "2026-08-01",
    "formaPagamento": "boleto",
    "nfseModoEmissao": "automatico_pagamento"
  }'

HTTP 201 · cobrança criada

{
  "id": 97,
  "clienteId": 20,
  "competenciaReferencia": "2026-08-01",
  "dataVencimentoSolicitada": "2026-08-31",
  "dataVencimento": "2026-08-31",
  "valorOriginal": 350.00,
  "valorRetencaoIss": 0.00,
  "valorTotal": 350.00,
  "moeda": "BRL",
  "status": "pendente",
  "formaPagamento": "boleto",
  "gateway": "mercadopago",
  "nfseModoEmissao": "automatico_pagamento",
  "checkoutUrl": "https://recopay.app/cobrancas/visualizar/HASH_PUBLICO",
  "repetido": false
}

O vencimento solicitado pode ser deslocado para o próximo dia útil brasileiro. Se o cliente retém ISS, valorOriginal preserva a base fiscal, valorRetencaoIss explicita o abatimento e valorTotal representa o valor a pagar.

A criação não abre o gateway imediatamente

O registro da cobrança, as notificações, a tentativa de pagamento, a conciliação e a NFS-e continuam nos fluxos oficiais do RecoPay.

Etapas 4 e 5

Consulte o status e cancele quando necessário

GET/integracoes/cobrancas/{cobrancaId}

cURL · consultar cobrança

curl --request GET \
  --url https://api.recopay.com.br/integracoes/cobrancas/97 \
  --header "Authorization: Bearer SUA_CHAVE" \
  --header "Accept: application/json"

Consuma os status existentes no RecoPay, como pendente, vencida, paga e cancelada. Não derive um novo status nem considere boleto expirado como cancelamento da obrigação.

POST/integracoes/cobrancas/{cobrancaId}/cancelamento

cURL · cancelar cobrança

curl --request POST \
  --url https://api.recopay.com.br/integracoes/cobrancas/97/cancelamento \
  --header "Authorization: Bearer SUA_CHAVE" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "motivo": "Pedido cancelado no sistema de origem"
  }'

Somente uma cobrança avulsa criada pela API, ainda pendente ou vencida, pode ser cancelada por esta rota. Uma cobrança paga retorna 409. Repetir o cancelamento devolve o mesmo estado com repetido: true.

Resiliência

Falhas esperadas e segurança

Status	Significado	Ação
400	Documento, payload, vencimento ou motivo inválido.	Corrigir os dados; não repetir automaticamente.
401	Chave ausente, inválida ou revogada.	Interromper e revisar a credencial.
403	Escopo ausente, empresa suspensa ou utilitário indisponível.	Revisar permissões e contrato no painel.
404	Recurso não pertence à empresa ou não é elegível.	Não trocar o ID por tentativa.
409	Conflito idempotente, cadastro existente ou cobrança não cancelável.	Consultar o recurso e reconciliar o estado.
429	Limite de requisições.	Aplicar backoff com jitter.

Use uma chave por sistema e conceda apenas os escopos necessários.
Não registre o Bearer, payloads sensíveis ou documentos completos em logs indiscriminados.
Em timeout de criação, repita com a mesma Idempotency-Key e o mesmo payload.
Uma chave idempotente identifica uma operação lógica; não a reutilize para outra venda.
Ao encerrar a integração, revogue a chave no RecoPay.

Antes de publicar

Checklist de produção

Utilitário Integrações Externas ativo
Chave nomeada por sistema consumidor
Segredo armazenado somente no backend
Escopos reduzidos ao necessário
Consulta por documento antes da criação
Cliente inativo tratado sem reativação automática
Idempotency-Key estável por cliente e cobrança
ID e checkoutUrl persistidos no sistema de origem
Status consultado pelos valores nativos
Cancelamento exige decisão e motivo explícitos
Retries usam backoff e respeitam 429
Testes de isolamento entre empresas aprovados

Implementação assistida

Contrato resumido para agentes de IA

Prompt de integração

OBJETIVO
Integrar um backend ao RecoPay para gerar cobranca avulsa.

AUTENTICACAO
Authorization: Bearer SUA_CHAVE e obrigatorio em TODA rota /integracoes,
inclusive GET. Enviar somente pelo backend.
Escopos: clientes:ler, clientes:escrever, cobrancas:escrever,
cobrancas:ler e cobrancas:cancelar conforme a necessidade.

IDEMPOTENCIA
Idempotency-Key nao autentica e nao substitui o Bearer.
Ela e obrigatoria somente nos POSTs de criacao de cliente e cobranca.
Gerar uma chave unica por criacao logica, com ate 120 caracteres.
Em timeout, repetir o mesmo endpoint e payload com a mesma chave.
Mesma chave + mesmo payload retorna o recurso anterior.
Mesma chave + payload diferente retorna 409.
Uma nova criacao exige uma nova chave.

FLUXO
1. GET /integracoes/clientes/por-documento/{documento}
2. Se 404: POST /integracoes/clientes com Idempotency-Key
3. POST /integracoes/clientes/{clienteId}/cobrancas com Idempotency-Key
4. Persistir id, status e checkoutUrl retornados
5. GET /integracoes/cobrancas/{cobrancaId} para consultar o status
6. POST /integracoes/cobrancas/{cobrancaId}/cancelamento somente
   quando houver decisao explicita e motivo

GUARDRAILS
- Nao acessar o banco nem enviar empresaId no payload.
- Nao expor a chave no navegador, logs ou repositorio.
- Nao vincular este fluxo a cobranca variavel por uso.
- Nao criar assinatura ou consumo.
- Repetir timeout com a mesma chave e o mesmo payload.
- Nao reativar cliente inativo automaticamente.
- Nao inventar status nem tratar expiracao de boleto como cancelamento.
- Usar somente checkoutUrl retornada pela API.

RESULTADO
Cliente identificado, cobranca criada e estado reconciliavel pelo ID.

Gere cobranças avulsas a partir do seu sistema

Plano e recursos necessários

Seu sistema origina a venda; o RecoPay conduz a cobrança

Sistema integrador

RecoPay

Pré-requisitos

Fluxo completo de implementação

Localize o cliente pelo documento

Crie o cliente somente quando necessário

Crie a cobrança avulsa

Guarde o ID e a URL de pagamento

Acompanhe ou cancele explicitamente

Autentique toda rota de integração com Bearer

Use uma Idempotency-Key por criação lógica

Localize ou crie o cliente

Crie a cobrança avulsa

Consulte o status e cancele quando necessário

Falhas esperadas e segurança

Checklist de produção

Contrato resumido para agentes de IA

Continue sua integração

Valide o contrato antes de conectar seu sistema