API de Planos

🤖 Explicar com IA

A API de Planos foi projetada para gerenciar planos de assinatura de forma eficiente. Ela suporta a criação de planos, listagem de todos os planos, recuperação por ID, modificação e exclusão, permitindo uma gestão contínua de membros.

A API garante respostas claras e consistentes, incluindo tratamento detalhado de erros, para proporcionar uma experiência tranquila aos desenvolvedores.

Criar um plano¶

Este endpoint permite criar um novo plano recorrente no sistema enviando uma solicitação POST com os detalhes do plano — como nome, descrição, valor, moeda, intervalo (frequência de cobrança), trial_period_days (dias de período de teste) e uma imagem opcional. Se a operação for bem-sucedida, ela confirma a criação do plano e fornece sua chave exclusiva.

Parâmetros de Consulta (Query Parameters):

Campos do Corpo da Solicitação (Request Body Fields):

Solicitação (cURL):

curl -X POST 'https://api.4geeks.io/v1/plans/?test=false' \
     -H 'Authorization: Api-Key sk_test_51O62xYzAbcDef123' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "Premium Plan",
           "description": "Unlimited access to all features",
           "currency": "USD",
           "amount": 9.99,
           "interval": "month",
           "interval_count": 1,
           "trial_period_days": 7,
           "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
         }'

Solicitação (Python):

import requests

api_key = "sk_test_51O62xYzAbcDef123"
response = requests.post(
    'https://api.4geeks.io/v1/plans/?test=false',
    headers={
        'Authorization': f'Api-Key {api_key}',
        'Content-Type': 'application/json'
    },
    json={
        "name": "Premium Plan",
        "description": "Unlimited access to all features",
        "currency": "USD",
        "amount": 9.99,
        "interval": "month",
        "interval_count": 1,
        "trial_period_days": 7
    }
)
print(response.json())

Solicitação (Postman):

1. Método: POST
2. URL: https://api.4geeks.io/v1/plans/?test=false
3. Autorização: Api-Key com o valor sk_test_51O62xYzAbcDef123
4. Corpo (raw JSON):

{
    "name": "Premium Plan",
    "description": "Unlimited access to all features",
    "currency": "USD",
    "amount": 9.99,
    "interval": "month",
    "interval_count": 1,
    "trial_period_days": 7
}

Resposta (201 Created):

{
    "code": 201,
    "title": "Complete registration",
    "content": "The registration was successfully completed.",
    "type": "success",
    "data": {
        "id": "d36a4a5c-9fa9-4d55-b47f-4f1d50f2a180"
    }
}

Obter todos os planos¶

Este endpoint recupera uma lista paginada de todos os planos com suporte a filtragem avançada.

Parâmetros de Consulta (Query Parameters):

Solicitação (Listar Todos os Planos):

curl -X GET 'https://api.4geeks.io/v1/plans/?page=1&page_size=10&test=false' \
     -H 'Authorization: Api-Key sk_test_51O62xYzAbcDef123'

Solicitação (Com Filtros):

curl -X GET 'https://api.4geeks.io/v1/plans/?page=1&name=premium&price_min=5&price_max=50&status=active' \
     -H 'Authorization: Api-Key sk_test_51O62xYzAbcDef123'

Resposta (200 OK):

{
  "count": 2,
  "current_page": 1,
  "total_pages": 1,
  "results": [
    {
      "key": "f1a2b3c4-5678-90ab-cdef-1234567890ab",
      "information": {
        "name": "Premium Plan",
        "created": "2025-08-17T20:00:00Z",
        "interval": "month",
        "interval_count": 1,
        "currency": "USD",
        "amount": "9.99",
        "trial_period_days": 7,
        "credit_card_description": "PREMIUM",
        "description": "Unlimited access to all features with premium support.",
        "email": "developer@example.com",
        "company_name": "Acme Corp",
        "page": "https://acme.com",
        "active": true,
        "count": 150,
        "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
        "image_dev": "https://acme.com/logo.png"
      },
      "test": false
    },
    {
      "key": "a1b2c3d4-5678-90ef-ghij-1234567890cd",
      "information": {
        "name": "Basic Plan",
        "created": "2025-08-17T20:05:00Z",
        "interval": "month",
        "interval_count": 1,
        "currency": "USD",
        "amount": "4.99",
        "trial_period_days": 0,
        "credit_card_description": "BASIC",
        "description": "Limited access to basic features with standard support.",
        "email": "developer@example.com",
        "company_name": "Acme Corp",
        "page": "https://acme.com",
        "active": true,
        "count": 45,
        "image": null,
        "image_dev": "https://acme.com/logo.png"
      },
      "test": false
    }
  ]
}

