Leve o financeiro e a gestão de planos para dentro do seu produto

Navegador autenticado
  └─ GET /api/minha-conta/financeiro        [sessão do produto]
       └─ Backend resolve assinaturaReferencia no banco local
            └─ GET https://api.recopay.com.br/integracoes/...
                 Authorization: Bearer rpk_... [segredo do servidor]

{
  "contaLocalId": "workspace_4831",
  "recopayContratacaoReferencia": "550e8400-e29b-41d4-a716-446655440000",
  "recopayAssinaturaReferencia": "assinatura-publica-estavel",
  "vinculoStatus": "ativo"
}

RECOPAY_API_BASE_URL=https://api.recopay.com.br
RECOPAY_API_KEY=rpk_PREFIXO_SEGREDO

# Nunca use VITE_, NEXT_PUBLIC_, PUBLIC_ ou equivalente nesta chave.

curl --request GET \
  --url "https://api.recopay.com.br/integracoes/assinaturas/REFERENCIA/cobrancas?status=pendente&pagina=1&tamanhoPagina=20" \
  --header "Authorization: Bearer SUA_CHAVE_RPK" \
  --header "Accept: application/json"

{
  "sucesso": true,
  "mensagem": "Cobrancas da assinatura carregadas com sucesso.",
  "dados": {
    "pagina": 1,
    "tamanhoPagina": 20,
    "total": 1,
    "itens": [{
      "id": 2481,
      "planoNome": "Plano Profissional",
      "competencia": "2026-09-01T00:00:00",
      "vencimento": "2026-09-10T00:00:00",
      "valorOriginal": 149.90,
      "valorDesconto": 0.00,
      "valorMulta": 0.00,
      "valorJuros": 0.00,
      "valorTotal": 149.90,
      "moeda": "BRL",
      "status": "pendente",
      "formaPagamento": "Pix",
      "dataPagamento": null,
      "checkoutUrl": "https://recopay.app/cobrancas/visualizar/..."
    }]
  }
}

{
  "sucesso": true,
  "mensagem": "Pagamentos da assinatura carregados com sucesso.",
  "dados": {
    "pagina": 1,
    "tamanhoPagina": 20,
    "total": 1,
    "itens": [{
      "id": 731,
      "cobrancaId": 2480,
      "planoNome": "Plano Profissional",
      "gateway": "mercadopago",
      "metodo": "Pix",
      "status": "pago",
      "valor": 149.90,
      "moeda": "BRL",
      "dataAutorizacao": "2026-08-10T10:31:00",
      "dataCaptura": "2026-08-10T10:31:02",
      "dataEstorno": null,
      "dataCriacao": "2026-08-10T10:29:00",
      "dataAtualizacao": "2026-08-10T10:31:02",
      "competenciaCobranca": "2026-08-01T00:00:00",
      "vencimentoCobranca": "2026-08-10T00:00:00",
      "statusCobranca": "paga",
      "cartaoBandeira": null,
      "cartaoUltimosDigitos": null,
      "checkoutUrl": "https://recopay.app/cobrancas/visualizar/..."
    }]
  }
}

{
  "sucesso": true,
  "mensagem": "Notas fiscais da assinatura carregadas com sucesso.",
  "dados": {
    "pagina": 1,
    "tamanhoPagina": 20,
    "total": 1,
    "itens": [{
      "id": 184,
      "cobrancaId": 2480,
      "planoNome": "Plano Profissional",
      "numeroNfse": "2214",
      "chaveAcesso": "350600312102565230001570000000002214...",
      "status": "autorizada",
      "dataEmissao": "2026-08-10T10:36:00",
      "dataCompetencia": "2026-08-01T00:00:00",
      "dataCancelamento": null,
      "valorServico": 149.90,
      "valorIss": 3.00,
      "aliquotaIss": 2.00,
      "descricaoServico": "Licenca mensal do produto",
      "pdfDisponivel": true,
      "xmlDisponivel": true
    }]
  }
}

{
  "assinaturaReferencia": "assinatura-publica-estavel",
  "planoAtual": {
    "id": 12,
    "nome": "Profissional",
    "valor": 149.90,
    "moeda": "BRL",
    "periodicidade": "mensal",
    "periodicidadeIntervalo": 1
  },
  "planosDisponiveis": [
    {
      "id": 11,
      "nome": "Essencial",
      "valor": 99.90,
      "moeda": "BRL",
      "periodicidade": "mensal",
      "periodicidadeIntervalo": 1,
      "tipoAlteracao": "downgrade"
    },
    {
      "id": 13,
      "nome": "Escala",
      "valor": 249.90,
      "moeda": "BRL",
      "periodicidade": "mensal",
      "periodicidadeIntervalo": 1,
      "tipoAlteracao": "upgrade"
    }
  ],
  "alteracaoPendente": null,
  "ultimaAlteracaoEfetivada": null
}

