GestorForms
Volver al inicioObtener API Key

API de GestorForms

v1.0 — REST API

La API de GestorForms te permite integrar formularios inteligentes, gestión de envíos y firma electrónica directamente en tus aplicaciones. Todos los endpoints devuelven JSON y utilizan autenticación por API Key.

API REST

JSON sobre HTTPS con verbos HTTP estándar

Segura

TLS 1.3 + API Keys con ámbito por organización

Rápida

Respuesta media < 100ms en nodos EU

Autenticación

Todas las peticiones deben incluir tu API Key en el header Authorization. Puedes obtener tu API Key desde el panel de ajustes de tu organización.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     https://api.gestorforms.com/v1/templates
Importante: Nunca expongas tu API Key en código frontend. Utiliza siempre llamadas desde tu servidor (backend).

URL Base

https://api.gestorforms.com/v1

Todas las URLs de los endpoints son relativas a esta URL base.

Códigos de error

La API utiliza códigos HTTP estándar para indicar el resultado de una petición:

CódigoSignificado
200Éxito
201Recurso creado
400Petición inválida (parámetros incorrectos)
401No autenticado (API Key inválida o ausente)
403Sin permisos para este recurso
404Recurso no encontrado
429Demasiadas peticiones (rate limit)
500Error interno del servidor

Las respuestas de error incluyen un objeto JSON con detalles:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "El campo 'email' es requerido",
    "details": { "field": "email" }
  }
}

Límites de uso

PlanPeticiones/minPeticiones/día
Starter301,000
Profesional12010,000
Enterprise600100,000

Formularios

GET/templates

Obtiene la lista de plantillas de formulario de tu organización.

Parámetros de query

ParámetroTipoRequeridoDescripción
pageintegerNoNúmero de página (default: 1)
per_pageintegerNoResultados por página (default: 20, max: 100)
categorystringNoFiltrar por categoría

Respuesta (200)

