Eventos de Steps
Webhooks para la ejecución de pasos en flujos de procesamiento de documentos
Webhooks de Steps
Los webhooks de steps se envían durante la ejecución de pasos individuales en flujos de procesamiento de documentos. Cada step puede realizar operaciones como conversión, identificación o validación.
Eventos de Steps
Step Iniciado (STEP_STARTED)
Se envía cuando comienza la ejecución de un step:
{
"step_execution_id": "step_exec_xyz123",
"step_id": "step_convert_invoice",
"step_name": "Convertir Factura",
"status": "PROCESSING",
"request_timestamp": "2024-01-15T10:30:00.000Z",
"document_metadata": {
"batch_id": "batch_001",
"priority": "high"
}
}Campos:
step_execution_id(string): ID único de la ejecución del stepstep_id(string): ID del step en el flujostep_name(string): Nombre descriptivo del stepstatus(string): Estado actual, siempre"PROCESSING"para este eventorequest_timestamp(string): Timestamp ISO 8601 de cuando se inició el stepdocument_metadata(object, opcional): Metadatos del documento siendo procesado
Step Completado (STEP_COMPLETED)
Se envía cuando un step termina exitosamente:
{
"step_execution_id": "step_exec_xyz123",
"step_id": "step_convert_invoice",
"step_name": "Convertir Factura",
"status": "completed",
"request_timestamp": "2024-01-15T10:30:00.000Z",
"response_timestamp": "2024-01-15T10:30:12.000Z",
"document_metadata": {
"batch_id": "batch_001",
"priority": "high"
},
"data": {
"invoiceNumber": "INV-2024-001",
"amount": 1250.00,
"vendor": "Empresa ABC S.A.",
"date": "2024-01-15"
},
"identification": {
"document_type": "invoice",
"confidence": 0.95
},
"validation": {
"errors": {
"count": 0,
"messages": []
},
"warnings": {
"count": 1,
"messages": ["El monto excede el promedio histórico"]
}
}
}Campos:
step_execution_id(string): ID único de la ejecución del stepstep_id(string): ID del step en el flujostep_name(string): Nombre descriptivo del stepstatus(string): Estado actual, siempre"completed"para este eventorequest_timestamp(string): Timestamp ISO 8601 de cuando se inició el stepresponse_timestamp(string): Timestamp ISO 8601 de cuando se completó el stepdocument_metadata(object, opcional): Metadatos del documento siendo procesadodata(object, opcional): Datos procesados del documento (si el step realizó conversión)identification(object, opcional): Resultado de identificación (si el step realizó identificación)validation(object, opcional): Resultado de validación con errores y advertencias
Step Fallido (STEP_FAILED)
Se envía cuando un step falla:
{
"step_execution_id": "step_exec_xyz123",
"step_id": "step_convert_invoice",
"step_name": "Convertir Factura",
"status": "failed",
"request_timestamp": "2024-01-15T10:30:00.000Z",
"response_timestamp": "2024-01-15T10:30:08.000Z",
"document_metadata": {
"batch_id": "batch_001",
"priority": "high"
},
"error": "Validation failed: required field 'invoiceNumber' is missing"
}Campos:
step_execution_id(string): ID único de la ejecución del stepstep_id(string): ID del step en el flujostep_name(string): Nombre descriptivo del stepstatus(string): Estado actual, siempre"failed"para este eventorequest_timestamp(string): Timestamp ISO 8601 de cuando se inició el stepresponse_timestamp(string): Timestamp ISO 8601 de cuando falló el stepdocument_metadata(object, opcional): Metadatos del documento siendo procesadoerror(string): Mensaje descriptivo del error ocurrido
Ejemplo de Implementación
app.post('/webhooks/docutray', (req, res) => {
const eventType = req.headers['x-docutray-event'];
const data = JSON.parse(req.body);
switch (eventType) {
case 'STEP_STARTED':
console.log(`Step iniciado: ${data.step_name} (${data.step_execution_id})`);
// Actualizar UI con progreso del flujo
break;
case 'STEP_COMPLETED':
console.log(`Step completado: ${data.step_name} (${data.step_execution_id})`);
// Procesar datos si están disponibles
if (data.data) {
console.log('Datos procesados:', data.data);
// Guardar datos en base de datos
}
// Verificar resultados de validación
if (data.validation) {
if (data.validation.errors.count > 0) {
console.log('Errores de validación:', data.validation.errors.messages);
// Notificar errores de validación
}
if (data.validation.warnings.count > 0) {
console.log('Advertencias:', data.validation.warnings.messages);
// Registrar advertencias
}
}
break;
case 'STEP_FAILED':
console.log(`Step fallido: ${data.step_name} (${data.step_execution_id})`);
console.log('Error:', data.error);
// Detener flujo y notificar error
// Registrar fallo para análisis
break;
}
res.status(200).send('OK');
});Casos de uso
Monitoreo de flujos complejos
Los webhooks de steps son ideales para monitorear la ejecución de flujos con múltiples pasos:
// Ejemplo: Rastrear progreso de un flujo multi-paso
const flowProgress = {
stepStates: {},
totalSteps: 0,
completedSteps: 0
};
function handleStepEvent(data, eventType) {
const stepId = data.step_id;
if (eventType === 'STEP_STARTED') {
flowProgress.stepStates[stepId] = 'processing';
flowProgress.totalSteps++;
} else if (eventType === 'STEP_COMPLETED') {
flowProgress.stepStates[stepId] = 'completed';
flowProgress.completedSteps++;
} else if (eventType === 'STEP_FAILED') {
flowProgress.stepStates[stepId] = 'failed';
}
// Calcular porcentaje de progreso
const progress = (flowProgress.completedSteps / flowProgress.totalSteps) * 100;
console.log(`Progreso del flujo: ${progress}%`);
}Validación y control de calidad
Usar los resultados de validación para implementar controles de calidad:
function handleValidationResults(validation) {
// Detener procesamiento si hay errores críticos
if (validation.errors.count > 0) {
// Enviar a revisión manual
sendToManualReview(validation.errors.messages);
return;
}
// Advertencias no bloquean el flujo
if (validation.warnings.count > 0) {
// Registrar para análisis pero continuar
logWarnings(validation.warnings.messages);
}
// Continuar con siguiente paso del flujo
proceedToNextStep();
}