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

# Listar planos

> Lista os planos de assinatura da sua conta, com filtro por status e paginação.

Esta rota devolve os planos de assinatura cadastrados, página por página. É a base para montar a vitrine de planos no seu site, conferir quais planos estão disponíveis para venda e acompanhar quantas assinaturas ativas cada um tem.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Montar a página de preços do seu produto | `status=active`, para mostrar só planos que aceitam novas assinaturas |
| Revisar o catálogo antes de uma mudança de preço | Sem filtro de status, para ver ativos e inativos |
| Acompanhar a base de assinantes por plano | Leia `activeSubscriptionsCount` de cada plano |
| Ver apenas os planos de um merchant específico | Filtre por `merchantId` |
| Detalhes de um plano específico | Use [Consultar plano](https://docs.fastpaybrasil.com/referencia/planos/consultar.md) |

## Antes de chamar

* Tenha uma chave secreta gerada por usuário com a permissão **visualizar assinaturas**. Nos perfis padrão, são **Owner**, **Manager**, **Operador** e **Visualizador**. Os perfis Desenvolvedor e Financeiro recebem `403` (veja [Permissões por perfil](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md#permissões-por-perfil)).
* Saiba como funciona a paginação da API: o parâmetro de tamanho da página é `size` ([Paginação, ordenação e idempotência](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md)).

> [!WARNING]
>
> Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste. Veja como homologar em [Assinaturas: visão geral](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md).

## Parâmetros de consulta

**merchantId** `string`

Filtra pelos planos de um merchant específico. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`.

**status** `string`

Filtra pelo status do plano: `active` (disponível para novas assinaturas) ou `inactive` (indisponível para novas assinaturas).

**page** `integer` (default: 1)

Número da página. A contagem começa em `1`.

**size** `integer` (default: 10)

Quantidade de planos por página.

## Respostas

**data** `object[]`

Planos da página atual.

**propriedades**

**id** `string`

Identificador único do plano. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`.

**merchantId** `string`

ID do merchant dono do plano.

**name** `string`

Nome do plano. Ex.: `Plano Premium Mensal`.

**price** `number`

Preço do plano, em reais: `99.9` significa R\$ 99,90.

**currency** `string`

Código da moeda. Ex.: `BRL`.

**recurrenceType** `string`

Periodicidade da cobrança: `weekly` (semanal), `biweekly` (quinzenal), `monthly` (mensal) ou `custom` (intervalo personalizado).

**recurrenceInterval** `integer | null`

Intervalo da recorrência personalizada, em dias corridos (ex.: `90` = a cada 90 dias). Vem `null` quando o plano não é `custom`.

**endDate** `string | null`

Data de término do plano (formato `date-time`). Vem `null` quando o plano não tem data de término.

**buyerMessage** `string | null`

Mensagem exibida ao comprador. Ex.: `Bem-vindo ao Plano Premium!`.

**paymentMethods** `string[]`

Formas de pagamento aceitas. Ex.: `["credit_card"]`.

**imageUrl** `string | null`

URL da imagem do plano, enviada por [Enviar imagem do plano](https://docs.fastpaybrasil.com/referencia/planos/enviar-imagem.md).

**status** `string`

Status do plano: `active` ou `inactive`.

**activeSubscriptionsCount** `integer`

Quantidade de assinaturas ativas no plano. Ex.: `150`.

**createdAt** `string`

Data de criação (formato `date-time`).

**updatedAt** `string`

Data da última atualização (formato `date-time`).

**meta** `object`

Dados da paginação.

**propriedades**

**total** `integer`

Total de planos encontrados. Ex.: `5`.

**page** `integer`

Página atual. Ex.: `1`.

**limit** `integer`

Itens por página. Ex.: `10`.

**totalPages** `integer`

Total de páginas. Ex.: `1`.

> [!NOTE]
>
> Na requisição o tamanho da página vai em `size`. Na resposta, o mesmo valor volta no campo `meta.limit`.

| HTTP | Significado | Corpo |
| - | - | - |
| `200` | Lista devolvida | `data` e `meta` |
| `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `403` | O usuário que gerou a chave não tem a permissão visualizar assinaturas | `{"message": "Acesso negado", "error": "Forbidden", "statusCode": 403}` |

> [!NOTE]
>
> **Para o negócio:** `activeSubscriptionsCount` mostra quantos assinantes ativos cada plano tem no momento. Antes de desativar ou reprecificar um plano, consulte esse número para saber quantos clientes já estão nele. Mudanças de preço e desativação não alteram as assinaturas existentes, que continuam com as condições da contratação.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `401` | Chave ausente, inválida ou header montado errado | Monte o header com o Base64 de `sua_chave:` (com os dois-pontos no final) |
| `403` com `Acesso negado` | O usuário que gerou a chave não tem a permissão visualizar assinaturas (ex.: Desenvolvedor ou Financeiro) | Gere a chave com um usuário Owner ou Manager. Veja [Permissões por perfil](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md#permissões-por-perfil) |
| Lista vem com 10 planos mesmo enviando `limit=50` | O parâmetro de tamanho é `size` | Envie `size=50` |
| Plano recém-desativado não aparece na vitrine | Filtro `status=active` | Comportamento esperado: plano `inactive` não aceita novas assinaturas |

```http REST (JSON) theme={null}
GET /v1/subscription-plans?status=active&page=1&size=10 HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
```

```bash cURL theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/subscription-plans?status=active&page=1&size=10" \
  -u "$FINVIA_API_KEY:"
```

```javascript Node.js theme={null}
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

const params = new URLSearchParams({ status: 'active', page: '1', size: '10' });
const response = await fetch(`https://api-global.fastpaybrasil.com/v1/subscription-plans?${params}`, {
  headers: { Authorization: `Basic ${credentials}` },
});

const { data, meta } = await response.json();
```

```python Python theme={null}
import os

import requests

response = requests.request(
    "GET",
    "https://api-global.fastpaybrasil.com/v1/subscription-plans?status=active&page=1&size=10",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    timeout=30,
)

print(response.status_code)
if response.content:
    print(response.json())
```

```php PHP theme={null}
<?php

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/subscription-plans?status=active&page=1&size=10');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status, PHP_EOL;
print_r(json_decode($body, true));
```

```java Java theme={null}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class Exemplo {
    public static void main(String[] args) throws Exception {
        String credentials = Base64.getEncoder()
            .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/subscription-plans?status=active&page=1&size=10"))
            .header("Authorization", "Basic " + credentials)
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
```

```csharp C# theme={null}
using System.Net.Http.Headers;
using System.Text;

var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY");
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:"));

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/subscription-plans?status=active&page=1&size=10");

var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/subscription-plans?status=active&page=1&size=10", nil)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode)
	fmt.Println(string(body))
}
```

```ruby Ruby theme={null}
require "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/subscription-plans?status=active&page=1&size=10")
request = Net::HTTP::Get.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.code
puts response.body
```

```json 200 theme={null}
{
  "data": [
    {
      "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
      "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
      "name": "Plano Premium Mensal",
      "price": 99.9,
      "currency": "BRL",
      "recurrenceType": "monthly",
      "recurrenceInterval": null,
      "endDate": null,
      "buyerMessage": "Bem-vindo ao Plano Premium!",
      "paymentMethods": ["credit_card"],
      "imageUrl": "https://storage.example.com/plans/image.png",
      "status": "active",
      "activeSubscriptionsCount": 150,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "total": 5,
    "page": 1,
    "limit": 10,
    "totalPages": 1
  }
}
```

```json 401 theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized"
}
```

## Veja também

> [card] [Visão geral de assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md)
>
> Como planos, clientes, cartões e assinaturas se encaixam.

> [card] [Planos](https://docs.fastpaybrasil.com/guias/assinaturas/planos.md)
>
> Recorrência, trial e status do plano.

> [card] [Ciclo de vida](https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md)
>
> Status, renovação, retentativas e cancelamento.

> [card] [Webhooks de assinatura](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md)
>
> Eventos enviados a cada etapa da assinatura.

> [card] [Registrar cartão](https://docs.fastpaybrasil.com/referencia/cartoes/registrar.md)
>
> Guarde o cartão no cofre antes de criar a assinatura.

> [card] [Criar plano](https://docs.fastpaybrasil.com/referencia/planos/criar.md)
>
> Cadastre um novo plano de assinatura.


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