Contratação de Assinatura — Fluxo Completo - Clubfix Seguradora

Visão geral

Uma Assinatura é um produto de proteção com cobrança mensal recorrente. O parceiro contrata o plano, cobra o cliente mensalmente no seu próprio sistema e notifica a ClubFix a cada pagamento confirmado.

A Assinatura só é ativada quando a primeira parcela é notificada como paga. Enquanto isso não acontece, o contrato fica em status pending e a proteção não está vigente.

Diagrama do fluxo

[1] Autenticar
      ↓
[2] Localizar ou cadastrar o cliente
      ↓
[3] Listar planos disponíveis
      ↓
[4] Cotar (com ou sem LMI personalizado)
      ↓
[5] Contratar → status: pending
      ↓
[6] Consultar parcelas
      ↓
[7] Cobrar parcela 1 (no seu sistema)
      ↓
[8] Notificar pagamento parcela 1 → status: pago ✓
      ↓
[9] Repetir 7–8 para parcelas 2..N (mensalmente)

Passo 1 — Autenticar

→ Referência do endpoint: POST /auth/login

curl -X POST "https://homolog.clubfix.com.br/webservice/auth/login" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"email": "parceiro@email.com", "password": "suasenha"}'

{
  "token": "eyJ0eXAiOiJKV1Q...",
  "token_type": "Bearer"
}

Use o token retornado como Authorization: Bearer {token} em todas as chamadas seguintes.

Passo 2 — Localizar ou cadastrar o cliente

→ Referência do endpoint: POST /customers Se o cliente ainda não está cadastrado na ClubFix, cadastre-o:

curl -X POST "https://homolog.clubfix.com.br/webservice/customers" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João da Silva",
    "document": "123.456.789-00",
    "email": "joao@email.com",
    "phone": "(47) 99999-9999"
  }'

Se o cliente já existe, use o CPF/CNPJ diretamente nos campos de contratação — não é necessário buscar o cliente antes.

Passo 3 — Listar planos disponíveis

→ Referência do endpoint: GET /plans

curl -X GET "https://homolog.clubfix.com.br/webservice/plans" \
  -H "Authorization: Bearer {token}"

[
  { "id": 7, "name": "Plano Básico", "installments": 12 },
  { "id": 8, "name": "Plano Premium", "installments": 12 }
]

Guarde o id do plano desejado para os próximos passos.

Passo 4 — Cotar

Cote para obter o prêmio mensal e o LMI que será aplicado: → Cotar todos os planos: GET /quotation

curl -X GET "https://homolog.clubfix.com.br/webservice/quotation?model_id=42" \
  -H "Authorization: Bearer {token}"

Com LMI personalizado

Se sua parceria prevê faixas de LMI negociadas, informe o valor desejado no campo maxima:

curl -X GET "https://homolog.clubfix.com.br/webservice/quotation?model_id=42&maxima=1500.00" \
  -H "Authorization: Bearer {token}"

{
  "plans": [
    {
      "id": 7,
      "name": "Plano Básico",
      "monthly_premium": 39.90,
      "lmi": 1500.00,
      "installments": 12
    }
  ]
}

Se o valor informado em maxima não estiver na faixa de LMIs autorizada para o seu parceiro, a API usa o valor padrão do modelo — sem retornar erro. Sua integração nunca é interrompida por esse campo.

Também é possível cotar um plano específico: → Cotar um único plano: GET /plans/{planId}/quotation

curl -X GET "https://homolog.clubfix.com.br/webservice/plans/7/quotation?model_id=42" \
  -H "Authorization: Bearer {token}"

Passo 5 — Contratar

→ Referência do endpoint: POST /subscriptions

curl -X POST "https://homolog.clubfix.com.br/webservice/subscriptions" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": 42,
    "customer_document": "123.456.789-00",
    "plan_id": 7
  }'

Para contratar com LMI personalizado:

curl -X POST "https://homolog.clubfix.com.br/webservice/subscriptions" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": 42,
    "customer_document": "123.456.789-00",
    "plan_id": 7,
    "maxima": 1500.00
  }'

{
  "id": 55,
  "status": "pending",
  "installments_count": 12,
  "lmi": 1500.00
}

Guarde o id da assinatura retornada.

Passo 6 — Consultar as parcelas

→ Referência do endpoint: GET /subscriptions/{id}/installments Liste as parcelas para obter os IDs necessários nas notificações de pagamento:

curl -X GET "https://homolog.clubfix.com.br/webservice/subscriptions/55/installments" \
  -H "Authorization: Bearer {token}"

[
  {
    "id": 101,
    "number": 1,
    "amount": 39.90,
    "due_date": "2026-07-05",
    "status": "pending",
    "status_label": "Pendente"
  },
  {
    "id": 102,
    "number": 2,
    "amount": 39.90,
    "due_date": "2026-08-05",
    "status": "pending",
    "status_label": "Pendente"
  }
]

Use sempre o campo id da parcela (não o number) nas chamadas de notificação. O id é único e imutável.

Passo 7 — Cobrar o cliente (no seu sistema)

