Cobrança variável por uso

Plano e recursos necessários

Você precisa de API habilitada, Cobrança variável por uso ativo e uma chave de Integrações Externas com os escopos de uso. A ativação do consumo também ativa sua dependência de integrações. O Starter oferece 100 requisições por mês para testes; escolha o volume de API conforme os eventos enviados e as consultas de reconciliação.

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

Fature consumo sem transferir sua regra comercial para outro sistema

Considere um plano com mensalidade fixa de R$ 250,00 e um componente de R$ 0,79 por venda aprovada. A cada venda, o sistema de origem registra apenas uma unidade consumida. Quando a cobrança da assinatura for gerada, o RecoPay soma os eventos ainda não faturados, desconta a franquia incluída no contrato e calcula o valor usando o preço preservado na assinatura.

Pré-requisitos

1. Ative o utilitário Cobrança variável por uso no RecoPay.
2. Tenha uma assinatura ativa com componente do tipo Uso / excedente.
3. Confirme a franquia incluída e o valor unitário no contrato da assinatura.
4. Abra Utilitários → Integrações Externas, crie uma chave com a finalidade Cobrança variável por uso e identifique a origem do consumo. Confira os escopos de uso e copie o segredo exibido uma única vez.
5. Obtenha a referência pública da assinatura e o código exato do componente que receberá o consumo.

Fluxo de implementação

Autenticação e escopos

Todas as rotas usam a chave gerada para uma fonte de integração. Envie-a no cabeçalho HTTP:

Authorization: Bearer SUA_CHAVE

A fonte padrão recebe os escopos usos:escrever, usos:ler e usos:cancelar. O tenant é derivado da chave: não envie empresaId no corpo ou na URL.

• Nunca exponha a chave em JavaScript, aplicativo móvel ou repositório.
• Nunca registre a chave Bearer em logs.
• Rotacione imediatamente uma chave suspeita; a anterior deixa de funcionar.

Endpoints e respostas

Registrar um consumo

Use esta rota no momento em que o consumo for confirmado no sistema de origem.

Não envie valor, preco, valorUnitario, valorTotal, desconto, moeda, status, empresaId, clienteId, assinaturaId, componenteId nem qualquer outro campo fora da tabela.

curl --request POST \
  --url https://api.recopay.com.br/integracoes/usos \
  --header "Authorization: Bearer SUA_CHAVE" \
  --header "Content-Type: application/json" \
  --data '{
    "assinaturaReferencia": "REFERENCIA_PUBLICA_DA_ASSINATURA",
    "componenteCodigo": "hub-ml-tpa",
    "idExterno": "venda-987654",
    "quantidade": 1,
    "ocorridoEm": "2026-08-06T12:00:00-03:00",
    "descricao": "Venda 987654 aprovada",
    "metadados": {
      "origem": "hub-full-ecommerce",
      "pedido": "987654"
    }
  }'

{
  "id": 1482,
  "idExterno": "venda-987654",
  "assinaturaReferencia": "REFERENCIA_PUBLICA_DA_ASSINATURA",
  "componenteCodigo": "hub-ml-tpa",
  "quantidade": 1,
  "status": "pendente",
  "ocorridoEm": "2026-08-06T15:00:00Z",
  "recebidoEm": "2026-08-06T15:00:01Z",
  "cobrancaId": null,
  "cobrancaItemId": null,
  "repetido": false
}

O primeiro registro retorna HTTP 201. A repetição idempotente do mesmo evento retorna HTTP 200 com repetido: true.

Registrar um lote

Envie de 1 a 500 eventos. O corpo externo aceita somente usos, e cada item segue exatamente a mesma lista de campos permitidos no registro individual. Cada item é processado de forma independente; por isso, avalie o resultado item a item mesmo quando a resposta geral for HTTP 200.

{
  "usos": [
    {
      "assinaturaReferencia": "ASSINATURA_A",
      "componenteCodigo": "armazenamento-gb",
      "idExterno": "medicao-2026-08-06-a",
      "quantidade": 12.75,
      "ocorridoEm": "2026-08-06T23:50:00-03:00",
      "descricao": "Armazenamento apurado"
    },
    {
      "assinaturaReferencia": "ASSINATURA_B",
      "componenteCodigo": "atendimento-extra",
      "idExterno": "ticket-456",
      "quantidade": 1,
      "ocorridoEm": "2026-08-06T18:30:00-03:00",
      "descricao": "Atendimento excedente 456"
    }
  ]
}

Consultar um consumo

curl --request GET \
  --url https://api.recopay.com.br/integracoes/usos/venda-987654 \
  --header "Authorization: Bearer SUA_CHAVE"

Depois do faturamento, a resposta passa a informar status: "faturado", cobrancaId e cobrancaItemId. Essa é a ligação auditável entre o evento e a cobrança.

Cancelar um consumo

O corpo desta rota aceita exclusivamente o campo motivo, obrigatório e limitado a 255 caracteres.

curl --request POST \
  --url https://api.recopay.com.br/integracoes/usos/venda-987654/cancelamento \
  --header "Authorization: Bearer SUA_CHAVE" \
  --header "Content-Type: application/json" \
  --data '{ "motivo": "Venda cancelada no sistema de origem" }'

O integrador não precisa consultar o estado para escolher uma operação. Se o consumo estiver pendente, ele será cancelado. Se já estiver faturado, o RecoPay preservará a cobrança consolidada e criará um lançamento compensatório para o próximo ciclo.

{
  "operacaoExecutada": "cancelamento",
  "repetido": false,
  "usoOriginal": {
    "idExterno": "venda-987654",
    "status": "cancelado"
  },
  "usoCompensatorio": null
}

