Endpoints — API de Zelta Forms

Base URL: https://api.zelta.dev/v1/forms

Todos los endpoints requieren autenticación mediante token Bearer. Consulta la para obtener tu token.

Formularios

Listar formularios

GET /forms

Parámetros de consulta:

Parámetro	Tipo	Descripción
page	integer	Número de página (default: 1)
per_page	integer	Resultados por página (default: 25, max: 100)
status	string	draft, published, closed
search	string	Buscar por nombre del formulario
sort_by	string	created_at, name, responses_count

Ejemplo:

curl -X GET "https://api.zelta.dev/v1/forms?status=published&per_page=10" \
  -H "Authorization: Bearer {token}"

Respuesta:

{
  "data": [
    {
      "id": "form_abc123",
      "name": "Encuesta de satisfacción Q1",
      "status": "published",
      "responses_count": 142,
      "fields_count": 8,
      "created_at": "2026-01-10T09:00:00Z",
      "published_at": "2026-01-12T10:30:00Z",
      "url": "https://forms.zelta.dev/f/abc123"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 3,
    "total_count": 27
  }
}

Crear formulario

POST /forms

Cuerpo de la petición:

{
  "name": "Formulario de contacto",
  "description": "Formulario para recibir consultas de clientes",
  "status": "draft",
  "theme": "moderno",
  "settings": {
    "show_progress": true,
    "allow_save_draft": false,
    "limit_responses": null,
    "close_date": null
  }
}

Scope requerido: forms:write

Obtener formulario

GET /forms/{form_id}

Actualizar formulario

PATCH /forms/{form_id}

Eliminar formulario

DELETE /forms/{form_id}

Scope requerido: forms:admin

Atención

Eliminar un formulario también elimina todas sus respuestas de forma permanente. Considera cerrar el formulario en lugar de eliminarlo para conservar los datos.

Publicar formulario

POST /forms/{form_id}/publish

Cerrar formulario

POST /forms/{form_id}/close

---

Respuestas (Submissions)

Listar respuestas de un formulario

GET /forms/{form_id}/submissions

Parámetros de consulta:

Parámetro	Tipo	Descripción
page	integer	Número de página
per_page	integer	Resultados por página
status	string	complete, partial, in_progress
from	date	Fecha de inicio (ISO 8601)
to	date	Fecha de fin (ISO 8601)
sort_by	string	submitted_at, completion_time

Ejemplo:

curl -X GET "https://api.zelta.dev/v1/forms/form_abc123/submissions?status=complete" \
  -H "Authorization: Bearer {token}"

Respuesta:

{
  "data": [
    {
      "id": "sub_xyz789",
      "form_id": "form_abc123",
      "status": "complete",
      "data": {
        "nombre": "María García",
        "email": "maria@empresa.com",
        "calificacion": 5,
        "comentarios": "Muy buen servicio."
      },
      "metadata": {
        "submitted_at": "2026-03-10T14:30:00Z",
        "completion_time_seconds": 180,
        "device": "mobile",
        "source": "direct_link"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 15,
    "total_count": 142
  }
}

Obtener una respuesta

GET /forms/{form_id}/submissions/{submission_id}

Crear una respuesta (programática)

POST /forms/{form_id}/submissions

{
  "data": {
    "nombre": "Carlos López",
    "email": "carlos@ejemplo.com",
    "calificacion": 4,
    "comentarios": "Buen producto, con margen de mejora."
  }
}

Eliminar una respuesta

DELETE /forms/{form_id}/submissions/{submission_id}

Scope requerido: forms:admin

---

Campos (Fields)

Listar campos de un formulario

GET /forms/{form_id}/fields

Respuesta:

{
  "data": [
    {
      "id": "field_001",
      "type": "text_short",
      "label": "Nombre completo",
      "required": true,
      "position": 1,
      "validations": {
        "min_length": 2,
        "max_length": 100
      }
    },
    {
      "id": "field_002",
      "type": "email",
      "label": "Correo electrónico",
      "required": true,
      "position": 2,
      "validations": {}
    },
    {
      "id": "field_003",
      "type": "rating",
      "label": "Calificación del servicio",
      "required": true,
      "position": 3,
      "validations": {
        "min": 1,
        "max": 5
      }
    }
  ]
}

Agregar campo

POST /forms/{form_id}/fields

{
  "type": "select",
  "label": "¿Cómo nos conociste?",
  "required": false,
  "position": 4,
  "options": [
    "Redes sociales",
    "Recomendación",
    "Búsqueda en Google",
    "Otro"
  ]
}

Actualizar campo

PATCH /forms/{form_id}/fields/{field_id}

Eliminar campo

DELETE /forms/{form_id}/fields/{field_id}

---

Códigos de respuesta

Código	Descripción
200	Solicitud exitosa
201	Recurso creado exitosamente
204	Recurso eliminado exitosamente
400	Solicitud mal formada
401	No autenticado
403	Sin permisos suficientes
404	Recurso no encontrado
422	Error de validación
429	Límite de tasa excedido
500	Error interno del servidor

Paginación

Todos los endpoints de listado soportan paginación. Usa los campos meta.current_page y meta.total_pages para navegar entre páginas.