> ## 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 Plano Anual — Fluxo Completo

> Sequência end-to-end para cotar, contratar e ativar um Plano Anual via API ClubFix

## Visão geral

O **Plano Anual** é uma proteção com vigência de 12 meses e pagamento único. O parceiro contrata o plano e, dependendo da configuração, processa o pagamento via ClubFix ou notifica após cobrança própria.

<Note>
  O Plano Anual é ativado assim que o pagamento é confirmado — seja via gateway ClubFix ou via notificação do parceiro.
</Note>

***

## Diagrama do fluxo

```
[1] Autenticar
      ↓
[2] Localizar ou cadastrar o cliente
      ↓
[3] Localizar o modelo do dispositivo
      ↓
[4] Cotar (com ou sem LMI personalizado)
      ↓
[5] Contratar → status: awaiting_payment
      ↓
[6] Processar pagamento (gateway ClubFix)
    OU cobrar e notificar (gateway externo)
      ↓
[7] Plano Anual ativo ✓
```

***

## 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"
}
```

***

## Passo 2 — Localizar ou cadastrar o cliente

*[→ Referência do endpoint: `POST /customers`](/api-reference/customers/post)*

```bash theme={null}
curl -X POST "https://homolog.clubfix.com.br/webservice/customers" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Oliveira",
    "document": "987.654.321-00",
    "email": "maria@email.com",
    "phone": "(11) 98888-8888"
  }'
```

***

## Passo 3 — Localizar o modelo do dispositivo

*[→ Listar marcas: `GET /brands`](/api-reference/devices/brands/index) · [→ Listar modelos: `GET /models`](/api-reference/devices/models/index)*

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

# Listar modelos de uma marca
curl -X GET "https://homolog.clubfix.com.br/webservice/models?brand_id=1" \
  -H "Authorization: Bearer {token}"
```

Guarde o `id` do modelo.

***

## Passo 4 — Cotar

*[→ Referência do endpoint: `GET /annual-plans/quote`](/api-reference/annual-plans/quotation/index)*

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

### Com LMI personalizado

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

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

```json theme={null}
{
  "model": {
    "id": 42,
    "name": "iPhone 14 Pro"
  },
  "premium": 89.90,
  "lmi": 2000.00
}
```

Também é possível informar se o dispositivo tem mais de 3 meses de uso com o campo `used=true`.

<Tip>
  Se o valor em `maxima` não estiver na faixa autorizada para o seu parceiro, a API aplica o valor padrão do modelo — **sem retornar erro**.
</Tip>

***

## Passo 5 — Contratar

*[→ Referência do endpoint: `POST /annual-plans`](/api-reference/annual-plans/post)*

```bash theme={null}
curl -X POST "https://homolog.clubfix.com.br/webservice/annual-plans" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": 42,
    "customer_document": "987.654.321-00"
  }'
```

Com LMI personalizado:

```bash theme={null}
curl -X POST "https://homolog.clubfix.com.br/webservice/annual-plans" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": 42,
    "customer_document": "987.654.321-00",
    "maxima": 2000.00
  }'
```

```json theme={null}
{
  "id": 101,
  "status": "awaiting_payment",
  "lmi": 2000.00,
  "premium": 89.90
}
```

Guarde o `id` do plano criado.

***

## Passo 6 — Pagamento

<Tabs>
  <Tab title="Gateway ClubFix">
    *[→ Referência do endpoint: `POST /annual-plans/{id}/payment`](/api-reference/annual-plans/payment/index)*

    Se o parceiro utiliza o gateway ClubFix, processe o pagamento com os dados do cartão:

    ```bash theme={null}
    curl -X POST "https://homolog.clubfix.com.br/webservice/annual-plans/101/payment" \
      -H "Authorization: Bearer {token}" \
      -H "Content-Type: application/json" \
      -d '{
        "card_number": "4111111111111111",
        "card_holder": "MARIA OLIVEIRA",
        "card_expiry": "12/28",
        "card_cvv": "123"
      }'
    ```
  </Tab>

  <Tab title="Gateway Externo">
    *[→ Referência do endpoint: `POST /annual-plans/{id}/notify-payment`](/api-reference/annual-plans/notify-payment/index)*

    Se o parceiro cobra o cliente no seu próprio sistema, após confirmar o pagamento notifique a ClubFix:

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

    ```json theme={null}
    {
      "id": 101,
      "status": "paid",
      "policy_number": "CF-2026-101"
    }
    ```

    <Note>
      O endpoint `notify-payment` não requer body. Uma única chamada é suficiente para ativar o plano.
    </Note>
  </Tab>
</Tabs>

***

## Passo 7 — Plano ativo

*[→ Referência do endpoint: `GET /annual-plans/{id}`](/api-reference/annual-plans/show)*

Após a confirmação do pagamento (por qualquer modalidade), o plano muda para o status `paid` e a proteção entra em vigor. Você pode consultar o plano a qualquer momento:

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

***

## Tabela de status do plano anual

| Status             | Significado                           |
| ------------------ | ------------------------------------- |
| `awaiting_payment` | Contrato criado, aguardando pagamento |
| `paid`             | Pago — proteção vigente               |
| `protected`        | Proteção ativa e confirmada           |
| `canceled`         | Cancelado                             |

***

## 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`  | `/brands`                           | [Listar Marcas de Dispositivos](/api-reference/devices/brands/index)                  |
| `GET`  | `/models`                           | [Listar Modelos de Dispositivos](/api-reference/devices/models/index)                 |
| `GET`  | `/annual-plans/quote`               | [Realiza uma Cotação](/api-reference/annual-plans/quotation/index)                    |
| `POST` | `/annual-plans`                     | [Registra um Plano Anual](/api-reference/annual-plans/post)                           |
| `POST` | `/annual-plans/{id}/payment`        | [Processa o pagamento de um Plano Anual](/api-reference/annual-plans/payment/index)   |
| `POST` | `/annual-plans/{id}/notify-payment` | [Notifica pagamento de Plano Anual](/api-reference/annual-plans/notify-payment/index) |
| `GET`  | `/annual-plans/{id}`                | [Obtém um Plano Anual](/api-reference/annual-plans/show)                              |

***

## Cancelamento

<CardGroup cols={2}>
  <Card title="Solicitar Cancelamento" icon="circle-xmark" href="/api-reference/annual-plans/cancellation/request">
    Inicia o processo de cancelamento do plano. Use `PUT /annual-plans/{id}/cancellation`.
  </Card>

  <Card title="Confirmar Cancelamento" icon="check" href="/api-reference/annual-plans/cancellation/confirm">
    Confirma e finaliza o cancelamento solicitado. Use `POST /annual-plans/{id}/cancellation/{protocol}`.
  </Card>
</CardGroup>

```bash theme={null}
# 1. Solicitar cancelamento
curl -X PUT "https://homolog.clubfix.com.br/webservice/annual-plans/101/cancellation" \
  -H "Authorization: Bearer {token}"

# 2. Confirmar cancelamento
curl -X POST "https://homolog.clubfix.com.br/webservice/annual-plans/101/cancellation/{protocol}" \
  -H "Authorization: Bearer {token}"
```