{
  "planoDestinoId": 13
}

{
  "assinaturaReferencia": "assinatura-publica-estavel",
  "tipo": "upgrade",
  "planoAtual": { "id": 12, "nome": "Profissional", "valor": 149.90, "moeda": "BRL", "periodicidade": "mensal", "periodicidadeIntervalo": 1 },
  "planoDestino": { "id": 13, "nome": "Escala", "valor": 249.90, "moeda": "BRL", "periodicidade": "mensal", "periodicidadeIntervalo": 1 },
  "valorAlteracao": 100.00,
  "moeda": "BRL",
  "aplicacao": "apos_pagamento",
  "efetivarEm": null,
  "inicioCicloAtual": "2026-09-10",
  "fimCicloAtual": "2026-10-09",
  "proximoVencimento": "2026-10-10",
  "mensagem": "O novo plano sera ativado somente depois da confirmacao do pagamento da diferenca integral. A data de renovacao nao muda."
}

curl --request POST \
  --url "https://api.recopay.com.br/integracoes/assinaturas/REFERENCIA/alteracoes-plano" \
  --header "Authorization: Bearer SUA_CHAVE_RPK" \
  --header "Idempotency-Key: troca-plano-workspace-4831-20260904" \
  --header "Content-Type: application/json" \
  --data '{"planoDestinoId":13}'

{
  "assinaturaReferencia": "assinatura-publica-estavel",
  "alteracaoReferencia": "3ae7807b-1eaf-4b5c-852d-ae92920f374d",
  "tipo": "upgrade",
  "status": "aguardando_pagamento",
  "valorAlteracao": 100.00,
  "moeda": "BRL",
  "aplicacao": "apos_pagamento",
  "efetivarEm": null,
  "efetivadaEm": null,
  "inicioCicloAtual": "2026-09-10",
  "fimCicloAtual": "2026-10-09",
  "proximoVencimento": "2026-10-10",
  "planoAtualId": 12,
  "planoDestinoId": 13,
  "cobrancaId": 2510,
  "checkoutUrl": "https://recopay.app/cobrancas/visualizar/...",
  "repetido": false
}

{
  "assinaturaReferencia": "assinatura-publica-estavel",
  "alteracaoReferencia": "4d2b063f-c37d-4b71-b27c-85bbc2261c5b",
  "tipo": "downgrade",
  "status": "agendada",
  "valorAlteracao": 0.00,
  "moeda": "BRL",
  "aplicacao": "proximo_ciclo",
  "efetivarEm": "2026-10-10",
  "efetivadaEm": null,
  "inicioCicloAtual": "2026-10-10",
  "fimCicloAtual": "2026-11-09",
  "proximoVencimento": "2026-11-10",
  "planoAtualId": 12,
  "planoDestinoId": 11,
  "cobrancaId": null,
  "checkoutUrl": null,
  "repetido": false
}

curl --request POST \
  --url "https://api.recopay.com.br/integracoes/assinaturas/REFERENCIA/alteracoes-plano/ALTERACAO/cancelamento" \
  --header "Authorization: Bearer SUA_CHAVE_RPK" \
  --header "Idempotency-Key: cancelar-troca-workspace-4831-20260904"

X-Recopay-Event-Id: 3b530fd4-493e-41ca-a52a-ddd98c63a875
X-Recopay-Timestamp: 1788541200
X-Recopay-Signature: v1=HMAC_SHA256(timestamp + "." + corpo_original)

{
  "eventoId": "3b530fd4-493e-41ca-a52a-ddd98c63a875",
  "evento": "assinatura.plano_alteracao_efetivada",
  "ocorridoEm": "2026-09-04T18:20:00Z",
  "assinaturaReferencia": "assinatura-publica-estavel",
  "alteracaoReferencia": "3ae7807b-1eaf-4b5c-852d-ae92920f374d",
  "tipoAlteracao": "upgrade",
  "status": "efetivada",
  "planoOrigem": { "id": 12, "nome": "Profissional" },
  "planoDestino": { "id": 13, "nome": "Escala" },
  "efetivarEm": null,
  "efetivadaEm": "2026-09-04T18:20:03Z",
  "inicioCicloAtual": "2026-09-10",
  "fimCicloAtual": "2026-10-09",
  "proximoVencimento": "2026-10-10",
  "cobrancaId": 2510,
  "erro": null
}

