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

# Criar um plano de assinatura

O Localpayment permite criar planos de assinatura fixos para cenários de cobrança recorrente padronizados. Este guia detalha como configurar planos de assinatura por meio da API do Localpayment, que podem então ser associados às assinaturas dos clientes para uma cobrança consistente e automatizada.

## Antes de começar

Certifique-se de ter:

> [card] [Credenciais da API](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md)
>
> Credenciais de API e token de acesso válidos para autenticação.

> [card] [Configuração da conta](https://docs.localpayment.com/pt-br/docs/make-your-first-test-payment.md)
>
> Configuração adequada da conta para o país de destino e verificação da empresa.

> [card] [Lista branca de IPs](https://docs.localpayment.com/pt-br/docs/dashboard-whitelist-your-ips.md)
>
> Adicione os endereços IP do seu servidor à lista de permissões para acesso à API.

> [card] [Endpoint do webhook](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Configure um URL de webhook para receber notificações de pagamento.

***

## Passo 1: Crie um plano de assinatura

Para criar um novo plano de assinatura, envie uma solicitação `POST` para o endpoint [Criar plano de assinatura](https://docs.localpayment.com/pt-br/reference/create-subscription-plan).

### Parâmetros-chave da solicitação

A solicitação requer vários objetos-chave:

| Parâmetro | Descrição | Obrigatório |
| - | - | - |
| `name` | Nome descritivo para o plano de assinatura | ✅ |
| `description` | Explicação detalhada das características e benefícios do plano. | ❌ |
| `country` | Código do país onde o plano estará disponível. | ✅ |
| `amount` | Valor de faturamento fixo | ✅ |
| `currency` | Código da moeda para faturamento | ✅ |
| `accountNumber` | Seu número de conta comercial | ✅ |
| `autoRecurring.repetitions` | Número de ciclos de faturamento (use `0` para recorrência sob demanda) | ✅ |
| `autoRecurring.type` | Unidade da frequência de faturamento (use `custom` para recorrência sob demanda) | |

### Frequências de faturamento suportadas

> [card] Diário
>
> Cobrar dos clientes diariamente. Ideal para serviços com uso diário ou assinaturas de curto prazo.
>
> Envie a propriedade `autoRecurring.type` com o valor: `day`

> [card] Mensal
>
> Cobrança mensal recorrente para a maioria dos produtos SaaS, serviços de associação e
> caixas de assinatura.
>
> Envie a propriedade `autoRecurring.type` com o valor: `month`

> [card] Personalizado (sob demanda)
>
> Cobrança sob demanda para cenários de uso variável. Ideal para serviços de pagamento
> conforme o uso ou baseados em consumo.
>
> Envie a propriedade `autoRecurring.type` com o valor: `custom`

### Exemplo de solicitação

Abaixo está um exemplo usando `curl`:

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
  --url https://api.stage.localpayment.com/api/subscriptions/plan \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Plan Básico Mensual",
    "description": "Acceso básico a contenido exclusivo",
    "country": "MEX",
    "amount": 50,
    "currency": "MXN",
    "accountNumber": "{{accountNumber}}",
    "autoRecurring": {
      "repetitions": 1,
      "type": "hour"
    }
  }'
```

Veja todos os [parâmetros disponíveis](https://docs.localpayment.com/pt-br/reference/create-subscription-plan) na solicitação.

***

## Etapa 2: Lidar com a resposta

### Resposta bem-sucedida

Um plano de assinatura criado com sucesso retorna todos os detalhes do plano:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "internalId": "70af52e2-ea99-46a8-a931-65f15f6a3c20",
    "name": "Plan Básico Mensual",
    "description": "Acceso básico a contenido exclusivo",
    "amount": 50,
    "country": "MEX",
    "currency": "MXN",
    "accountNumber": "{{accountNumber}}",
    "autoRecurring": {
        "repetitions": 1,
        "type": "hour"
    },
    "status": {
        "code": "100",
        "description": "ACTIVE",
        "detail": "Subscription plan is active"
    }
}
```

### Campos de resposta principais

| Parâmetro | Descrição | Caso de uso |
| - | - | - |
| `internalId` | Identificador exclusivo do plano da Localpayment. | Use como `planId` ao criar assinaturas |
| `status.code` | Código de status do plano atual. | Monitoramento de status. |
| `autoRecurring.type` | Frequência de faturamento confirmada. | Verificação do ciclo de faturamento. |
| `autoRecurring.repetitions` | Número confirmado de ciclos de faturamento. | Acompanhamento da duração do plano. |

### Resposta de erro

Quando a criação do plano de assinatura falhar, você receberá informações detalhadas sobre o erro:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "status": {
        "code": "400",
        "description": "REJECTED",
        "detail": "autoRecurring.type is required"
    }
}
```

***

## Etapa 3: Rastrear o status da transação

Após criar um plano de assinatura, monitore o status dele por meio destes métodos:

> [card] [Webhooks (Recomendado)](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Receba notificações em tempo real quando o status da transação mudar. Ideal para ambientes de produção.

> [card] [Endpoint da API de Status](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md)
>
> Consultar o status da transação programaticamente. Útil para consultar ou recuperar notificações de webhook perdidas.

> [card] [Visualização do Business Portal](https://docs.localpayment.com/pt-br/docs/dashboard-overview.md)
>
> Interface visual para monitoramento de transações. Ideal para supervisão manual e análise detalhada de transações.

### Códigos de status comuns

| Código | Status | Descrição |
| :- | :- | :- |
| `100` | `ACTIVE` | O plano está ativo e disponível para associações assinantes. |
| `400` | `REJECTED` | A criação do plano falhou devido a erros de validação ou parâmetros inválidos. |

> [!NOTE]
>
> **Referência completa**
>
> Consulte todos os códigos de status em nossa [Documentação de Status da Transação](https://docs.localpayment.com/pt-br/reference/transaction-status-error-codes).

***

## Testando sua integração

### Cenários de teste

Verifique se sua integração lida com esses cenários:

1. **Criação de plano bem-sucedida**: Criação de plano padrão com parâmetros válidos.
2. **Estrutura de preços por níveis**: Criação de múltiplos planos com preços diferentes.
3. **Diversas opções de cobrança**: planos diários, mensais e personalizados sob demanda.
4. **Erros de validação**: Campos obrigatórios ausentes, valores inválidos, países não suportados.
5. **Associação de Assinaturas**: Testando se os planos podem ser vinculados com sucesso às assinaturas.

***

## Próximos passos

Após criar um plano de assinatura, você poderá precisar realizar ações adicionais:

> [card] [Criar assinatura com plano](https://docs.localpayment.com/pt-br/docs/create-a-subscription.md)
>
> Utilize o internalId do plano como parâmetro planId para criar assinaturas de clientes
> com o seu novo plano.

> [card] [Atualizar plano de assinatura](https://docs.localpayment.com/pt-br/docs/update-a-subscription-plan.md)
>
> Modifique os detalhes de um plano existente, mantendo as associações com as assinaturas
> ativas.


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