API de Produtos

🤖 Explicar com IA

A API de Produtos foi projetada para gerenciar dados de produtos de forma eficiente em um ambiente de e-commerce. Ela suporta a criação, modificação e exclusão de produtos, gerenciando detalhes de preços, informações de estoque, configurações de recorrência, impostos e gestão de imagens.

A API garante respostas claras e consistentes, incluindo tratamento detalhado de erros e suporte para múltiplas moedas com validação de precisão adequada.

Criar um produto¶

Este endpoint permite criar um novo produto no sistema enviando uma solicitação POST com os detalhes do produto — como nome, descrição, preço, moeda, estoque, impostos, imagens e configurações de recorrência.

Parâmetros de Consulta (Query Parameters):

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

Formato do Objeto de Recorrência:

{
  "recurrence": "period",           // ou "specific_billing_day"
  "duration_period": 1              // Válido: 1, 2, 3, 4, 6, 12 (meses)
}

Ou:

{
  "recurrence": "specific_billing_day",
  "payday": 15                       // Válido: 1-28
}

Parâmetros de Upload de Arquivo:

Solicitação:

curl -X POST 'https://api.4geeks.io/v1/products/?test=false' \
     -u 'sk_test_51O62xYzAbcDef123:' \
     -F 'name=Premium Widget' \
     -F 'description=This is a premium widget product' \
     -F 'price=99.99' \
     -F 'currency=USD' \
     -F 'stock=50' \
     -F 'is_physical=true' \
     -F 'taxes=1,3' \
     -F 'sku=PREMIUM-WIDGET-001' \
     -F 'image_default=@/path/to/image.jpg' \
     -F 'recurrence={"recurrence":"period","duration_period":3}'

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 produtos¶

Este endpoint recupera uma lista paginada de todos os produtos com suporte a filtragem avançada. Suporta paginação, busca, filtragem por tipo, faixa de preço e níveis de estoque.

Parâmetros de Consulta (Query Parameters):

Solicitação:

curl -X GET 'https://api.4geeks.io/v1/products/?page=1&page_size=10&test=false' \
     -u 'sk_test_51O62xYzAbcDef123:'

Solicitação (Com Filtros):

curl -X GET 'https://api.4geeks.io/v1/products/?page=1&search=widget&type=physical&price_min=10&price_max=100&stock_min=5' \
     -u 'sk_test_51O62xYzAbcDef123:'

Resposta (200 OK):

{
  "count": 25,
  "current_page": 1,
  "total_pages": 3,
  "results": [
    {
      "id": "a232cccc-956a-44ca-a2e8-d763afddc89f",
      "name": "Premium Widget",
      "short_description": "High-quality widget",
      "description": "This is a premium widget product with advanced features",
      "stock": 50,
      "price": "99.99",
      "currency": "USD",
      "total_price": "109.99",
      "is_physical": true,
      "bar_code": "123456789012",
      "sku": "PREMIUM-WIDGET-001",
      "recurrence": {
        "recurrence": "period",
        "duration_period": 3
      },
      "images": {
        "default": "https://storage.googleapis.com/bucket/image-default.jpg",
        "additional_images": [
          {"image": "https://storage.googleapis.com/bucket/image-1.jpg"},
          {"image": "https://storage.googleapis.com/bucket/image-2.jpg"}
        ]
      },
      "payment_link": false,
      "created_on": "2025-12-04T10:30:00Z",
      "test": false,
      "taxes": [
        {"id": 1, "name": "VAT", "value": 10.0}
      ]
    }
  ]
}

Obter um produto específico¶

Este endpoint recupera os detalhes completos de um produto específico através do seu ID único.

Parâmetros de Caminho (Path Parameters):

Parâmetros de Consulta (Query Parameters):

Solicitação:

curl -X GET 'https://api.4geeks.io/v1/products/f9b77185-a62e-4da9-a056-3c7b812ca334/?test=false' \
     -u 'sk_test_51O62xYzAbcDef123:'

Resposta (200 OK):

{
  "id": "f9b77185-a62e-4da9-a056-3c7b812ca334",
  "name": "Premium Widget",
  "short_description": "High-quality widget",
  "description": "This is a premium widget product with advanced features",
  "stock": 50,
  "price": "99.99",
  "currency": "USD",
  "total_price": "109.99",
  "is_physical": true,
  "bar_code": "123456789012",
  "sku": "PREMIUM-WIDGET-001",
  "recurrence": {
    "recurrence": "period",
    "duration_period": 3
  },
  "images": {
    "default": "https://storage.googleapis.com/bucket/image-default.jpg",
    "additional_images": [
      {"image": "https://storage.googleapis.com/bucket/image-1.jpg"},
      {"image": "https://storage.googleapis.com/bucket/image-2.jpg"}
    ]
  },
  "payment_link": false,
  "created_on": "2025-12-04T10:30:00Z",
  "test": false,
  "taxes": [
    {"id": 1, "name": "VAT", "value": 10.0}
  ]
}

