Bloqueio de acesso por inadimplência com a API RecoPay

Plano e recursos necessários

Você precisa de API habilitada e Integrações Externas ativo, com o escopo financeiro:ler. O Starter oferece 100 requisições por mês para testes. Dimensione o plano considerando a frequência das consultas, sem transformar indisponibilidade da API em bloqueio do cliente.

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

O problema resolvido

Use a verdade financeira do RecoPay sem terceirizar sua regra de acesso

Um software pode bloquear imediatamente, conceder 15 dias de carência ou limitar apenas recursos premium. Essas decisões pertencem ao produto integrado. O RecoPay fornece os dados objetivos para que a decisão seja consistente: situação da assinatura, dias do maior atraso, valor vencido e cobranças que podem ser pagas.

Guardrail de responsabilidade

Não replique status de pagamento em uma tabela paralela como fonte de verdade. Consulte o RecoPay nos pontos de decisão e mantenha apenas cache curto para resiliência.

Sistema consumidor

Define a carência e os níveis de restrição.
Decide quando consultar ou renovar o cache.
Mostra aviso e link de regularização.
Libera o acesso após nova consulta adimplente.

RecoPay

Concilia pagamentos e vencimentos.
Ignora cobranças pagas, canceladas ou estornadas.
Calcula os dias em atraso em São Paulo.
Retorna links oficiais de checkout.

Antes da consulta

Pré-requisitos

Em Integrações externas, crie uma chave com a finalidade Bloqueio de acesso por inadimplência. O escopo financeiro:ler será selecionado automaticamente.
Armazene a referência pública opaca da assinatura no sistema consumidor.
Defina por escrito a carência e o comportamento durante indisponibilidade.
Mantenha a chave exclusivamente no backend.

Roadmap literal

Fluxo de implementação

Associe a referência da assinatura

Salve a assinaturaReferencia no cadastro interno do contrato. Não use nome, documento ou ID sequencial como substituto.

Consulte no backend

Faça a chamada no login, na abertura de uma sessão protegida ou durante a renovação do cache.

Aplique sua carência

Compare situacaoFinanceira e maiorAtrasoDias com a política do seu produto.

Oriente a regularização

Mostre a cobrança relevante e use somente o checkoutUrl retornado pela API.

Revalide e libere

Após o pagamento, uma nova consulta adimplente deve remover a restrição automaticamente.

Acesso servidor a servidor

Autenticação

Envie a chave no cabeçalho Bearer. Nunca exponha esta credencial em JavaScript entregue ao navegador.

Cabeçalho HTTP

Authorization: Bearer SUA_CHAVE
Accept: application/json

Contrato HTTP

Consultar a situação financeira

GET/integracoes/assinaturas/{assinaturaReferencia}/situacao-financeira

cURL · requisição

curl --request GET \
  --url https://api.recopay.com.br/integracoes/assinaturas/ass_01HXYZ/situacao-financeira \
  --header "Authorization: Bearer SUA_CHAVE" \
  --header "Accept: application/json"

HTTP 200 · resposta

{
  "assinaturaReferencia": "ass_01HXYZ",
  "assinaturaStatus": "ativa",
  "situacaoFinanceira": "inadimplente",
  "maiorAtrasoDias": 18,
  "valorTotalEmAtraso": 199.90,
  "cobrancasEmAtraso": [
    {
      "cobrancaId": 4821,
      "vencimento": "2026-07-20",
      "diasEmAtraso": 18,
      "valor": 199.90,
      "checkoutUrl": "https://recopay.app/cobrancas/visualizar/..."
    }
  ]
}

Resposta factual

inadimplente não significa bloqueio automático. A resposta descreve a situação; sua política decide o efeito no produto.

Exemplo complementar

Aplique uma política de bloqueio previsível

O exemplo abaixo usa JavaScript apenas para interpretar uma resposta que já veio do backend. A chamada HTTP principal permanece documentada em cURL.

JavaScript · regra no sistema consumidor

function decidirAcesso(financeiro, diasCarencia = 15) {
  if (financeiro.situacaoFinanceira !== "inadimplente") {
    return { acesso: "liberado", cobranca: null };
  }

  const cobranca = financeiro.cobrancasEmAtraso
    .sort((a, b) => b.diasEmAtraso - a.diasEmAtraso)[0];

  if (financeiro.maiorAtrasoDias < diasCarencia) {
    return { acesso: "aviso", cobranca };
  }

  return { acesso: "bloqueado", cobranca };
}

Situação	Decisão sugerida	Experiência
Adimplente	Liberar	Acesso normal.
Inadimplente dentro da carência	Avisar	Banner com vencimento e link.
Inadimplente após carência	Restringir	Bloqueio reversível com checkout.
API indisponível	Usar cache curto	Não bloquear por falha técnica isolada.

Resiliência

Falhas esperadas e segurança

401: chave ausente, inválida ou revogada.
403: escopo financeiro:ler ausente.
404: assinatura não localizada no escopo da empresa.
429: limite de requisições atingido; respeite o retry.
5xx ou timeout: use o último estado conhecido por uma janela curta e registre a falha.

Não bloqueie por indisponibilidade

Uma falha de rede não prova inadimplência. Defina TTL, retry com backoff e uma janela operacional antes de negar acesso.

Antes de ativar

Checklist de produção

Chave restrita ao backend
Escopo financeiro:ler validado
Referência opaca persistida
Carência definida por produto
Cache com TTL curto
Timeout e retry configurados
Checkout oficial exibido
Liberação revalidada
Falhas registradas sem segredos
Testes de 401, 403, 404 e 429

Implementação assistida

Contrato resumido para agentes de IA

Prompt de integração

OBJETIVO
Controlar acesso a um sistema conforme a situacao financeira de uma assinatura RecoPay.

ENTRADA
- assinaturaReferencia: referencia publica opaca.
- diasCarencia: politica definida pelo sistema consumidor.

CHAMADA
GET /integracoes/assinaturas/{assinaturaReferencia}/situacao-financeira
Authorization: Bearer com escopo financeiro:ler.

REGRA
- Liberar quando situacaoFinanceira for diferente de inadimplente.
- Avisar quando inadimplente e maiorAtrasoDias for menor que diasCarencia.
- Bloquear quando inadimplente e maiorAtrasoDias for igual ou maior que diasCarencia.
- Usar somente checkoutUrl retornado pela API.
- Nao bloquear por timeout ou erro 5xx; usar cache curto e registrar falha.

SEGURANCA
- Executar a chamada somente no backend.
- Nunca expor a chave no navegador.
- Nao usar nome, documento ou ID interno no lugar da referencia publica.

Bloqueie acesso conforme sua política de inadimplência