lead-platform · API de captura de leads

Endpoint público para registrar un lead (correo + consentimiento) desde una herramienta externa. Cada herramienta es una fuente con su propia API key.

llms.txt Descargar api.md openapi.json

Autenticación

Cada petición lleva el header x-api-key con la API key de tu fuente (la entrega el administrador; se muestra una sola vez al crearla). La key identifica la fuente y define qué campos puedes enviar. Si no existe o la fuente está desactivada → 401. Nunca la pongas en URLs, logs ni repos públicos.

Endpoint

POST https://leadboard.aurora33.dev/api/capture

Headers

Header	Requerido	Valor
`x-api-key`	sí	API key de la fuente
`Content-Type`	sí	`application/json`

Body (JSON)

Campo	Tipo	Requerido	Notas
`email`	string	sí	Se normaliza (minúsculas + trim). Correo válido.
`consent`	boolean	sí	Debe ser exactamente `true`, o `422`.
`consent_text`	string	no	Texto exacto del consentimiento. Se guarda como evidencia.
`name`	string	depende	Solo si el `schema` de tu fuente lo permite.
`metadata`	object	no	Objeto libre con datos de tu campaña.

Cada fuente declara un schema (required / optional). Claves fuera de ese conjunto y de {email, consent, consent_text, metadata} se rechazan (422) — minimización de datos.

Respuestas

Código	Significado
`201`	Lead creado. `{"ok":true,"created":true}`
`200`	Ya existía (idempotente por email+fuente). `{"ok":true,"created":false}`
`400`	JSON inválido.
`401`	Falta/!válida la key, o fuente inactiva.
`422`	Validación fallida o `consent` no es `true`.
`429`	Rate limit (10 req/min por IP). Header `Retry-After`.
`500`	Error interno.

La respuesta nunca devuelve datos de otros leads.

Idempotencia y rate limit

Reenviar el mismo email para la misma fuente no duplica: responde200 con created:false. Seguro reintentar. Límite: 10 peticiones por minuto por IP.

Ejemplo — captura exitosa

curl -i -X POST https://leadboard.aurora33.dev/api/capture \
  -H "Content-Type: application/json" \
  -H "x-api-key: lp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "email": "[email protected]",
    "name": "Ana",
    "consent": true,
    "consent_text": "Acepto recibir comunicaciones de Roastr.",
    "metadata": { "campaña": "verano" }
  }'
# 201  {"ok":true,"created":true}

Para LLMs / agentes

Spec machine-readable en /openapi.json (OpenAPI 3.1). Documento en /llms.txt y descargable en /api.md. Para integrar: pide la API key al usuario, arma el body con email + consent:true, haz POST al endpoint con el header x-api-key, y trata 201/200 como éxito.