Evento documento.error

Evento documento.error de los webhooks de Facturalo: cuándo llega, qué trae el payload y cómo reaccionar cuando un comprobante enviado con webhook: true no se pudo procesar.

Facturalo envía documento.error cuando un comprobante o una guía que enviaste con webhook: true no se pudo procesar en segundo plano, ni siquiera después de todos los reintentos. Es distinto de un rechazo: aquí SUNAT no llegó a dar una respuesta.

Cuándo llega

Facturalo reintenta el envío a SUNAT antes de rendirse (hasta 10 intentos para documentos). Solo cuando se agotan llega este evento.
Las causas más comunes son que SUNAT no responde por un tiempo prolongado o que un dato de la empresa impide firmar el XML (por ejemplo, el certificado o la Clave SOL).
Si SUNAT sí respondió y rechazó el comprobante, no llega documento.error, sino documento.sunat.respuesta con sunat.estado: RECHAZADA.

Campos

Campo	Descripción
`id`	Identificador único de la entrega. Úsalo para no procesar dos veces el mismo evento.
`evento`	Siempre `documento.error`.
`timestamp`	Fecha y hora del evento (hora de Perú, UTC−5).
`entorno`	`demo` o `produccion`.
`documento`	Identifica el comprobante: `id`, `serie`, `correlativo` y `tipo`. Para guías el bloque se llama `guia` y trae solo `serie` y `correlativo`.
`error.mensaje`	Motivo del fallo, en texto legible. Guárdalo en tu sistema para revisarlo.

Payloadjson

{
  "id": "0d9f6c2e-6a1b-4f43-9a7e-3c5b8d2e1f00",
  "evento": "documento.error",
  "timestamp": "2026-06-14T10:30:00-05:00",
  "entorno": "demo",
  "documento": {
    "id": "83ad82a0-680e-11f1-8e35-2d93ac0f2c84",
    "serie": "F001",
    "correlativo": "00000001",
    "tipo": "FACTURA"
  },
  "error": {
    "mensaje": "No se pudo conectar con SUNAT."
  }
}

Qué hacer cuando llega

Marca el comprobante en tu sistema como pendiente de revisión: todavía no está aceptado por SUNAT.
Consulta su estado actual con GET /documentos/{id} y su historial con eventos del documento.
Si error.mensaje apunta a la empresa (certificado, Clave SOL o PSE), corrígelo en la consola y vuelve a enviar el comprobante.
Si fue una caída de SUNAT, vuelve a enviarlo cuando el servicio se recupere. Puedes revisar el estado de SUNAT en status.facturalo.pe.

Responde al webhook con un código 2xx en cuanto lo recibas y procesa el contenido después. Si tu servidor no responde, Facturalo reintenta la entrega hasta 5 veces. Más detalles en Webhooks.