Referencia de la API
Documentación técnica del único endpoint público de Farvane: POST /api/v1/submit. No requiere autenticación — el access_key identifica el formulario.
Campos reservados
Estos tres nombres de campo están reservados por Farvane. No los uses para datos propios del formulario.
| Campo | Obligatorio | Qué hace |
|---|---|---|
access_key | Sí | UUID del formulario. Identifica a qué formulario de tu cuenta pertenece el envío. Si falta o no es un UUID válido, o no corresponde a ningún formulario, la petición se rechaza con 400. |
botcheck | Sí (vacío) | Campo honeypot anti-spam: debe existir en el formulario pero llegar siempre vacío. Si llega con contenido, Farvane trata el envío como spam. |
turnstile_token | Condicional | Solo si el formulario tiene Cloudflare Turnstile activado en Ajustes. Si falta o no verifica, la petición se rechaza con 422. |
El resto de campos del formulario son libres: cualquier otro nombre que envíes (name, email, message, o los que quieras) se reenvía tal cual en el email de notificación, sin validación de esquema.
Content-Type admitidos
El endpoint acepta tanto application/json (un objeto con access_key, botcheck, turnstile_token y el resto de campos como propiedades) como application/x-www-form-urlencoded o multipart/form-data — el resultado de un <form> nativo o de un FormData. Usa el que mejor encaje con tu integración.
JSON o redirección 302
Si la petición incluye la cabecera Accept: text/html (el valor por defecto de un envío de formulario nativo del navegador) y el formulario tiene una redirect_url configurada en Ajustes, Farvane responde 302 Found con esa URL en Location. En cualquier otro caso — un fetch con Accept: application/json, o sin redirect_url configurada — responde 200 con JSON.
Nota sobre el honeypot: cuando botcheck llega relleno, Farvane responde 200 igual que un envío legítimo — nunca delata al bot que fue detectado. El envío no se reenvía por email; se guarda internamente marcado como spam.
Códigos de respuesta
| Código | Cuándo ocurre | Cuerpo |
|---|---|---|
200 | Envío aceptado (o detectado como honeypot, ver nota anterior). | {"success":true,"message":"Enviado correctamente"} |
302 | Envío aceptado, cabecera Accept: text/html y el formulario tiene redirect_url configurada. | Sin cuerpo — Location: <redirect_url> |
400 | access_key ausente, no es un UUID válido, o no corresponde a ningún formulario existente. | {"success":false,"message":"..."} |
403 | El formulario tiene allowed_domains configurado y el origen de la petición (cabecera Origin, o Referer si falta Origin) no está en esa lista. | {"message":"...","status":403,"timestamp":"..."} |
422 | El formulario tiene Turnstile activado y turnstile_token falta, está vacío o no verifica. | {"success":false,"message":"Verificación de seguridad fallida"} |
429 | Más de 20 peticiones/minuto para el mismo access_key + IP, o la cuota mensual de envíos del plan está agotada. | {"success":false,"message":"..."} |
El límite de 20 peticiones/minuto se aplica por combinación de access_key + IP, en memoria del proceso — es independiente de la cuota mensual de tu plan, que es un límite distinto y se comprueba por separado.
Ejemplo curl
curl -X POST https://farvane-api.panergos.com/api/v1/submit -H "Accept: application/json" -F "access_key=YOUR_ACCESS_KEY_HERE" -F "botcheck=" -F "name=Ada Lovelace" -F "[email protected]" -F "message=Hola desde curl"