> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Portal do Cliente

> Ofereça um portal self-service para seus clientes gerenciarem assinaturas, pagamentos e vendas.

## Visão Geral

O Portal do Cliente é uma interface self-service que permite aos seus clientes gerenciar suas assinaturas, métodos de pagamento, histórico de vendas e downloads de benefícios — sem precisar entrar em contato com o suporte.

O portal pode ser acessado de duas formas:

* **Portal hospedado pela Chargefy** — URL pronta para uso, sem necessidade de implementação
* **Portal embarcado** — componentes React para integrar diretamente na sua aplicação

## Funcionalidades Disponíveis

### Visualizar Assinaturas

O cliente pode ver todas as suas assinaturas ativas, suspensas e canceladas, incluindo:

* Status atual da assinatura
* Próxima data de cobrança e valor
* Histórico de cobranças anteriores
* Opção de cancelar ou pausar a assinatura

### Gerenciar Métodos de Pagamento

O cliente pode adicionar, remover e atualizar seus métodos de pagamento:

* **Cartão de Crédito** — adicionar novo cartão, definir cartão padrão, remover cartões
* **PIX** — gerar QR Code para pagamentos avulsos
* **Boleto** — visualizar boletos pendentes e segunda via

> [!NOTE]
>
> A atualização de cartão em assinaturas ativas é refletida automaticamente nas próximas cobranças.

### Download de Benefícios

Para produtos digitais, o cliente pode acessar e baixar seus benefícios:

* Arquivos para download (PDFs, e-books, etc.)
* Chaves de licença
* Links de acesso a conteúdo exclusivo

## Configuração e Customização

### Ativar o Portal

No dashboard da Chargefy, acesse **Configurações > Portal do Cliente** para ativar e configurar o portal.

| Configuração | Descrição |
| - | - |
| **URL do portal** | Domínio customizado ou subdomínio Chargefy |
| **Logo** | Logo da sua marca exibido no portal |
| **Cores** | Cores primária e secundária do tema |
| **Funcionalidades** | Habilitar/desabilitar seções do portal |
| **Política de cancelamento** | Permitir cancelamento imediato ou apenas no final do período |

```typescript theme={null}
import { Chargefy } from "@chargefy/sdk";

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN,
});

// Configurar o portal do cliente
await chargefy.customerPortal.updateSettings({
  organization_id: "org_xxx",
  enabled: true,
  allow_cancellation: true,
  cancel_at_period_end: true,
  allow_payment_method_update: true,
  show_sale_history: true,
  branding: {
    logo_url: "https://suaempresa.com.br/logo.png",
    primary_color: "#6366f1",
    secondary_color: "#818cf8",
  },
});
```

## Customer Session Token

Para que um cliente acesse o portal, ele precisa de um **Customer Session Token** (`chargefy_cst_xxx`). O token pode ser obtido de duas formas:

### Magic Link (OTP)

O cliente informa seu email e recebe um código de 6 dígitos por email:

**1. Solicitar código OTP**

O cliente informa o email cadastrado. A Chargefy envia um código OTP de 6 dígitos.

**2. Validar código**

O cliente informa o código recebido e a Chargefy retorna um `customer_session_token`.

**3. Acessar o portal**

Com o token, o cliente pode acessar todas as funcionalidades do portal.

```typescript theme={null}
// 1. Solicitar código OTP
await chargefy.customerSessions.requestOTP({
  email: "joao@exemplo.com.br",
  organization_id: "org_xxx",
});

// 2. Validar código e obter token
const session = await chargefy.customerSessions.authenticate({
  email: "joao@exemplo.com.br",
  otp_code: "847293",
  organization_id: "org_xxx",
});

console.log(session.token); // "chargefy_cst_xxx"
// Token válido por 15 dias
```

### Via API (Server-side)

Para integrar o portal diretamente na sua aplicação, você pode criar uma sessão no backend sem exigir OTP do cliente:

```typescript theme={null}
// No seu servidor — gera um token para o cliente autenticado
const session = await chargefy.customerSessions.create({
  customer_id: "cust_xxx",
});

console.log(session.token); // "chargefy_cst_xxx"
console.log(session.expires_at); // "2026-03-27T00:00:00Z"
```

> [!NOTE]
>
> Sessões criadas via API server-side são ideais quando o cliente já está autenticado no seu sistema. Nunca exponha seu `CHARGEFY_ACCESS_TOKEN` no frontend.

## API do Portal do Cliente

### Listar assinaturas do cliente

```bash cURL theme={null}
curl -X GET "https://api.chargefy.io/api/v1/customer-portal/subscriptions" \
  -H "Authorization: Bearer chargefy_cst_xxx"
```

```typescript SDK theme={null}
const chargefy = new Chargefy({
  accessToken: "chargefy_cst_xxx", // Customer Session Token
});

const subscriptions = await chargefy.customerPortal.listSubscriptions();

subscriptions.items.forEach((sub) => {
  console.log(sub.product.name);     // "Plano Pro"
  console.log(sub.status);           // "active"
  console.log(sub.current_period_end); // "2026-04-12T00:00:00Z"
  console.log(sub.amount);           // 4990 (R$ 49,90)
});
```