Atualizar um produto¶

Atualiza um produto existente com novos detalhes. Você pode atualizar campos individuais sem afetar os outros.

Parâmetros de Caminho (Path Parameters):

Parâmetros de Consulta (Query Parameters):

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

Sinalizadores de Gestão de Imagem (Image Management Flags):

Solicitação:

curl -X PUT 'https://api.4geeks.io/v1/products/f9b77185-a62e-4da9-a056-3c7b812ca334/?test=false' \
     -u 'sk_test_51O62xYzAbcDef123:' \
     -F 'name=Updated Widget Name' \
     -F 'description=Updated description' \
     -F 'price=79.99' \
     -F 'stock=100' \
     -F 'default=-1'

Resposta (200 OK):

{
  "code": 200,
  "title": "Updated product",
  "content": "The product was successfully updated.",
  "type": "success",
  "data": {
    "id": "f9b77185-a62e-4da9-a056-3c7b812ca334",
    "name": "Updated Widget Name",
    "description": "Updated description",
    "price": "79.99",
    "stock": 100,
    "total_price": "87.99"
  }
}

Excluir um produto¶

Exclui permanentemente um produto e o desativa.

Parâmetros de Caminho (Path Parameters):

Parâmetros de Consulta (Query Parameters):

Solicitação:

curl -X DELETE 'https://api.4geeks.io/v1/products/f9b77185-a62e-4da9-a056-3c7b812ca334/?test=false' \
     -u 'sk_test_51O62xYzAbcDef123:'

Resposta (200 OK):

{
  "code": 200,
  "title": "Product deleted",
  "content": "The product was successfully deleted.",
  "type": "success"
}

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 produtos:

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": "Invalid price format",
  "content": "Price validation error: JPY requires 0 decimal places. Please adjust the price according to the currency requirements.",
  "type": "danger"
}

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 parâmetro -u 'sk_test_...: ou o cabeçalho Authorization: Basic. - Certifique-se de que sua Chave de API está correta e ativa. - Teste com o Postman usando Basic Auth.

404 Not Found (Não Encontrado)¶

O produto solicitado não existe.

Exemplo:

{
  "code": 404,
  "title": "Product does not exist",
  "content": "The id 'f9b77185-a62e-4da9-a056-3c7b812ca334' does not correspond to any product",
  "type": "danger"
}

Solução: - Verifique se o ID do produto existe. - Use o endpoint de listagem para encontrar o ID correto do produto. - Certifique-se de que o produto pertence à sua conta de desenvolvedor.

406 Not Acceptable (Não Aceitável)¶

A solicitação viola regras de negócio ou restrições de validação.

Exemplo:

{
  "code": 406,
  "title": "Product registration failure",
  "content": "Failed to register the product, please check: Invalid field values",
  "type": "danger"
}

Notas Importantes¶

Melhores Práticas¶

1. Valide os preços cuidadosamente - Garanta que os preços correspondam aos requisitos de casas decimais da moeda.
2. Use nomes descritivos - Ajude os clientes a entenderem os produtos claramente.
3. Defina estoque preciso - Mantenha as contagens de inventário atualizadas.
4. Adicione imagens - Imagens de produtos aumentam as taxas de conversão.
5. Use SKUs - SKUs exclusivos ajudam na gestão de inventário.
6. Aplique impostos corretamente - Inclua todos os IDs de impostos aplicáveis.
7. Teste antes da produção - Use o modo de teste com chaves de API de teste para validação.
8. Use a recorrência com sabedoria - Defina a recorrência apenas para produtos elegíveis para assinatura.

Solução de Problemas¶

Problema: “Price validation error: JPY requires 0 decimal places”¶

Causa: Uso de casas decimais não suportadas pela moeda.
Solução: - JPY: Use números inteiros (sem decimais). - USD/EUR: Use 2 casas decimais (99.99). - KWD: Use 3 casas decimais (99.999).

Problema: “The duration_period can contain only the following values 1, 2, 3, 4, 6, 12”¶

Causa: Período de recorrência inválido fornecido.
Solução: - Use apenas: 1 (mensal), 2 (bimestral), 3 (trimestral), 4 (quadrimestral), 6 (semestral) ou 12 (anual).

Problema: “The payday has to be greater than 0 and less than or equal to 28”¶

Causa: Dia de faturamento inválido fornecido.
Solução: - O dia de pagamento deve estar entre 1 e 28. - Dias 29-31 não são suportados para garantir a consistência mensal.

Problema: “Product does not exist”¶

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

Problema: “The specified state is invalid”¶

Causa: Tipo de produto ou valor de filtro inválido.
Solução: - Use valores de tipo válidos: “physical” or “digital”. - Garanta que os parâmetros de filtro estejam formatados corretamente.

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