Documentação / API
API de contactos (leads)
O formulário da landing envia pedidos para o mesmo host, sob o prefixo /api/.
Em produção o nginx encaminha estes pedidos para um serviço Node à escuta em 127.0.0.1 (ver Deploy).
Em desenvolvimento local, o Vite faz proxy de /api para 127.0.0.1:3847.
GET /api/health
Verificação simples de disponibilidade do serviço.
- 200 — corpo JSON:
{"ok":true}
curl -sS https://bitreport.pt/api/healthPOST /api/leads
Cria um registo de lead em SQLite. Cabeçalho obrigatório: Content-Type: application/json.
Corpo JSON
| Campo | Obrigatório | Notas |
|---|---|---|
| name | Sim | Máx. 200 caracteres (após trim) |
| Sim | Formato email simples; normalizado para minúsculas | |
| company | Não | Máx. 200 caracteres |
| message | Não | Máx. 5000 caracteres |
| _company_extra | Não | Honeypot anti-spam: se não vazio, resposta 200 sem gravar |
Respostas de sucesso
- 201 — lead criado:
{"ok":true,"id":<número>} - 200 — honeypot preenchido (silencioso):
{"ok":true}
Erros (JSON error)
| HTTP | error | Significado |
|---|---|---|
| 400 | invalid_json | Corpo não é JSON válido |
| 400 | name_required | Nome em falta |
| 400 | email_invalid | Email em falta ou inválido |
| 413 | payload_too_large | Corpo > 32 KiB |
| 429 | rate_limited | Demasiados pedidos por IP (janela deslizante) |
| 404 | not_found | Método ou caminho não suportado |
| 500 | server_error | Falha interna (ex.: base de dados) |
Limitação de taxa
Por endereço IP (primeiro valor de X-Forwarded-For quando presente, caso contrário o IP da ligação). Por defeito: 30 pedidos por 60 segundos à rota POST /api/leads.
OPTIONS /api/leads
Resposta 204 com cabeçalhos CORS limitados (POST, OPTIONS; Content-Type).
Exemplo
curl -sS -X POST https://bitreport.pt/api/leads \
-H 'Content-Type: application/json' \
-d '{"name":"Demo","email":"[email protected]","company":"ACME","message":"Olá","_company_extra":""}'Código-fonte (Gitea)
Os únicos caminhos expostos por este serviço são os documentados acima. A implementação vive no repositório bitreport-website (sem outros endpoints públicos inventados aqui).
- server/handler.mjs — rotas, validação, limites e respostas JSON
- server/index.mjs — arranque HTTP em
127.0.0.1 - server/db.mjs — SQLite (
website_leads) - tests/leads-api.test.mjs — contratos cobertos por teste
Variáveis de ambiente (serviço Node)
| Variável | Predefinição | Descrição |
|---|---|---|
| LEADS_API_PORT / PORT | 3847 | Porta em 127.0.0.1 |
| LEADS_DB_PATH | data/leads.sqlite no repo | Caminho absoluto recomendado em produção |