> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clubfix.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Contratação de Assinatura — Fluxo Completo

> Sequência end-to-end para cotar, contratar e ativar uma Assinatura via API ClubFix

## 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.

<Note>
  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.
</Note>

***

## 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`](/api-reference/auth/index)*

```bash theme={null}
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"}'
```

```json theme={null}
{
  "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`](/api-reference/customers/post)*

Se o cliente ainda não está cadastrado na ClubFix, cadastre-o:

```bash theme={null}
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`](/api-reference/subscriptions/plans/index)*

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

```json theme={null}
[
  { "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`](/api-reference/subscriptions/quotation/index)*

```bash theme={null}
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`:

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

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

<Tip>
  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.
</Tip>

Também é possível cotar um plano específico:

*[→ Cotar um único plano: `GET /plans/{planId}/quotation`](/api-reference/subscriptions/quotation/show)*

```bash theme={null}
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`](/api-reference/subscriptions/post)*

```bash theme={null}
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:

```bash theme={null}
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
  }'
```

```json theme={null}
{
  "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`](/api-reference/subscriptions/installments/index)*

Liste as parcelas para obter os IDs necessários nas notificações de pagamento:

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

```json theme={null}
[
  {
    "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"
  }
]
```

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

***

## 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`](/api-reference/subscriptions/installments/notify-payment)*

Após confirmar o pagamento no seu sistema, notifique a ClubFix:

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

```json theme={null}
{
  "id": 101,
  "number": 1,
  "status": "paid",
  "status_label": "Pago"
}
```

<Warning>
  **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.
</Warning>

***

## Passo 9 — Parcelas mensais seguintes

Repita os passos 7 e 8 para cada parcela mensal:

```bash theme={null}
# 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](/api-reference/auth/index)                                                         |
| `POST` | `/customers`                                           | [Registra um cliente](/api-reference/customers/post)                                            |
| `GET`  | `/plans`                                               | [Listar Planos de Assinatura](/api-reference/subscriptions/plans/index)                         |
| `GET`  | `/quotation`                                           | [Cota todos os planos](/api-reference/subscriptions/quotation/index)                            |
| `GET`  | `/plans/{id}/quotation`                                | [Cota um único plano](/api-reference/subscriptions/quotation/show)                              |
| `POST` | `/subscriptions`                                       | [Registra uma assinatura](/api-reference/subscriptions/post)                                    |
| `GET`  | `/subscriptions/{id}/installments`                     | [Lista as parcelas de uma assinatura](/api-reference/subscriptions/installments/index)          |
| `POST` | `/subscriptions/{id}/installments/{id}/notify-payment` | [Notifica o pagamento de uma parcela](/api-reference/subscriptions/installments/notify-payment) |

***

## Modalidades de pagamento

A ClubFix suporta duas modalidades para assinaturas:

<CardGroup cols={2}>
  <Card title="Gateway ClubFix" icon="credit-card" href="/api-reference/subscriptions/payment">
    O pagamento é processado pela ClubFix. Use o endpoint `POST /subscriptions/{id}/payment` com os dados do cartão do cliente.
  </Card>

  <Card title="Gateway Externo" icon="building-columns" href="/api-reference/subscriptions/installments/notify-payment">
    O parceiro cobra o cliente e notifica a ClubFix. Use o endpoint `POST /subscriptions/{id}/installments/{id}/notify-payment` para cada parcela confirmada.
  </Card>
</CardGroup>

<Note>
  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.
</Note>