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

# Obtenha um plano de assinatura

A Localpayment fornece um endpoint para recuperar informações detalhadas sobre planos de assinatura existentes. Este guia explica como obter detalhes de planos de assinatura por meio da API da Localpayment, permitindo que você verifique as configurações do plano, consulte o status e utilize as informações do plano em seu aplicativo.

## 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: Obtenha detalhes do plano de assinatura

Para recuperar informações do plano de assinatura, envie uma solicitação `GET` para o endpoint [Obtenha um plano de assinatura](https://docs.localpayment.com/pt-br/docs/get-subscription-plan.md).

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

A solicitação requer vários parâmetros-chave:

| Parâmetro | Descrição | Obrigatório |
| - | - | - |
| `internalId` | Identificador de plano exclusivo da Localpayment a partir do caminho da URL | ✅ |

### 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 GET \
  --url 'https://api.stage.localpayment.com/api/subscriptions/plan/{internalId}' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json'
```

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

***

## Etapa 2: Lidar com a resposta

### Resposta bem-sucedida

Uma solicitação bem-sucedida retorna os detalhes completos do plano de assinatura:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "internalId": "b8546575-5d4f-4a56-9e21-522d01cf5992",
    "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",
        "frequency": 1
    },
    "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. | Referência para operações de API. |
| `name` | Nome descritivo do plano de assinatura. | Exibir para os clientes. |
| `description` | Explicação detalhada das características do plano. | Comunicação com o cliente. |
| `amount` | Valor da fatura. | Processamento de pagamentos. |
| `country` | País onde o plano está disponível. | Restrições geográficas. |
| `currency` | Moeda de faturamento. | Cálculos financeiros. |
| `accountNumber` | Número da conta comercial associada. | Reconciliação. |
| `autoRecurring.type` | Tipo de frequência de faturamento. | Gestão do ciclo de faturamento. |
| `autoRecurring.repetitions` | Número de ciclos de faturamento. | Acompanhamento da duração do plano. |
| `autoRecurring.frequency` | Valor da frequência de faturamento. | Configuração de cobrança recorrente. |
| `status.code` | Código de status do plano atual. | Verificação de disponibilidade. |

### Resposta de erro

Quando um plano de assinatura não puder ser encontrado ou acessado, você receberá as seguintes informações de erro:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "status": {
    "code": "400",
    "description": "ERROR",
    "detail": "Plan subscription not found"
  }
}
```

***

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

Após obter um plano de assinatura, você pode verificar sua disponibilidade e status atual:

> [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 recuperação do plano falhou devido a parâmetros inválidos ou plano não encontrado. |

> [!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. **Recuperação bem-sucedida do plano**: Obtenha detalhes de um plano ativo existente.
2. **Plano Inexistente**: Tentativa de recuperar um plano que não existe.
3. **ID do plano inválido**: teste com formatos internalId malformados ou incorretos.
4. **Falhas de autenticação**: Recuperar planos com tokens de acesso inválidos ou expirados.

***

## Próximos passos

> [card] [Crie um plano de assinatura](https://docs.localpayment.com/pt-br/docs/create-a-subscription-plan.md)
>
> Configure novos planos de assinatura para diferentes níveis de serviço ou modelos de preços.

> [card] [Atualizar plano de assinatura](https://docs.localpayment.com/pt-br/docs/update-a-subscription-plan.md)
>
> Modifique os detalhes do plano existente com base nas informações obtidas.

> [card] [Criar assinatura com plano](https://docs.localpayment.com/pt-br/docs/create-a-subscription.md)
>
> Utilize o ID do plano para criar novas assinaturas de clientes.


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