Obter um plano específico¶

Este endpoint recupera os detalhes completos de um plano específico através de sua chave exclusiva.

Parâmetros de Caminho (Path Parameters):

Parâmetros de Consulta (Query Parameters):

Solicitação:

curl -X GET 'https://api.4geeks.io/v1/plans/f9b77185-a62e-4da9-a056-3c7b812ca334/' \
     -H 'Authorization: Api-Key sk_test_51O62xYzAbcDef123'

Resposta (200 OK):

{
  "key": "f9b77185-a62e-4da9-a056-3c7b812ca334",
  "information": {
    "name": "Standard Plan",
    "created": "2025-03-25T08:50:15.732299Z",
    "interval": "month",
    "interval_count": 1,
    "currency": "USD",
    "amount": "19.99",
    "trial_period_days": 0,
    "credit_card_description": "STANDARD",
    "description": "This plan offers access to standard features with basic support.",
    "email": "developer@example.com",
    "company_name": "Acme Corp",
    "page": "https://acme.com",
    "active": true,
    "count": 75,
    "image": null,
    "image_dev": "https://acme.com/logo.png"
  },
  "test": true
}

Resposta (404 Not Found):

{
  "code": 404,
  "title": "Plan does not exist",
  "content": "The requested plan does not exist, please verify.",
  "type": "danger"
}

Atualizar um plano¶

Atualiza um plano existente com novos detalhes. Você pode atualizar campos individuais, incluindo nome, descrição, imagem e dias de período de teste, sem afetar os outros.

Parâmetros de Caminho (Path Parameters):

Parâmetros de Consulta (Query Parameters):

Campos do Corpo da Solicitação (todos opcionais):

Solicitação:

curl -X PUT 'https://api.4geeks.io/v1/plans/f9b77185-a62e-4da9-a056-3c7b812ca334/' \
     -H 'Authorization: Api-Key sk_test_51O62xYzAbcDef123' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "Updated Premium Plan",
           "description": "Updated description with full access to features",
           "trial_period_days": 14,
           "is_test": false
         }'

Resposta (200 OK):

{
    "code": 200,
    "title": "Plan actualizado",
    "content": "El plan Updated Premium Plan fue actualizado correctamente.",
    "type": "success",
    "data": "f9b77185-a62e-4da9-a056-3c7b812ca334"
}

Resposta (404 Not Found):

{
    "code": 404,
    "title": "Plan no encontrado",
    "content": "El plan con ID f9b77185-a62e-4da9-a056-3c7b812ca334 no existe o no tienes permisos para modificarlo.",
    "type": "danger"
}

Resposta (200 - Sem alterações):

{
    "code": 200,
    "title": "Sin cambios",
    "content": "No se detectaron cambios en el plan.",
    "type": "info",
    "data": "f9b77185-a62e-4da9-a056-3c7b812ca334"
}

Excluir um plano¶

Exclui permanentemente um plano e todas as assinaturas associadas. Quando um plano é excluído, todos os clientes com assinaturas ativas são notificados por e-mail.

Parâmetros de Caminho (Path Parameters):

Solicitação:

curl -X DELETE 'https://api.4geeks.io/v1/plans/f9b77185-a62e-4da9-a056-3c7b812ca334/' \
     -H 'Authorization: Api-Key sk_test_51O62xYzAbcDef123'

Resposta (200 OK):

{
    "code": 200,
    "title": "Plan deleted",
    "content": "The plan f9b77185-a62e-4da9-a056-3c7b812ca334 was deleted successfully.",
    "type": "success"
}

Resposta (404 Not Found):

{
    "code": 404,
    "title": "Plan does not exist",
    "content": "The plan f9b77185-a62e-4da9-a056-3c7b812ca334 does not exist or has already been deleted.",
    "type": "danger"
}

Tratamento de Erros¶

A API retorna códigos de status HTTP padrão para indicar o sucesso ou a falha de uma solicitação. Abaixo estão erros comuns específicos para planos:

400 Bad Request (Solicitação Inválida)¶

Ocorre quando a solicitação está malformada ou contém dados inválidos.

Cenários:

Exemplo de Resposta de Erro:

