Endpoints — API de Zelta Forms

Base URL: /api/v1

Todos los endpoints requieren autenticación mediante API Key en el header X-API-Key. Consulta la para crear tu clave.

Formularios

Listar formularios

GET /api/v1/forms

Parámetros de consulta:

Parámetro	Tipo	Descripción
limit	integer	Resultados por página (default: 25, max: 100)
offset	integer	Número de resultados a omitir para paginación

Ejemplo:

curl -X GET "https://tu-dominio.com/api/v1/forms?limit=10&offset=0" \
  -H "X-API-Key: fai_sk_tu_clave"

Respuesta:

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Encuesta de satisfacción Q1",
      "description": "Evaluación trimestral de satisfacción del cliente",
      "status": "published",
      "defaultMode": "conversational",
      "slug": "enc-satisfaccion-q1",
      "isPublic": true,
      "createdAt": "2026-01-10T09:00:00Z",
      "publishedAt": "2026-01-12T10:30:00Z"
    }
  ]
}

Crear formulario

POST /api/v1/forms

Cuerpo de la petición:

{
  "title": "Formulario de contacto",
  "description": "Formulario para recibir consultas de clientes"
}

Ejemplo:

curl -X POST "https://tu-dominio.com/api/v1/forms" \
  -H "X-API-Key: fai_sk_tu_clave" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Formulario de contacto",
    "description": "Formulario para recibir consultas"
  }'

Obtener formulario

GET /api/v1/forms/{formId}

Retorna el detalle completo del formulario incluyendo su schema (campos, validaciones, configuración) y ajustes de modo.

Ejemplo:

curl -X GET "https://tu-dominio.com/api/v1/forms/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-API-Key: fai_sk_tu_clave"

---

Respuestas

Listar respuestas de un formulario

GET /api/v1/forms/{formId}/responses

Parámetros de consulta:

Parámetro	Tipo	Descripción
limit	integer	Resultados por página
offset	integer	Número de resultados a omitir

Ejemplo:

curl -X GET "https://tu-dominio.com/api/v1/forms/a1b2c3d4/responses?limit=25" \
  -H "X-API-Key: fai_sk_tu_clave"

Respuesta:

{
  "data": [
    {
      "id": "r1s2t3u4-v5w6-7890-abcd-ef1234567890",
      "formId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "completed",
      "mode": "conversational",
      "respondentEmail": "[email protected]",
      "startedAt": "2026-03-10T14:25:00Z",
      "completedAt": "2026-03-10T14:30:00Z",
      "totalTimeSeconds": 300,
      "completionPercentage": 100
    }
  ]
}

Obtener detalle de una respuesta

GET /api/v1/forms/{formId}/responses/{responseId}

Retorna la respuesta completa con todas las respuestas por campo (field answers), incluyendo el valor, tiempo por campo y conteo de revisiones.

Ejemplo:

curl -X GET "https://tu-dominio.com/api/v1/forms/a1b2c3d4/responses/r1s2t3u4" \
  -H "X-API-Key: fai_sk_tu_clave"

---

Envío público de formularios

Los formularios publicados aceptan respuestas a través de una ruta pública que no requiere autenticación:

POST /api/forms/{formId}/submit

Esta ruta es utilizada por los formularios publicados (/f/[slug] y /embed/[slug]). Está protegida por rate limiting (10 envíos por minuto por IP).

Nota

Este endpoint no forma parte de la API v1 y no usa API Key. Es la ruta interna que los formularios publicados utilizan para enviar respuestas.

---

Códigos de respuesta

Código	Descripción
200	Solicitud exitosa
201	Recurso creado exitosamente
400	Solicitud mal formada o datos inválidos
401	No autenticado (API Key ausente o inválida)
403	Sin permisos suficientes o plan sin acceso API
404	Recurso no encontrado
422	Error de validación en los datos enviados
429	Límite de tasa excedido
500	Error interno del servidor

Paginación

Los endpoints de listado usan limit y offset para paginación. El valor máximo de limit es 100.