{
  "operacaoExecutada": "estorno",
  "repetido": false,
  "usoOriginal": {
    "idExterno": "venda-987654",
    "status": "estornado",
    "cobrancaId": 781
  },
  "usoCompensatorio": {
    "idExterno": "estorno:1482",
    "quantidade": -1,
    "status": "pendente"
  }
}

operacaoExecutada informa a decisão tomada pelo RecoPay. Repetir o mesmo cancelamento é seguro e retorna repetido: true. Um uso reservado pelo faturamento retorna HTTP 409; consulte novamente antes de repetir.

Idempotência, timeout e retry

O idExterno é a chave de idempotência funcional. Ele é único dentro da fonte e deve representar um único fato de negócio.

Sugestão: 1 s, 2 s, 4 s, 8 s e 16 s de espera, sempre com variação aleatória e limite de tentativas.

Como o consumo vira cobrança

A integração não precisa aguardar o fechamento do mês. Na geração da cobrança, o RecoPay fixa um corte, reserva os usos pendentes e calcula o componente com os valores preservados na assinatura.

Exemplo: foram registradas 108 unidades, a assinatura inclui 100 e o valor unitário é R$ 0,79. A cobrança terá 8 unidades faturáveis, totalizando R$ 6,32 nesse componente.

• Eventos recebidos depois do corte permanecem pendentes para o próximo ciclo.
• Se a quantidade faturável for zero, o ciclo é encerrado sem criar valor e sem permitir dupla cobrança.
• Cupons de desconto não reduzem componentes variáveis por uso.
• Cancelar uma cobrança libera os usos vinculados para nova apuração.

Estados e rastreabilidade

O painel do utilitário preserva a cadeia fonte → evento → apuração → item → cobrança. Use o idExterno como referência comum entre logs do sistema de origem e do RecoPay.

Respostas de erro

{
  "sucesso": false,
  "codigo": "uso.componente_nao_encontrado",
  "mensagem": "Assinatura ativa ou componente de uso nao encontrado.",
  "requestId": "0HN9ABC123:00000001",
  "detalhes": null
}

Limites adicionais: idExterno até 150 caracteres, descrição e motivo até 255, componente até 50, referência até 64 e metadados até 8 KB.

Checklist de produção

• Uma fonte e uma chave exclusivas por ambiente.
• Segredo armazenado fora do código-fonte.
• ID externo estável, único e pesquisável.
• Fila local de saída para não perder eventos.
• Retry apenas para erros transitórios.
• Consulta após timeout de resultado incerto.
• Logs sem token e sem dados sensíveis.
• Alertas para 401, 403, 409 e falhas repetidas.
• Rotina de reconciliação por ID externo.
• Teste de cancelamento antes do faturamento.
• Teste de estorno depois do faturamento.
• Validação da franquia e do primeiro ciclo real.

Contrato resumido para uma LLM

Forneça o bloco abaixo junto com o contexto do seu projeto. Ele reduz ambiguidades e impede que um agente externo invente campos comerciais ou rotas alternativas.

Implemente a integração de consumo variável com a API RecoPay.

BASE URL
https://api.recopay.com.br

AUTENTICAÇÃO
Authorization: Bearer SUA_CHAVE
Nunca exponha ou registre a chave em logs.

ROTAS CANÔNICAS
POST /integracoes/usos
POST /integracoes/usos/lote
GET /integracoes/usos/{idExterno}
POST /integracoes/usos/{idExterno}/cancelamento

PAYLOAD DE REGISTRO
{
  "assinaturaReferencia": "REFERENCIA_PUBLICA_DA_ASSINATURA",
  "componenteCodigo": "CODIGO_DO_COMPONENTE_DE_USO",
  "idExterno": "IDENTIFICADOR_UNICO_NO_SISTEMA_DE_ORIGEM",
  "quantidade": 1,
  "ocorridoEm": "2026-08-06T12:00:00-03:00",
  "descricao": "DESCRICAO_AUDITAVEL",
  "metadados": { "origem": "MEU_SISTEMA" }
}

CAMPOS PERMITIDOS NO REGISTRO
Obrigatórios: assinaturaReferencia, componenteCodigo, idExterno, quantidade, ocorridoEm.
Opcionais: descricao, metadados.
Esta lista é exaustiva. Use exatamente camelCase e não serialize uma entidade completa.
O lote aceita somente { "usos": [...] } no nível externo.
O cancelamento aceita somente { "motivo": "..." } no corpo.

REGRAS OBRIGATÓRIAS
1. Não envie campos além da lista permitida, nem mesmo IDs internos, status ou dados informativos.
2. Não envie empresaId, preço, valor, desconto, imposto, moeda ou total.
3. O idExterno é imutável e idempotente por evento.
4. Quantidade deve ser positiva e ter no máximo 4 casas decimais.
5. ocorridoEm deve ser ISO 8601 com fuso explícito.
6. HTTP 201 cria; HTTP 200 com repetido=true também é sucesso.
7. Mesmo idExterno com payload diferente retorna HTTP 409.
8. Após timeout, consulte pelo idExterno antes de repetir.
9. Faça retry somente em 408, 429 e 5xx, com backoff e jitter.
10. Para desfazer qualquer evento, use apenas a rota de cancelamento e informe o motivo.
11. O RecoPay decide entre cancelamento e estorno compensatório conforme o estado do uso.
12. Em lote, avalie sucesso e erro de cada item.
13. Armazene idExterno, status, id interno e requestId para reconciliação.

Implemente DTOs estritos, cliente HTTP resiliente, testes de idempotência,
cancelamento unificado, timeout e reconciliação. Não crie aliases de rota.

Continue sua integração

• Ciclo completo: contratação, pagamento e liberação de acesso
• Cobrança avulsa para valores pontuais