app.get('/api/minha-conta/financeiro', exigirSessao, async (req, res) => {
  const contaLocalId = req.session.contaId;
  const vinculo = await db.vinculosRecopay.findByConta(contaLocalId);

  if (!vinculo?.assinaturaReferencia) {
    return res.status(404).json({ codigo: 'financeiro_nao_vinculado' });
  }

  const base = `${process.env.RECOPAY_API_BASE_URL}/integracoes/assinaturas/` +
    encodeURIComponent(vinculo.assinaturaReferencia);
  const headers = {
    Authorization: `Bearer ${process.env.RECOPAY_API_KEY}`,
    Accept: 'application/json'
  };

  const [cobrancas, pagamentos, notas] = await Promise.all([
    fetch(`${base}/cobrancas?tamanhoPagina=20`, { headers }),
    fetch(`${base}/pagamentos?tamanhoPagina=20`, { headers }),
    fetch(`${base}/notas?tamanhoPagina=20`, { headers })
  ]);

  if ([cobrancas, pagamentos, notas].some(r => !r.ok)) {
    return res.status(502).json({ codigo: 'financeiro_temporariamente_indisponivel' });
  }

  res.set('Cache-Control', 'private, no-store');
  return res.json({
    cobrancas: (await cobrancas.json()).dados,
    pagamentos: (await pagamentos.json()).dados,
    notas: (await notas.json()).dados
  });
});

OBJETIVO
Exibir cobrancas, pagamentos e NFS-e e permitir upgrade ou downgrade de uma assinatura RecoPay dentro do dashboard do produto terceiro.

IDENTIDADES
- O cliente autentica somente no produto terceiro.
- Nao pedir, armazenar ou conhecer a senha RecoPay.
- Nao usar token rct.* neste fluxo.
- A Central do Cliente RecoPay permanece opcional e independente.

VINCULO
- Persistir contratacaoReferencia para correlacao do onboarding.
- Persistir assinaturaReferencia junto ao tenant local provisionado.
- Confirmar o vinculo pelo webhook de primeiro pagamento.
- Nao vincular contas apenas por coincidencia de e-mail ou documento.
- O navegador nunca escolhe livremente assinaturaReferencia.

AUTENTICACAO DA API
- Criar chave rpk_ com os escopos financeiro:cliente:ler e assinaturas:cliente:alterar-plano.
- Manter a chave somente no backend e fora de logs.
- Enviar Authorization: Bearer em todas as chamadas.

ROTAS
- GET /integracoes/assinaturas/{assinaturaReferencia}/cobrancas
- GET /integracoes/assinaturas/{assinaturaReferencia}/pagamentos
- GET /integracoes/assinaturas/{assinaturaReferencia}/notas
- GET /integracoes/assinaturas/{assinaturaReferencia}/notas/{notaId}/pdf
- GET /integracoes/assinaturas/{assinaturaReferencia}/notas/{notaId}/xml
- GET /integracoes/assinaturas/{assinaturaReferencia}/planos-disponiveis
- POST /integracoes/assinaturas/{assinaturaReferencia}/alteracoes-plano/simulacao
- POST /integracoes/assinaturas/{assinaturaReferencia}/alteracoes-plano [Idempotency-Key]
- GET /integracoes/assinaturas/{assinaturaReferencia}/alteracoes-plano/{alteracaoReferencia}
- POST /integracoes/assinaturas/{assinaturaReferencia}/alteracoes-plano/{alteracaoReferencia}/cancelamento [Idempotency-Key]
- Listagens aceitam status, pagina e tamanhoPagina entre 1 e 100.

ALTERACAO DE PLANO
- Enviar somente planoDestinoId; RecoPay define tipo, valor, componentes, data e cobranca.
- Sempre simular antes de confirmar.
- Persistir Idempotency-Key por operacao e reutiliza-la em timeout.
- Upgrade cobra a diferenca integral, preserva o ciclo e so efetiva apos pagamento.
- Downgrade nao gera credito ou estorno e efetiva no proximo ciclo.
- Somente downgrade agendado pode ser cancelado.
- Nao liberar recursos enquanto o status nao for efetivada.

WEBHOOKS DE PLANO
- assinatura.plano_alteracao_agendada
- assinatura.plano_alteracao_efetivada
- assinatura.plano_alteracao_cancelada
- assinatura.plano_alteracao_falhou
- Validar X-Recopay-Timestamp e X-Recopay-Signature sobre timestamp + "." + corpo original.
- Deduplicar X-Recopay-Event-Id e reconciliar pela rota GET.

ARQUITETURA
1. Navegador chama o backend do produto com sua sessao local.
2. Backend resolve o tenant e busca assinaturaReferencia no banco local.
3. Backend chama o RecoPay com a chave rpk_.
4. Backend devolve apenas os dados necessarios ou transmite o arquivo.

GUARDRAILS
- Nao expor rpk_ em JavaScript, app distribuido, cookie, URL ou resposta.
- Nao aceitar empresaId, clienteId ou assinaturaId numerico do navegador.
- Autorizar a conta local antes de toda consulta e download.
- Nao recalcular valores ou reinterpretar status financeiros.
- Nao enviar valor, periodicidade, tipo de alteracao, data ou componentes ao solicitar troca.
- Recurso de outra empresa ou assinatura deve resultar em 404.
- Indisponibilidade da API nunca significa inadimplencia.