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

# Gerenciamento de assinaturas

> Escolha um plano, assine via checkout, gerencie complementos e lide com o cancelamento usando a API ou o console.

Você pode gerenciar todo o seu ciclo de vida de cobrança através da API ou do console. Este guia aborda como listar planos, estimar custos, criar uma sessão de checkout, verificar sua assinatura, anexar complementos e cancelar quando necessário.

## Pré-requisitos

* Uma conta Truthlocks com um inquilino ativo.
* Uma chave de API com permissões de faturamento. Consulte [Chaves de API](https://docs.truthlocks.com/pt/api-reference/api-keys/create.md) para criar uma.

## Escolha um plano

Truthlocks oferece cinco níveis de plano. Use o endpoint de planos para buscar o catálogo completo — este é um endpoint público e não requer autenticação.

```bash theme={null}
curl https://api.truthlocks.com/v1/billing/plans
```

```json theme={null}
[
  {
    "key": "plan_developer",
    "name": "Developer",
    "price": 0,
    "currency": "USD",
    "interval": "month",
    "features": ["500 mints/month", "Plan-dependent verifications", "Community support"],
    "highlight": false
  },
  {
    "key": "plan_starter",
    "name": "Starter",
    "price": 29,
    "currency": "USD",
    "interval": "month",
    "features": ["Higher quotas", "3 webhook endpoints", "Priority processing"],
    "highlight": true
  }
]
```

Consulte [visão geral de faturamento](https://docs.truthlocks.com/pt/billing/overview.md#plan-tiers) para uma comparação de todos os planos.

## Estimar seus custos

Antes de assinar, use o endpoint de estimativa para obter uma recomendação de plano com base no seu uso esperado. Este também é um endpoint público.

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/estimate \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "US",
    "expected_verifications_monthly": 10000,
    "team_seats": 5,
    "webhook_endpoints_needed": 5,
    "storage_gb": 10
  }'
```

A resposta inclui um plano recomendado e o total mensal estimado. Para um detalhamento de custos por item, use o endpoint [fatura projetada](https://docs.truthlocks.com/pt/api-reference/billing/projected-invoice.md) em vez disso.

## Verifique suas taxas atuais

As taxas efetivas por uso do seu locatário dependem da sua tabela de preços e região. Obtenha-as com:

```bash theme={null}
curl https://api.truthlocks.com/v1/billing/rates \
  -H "X-API-Key: tl_live_..."
```

A resposta inclui taxas básicas e quaisquer ajustes de preços regionais:

```json theme={null}
{
  "rate_card": { "id": "rc_default", "name": "Standard Rates", "currency": "USD" },
  "items": [
    { "metric": "attestations.mint", "unit_price": 25, "volume_min": 0, "volume_max": 0 },
    { "metric": "verifications", "unit_price": 10, "volume_min": 0, "volume_max": 0 }
  ],
  "is_default": true,
  "regional_rates": {
    "region": "TIER_1",
    "multiplier": 1.0,
    "mint_rate_cents": 25,
    "verify_rate_cents": 10
  }
}
```

> [!NOTE]
>
> Se sua organização tiver um cartão de tarifas personalizado atribuído por um administrador da plataforma, essas tarifas aparecerão aqui em vez das padrão.

## Assinar um plano

Crie uma sessão de checkout para iniciar ou atualizar sua assinatura. O serviço de faturamento seleciona automaticamente o provedor de pagamento correto para sua região.

**1. Criar uma sessão de checkout**

Chame o endpoint de checkout com o plano desejado e URLs de redirecionamento:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/checkout \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "plan_key": "STARTER",
    "success_url": "https://yourapp.com/billing?success=true",
    "cancel_url": "https://yourapp.com/billing?canceled=true"
  }'
```

A resposta contém um `checkout_url` hospedado pelo provedor de pagamento.

**2. Redirecionar para o checkout**

Envie o usuário para o `checkout_url` para concluir o pagamento.

```javascript theme={null}
const res = await fetch("https://api.truthlocks.com/v1/billing/checkout", {
  method: "POST",
  headers: {
    "X-API-Key": "tl_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    plan_key: "STARTER",
    success_url: `${window.location.origin}/billing?success=true`,
    cancel_url: `${window.location.origin}/billing?canceled=true`,
  }),
});
const { checkout_url } = await res.json();
window.location.href = checkout_url;
```

**3. Confirmar a assinatura**

Após o pagamento, verifique se a assinatura está ativa:

```bash theme={null}
curl https://api.truthlocks.com/v1/billing/subscription \
  -H "X-API-Key: tl_live_..."
```

```json theme={null}
{
  "status": "active",
  "plan_key": "plan_starter",
  "current_period_end": "2026-05-01T00:00:00Z",
  "cancel_at_period_end": false
}
```

> [!TIP]
>
> Opcionalmente, você pode passar um parâmetro `provider` (`stripe`, `paystack` ou `flutterwave`) para substituir o roteamento automático baseado em região. Consulte [roteamento do provedor](https://docs.truthlocks.com/pt/billing/provider-routing.md) para detalhes.

## Anexar complementos

Os complementos estendem seu plano com recursos extras. Anexe-os via API:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/addons/attach \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "addon_key": "addon_seat",
    "quantity": 2
  }'
```

Se o complemento tiver um preço, a resposta inclui um `checkout_url` para concluir o pagamento. Complementos gratuitos são ativados imediatamente.

> [!NOTE]
>
> Os preços dos complementos são ajustados automaticamente com base no país de faturamento da sua organização. Locatários em regiões de menor custo pagam uma taxa reduzida — por exemplo, o Pacote de Conformidade custa US$ 149,50/mês na Nigéria (multiplicador de 0,5x) em vez do preço base de US$ 299. Consulte [preços regionais de complementos](https://docs.truthlocks.com/pt/billing/overview.md#regional-add-on-pricing) para a tabela de níveis completa.

Para remover um complemento:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/addons/detach \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"addon_key": "addon_seat"}'
```

Consulte [gerenciar complementos](https://docs.truthlocks.com/pt/api-reference/billing/addons.md) para o catálogo completo de complementos e detalhes de resposta.

## Monitorar uso

Acompanhe o consumo do seu ciclo de faturamento atual para se manter dentro dos limites do seu plano:

```bash theme={null}
curl https://api.truthlocks.com/v1/billing/usage \
  -H "X-API-Key: tl_live_..."
```

Para verificar se uma operação específica está dentro da cota antes de executá-la:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/limits/check \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"metric": "attestations.mint", "amount": 1}'
```

## Abrir o portal de faturamento

Redirecione os usuários para o portal de autoatendimento de seu provedor de pagamento para atualizar métodos de pagamento, visualizar faturas ou gerenciar sua assinatura:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/portal \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "return_url": "https://yourapp.com/settings/billing"
  }'
```

A resposta inclui um `portal_url`. Redirecione o usuário para essa URL. As sessões do portal expiram rapidamente, então gere uma nova URL a cada vez.

## Cancelar uma assinatura

Para cancelar, chame o endpoint de cancelamento. O cancelamento entra em vigor no final do período de faturamento atual — você mantém acesso total até então.

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/cancel \
  -H "X-API-Key: tl_live_..."
```

```json theme={null}
{
  "status": "active",
  "plan_key": "plan_starter",
  "current_period_end": "2026-05-01T00:00:00Z",
  "cancel_at_period_end": true
}
```

Após o término do período, sua conta será rebaixada para o plano Desenvolvedor (gratuito). Para assinar novamente, crie uma nova [sessão de checkout](https://docs.truthlocks.com/pt/api-reference/billing/checkout.md).

> [!WARNING]
>
> Você não pode desfazer um cancelamento via API. Para retomar sua assinatura, você precisa passar pelo processo de checkout novamente.

## Relacionado

> [card] [Visão geral do faturamento](https://docs.truthlocks.com/billing/overview.md)
>
> Planeje níveis, taxas, direitos e complementos.

> [card] [Roteamento do provedor](https://docs.truthlocks.com/billing/provider-routing.md)
>
> Como os pagamentos são roteados por região.

> [card] [Referência da API de faturamento](https://docs.truthlocks.com/api-reference/billing/config.md)
>
> Referência completa do endpoint da API de faturamento.

> [card] [Direitos](https://docs.truthlocks.com/api-reference/billing/entitlements.md)
>
> Verifique seus recursos e cotas ativos.


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