{
  "data": [
    {
      "id": "tpl_abc123",
      "name": "Transferencia de vehículo",
      "category": "DGT",
      "pdf_url": "https://storage.gestorforms.com/...",
      "client_fields": ["nombre", "dni", "matricula"],
      "gestoria_fields": ["num_expediente"],
      "is_active": true,
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 45
  }
}
GET/templates/:id

Obtiene los detalles de una plantilla específica.

Parámetros de ruta

ParámetroTipoRequeridoDescripción
idstringSíID de la plantilla

Respuesta (200)

{
  "id": "tpl_abc123",
  "name": "Transferencia de vehículo",
  "category": "DGT",
  "description": "Formulario de transferencia...",
  "pdf_url": "https://storage.gestorforms.com/...",
  "client_fields": [
    { "key": "nombre", "label": "Nombre completo", "type": "text", "required": true },
    { "key": "dni", "label": "DNI/NIE", "type": "text", "required": true },
    { "key": "matricula", "label": "Matrícula", "type": "text", "required": true }
  ],
  "gestoria_fields": [
    { "key": "num_expediente", "label": "Nº Expediente", "type": "text", "required": true }
  ],
  "is_active": true,
  "slug": "transferencia-vehiculo",
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-02-10T08:45:00Z"
}
POST/templates

Crea una nueva plantilla de formulario.

Body (JSON)

ParámetroTipoRequeridoDescripción
namestringSíNombre de la plantilla
categorystringNoCategoría (DGT, Extranjería, etc.)
descriptionstringNoDescripción del formulario
pdf_filebase64SíArchivo PDF en Base64
client_fieldsarraySíCampos a rellenar por el cliente
gestoria_fieldsarrayNoCampos internos de la gestoría

Ejemplo de petición

{
  "name": "Mandato DGT",
  "category": "DGT",
  "pdf_file": "JVBERi0xLjQKMSA...",
  "client_fields": [
    { "key": "nombre", "label": "Nombre completo", "type": "text", "required": true },
    { "key": "dni", "label": "DNI/NIE", "type": "text", "required": true }
  ]
}

Respuesta (201)

{
  "id": "tpl_xyz789",
  "name": "Mandato DGT",
  "slug": "mandato-dgt",
  "created_at": "2026-02-25T12:00:00Z"
}

Envíos

GET/submissions

Obtiene la lista de envíos de formularios.

ParámetroTipoRequeridoDescripción
pageintegerNoNúmero de página
statusstringNoFiltrar por estado: draft, submitted, signing, signed, completed, rejected
template_idstringNoFiltrar por plantilla

Respuesta (200)

{
  "data": [
    {
      "id": "sub_001",
      "template_id": "tpl_abc123",
      "client_email": "cliente@example.com",
      "status": "signed",
      "filled_pdf_url": "https://...",
      "signed_pdf_url": "https://...",
      "created_at": "2026-02-20T14:00:00Z"
    }
  ],
  "pagination": { "page": 1, "per_page": 20, "total": 128 }
}
GET/submissions/:id

Obtiene los detalles de un envío específico, incluyendo los datos del cliente.

ParámetroTipoRequeridoDescripción
idstringSíID del envío

Respuesta (200)

{
  "id": "sub_001",
  "template_id": "tpl_abc123",
  "template_name": "Transferencia de vehículo",
  "client_email": "cliente@example.com",
  "client_data": {
    "nombre": "Juan García López",
    "dni": "12345678A",
    "matricula": "1234 ABC"
  },
  "gestoria_data": {
    "num_expediente": "EXP-2026-001"
  },
  "status": "signed",
  "filled_pdf_url": "https://...",
  "signed_pdf_url": "https://...",
  "signature_request_id": "sig_vf_abc123",
  "signature_provider": "viafirma",
  "created_at": "2026-02-20T14:00:00Z",
  "updated_at": "2026-02-21T09:30:00Z"
}
POST/submissions

Crea un nuevo envío para una plantilla específica.

ParámetroTipoRequeridoDescripción
template_idstringSíID de la plantilla
client_emailstringSíEmail del cliente
client_dataobjectNoDatos pre-rellenados del cliente
gestoria_dataobjectNoDatos internos de gestoría
send_notificationbooleanNoEnviar email al cliente (default: true)

Ejemplo de petición

{
  "template_id": "tpl_abc123",
  "client_email": "cliente@example.com",
  "client_data": {
    "nombre": "Juan García López"
  },
  "send_notification": true
}
GET/submissions/:id/pdf

Descarga el PDF rellenado de un envío.

ParámetroTipoRequeridoDescripción
idstringSíID del envío
typestringNo'filled' (default) o 'signed'

Devuelve el archivo PDF con Content-Type: application/pdf

Firma electrónica

POST/submissions/:id/sign

Envía un documento para firma electrónica usando el proveedor configurado en tu organización.

ParámetroTipoRequeridoDescripción
idstringSíID del envío
signer_namestringSíNombre del firmante
signer_emailstringSíEmail del firmante
signer_phonestringNoTeléfono del firmante (para firma SMS)
callback_urlstringNoURL para recibir notificaciones de estado

Ejemplo de petición

{
  "signer_name": "Juan García López",
  "signer_email": "cliente@example.com",
  "signer_phone": "+34600000000",
  "callback_url": "https://tu-app.com/api/signature-callback"
}

Respuesta (200)

{
  "signature_request_id": "sig_vf_abc123",
  "provider": "viafirma",
  "status": "pending",
  "signing_url": "https://documents.viafirma.com/..."
}
GET/submissions/:id/sign/status

Consulta el estado actual de una solicitud de firma.

ParámetroTipoRequeridoDescripción
idstringSíID del envío

Respuesta (200)

{
  "signature_request_id": "sig_vf_abc123",
  "status": "signed",
  "provider": "viafirma",
  "signed_pdf_url": "https://...",
  "completed_at": "2026-02-21T09:30:00Z"
}

Estados posibles

EstadoDescripción
pendingEnviado, esperando firma
signedDocumento firmado correctamente
rejectedFirma rechazada por el firmante
expiredLa solicitud ha expirado
errorError en el proceso de firma

Webhooks

Configura un webhook para recibir notificaciones automáticas cuando cambie el estado de una firma. GestorForms enviará un POST a tu URL con los datos actualizados.

Payload del webhook

{
  "event": "signature.status_changed",
  "timestamp": "2026-02-21T09:30:00Z",
  "data": {
    "submission_id": "sub_001",
    "signature_request_id": "sig_vf_abc123",
    "previous_status": "pending",
    "new_status": "signed",
    "provider": "viafirma",
    "signed_pdf_url": "https://...",
    "completed_at": "2026-02-21T09:30:00Z"
  }
}
Tip: Verifica siempre la autenticidad del webhook comprobando el header X-GestorForms-Signature que contiene un HMAC-SHA256 del body.

¿Necesitas ayuda con la integración?

Nuestro equipo de soporte técnico te ayuda a integrar la API de GestorForms en tu aplicación. Los clientes Enterprise tienen acceso a soporte dedicado.

Obtener API KeyContactar soporte API