Integración para desarrolladores

Puedes incrustar DocuGuest directamente en tu propia aplicación web con una sola etiqueta <script>. El escáner se ejecuta dentro de un iframe en tu página y notifica a tu código mediante un callback de JavaScript cada vez que se escanea un documento.

Esta página cubre el script de integración. Si necesitas una integración servidor a servidor o un conector específico para tu plataforma, contacta con nosotros.

Inicio rápido

Añade el script en cualquier página donde quieras que aparezca el escáner, sustituyendo ACTIVATION_CODE por el código de integración de tu panel de DocuGuest:

<script src="https://docuguest.com/docuguest.js" data-code="ACTIVATION_CODE"></script>
<script>
document.addEventListener('DOMContentLoaded', function () {
    DocuGuest.start(function (type, result) {
        console.log('DocuGuest event:', type, result);
    });
});
</script>

Eso es todo. Cuando se llama a DocuGuest.start(), el escáner se carga en un iframe colocado donde estaba la etiqueta <script>. Cada evento del escáner (cámara lista, escaneo completado, errores, etc.) llega a tu callback.

Cómo funciona

Cuando se carga la página, el script de integración:

Crea un <iframe> junto a la etiqueta <script> (anchura completa, 80vh de alto, con permiso de cámara).
Espera a que llames a DocuGuest.start().
Carga el escáner dentro del iframe usando tu código de activación.
Reenvía cada mensaje del escáner a tu callback.

Puedes llamar a start y stop tantas veces como necesites, por ejemplo para abrir y cerrar el escáner según las acciones del usuario.

Referencia de la API

El script expone un objeto global DocuGuest con dos métodos.

`DocuGuest.start(callback, data)`

Abre el escáner dentro del iframe incrustado.

Parámetro	Tipo	Descripción
`callback`	`Function`	Obligatorio. Recibe `(type, payload)` en cada evento del escáner.
`data`	`Object`	Opcional. Objeto de contexto que se reenvía al escáner (ID de reserva, huésped, etc.).

DocuGuest.start(function (type, result) {
    if (type === 'scan') {
        console.log('Document scanned:', result);
    }
}, {
    booking_id: '123',
    guest_name: 'John Doe',
});

El objeto data se envía al escáner en cuanto este señala que está listo, y se adjunta a cada escaneo guardado en el backend de DocuGuest, así puedes correlacionar los escaneos con reservas o clientes en tu sistema.

`DocuGuest.stop()`

Detiene el escáner y limpia el iframe (src se restablece a about:blank). Úsalo cuando el usuario cierre un modal o cambie de página.

DocuGuest.stop();

Eventos del callback

Tu callback recibe dos argumentos: un type (cadena) y un payload (objeto). Se emiten tres tipos de eventos:

`scan_result`

Se dispara cada vez que se procesa un documento, tanto si la lectura tiene éxito como si no. Es el evento principal: gestiónalo para recibir los datos del documento.

DocuGuest.start(function (type, payload) {
    if (type === 'scan_result') {
        if (payload.success) {
            console.log('Document data:', payload.data);
        } else {
            console.warn('Scan failed validation');
        }
    }
});

Payload:

Campo	Tipo	Descripción
`success`	`boolean`	`true` si el documento se leyó y parseó correctamente, `false` si la validación de OCR/MRZ falló.
`data`	`object`	Campos del documento extraídos (nombre, número de documento, fecha de nacimiento, nacionalidad, caducidad, etc.).
`ocrText`	`string`	Texto OCR en bruto extraído de la imagen. Útil para depurar.
`sent`	`boolean`	Indica si los datos ya se enviaron a tu integración. Aquí siempre `false`.

`scan_sent`

Se dispara después de que un escaneo correcto se envía a tu integración servidor a servidor. Solo se emite cuando hay una integración configurada para el código de activación y el envío fue correcto. Úsalo para confirmar la entrega de extremo a extremo, no solo una lectura correcta.

DocuGuest.start(function (type, payload) {
    if (type === 'scan_sent') {
        console.log('Scan delivered to backend');
    }
});

Payload: misma forma que scan_result, con sent: true.

`error`

Se dispara cuando un intento de escaneo falla antes de producir un resultado (error de red, fallo al subir la imagen, error del servidor, etc.). Es distinto de un scan_result con success: false, que significa que el escaneo se ejecutó pero el documento no se pudo parsear.

DocuGuest.start(function (type, payload) {
    if (type === 'error') {
        console.error('Scan error:', payload.message);
    }
});

Payload:

Campo	Tipo	Descripción
`message`	`string`	Descripción del error en formato legible.

Referencia rápida

Evento	Cuándo	Payload
`scan_result`	Un escaneo se completa (correcto o con fallo de parseo)	`{success, data, ocrText, sent}`
`scan_sent`	Un escaneo correcto se reenvió a tu integración	`{success, data, ocrText, sent}`
`error`	Un intento de escaneo falló antes de producir un resultado	`{message}`

Durante el desarrollo, registra cada evento para inspeccionar la forma exacta del payload:
DocuGuest.start(function (type, payload) {
  console.log('[DocuGuest]', type, payload);
});

Patrones de incrustación

En línea (por defecto)

El iframe se inserta en el lugar donde está la etiqueta <script>. Es la forma más sencilla: coloca el script dentro de un contenedor y el escáner aparece allí.

<div id="scanner-container">
    <script src="https://docuguest.com/docuguest.js" data-code="ACTIVATION_CODE"></script>
</div>
<script>
    DocuGuest.start(function (type, result) { /* ... */ });
</script>

En un modal

Si prefieres mantener la página limpia y mostrar el escáner solo bajo demanda, coloca el script dentro de un modal oculto y llama a start al abrirlo y a stop al cerrarlo.

<button onclick="openScanner()">Scan document</button>

<div id="scanner-modal" style="display:none">
    <button onclick="closeScanner()">Close</button>
    <script src="https://docuguest.com/docuguest.js" data-code="ACTIVATION_CODE"></script>
</div>

<script>
    function openScanner() {
        document.getElementById('scanner-modal').style.display = 'block';
        DocuGuest.start(function (type, result) {
            if (type === 'scan') closeScanner();
        });
    }
    function closeScanner() {
        DocuGuest.stop();
        document.getElementById('scanner-modal').style.display = 'none';
    }
</script>

Permisos de cámara

El iframe se crea con allow="camera", lo que permite al escáner solicitar acceso a la webcam del usuario. La primera vez, el navegador mostrará su diálogo de permiso. Para que funcione:

La página que aloja la integración debe servirse por HTTPS (los navegadores bloquean el acceso a la cámara en HTTP).
El usuario debe pulsar Allow en el diálogo de permiso.

Si trabajas en localhost para desarrollo, los navegadores lo tratan como seguro y la cámara funcionará sin HTTPS.

Código de activación

El atributo data-code identifica tu integración. Cada escaneo realizado a través de tu integración queda asociado a este código, lo que te permite:

Ver todos los escaneos de tu integración en el panel de DocuGuest.
Hacer seguimiento del uso y la facturación.
Recibir los escaneos en tu servidor por webhook (si está configurado).

No expongas tu código de activación públicamente fuera de tu propio sitio. Si se filtra, regéneralo desde el panel.

Integraciones servidor a servidor y a medida

La integración por script cubre la mayoría de los casos. Si necesitas algo distinto, una API en el servidor, un conector para un PMS o CRM concreto, despliegue en marca blanca, etc., podemos construirlo por ti.

Contacta con nosotros y cuéntanos cómo es tu setup. Te ayudaremos a encontrar la mejor forma de conectar DocuGuest con tu stack.