Conduza um ciclo de venda completo em seu sistema

VITE_RECO_API_URL=https://api.recopay.com.br
VITE_RECOPAY_APP_URL=https://recopay.app
VITE_CLIENTES_URL=https://clientes.recopay.com.br
VITE_CHECKOUT_PUBLICO_ID=SEU_CHECKOUT_PUBLICO_ID
VITE_PRODUTO_CODIGO=produto-a

curl --request GET \
  --url https://api.recopay.com.br/checkout/SEU_CHECKOUT_PUBLICO_ID/produtos/produto-a/planos \
  --header "Accept: application/json"

curl --request GET \
  --url https://api.recopay.com.br/checkout/SEU_CHECKOUT_PUBLICO_ID/planos/42 \
  --header "Accept: application/json"

curl --request POST \
  --url https://api.recopay.com.br/checkout/SEU_CHECKOUT_PUBLICO_ID/clientes/verificacao \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "documento": "12345678000190",
    "email": "[email protected]"
  }'

{
  "mensagem": "Cliente ja cadastrado para esta empresa. Faca login para continuar a contratacao.",
  "dados": {
    "clienteExistente": true,
    "documentoEmUso": true,
    "emailEmUso": true,
    "requerLogin": true
  }
}

curl --request POST \
  --url https://api.recopay.com.br/clientes/auth/login \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "checkoutPublicoId": "SEU_CHECKOUT_PUBLICO_ID",
    "email": "[email protected]",
    "senha": "SENHA_DO_CLIENTE"
  }'

{
  "sucesso": true,
  "mensagem": "Login realizado com sucesso.",
  "dados": {
    "token": "rct_TOKEN_DO_CLIENTE",
    "expiraEm": "2026-08-31T19:00:00Z",
    "trocaSenhaObrigatoria": false
  }
}

curl --request POST \
  --url https://api.recopay.com.br/checkout/SEU_CHECKOUT_PUBLICO_ID/contratacoes \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: venda-produto-a-20260831-000184" \
  --data '{
    "planoId": 42,
    "cliente": {
      "tipoPessoa": "J",
      "nome": "Empresa Exemplo LTDA",
      "nomeFantasia": "Empresa Exemplo",
      "documento": "12345678000190",
      "email": "[email protected]",
      "telefone": "11999999999",
      "endereco": {
        "cep": "01001000",
        "logradouro": "Praca da Se",
        "numero": "100",
        "bairro": "Se",
        "municipio": "Sao Paulo",
        "uf": "SP",
        "codigoMunicipioIbge": "3550308"
      }
    },
    "componentes": [
      { "planoPrecoId": 73, "quantidade": 1 }
    ],
    "formaPagamento": "pix",
    "nfseModoEmissao": "automatico_pagamento",
    "descricao": "Contratacao pelo checkout do Produto A",
    "dataInicio": "2026-08-31",
    "diaVencimento": 10,
    "termosUsoAceitos": true
  }'

{
  "mensagem": "Contratacao criada com sucesso.",
  "dados": {
    "checkoutUrl": "https://recopay.app/cobrancas/visualizar/...",
    "contratacaoReferencia": "550e8400-e29b-41d4-a716-446655440000",
    "assinaturaReferencia": "b9df2f8020574c2d812863f59a86a264",
    "pagamentoNecessario": true,
    "statusAssinatura": "pendente"
  }
}

window.location.assign(resultado.dados.checkoutUrl);

POST /webhooks/recopay/plano-ativo HTTP/1.1
Host: api.produto-a.example
Content-Type: application/json; charset=utf-8
User-Agent: RecoPay-Webhooks/1.0
X-Recopay-Event-Id: 93a8f7a1-37e4-4ce5-9c1c-41b918b17765
X-Recopay-Timestamp: 1788197538
X-Recopay-Signature: v1=HMAC_SHA256_EM_HEXADECIMAL_MINUSCULO

{ ...corpo JSON documentado abaixo... }