### Listar métodos de pagamento

```typescript theme={null}
const paymentMethods = await chargefy.customerPortal.listPaymentMethods();

paymentMethods.items.forEach((pm) => {
  console.log(pm.type);       // "credit_card"
  console.log(pm.brand);      // "visa"
  console.log(pm.last4);      // "4242"
  console.log(pm.exp_month);  // 12
  console.log(pm.exp_year);   // 2028
  console.log(pm.is_default); // true
});
```

### Cancelar assinatura

```typescript theme={null}
await chargefy.customerPortal.cancelSubscription("sub_xxx", {
  cancel_at_period_end: true,
});
// O cliente mantém acesso até o final do período pago
```

## Embarcando o Portal na Sua Aplicação

### Instalação

```bash theme={null}
npm install @chargefy/sdk
```

### Componente React

Use o componente `CustomerPortal` para embarcar o portal completo na sua aplicação React:

```tsx theme={null}
import { CustomerPortal } from "@chargefy/sdk/react";

function PortalPage() {
  // Token obtido do seu backend
  const customerSessionToken = "chargefy_cst_xxx";

  return (
    <CustomerPortal
      token={customerSessionToken}
      theme={{
        primaryColor: "#6366f1",
        borderRadius: "8px",
      }}
      onSubscriptionCancel={(subscriptionId) => {
        console.log("Assinatura cancelada:", subscriptionId);
      }}
      onError={(error) => {
        console.error("Erro no portal:", error);
      }}
    />
  );
}
```

### Componentes Individuais

Se você precisa de mais controle, utilize os componentes individuais:

```tsx theme={null}
import {
  CustomerSubscriptions,
  CustomerPaymentMethods,
} from "@chargefy/sdk/react";

function CustomPortal({ token }: { token: string }) {
  return (
    <div className="space-y-8">
      <section>
        <h2>Minhas Assinaturas</h2>
        <CustomerSubscriptions token={token} />
      </section>

      <section>
        <h2>Métodos de Pagamento</h2>
        <CustomerPaymentMethods
          token={token}
          allowAdd={true}
          allowRemove={true}
        />
      </section>
    </div>
  );
}
```

### Exemplo Completo com Next.js

Exemplo de integração do portal em uma aplicação Next.js com autenticação:

```tsx theme={null}
// app/portal/page.tsx
"use client";

import { useEffect, useState } from "react";
import { CustomerPortal } from "@chargefy/sdk/react";

export default function PortalPage() {
  const [token, setToken] = useState<string | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function createSession() {
      // Seu backend cria a sessão do cliente
      const response = await fetch("/api/customer-session", {
        method: "POST",
      });
      const data = await response.json();
      setToken(data.token);
      setLoading(false);
    }
    createSession();
  }, []);

  if (loading) return <div>Carregando...</div>;
  if (!token) return <div>Erro ao criar sessão</div>;

  return (
    <div className="max-w-4xl mx-auto py-8">
      <h1 className="text-2xl font-bold mb-6">Minha Conta</h1>
      <CustomerPortal token={token} />
    </div>
  );
}
```

```typescript theme={null}
// app/api/customer-session/route.ts
import { Chargefy } from "@chargefy/sdk";
import { NextResponse } from "next/server";

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN!,
});

export async function POST(request: Request) {
  // Obtenha o customer_id do usuário autenticado no seu sistema
  const customerId = await getAuthenticatedCustomerId(request);

  const session = await chargefy.customerSessions.create({
    customer_id: customerId,
  });

  return NextResponse.json({
    token: session.token,
    expires_at: session.expires_at,
  });
}
```

## Escopos de API

| Escopo | Permissão |
| - | - |
| `customer_portal:read` | Visualizar dados do portal (assinaturas, vendas, benefícios) |
| `customer_portal:write` | Gerenciar assinaturas e métodos de pagamento |
| `customer_sessions:write` | Criar sessões de cliente (server-side) |

## Webhooks

Eventos disparados por ações no portal do cliente:

| Evento | Descrição |
| - | - |
| `customer_portal.session_created` | Nova sessão de portal criada |
| `customer_portal.subscription_canceled` | Cliente cancelou uma assinatura pelo portal |
| `customer_portal.payment_method_added` | Cliente adicionou novo método de pagamento |
| `customer_portal.payment_method_removed` | Cliente removeu um método de pagamento |

***

> [card] [Gestão de Clientes](https://scaleup-c34c4386.mintlify.site/features/customer-management.md)
>
> Crie e gerencie clientes via API

> [card] [Assinaturas](https://scaleup-c34c4386.mintlify.site/features/subscriptions.md)
>
> Configure assinaturas recorrentes

> [card] [Métodos de Pagamento](https://scaleup-c34c4386.mintlify.site/features/payment-methods.md)
>
> PIX, Cartão e Boleto

> [card] [Autenticação](https://scaleup-c34c4386.mintlify.site/integrate/authentication.md)
>
> Configure tokens e escopos de acesso


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.