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

# Portal do cliente

> Uma experiência hospedada para clientes gerenciarem dados de cobrança, métodos de pagamento, assinaturas e faturas.

O **Portal do cliente** é uma superfície hospedada da Chargefy onde o seu
cliente final acessa dados de cobrança sem entrar no seu dashboard. Ele pode
consultar informações de cobrança, atualizar dados cadastrais, gerenciar métodos
de pagamento e executar ações permitidas em assinaturas.

Use o portal quando você quer reduzir suporte operacional sem construir uma área
financeira própria: segunda via de faturas, troca de cartão, atualização de
dados de cobrança, cancelamento guiado ou acesso autenticado por e-mail.

<Frame caption="Página pública de login com a identidade visual da organização.">
  <img src="https://mintcdn.com/scaleup-28315a31/rfus1Cw0Vcv8WSdF/assets/customer-portal-login.png?fit=max&auto=format&n=rfus1Cw0Vcv8WSdF&q=85&s=097a36c673ce51949cf2df2ff9ff633d" alt="Página de login do portal do cliente com sidebar de marca da organização e formulário de email" width="1600" height="900" data-path="assets/customer-portal-login.png" />
</Frame>

<Frame caption="Área logada do portal com métodos de pagamento, informações de cobrança e histórico de faturas.">
  <img src="https://mintcdn.com/scaleup-28315a31/rfus1Cw0Vcv8WSdF/assets/customer-portal-overview.png?fit=max&auto=format&n=rfus1Cw0Vcv8WSdF&q=85&s=e92d64aa4b2efa82c65f3d8edfa59d0e" alt="Área logada do portal do cliente mostrando métodos de pagamento, dados de cobrança e histórico de faturas" width="1600" height="900" data-path="assets/customer-portal-overview.png" />
</Frame>

## Quando usar

O portal resolve tarefas recorrentes de pós-venda e billing:

| Caso de uso                                                | Caminho recomendado                                  |
| ---------------------------------------------------------- | ---------------------------------------------------- |
| Cliente quer acessar cobrança por conta própria            | Link público da organização                          |
| Seu app já sabe quem é o cliente logado                    | Criar uma `customer_portal.session` pela API         |
| Suporte quer enviar um link pontual para um cliente        | Criar uma `customer_portal.session` e enviar a `url` |
| Cliente precisa trocar cartão de uma assinatura específica | Session com flow `payment_method_update`             |
| Cliente quer cancelar uma assinatura                       | Session com flow `subscription_cancel`               |
| Cliente precisa corrigir dados de cobrança                 | Home do portal ou flow `customer_update`             |

<Info>
  O portal não substitui webhooks nem a sua fonte interna de autorização. Ele é a
  experiência hospedada para o cliente executar ações; o seu backend continua
  acompanhando mudanças pelos objetos canônicos e pelos webhooks correspondentes.
</Info>

## Dois caminhos de acesso

Existem dois jeitos de abrir o portal. Eles atendem momentos diferentes do
produto.

### Link público da organização

Cada organização pode ter uma página pública exclusiva:

```txt theme={}
https://billing.chargefy.io/portal/login/{public_token}
```

Esse link é permanente e pertence à organização. Ele é criado quando o portal é
ativado pela primeira vez no dashboard e pode ser ligado ou desligado nas
configurações da organização.

O link público **não autentica o cliente sozinho**. Ele só abre a tela de login.
O cliente informa o e-mail cadastrado, recebe um link por e-mail e entra no
portal.

<Steps>
  <Step title="A organização ativa o portal">
    A Chargefy gera uma URL pública única para aquela organização. O mesmo link
    continua sendo usado enquanto o portal estiver ativo.
  </Step>

  <Step title="O cliente informa o e-mail">
    A página pública usa o branding da organização e pede o e-mail do cliente.
  </Step>

  <Step title="A Chargefy envia um link de acesso">
    Se o e-mail existir para um customer ativo da organização, o cliente recebe
    um link com código de autorização.
  </Step>

  <Step title="O cliente abre a sessão curta">
    O código do e-mail é de uso único e expira em 1 hora. Depois de aberto com
    sucesso, o navegador mantém uma sessão curta do portal por até 1 hora.
  </Step>
</Steps>

Use esse caminho quando o cliente precisa de um ponto de entrada simples e
self-service, por exemplo um link em e-mails de cobrança, central de ajuda ou
área "Financeiro" do seu produto.

### Customer portal sessions