{
  "eventoId": "93a8f7a1-37e4-4ce5-9c1c-41b918b17765",
  "evento": "primeiro_pagamento_confirmado",
  "ocorridoEm": "2026-08-31T17:32:18.114Z",
  "contratacaoReferencia": "550e8400-e29b-41d4-a716-446655440000",
  "assinaturaReferencia": "b9df2f8020574c2d812863f59a86a264",
  "cliente": {
    "nome": "Empresa Exemplo LTDA",
    "documento": "12345678000190",
    "email": "[email protected]"
  },
  "checkout": {
    "publicoId": "79be63f8765b11f18848bc2411061702"
  },
  "produto": {
    "codigo": "produto-a"
  },
  "plano": {
    "id": 42
  },
  "cobranca": {
    "id": 2310,
    "valor": 149.90,
    "moeda": "BRL",
    "vencimento": "2026-08-31",
    "formaPagamento": "pix",
    "gateway": "mercadopago"
  }
}

{
  "eventoId": "93a8f7a1-37e4-4ce5-9c1c-41b918b17765",
  "evento": "assinatura_ativada_sem_cobranca",
  "ocorridoEm": "2026-09-19T16:30:00Z",
  "contratacaoReferencia": "550e8400-e29b-41d4-a716-446655440000",
  "assinaturaReferencia": "b9df2f8020574c2d812863f59a86a264",
  "cliente": {
    "nome": "Empresa Exemplo LTDA",
    "documento": "12345678000190",
    "email": "[email protected]"
  },
  "checkout": {
    "publicoId": "79be63f8765b11f18848bc2411061702"
  },
  "produto": {
    "codigo": "produto-a"
  },
  "plano": {
    "id": 42
  },
  "ativacao": {
    "status": "ativa",
    "motivo": "valor_inicial_zero",
    "valorInicial": 0.00,
    "moeda": "BRL"
  }
}

curl --request POST \
  --url https://api.produto-a.example/webhooks/recopay/plano-ativo \
  --header "Content-Type: application/json" \
  --header "X-Recopay-Event-Id: 93a8f7a1-37e4-4ce5-9c1c-41b918b17765" \
  --header "X-Recopay-Timestamp: 1788197538" \
  --header "X-Recopay-Signature: v1=HMAC_HEXADECIMAL" \
  --data @plano-ativo.json

import crypto from 'node:crypto';
import express from 'express';

const app = express();
app.post('/webhooks/recopay/plano-ativo',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const eventId = req.get('X-Recopay-Event-Id') || '';
    const timestamp = req.get('X-Recopay-Timestamp') || '';
    const received = req.get('X-Recopay-Signature') || '';
    const now = Math.floor(Date.now() / 1000);

    if (!/^\d+$/.test(timestamp) || Math.abs(now - Number(timestamp)) > 300) {
      return res.sendStatus(401);
    }

    const rawBody = req.body;
    const expected = 'v1=' + crypto
      .createHmac('sha256', process.env.RECOPAY_WEBHOOK_SECRET)
      .update(timestamp + '.')
      .update(rawBody)
      .digest('hex');
    const a = Buffer.from(expected, 'ascii');
    const b = Buffer.from(received, 'ascii');
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.sendStatus(401);
    }

    const evento = JSON.parse(rawBody.toString('utf8'));
    const eventosAceitos = new Set([
      'primeiro_pagamento_confirmado',
      'assinatura_ativada_sem_cobranca'
    ]);
    if (evento.eventoId !== eventId || !eventosAceitos.has(evento.evento)) {
      return res.sendStatus(400);
    }

    await persistirEventoEEnfileirarProvisionamento(evento); // UNIQUE(eventoId)
    return res.sendStatus(204);
  });

HTTP/1.1 204 No Content

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "recebido": true,
  "eventoId": "93a8f7a1-37e4-4ce5-9c1c-41b918b17765"
}

https://app.produto-a.example/onboarding?ref=550e8400-e29b-41d4-a716-446655440000

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