{
    "code": 400,
    "title": "Rango de precios inválido",
    "content": "El precio mínimo no pode ser maior que o máximo.",
    "type": "warning"
}

401 Unauthorized (Não Autorizado)¶

Falha na autenticação. A Chave de API é inválida, está ausente ou malformada.

Exemplo:

{
    "detail": "Authentication credentials were not provided."
}

Solução:

• Verifique se você incluiu o cabeçalho Authorization: Api-Key sk_test_....
• Certifique-se de que sua Chave de API está correta e ativa.
• Teste com o Postman usando o método de autenticação Api-Key.

404 Not Found (Não Encontrado)¶

O plano solicitado não existe.

Exemplo:

{
  "code": 404,
  "title": "Plan does not exist",
  "content": "The requested plan does not exist, please verify.",
  "type": "danger"
}

Solução:

• Verifique se a chave do plano existe.
• Use o endpoint de listagem para encontrar a chave correta do plano.
• Certifique-se de que o plano pertence à sua conta de desenvolvedor.

Notas Importantes¶

Melhores Práticas¶

1. Nomes de planos claros - Use nomes descritivos que indiquem claramente o nível e os recursos.
2. Descrições precisas - Forneça descrições detalhadas do que está incluído em cada plano.
3. Preços apropriados - Garanta que os preços sejam competitivos e reflitam o valor fornecido.
4. Períodos de teste - Considere oferecer períodos de teste para reduzir a fricção na aquisição de clientes.
5. Teste antes da produção - Use o modo de teste com chaves de API de teste para validação.
6. Monitore os assinantes - Use a contagem de assinantes nas respostas para acompanhar a adoção do plano.
7. Versionamento de planos - Crie novos planos em vez de modificar drasticamente os planos existentes com assinantes.
8. Otimização de imagem - Use imagens otimizadas para reduzir os tempos de resposta da API.

Solução de Problemas¶

Problema: “Plan does not exist”¶

Causa: A chave do plano não existe ou pertence a uma conta de desenvolvedor diferente.
Solução: - Verifique a chave do plano usando o endpoint de listagem. - Certifique-se de que está usando a Chave de API correta. - Verifique se o plano não foi excluído.

Problema: “Authentication credentials were not provided”¶

Causa: Autenticação de Chave de API ausente ou inválida.
Solução: - Use o cabeçalho Authorization: Api-Key sk_test_... em sua solicitação. - Verifique se sua Chave de API está ativa. - Teste com o Postman usando a autenticação Api-Key.

Problema: “El precio mínimo no puede ser mayor que el máximo”¶

Causa: Filtro de faixa de preço inválido fornecido.
Solução: - Garanta que price_min ≤ price_max. - Verifique se os valores do filtro são números válidos.

Problema: “El plan consultado no existe”¶

Causa: Os filtros da consulta não corresponderam a nenhum plano.
Solução: - Verifique se os parâmetros de filtro estão corretos. - Tente listar todos os planos sem filtros. - Verifique se o plano existe no modo de teste (ajuste o parâmetro test).

FAQ (Perguntas Frequentes)¶

P: Posso alterar o preço de um plano existente?
R: Não, os preços dos planos são imutáveis. Crie um novo plano com o preço atualizado e migre os clientes para ele.

P: O que acontece quando eu excluo um plano?
R: Todas as assinaturas ativas são canceladas e os clientes são notificados. Esta ação não pode ser desfeita.

P: Posso ter múltiplos planos com o mesmo nome?
R: Sim, mas recomenda-se usar nomes exclusivos para facilitar a gestão e identificação.

P: Quantos planos posso criar?
R: Não há limite para o número de planos que você pode criar.

P: Posso atualizar o interval ou interval_count após a criação?
R: Não, eles são imutáveis. Crie um novo plano com a frequência de faturamento desejada.

P: Qual é a diferença entre interval e interval_count?
R: interval é a unidade (mês, ano), e interval_count é o multiplicador (ex: a cada 3 meses = interval=month, interval_count=3).

P: Posso usar o mesmo plano para múltiplos produtos?
R: Sim, os planos são independentes dos produtos. Um plano representa uma configuração de ciclo de faturamento.

P: Como verifico o número de assinantes ativos de um plano?
R: Use os endpoints list ou get. O campo information.count mostra as assinaturas ativas.

• Ainda tem dúvidas? Pergunte na comunidade..
• Consulte el changelog.