Documentación API

API de Embed / Iframe

La API de Embed permite integrar el visor de extracciones de Docmind directamente en tu aplicación mediante un iframe seguro con tokens temporales.

Flujo de integración

  1. Crea un token de embed con los permisos deseados (POST /api/embed/token/create)
  2. Usa la URL del iframe devuelta (/api/embed/view?token=...)
  3. Escucha eventos postMessage del iframe para sincronizar tu aplicación

POST /api/embed/token/create

Crea un token de acceso temporal para visualizar una extracción en un iframe. Requiere JWT o API Key.

POST /api/embed/token/create

Headers

Content-Type: application/json
Authorization: Bearer JWT_TOKEN  (o x-api-key: TU_API_KEY)

Body (JSON)

{
  "extraction_id": "b67162ac-8a79-4dc0-9bb5-87c245e4f779",
  "permissions": {
    "can_edit": true,
    "can_download": true,
    "can_change_status": true
  },
  "expires_in_hours": 24,
  "allowed_origins": ["https://mi-aplicacion.com"]
}
  • extraction_id: (obligatorio) ID de la extracción a visualizar.
  • permissions: (opcional) Permisos del token: can_edit, can_download, can_change_status.
  • expires_in_hours: (opcional) Horas de validez. Por defecto: 24.
  • allowed_origins: (opcional) Lista de orígenes permitidos para el iframe.

Ejemplos

curl -X POST https://api-docmind.devol.es/api/embed/token/create \
  -H "Content-Type: application/json" \
  -H "x-api-key: TU_API_KEY" \
  -d '{
    "extraction_id": "b67162ac-8a79-4dc0-9bb5-87c245e4f779",
    "permissions": {"can_edit": true, "can_download": true, "can_change_status": true},
    "expires_in_hours": 24
  }'

Respuesta exitosa

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "embed_url": "https://api-docmind.devol.es/api/embed/view?token=eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2025-07-25T15:30:00Z",
  "permissions": {
    "can_edit": true,
    "can_download": true,
    "can_change_status": true
  }
}

Devuelve el token y la URL completa para usar en el iframe.

Respuestas de error

400 Bad Request

Falta extraction_id o datos inválidos.

{"error": "extraction_id es obligatorio"}
401 Unauthorized

Token JWT o API Key inválida.

{"error": "No autorizado"}
404 Not Found

Extracción no encontrada.

{"error": "Extracción no encontrada"}
500 Internal Server Error

Error al crear el token.

{"error": "Error interno del servidor"}

POST /api/embed/token/{token_id}/invalidate

Invalida un token de embed existente para revocar el acceso.

POST /api/embed/token/{token_id}/invalidate

Headers

Authorization: Bearer JWT_TOKEN  (o x-api-key: TU_API_KEY)

Ejemplos

curl -X POST https://api-docmind.devol.es/api/embed/token/TOKEN_ID/invalidate \
  -H "x-api-key: TU_API_KEY"

Respuesta exitosa

{"message": "Token invalidado exitosamente"}

El token queda inmediatamente inválido y no se puede usar más.

Respuestas de error

401 Unauthorized

No autorizado.

{"error": "No autorizado"}
404 Not Found

Token no encontrado.

{"error": "Token no encontrado"}

GET /api/embed/tokens/{extraction_id}

Lista todos los tokens de embed activos para una extracción específica.

GET /api/embed/tokens/{extraction_id}

Headers

Authorization: Bearer JWT_TOKEN  (o x-api-key: TU_API_KEY)

Ejemplos

curl -X GET https://api-docmind.devol.es/api/embed/tokens/EXTRACTION_ID \
  -H "x-api-key: TU_API_KEY"

Respuesta exitosa

{
  "tokens": [
    {
      "id": "token-uuid-1",
      "created_at": "2025-07-24T15:30:00Z",
      "expires_at": "2025-07-25T15:30:00Z",
      "is_active": true,
      "permissions": {"can_edit": true, "can_download": true, "can_change_status": true}
    }
  ],
  "count": 1
}