{
  "assinaturaReferencia": "REFERENCIA_PUBLICA",
  "assinaturaStatus": "ativa",
  "cliente": {
    "id": 318,
    "nome": "Empresa Exemplo LTDA",
    "documento": "12345678000190",
    "email": "[email protected]"
  },
  "situacaoFinanceira": "inadimplente",
  "possuiCobrancasEmAtraso": true,
  "quantidadeCobrancasEmAtraso": 1,
  "valorTotalEmAtraso": 149.90,
  "maiorAtrasoDias": 8,
  "consultadoEm": "2026-09-18T10:20:00-03:00",
  "cobrancasEmAtraso": [
    {
      "id": 2441,
      "vencimento": "2026-09-10",
      "diasEmAtraso": 8,
      "valor": 149.90,
      "linkPagamento": "https://recopay.app/cobrancas/visualizar/..."
    }
  ]
}

OBJETIVO
Integrar um ciclo de venda de SaaS com Checkout, API e webhook do RecoPay.

CONFIGURACAO DO CHECKOUT
- VITE_CHECKOUT_PUBLICO_ID identifica a empresa e nao e segredo.
- VITE_PRODUTO_CODIGO fixa o produto exibido neste dominio.
- A origem deve ser HTTPS exata e estar vinculada ao produto no RecoPay.

FLUXO DE AQUISICAO
1. GET /checkout/{checkoutPublicoId}/produtos/{produtoCodigo}/planos
2. GET /checkout/{checkoutPublicoId}/planos/{planoId}
3. POST /checkout/{checkoutPublicoId}/clientes/verificacao
4. Se existente, POST /clientes/auth/login e usar o token do cliente.
5. POST /checkout/{checkoutPublicoId}/contratacoes com Idempotency-Key.
6. Ler dados.pagamentoNecessario e dados.statusAssinatura.
7. Redirecionar exclusivamente para dados.checkoutUrl, que permanece obrigatoria nos dois fluxos.
8. Nao ativar acesso pelo navegador ou pela emissao de Pix/boleto.

ATIVACAO
- Gerar um segredo de webhook por produto e guarda-lo somente no backend.
- Receber primeiro_pagamento_confirmado quando uma cobranca inicial for paga.
- Receber assinatura_ativada_sem_cobranca quando o valor inicial for zero.
- Tratar os dois eventos como fatos de ativacao capazes de iniciar o provisionamento.
- No evento sem cobranca, validar ativacao.status = ativa e ativacao.motivo = valor_inicial_zero; nao exigir cobranca.
- Antes do JSON, validar timestamp de ate 5 minutos e HMAC-SHA256 de timestamp + "." + corpo bruto.
- Comparar X-Recopay-Signature em tempo constante.
- Confirmar X-Recopay-Event-Id = eventoId e persistir com restricao unica.
- Enfileirar provisionamento e responder 2xx rapidamente.
- Persistir contratacaoReferencia e assinaturaReferencia.
- Tratar /boas-vindas?ref=contratacaoReferencia somente como experiencia.

POS-VENDA
- O RecoPay gera recorrencia, cobra, concilia, notifica e processa NFS-e.
- Consultar no backend:
  GET /integracoes/assinaturas/{assinaturaReferencia}/situacao-financeira
- Usar chave Bearer rpk_ com escopo financeiro:ler.
- A API retorna fatos; carencia e bloqueio pertencem ao sistema consumidor.
- Nao bloquear exclusivamente por timeout ou erro 5xx.

ENTREGA
- O RecoPay entrega somente quando recebe HTTP 2xx.
- A resposta recomendada e 204 No Content; qualquer corpo de resposta e ignorado.
- Rede, 408, 425, 429 e 5xx recebem retentativa progressiva.
- Demais respostas 4xx sao falhas permanentes ate reprocessamento manual.
- Falhas permanentes ficam disponiveis para analise e reprocessamento em Planos.
- Reprocessamentos repetem o mesmo eventoId e corpo; o receptor deve ser idempotente.

GUARDRAILS
- Nao acessar o banco RecoPay.
- Nao inventar preco, plano, componente ou forma de pagamento.
- Nao expor rpk_, senha ou token de cliente em logs.
- Reutilizar Idempotency-Key apenas no retry do mesmo payload.
- Provisionamento deve ser idempotente, auditavel e reversivel.