Documentação da API

1. Visão geral e Base URL

A API VerdePote permite cruzar listas de ingredientes fornecidas pelo utilizador com uma base de dados estruturada de receitas tradicionais e vegetarianas portuguesas.

Endpoint Base:

2. Autenticação

Todas as requisições à API devem incluir a tua chave de acesso pessoal através do cabeçalho HTTP X-Api-Key.

Podes obter ou gerir a tua chave diretamente no teu painel de controlo de programador após efetuar o registo.

3. Especificação do Pedido (Request)

• Método HTTP: POST
• Content-Type: application/json

Payload de Exemplo (JSON):

{
  "ingredientes": [
    "tomate",
    "cebola",
    "azeite",
    "feijão frade"
  ]
}

4. Estrutura da Resposta (Response)

A API devolve um objeto JSON contendo metadados de execução, o estado da quota do plano e um array com as receitas compatíveis e respetivos detalhes nutricionais.

{
  "sucesso": true,
  "plano": "pro",
  "pedidos_restantes_mes": 489,
  "total_receitas_avaliadas": 20,
  "total_resultados": 20,
  "resultados": [
    {
      "id": 1,
      "titulo": "Salada de Feijão Frade com Tomate",
      "match_percent": 85,
      "tempo_preparo": "15m",
      "dificuldade": "Fácil",
      "custo_estimado": "baixo",
      "ingredientes_que_tens": ["tomate", "cebola", "azeite", "feijão frade"],
      "ingredientes_em_falta": [],
      "instrucoes": "Cozer o feijão frade, picar a cebola e o tomate, envolver tudo com azeite e vinagre.",
      "substituicoes": [],
      "nutricao": {
        "calorias": 350,
        "proteina_g": 12,
        "hidratos_g": 40,
        "gordura_g": 10
      },
      "tags_dieta": ["Vegetariano", "Vegan"],
      "alergenios": []
    }
  ]
}

5. Limites e Quotas (Rate Limiting)

O consumo de pedidos é contabilizado por mês civil com base no plano ativo:

• Plano Gratuito: 30 pedidos / mês.
• Plano Pro: 500 pedidos / mês.
• Plano Enterprise: Pedidos ilimitados com servidor dedicado e SLA de 99.9%.

6. Códigos de Erro HTTP

Em caso de falha, a API retorna um código de estado HTTP apropriado acompanhado de uma descrição em JSON:

• 400 Bad Request

  Lista de ingredientes inválida ou vazia.

• 401 Unauthorized

  Chave de API ausente ou inválida no cabeçalho X-Api-Key.

• 429 Too Many Requests

  Limite mensal de pedidos do plano atual esgotado.

• 500 Internal Server Error

  Erro interno no servidor ou falha na base de dados.

7. Exemplos de Integração

Vê como podes efetuar pedidos à API utilizando diferentes linguagens:

curl -X POST https://verdepote.com/match-ingredientes.php \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: a-tua-chave-api" \
  -d '{"ingredientes": ["tomate", "cebola"]}'

fetch('https://verdepote.com/match-ingredientes.php', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'a-tua-chave-api'
  },
  body: JSON.stringify({
    ingredientes: ['tomate', 'cebola']
  })
})
.then(response => response.json())
.then(data => console.log(data));