Lista de tokens activos con sus permisos y fechas de expiración.

Respuestas de error

401 Unauthorized

No autorizado.

{"error": "No autorizado"}
404 Not Found

Extracción no encontrada.

{"error": "Extracción no encontrada"}

GET /api/embed/view

Renderiza la vista HTML del iframe para visualizar la extracción. Se accede directamente desde el navegador.

GET /api/embed/view

Query Parameters

  • token: (obligatorio) Token de embed válido obtenido con POST /api/embed/token/create

Ejemplos

Devuelve una página HTML completa con el visor de la extracción. No es una respuesta JSON.

Respuestas de error

401 Unauthorized

Token inválido o expirado.

Página HTML de error
404 Not Found

Extracción no encontrada.

Página HTML de error

GET /api/embed/data

Obtiene los datos de la extracción en formato JSON para uso dentro del iframe.

GET /api/embed/data

Query Parameters

  • token: (obligatorio) Token de embed válido

Ejemplos

curl -X GET "https://api-docmind.devol.es/api/embed/data?token=TU_EMBED_TOKEN"

Respuesta exitosa

{
  "extraction": {
    "id": "b67162ac-...",
    "origin_name": "factura.pdf",
    "status": "completado",
    "fields": [...]
  },
  "permissions": {
    "can_edit": true,
    "can_download": true,
    "can_change_status": true
  }
}

Datos de la extracción y permisos del token.

Respuestas de error

401 Unauthorized

Token inválido o expirado.

{"error": "Token inválido o expirado"}

POST /api/embed/action

Ejecuta una acción dentro del iframe (editar campo, cambiar status, descargar).

POST /api/embed/action

Headers

Content-Type: application/json

Body (JSON)

{
  "token": "TU_EMBED_TOKEN",
  "action": "update_field",
  "data": {
    "field_id": "field-uuid-123",
    "value": "nuevo valor"
  }
}
  • token: (obligatorio) Token de embed válido.
  • action: (obligatorio) Acción: "update_field", "change_status", "download".
  • data: (obligatorio) Datos de la acción (varía según la acción).

Ejemplos

curl -X POST https://api-docmind.devol.es/api/embed/action \
  -H "Content-Type: application/json" \
  -d '{
    "token": "TU_EMBED_TOKEN",
    "action": "update_field",
    "data": {"field_id": "field-uuid-123", "value": "nuevo valor"}
  }'

Respuesta exitosa

{"message": "Acción ejecutada exitosamente", "result": {...}}

Resultado de la acción ejecutada.

Respuestas de error

400 Bad Request

Acción inválida o datos faltantes.

{"error": "Acción no válida"}
401 Unauthorized

Token inválido o sin permisos.

{"error": "No tienes permisos para esta acción"}
403 Forbidden

El token no tiene permisos para esta acción.

{"error": "Permiso can_edit no habilitado"}

Eventos postMessage

El iframe envía eventos a la ventana padre mediante window.postMessage. Escúchalos para sincronizar tu aplicación:

window.addEventListener("message", (event) => {
  if (event.origin !== "https://api-docmind.devol.es") return;
  
  const { type, data } = event.data;
  
  switch (type) {
    case "docmind:field_updated":
      console.log("Campo actualizado:", data.field_id, data.value);
      break;
    case "docmind:status_changed":
      console.log("Status cambiado a:", data.status);
      break;
    case "docmind:download_requested":
      console.log("Descarga solicitada");
      break;
    case "docmind:ready":
      console.log("Iframe cargado y listo");
      break;
  }
});

Tipos de evento

  • docmind:ready — El iframe se cargó correctamente
  • docmind:field_updated — Un campo fue editado (data: field_id, value)
  • docmind:status_changed — El status de la extracción cambió (data: status)
  • docmind:download_requested — El usuario solicitó descargar el documento
  • docmind:error — Ocurrió un error (data: message)

© 2025 Devol. Todos los derechos reservados.