Processe o pagamento da parcela no seu próprio gateway ou plataforma. Este passo acontece fora da API ClubFix.

Passo 8 — Notificar o pagamento da parcela

→ Referência do endpoint: POST /subscriptions/{id}/installments/{id}/notify-payment Após confirmar o pagamento no seu sistema, notifique a ClubFix:

curl -X POST "https://homolog.clubfix.com.br/webservice/subscriptions/55/installments/101/notify-payment" \
  -H "Authorization: Bearer {token}"

{
  "id": 101,
  "number": 1,
  "status": "paid",
  "status_label": "Pago"
}

A notificação da parcela 1 ativa a assinatura automaticamente. Após esta chamada, o status da assinatura muda de pending para pago e a proteção entra em vigor. As notificações das parcelas 2 em diante apenas registram o pagamento — não alteram o status da assinatura.

Passo 9 — Parcelas mensais seguintes

Repita os passos 7 e 8 para cada parcela mensal:

# Parcela 2 (mês seguinte)
curl -X POST "https://homolog.clubfix.com.br/webservice/subscriptions/55/installments/102/notify-payment" \
  -H "Authorization: Bearer {token}"

# Parcela 3
curl -X POST "https://homolog.clubfix.com.br/webservice/subscriptions/55/installments/103/notify-payment" \
  -H "Authorization: Bearer {token}"

Tabela de status da assinatura

Status	Significado
`pending`	Contrato criado, aguardando pagamento da parcela 1
`pago`	Ativo — proteção vigente
`canceled`	Cancelado

Tabela de status da parcela

Status	Significado
`pending`	Aguardando pagamento
`paid`	Pagamento confirmado
`refused`	Pagamento recusado
`canceled`	Parcela cancelada

Endpoints utilizados neste fluxo

Método	Endpoint	Referência
`POST`	`/auth/login`	Autenticar
`POST`	`/customers`	Registra um cliente
`GET`	`/plans`	Listar Planos de Assinatura
`GET`	`/quotation`	Cota todos os planos
`GET`	`/plans/{id}/quotation`	Cota um único plano
`POST`	`/subscriptions`	Registra uma assinatura
`GET`	`/subscriptions/{id}/installments`	Lista as parcelas de uma assinatura
`POST`	`/subscriptions/{id}/installments/{id}/notify-payment`	Notifica o pagamento de uma parcela

Modalidades de pagamento

A ClubFix suporta duas modalidades para assinaturas:

Gateway ClubFix

O pagamento é processado pela ClubFix. Use o endpoint POST /subscriptions/{id}/payment com os dados do cartão do cliente.

Gateway Externo

O parceiro cobra o cliente e notifica a ClubFix. Use o endpoint POST /subscriptions/{id}/installments/{id}/notify-payment para cada parcela confirmada.

A modalidade Gateway Externo é configurada previamente pelo time ClubFix no cadastro do parceiro. Uma vez habilitada, apenas o endpoint de notificação fica disponível.

Visão Geral

Guias de Integração

Autenticação

Clientes

Dispositivos

Assinaturas

Planos Anuais

Lojistas

Contratação de Assinatura — Fluxo Completo

Visão geral

Diagrama do fluxo

Passo 1 — Autenticar

Passo 2 — Localizar ou cadastrar o cliente

Passo 3 — Listar planos disponíveis

Passo 4 — Cotar

Com LMI personalizado

Passo 5 — Contratar

Passo 6 — Consultar as parcelas

Passo 7 — Cobrar o cliente (no seu sistema)

Passo 8 — Notificar o pagamento da parcela

Passo 9 — Parcelas mensais seguintes

Tabela de status da assinatura

Tabela de status da parcela

Endpoints utilizados neste fluxo

Modalidades de pagamento

Gateway ClubFix

Gateway Externo

​Visão geral

​Diagrama do fluxo

​Passo 1 — Autenticar

​Passo 2 — Localizar ou cadastrar o cliente

​Passo 3 — Listar planos disponíveis

​Passo 4 — Cotar

​Com LMI personalizado

​Passo 5 — Contratar

​Passo 6 — Consultar as parcelas

​Passo 7 — Cobrar o cliente (no seu sistema)

​Passo 8 — Notificar o pagamento da parcela

​Passo 9 — Parcelas mensais seguintes

​Tabela de status da assinatura

​Tabela de status da parcela

​Endpoints utilizados neste fluxo

​Modalidades de pagamento

Gateway ClubFix

Gateway Externo

Visão geral

Diagrama do fluxo

Passo 1 — Autenticar

Passo 2 — Localizar ou cadastrar o cliente

Passo 3 — Listar planos disponíveis

Passo 4 — Cotar

Com LMI personalizado

Passo 5 — Contratar

Passo 6 — Consultar as parcelas

Passo 7 — Cobrar o cliente (no seu sistema)

Passo 8 — Notificar o pagamento da parcela

Passo 9 — Parcelas mensais seguintes

Tabela de status da assinatura

Tabela de status da parcela

Endpoints utilizados neste fluxo

Modalidades de pagamento