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

# Roadmap de Integrações

> SDKs, conectores e próximas capacidades da API ClubFix para parceiros

## Visão geral

O objetivo da ClubFix é que a integração com nossa API seja a mais simples possível para qualquer stack técnica. Este roadmap descreve as ferramentas que estão sendo planejadas para reduzir a fricção de adoção por parceiros B2B.

***

## SDK Node.js

**Status: Planejado**

Um pacote NPM oficial para integração com a API ClubFix em projetos Node.js e TypeScript.

### O que estará disponível

```typescript theme={null}
import { ClubfixClient } from '@clubfix/sdk';

const client = new ClubfixClient({
  apiKey: process.env.CLUBFIX_API_KEY,
  environment: 'sandbox', // ou 'production'
});

// Cotar assinatura
const quote = await client.subscriptions.quote({
  modelId: 42,
  maxima: 1500.00,
});

// Contratar
const subscription = await client.subscriptions.create({
  modelId: 42,
  customerDocument: '123.456.789-00',
  planId: 7,
  maxima: 1500.00,
});

// Notificar pagamento de parcela
await client.subscriptions.notifyInstallmentPayment(
  subscription.id,
  installmentId,
);
```

### Funcionalidades previstas

* Autenticação automática com renovação de token
* Tipagem completa (TypeScript)
* Retry com backoff exponencial em erros 5xx
* Logging configurável
* Suporte a ESM e CommonJS

***

## SDK PHP

**Status: Planejado**

Um pacote Composer para integração nativa em projetos PHP, com suporte dedicado ao Laravel.

### Instalação via Composer

```bash theme={null}
composer require clubfix/sdk
```

### Uso standalone (PHP puro)

```php theme={null}
use Clubfix\ClubfixClient;

$client = new ClubfixClient([
    'api_key'     => getenv('CLUBFIX_API_KEY'),
    'environment' => 'sandbox',
]);

// Contratar plano anual
$plan = $client->annualPlans()->create([
    'model_id'          => 42,
    'customer_document' => '987.654.321-00',
    'maxima'            => 2000.00,
]);

// Notificar pagamento
$client->annualPlans()->notifyPayment($plan->id);
```

### Integração Laravel via ServiceProvider

O pacote incluirá um `ClubfixServiceProvider` para configuração automática no Laravel:

```bash theme={null}
php artisan vendor:publish --tag=clubfix-config
```

```php theme={null}
// config/clubfix.php
return [
    'api_key'     => env('CLUBFIX_API_KEY'),
    'environment' => env('CLUBFIX_ENV', 'sandbox'),
];
```

```php theme={null}
// Injeção de dependência automática
use Clubfix\Contracts\ClubfixClientInterface;

class SubscriptionController extends Controller
{
    public function __construct(
        private ClubfixClientInterface $clubfix,
    ) {}

    public function store(Request $request): JsonResponse
    {
        $subscription = $this->clubfix
            ->subscriptions()
            ->create($request->validated());

        return response()->json($subscription);
    }
}
```

### Funcionalidades previstas

* Facade `Clubfix::` para uso rápido no Laravel
* Suporte a Eloquent models opcionais (sincronização de assinaturas)
* Eventos Laravel (`SubscriptionCreated`, `InstallmentPaid`, etc.)
* Compatível com PHP 8.1+, Laravel 10 e 11

***

## Conector n8n

**Status: Planejado**

Um **Community Node** oficial para [n8n](https://n8n.io), permitindo que parceiros montem fluxos de automação com a API ClubFix sem escrever código.

### Casos de uso

* **Checkout integrado**: ao receber um pedido no WooCommerce/Shopify, criar automaticamente uma assinatura ClubFix e notificar o cliente
* **Cobrança recorrente**: integrar com Asaas, Pagar.me ou Stripe e notificar a ClubFix quando o pagamento mensal for confirmado
* **Sincronização de CRM**: criar clientes na ClubFix a partir de leads convertidos no HubSpot ou Pipedrive
* **Alertas de vencimento**: monitorar parcelas pendentes e disparar notificações via WhatsApp ou e-mail

### Nodes planejados

| Node                       | Tipo       | Função                             |
| -------------------------- | ---------- | ---------------------------------- |
| ClubFix Auth               | Credential | Autenticação na API                |
| Create Subscription        | Action     | Contratar assinatura               |
| Create Annual Plan         | Action     | Contratar plano anual              |
| Notify Installment Payment | Action     | Notificar pagamento de parcela     |
| Notify Annual Plan Payment | Action     | Notificar pagamento de plano anual |
| Get Subscription           | Action     | Consultar assinatura               |
| List Installments          | Action     | Listar parcelas                    |
| Create Customer            | Action     | Cadastrar cliente                  |

### Exemplo de fluxo n8n

```
[Webhook — pagamento confirmado]
      ↓
[IF — tipo de produto]
  ↓ Assinatura          ↓ Plano Anual
[ClubFix:              [ClubFix:
 Notify Installment]    Notify Annual Plan]
      ↓
[Send WhatsApp — confirmação ao cliente]
```

***

## Próximas capacidades da API

Além das ferramentas de SDK, as seguintes capacidades da API estão no horizonte:

| Capacidade               | Descrição                                                                                        |
| ------------------------ | ------------------------------------------------------------------------------------------------ |
| **Webhooks**             | Receba notificações em tempo real de eventos (pagamento, cancelamento, sinistro) em seu endpoint |
| **Renovação automática** | API para renovar planos anuais que vencerão nos próximos dias                                    |
| **Portal do segurado**   | Link personalizado para que o cliente final consulte sua apólice                                 |
| **Relatórios**           | Endpoints de consolidação para relatórios de carteira                                            |

***

## Interesse ou sugestões?

Se você tem interesse em algum destes itens ou quer sugerir prioridades, entre em contato com o time de parceiros ClubFix:

* **E-mail**: [contato@clubfix.com.br](mailto:contato@clubfix.com.br)
* **WhatsApp**: [47 98839-9494](https://wa.me/5547988399494)