Terra v2 API · v1

Read-only JSON endpoints para integración Cesantoni ERP/CRM. Auth via X-API-Key header (excepto /index.json público). GET-only, regenerados en cada deploy. Rate limit razonable.

🔐 Auth (NEW — protect contra scraping)

Cómo autenticar
  • Header auth (recomendado): X-API-Key: <key>
  • Query param (fallback para webhooks): ?api_key=<key>
  • Sin key válido → HTTP 401 con JSON {error, message, docs}
  • Key inválido → HTTP 403
Recibir + rotar key
  • Cesantoni IT recibe el key via secret manager (1Password / AWS Secrets / Bitwarden)
  • NUNCA en email plano, repo, o Slack
  • Rotación: cada 90 días o si alguien lo expone
  • Para revocar/rotar: wrangler pages secret put DATA_API_KEY (genera nuevo, distribuye)

Set en Cloudflare Pages: wrangler pages secret put DATA_API_KEY --project-name=terra-v2· Bypass dev local: si DATA_API_KEY no está set, middleware permite con header X-API-Auth-Status: dev-no-key.

📡 8 Endpoints disponibles

PathDescripción
/data-api/v1/index.jsonIndex con todos los endpoints disponibles
/data-api/v1/plazas.jsonLista de 109 plazas con metrics resumen (TAM, SOM, NSE, verdict pisos)
/data-api/v1/plazas/{slug}.jsonDetalle de plaza específica con todos los productos. Ej: /data-api/v1/plazas/zm-monterrey.json
/data-api/v1/products.jsonAgregados nacionales por producto (5 productos)
/data-api/v1/competitor-prices.jsonPrecios competidores live (Azulemex scrape diario)
/data-api/v1/dof-watch.jsonDOF antidumping watch (investigaciones activas + hits)
/data-api/v1/data-quality.jsonConfidence score actual + breakdown por regla
/data-api/v1/win-loss.jsonCesantoni deals tracker resumen + calibración

Ejemplos de uso

Discover endpoints (público, sin key)
curl https://t3rra.uk/data-api/v1/index.json | jq '.endpoints'
Get all plazas (requiere X-API-Key)
curl -H "X-API-Key: $DATA_API_KEY" https://t3rra.uk/data-api/v1/plazas.json | jq '.data[] | select(.cesa_pts >= 5)'
Get specific plaza detail
curl -H "X-API-Key: $DATA_API_KEY" https://t3rra.uk/data-api/v1/plazas/zm-monterrey.json
Live competitor prices
curl -H "X-API-Key: $DATA_API_KEY" https://t3rra.uk/data-api/v1/competitor-prices.json | jq '.current_prices'
Alternative: query param (menos seguro pero útil para webhooks)
curl "https://t3rra.uk/data-api/v1/data-quality.json?api_key=$DATA_API_KEY"
JavaScript fetch desde sistema externo
const r = await fetch('https://t3rra.uk/data-api/v1/plazas.json', {
  headers: { 'X-API-Key': process.env.DATA_API_KEY }
});
const { data } = await r.json();
console.log(data.find(p => p.slug === 'zm-monterrey'));

📋 Notas técnicas

/data-quality·/methodology