Todos nuestros endpoints son accesibles mediante la siguiente URL base:

La API espera el siguiente encabezado de autorización:

Todas las respuestas JSON (tanto exitosas como errores) siguen la siguiente estructura envelope:

{
  "response": { ... },                // Contenido específico del endpoint (puede ser null en errores)
  "apiVersion": "1.0",                // Versión actual de la API
  "trackingId": "uuid-del-request",   // Identificador único para seguimiento
  "timeStamp": "2025-02-23T12:34:56Z",// Fecha y hora UTC de la respuesta
  "error": false,                     // Indica si ocurrió un error
  "errorDetail": null                  // Detalle del error (solo cuando error=true)
}
                            

En caso de error, el campo errorDetail contiene:

{
  "code": 400,
  "message": "Descripción del error",
  "stackTrace": null || string
}
                            

El campo response varía según el endpoint; a continuación se detalla su contenido para cada caso.

Una vez que el procesamiento asíncrono de un documento finaliza (con estado Completed, Error o Deleted), nuestro sistema enviará automáticamente una solicitud HTTP POST a la URL que hayas configurado en el panel de administración. Esto te permite reaccionar en tiempo real al resultado sin necesidad de realizar consultas periódicas (polling).

Formato del payload enviado

{
    "ClientId": "uuid-del-cliente",
    "DocumentId": "uuid-del-documento",
    "Status": "Completed | Error | Deleted",
    "ExpiresAt": "2025-03-01T12:00:00Z",
    "StatusMessage": "Mensaje opcional (ej. error detallado)",
    "TimeStamp": "1710000000",  // Unix timestamp en segundos
    "Hash": "Base64(HMAC-SHA256 de TimeStamp con MasterKey)"
}
                            

Seguridad y autenticidad

Para garantizar que la petición realmente proviene de nuestros servidores y no de un tercero, cada webhook incluye un campo Hash. Este hash se genera aplicando HMAC-SHA256 sobre el valor del campo TimeStamp (en bytes UTF-8) utilizando la Master Key (también en bytes UTF-8) que puedes configurar en el panel. Debes calcular el hash en tu servidor y compararlo con el recibido; si coinciden, puedes confiar en que la petición es legítima.

Comportamiento esperado de tu endpoint

Tu endpoint debe responder con un código HTTP 200 OK lo antes posible para confirmar la recepción. Nosotros no procesamos el contenido de la respuesta; simplemente necesitamos saber que el mensaje llegó. Si no recibimos un 200, el sistema reintentará el envío hasta 10 veces adicionales.

Nota: El timeout de la solicitud es de 30 segundos. Asegúrate de que tu endpoint responda rápidamente para evitar reintentos innecesarios.

Ejemplo de implementación (Node.js - Express)

app.post('/webhook', (req, res) => {
    const { ClientId, DocumentId, Status, ExpiresAt, StatusMessage, TimeStamp, Hash } = req.body;

    // 1. Obtener la Master Key desde las variables de entorno
    const masterKey = process.env.WEBHOOK_MASTER_KEY;

    // 2. Convertir a bytes (UTF-8)
    const keyBytes = Buffer.from(masterKey, 'utf8');
    const timeBytes = Buffer.from(TimeStamp, 'utf8');

    // 3. Calcular HMAC-SHA256
    const hmac = crypto.createHmac('sha256', keyBytes);
    hmac.update(timeBytes);
    const computedHash = hmac.digest().toString('base64');

    // 4. Comparar ambos hashes
     if (computedHash !== Hash) {
        return res.status(401).send('Firma inválida');
    }

    // 5. Procesar según el estado (opcional)
    console.log(`Documento ${DocumentId} para cliente ${ClientId} cambió a ${Status}`);

    // 6. Responder inmediatamente
    res.status(200).send('OK');
});