Uma `customer_portal.session` é uma URL temporária criada pelo seu backend para
um customer específico. Ela é ideal quando o seu sistema já autenticou o usuário
e sabe qual `customer` deve abrir o portal.

```bash theme={}
curl -X POST "https://api.chargefy.io/v1/customer-portal-sessions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_123",
    "locale": "pt-BR",
    "return_url": "https://app.example.com/account"
  }'
```

A resposta retorna uma `url` hospedada. Redirecione o cliente para essa URL ou
envie por e-mail quando fizer sentido. Ela contém um `authorization_code` de uso
único, válido por 1 hora. Após o primeiro acesso, a hosted page usa uma sessão
curta no navegador por até 1 hora.

Veja o contrato completo em [Customer Portal Sessions](/api-reference/customer-portal-sessions/create).

## Como funciona

```mermaid theme={}
flowchart LR
  A[Seu app ou link público] --> B[Portal hospedado]
  B --> C[customer]
  B --> D[Métodos de pagamento]
  B --> E[Assinaturas]
  B --> F[Faturas]
  B --> G[Webhooks dos objetos alterados]
```

O portal lê e altera recursos que já existem na API: `customer`,
`payment_method`, `subscription` e `invoice`. Ele não cria um novo objeto de
"conta do cliente" separado.

| Recurso          | Como aparece no portal                                |
| ---------------- | ----------------------------------------------------- |
| `customer`       | Dados cadastrais e dados de cobrança.                 |
| `payment_method` | Métodos de pagamento salvos e troca de cartão.        |
| `subscription`   | Plano ativo, próxima cobrança e ações permitidas.     |
| `invoice`        | Histórico de faturas quando disponível para a sessão. |

## Flows

`flow_data` permite abrir a sessão direto em uma tarefa específica, em vez de
mostrar a home do portal. Isso é útil para links contextuais: "trocar cartão",
"corrigir dados" ou "cancelar assinatura".

| Flow                    | Para que serve                                  | Campos                        |
| ----------------------- | ----------------------------------------------- | ----------------------------- |
| `customer_update`       | Abrir direto na edição dos dados do cliente.    | Não exige opções extras.      |
| `payment_method_update` | Abrir direto na troca de método de pagamento.   | `subscription` é opcional.    |
| `subscription_cancel`   | Abrir direto no cancelamento de uma assinatura. | `subscription` é obrigatório. |

Todos os flows podem receber `after_completion` para redirecionar o cliente
depois da conclusão. No V1, o tipo suportado é `redirect`.

```bash theme={}
curl -X POST "https://api.chargefy.io/v1/customer-portal-sessions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_123",
    "flow_data": {
      "after_completion": {
        "redirect": {
          "return_url": "https://app.example.com/account/subscription"
        },
        "type": "redirect"
      },
      "subscription_cancel": {
        "subscription": "sub_123"
      },
      "type": "subscription_cancel"
    },
    "return_url": "https://app.example.com/account"
  }'
```

<Note>
  Um flow define a tela inicial e as opções daquela sessão. Ele não muda a regra
  de negócio sozinho: a Chargefy valida se o customer, a assinatura e o modo
  (`test`/`live`) pertencem ao escopo da API key antes de criar a sessão.
</Note>

## Segurança e expiração

| Item                        | Duração    | Observação                                                        |
| --------------------------- | ---------- | ----------------------------------------------------------------- |
| Link público da organização | Permanente | Pode ser desligado no dashboard. Não autentica o cliente sozinho. |
| Código enviado por e-mail   | 1 hora     | Uso único. Criado pelo login público ou por uma session.          |
| Sessão no navegador         | 1 hora     | Criada após o primeiro acesso bem-sucedido.                       |

Se o cliente tentar usar um link expirado, crie uma nova
`customer_portal.session` ou peça para ele solicitar outro acesso pelo link
público da organização.

## Branding

O portal usa a identidade visual da organização: logo, nome, cor de marca, cor
de destaque, tema e formato de borda. A mesma configuração visual vale para a
tela pública de login e para a área logada do portal.

Isso permite que o cliente final reconheça a organização antes de interagir com
dados sensíveis de cobrança.

## Próximos passos

* Ative o link público em **Configurações da organização → Portal do cliente**.
* Para links gerados pelo seu backend, use [Criar customer portal session](/api-reference/customer-portal-sessions/create).
* Para entender o objeto retornado, veja [Objeto customer\_portal.session](/api-reference/customer-portal-sessions/object).