ISFactura

Eventos de un documento

Historial de eventos DIAN reportados sobre una factura, a partir de su CUFE.

GET /api/documento/{uuid}/eventos

Es la ruta de la función, y no cambia entre ambientes. La URL base con la que la ejecutas aquí es la del sandbox. Es la URL del sandbox y no corresponde a la etapa productiva de la integración. La URL base de producción se te entrega al adquirir el servicio.
¿Es tu primer contacto con esta parte de la plataforma? Empieza por Consultas generales, donde se explica qué documentos existen, cómo se arma el JSON y qué valida el servidor antes de que ejecutes nada.

Entrega los eventos que se han reportado sobre una factura electrónica: acuse de recibo, reclamo, recibo del bien o servicio, aceptación expresa y aceptación tácita. Con ellos se reconstruye el estado del documento en el ciclo de vida que define la DIAN.

Los eventos llegan convertidos a documentos de evento (TDocumentoDE), de modo que la integración los recibe con la misma estructura con la que los emite y no tiene que interpretar el XML de la DIAN.

Es la consulta que determina si una factura ya es título valor: lo es cuando existen el recibo del bien o servicio (032) y la aceptación, expresa (033) o tácita (034).

Cómo resuelve el sandbox esta función

Consultas a la DIAN

Las consultas comparten la misma forma: los datos van en la ruta, no llevan cuerpo y no gastan consecutivos ni dejan nada reportado en la DIAN. Por eso son las funciones con las que conviene empezar: se pueden repetir tantas veces como haga falta. La consulta se resuelve ante la DIAN, y si hay registro responde 200 con los datos encontrados. Si no hay registro también responde 200, con los mismos campos vacíos: la ausencia de resultado también es un resultado, y una integración que espere un 404 para decidir «no encontrado» no lo va a recibir nunca. **La consulta del XML de un documento es la excepción**: esa sí responde 404, y tiene su propio diagrama.

Consultas a la DIANLas consultas comparten la misma forma: los datos van en la ruta, no llevan cuerpo y no gastan consecutivos ni dejan nada reportado en la DIAN. Por eso son las funciones con las que conviene empezar: se pueden repetir tantas veces como haga falta. La consulta se resuelve ante la DIAN, y si hay registro responde 200 con los datos encontrados. Si no hay registro también responde 200, con los mismos campos vacíos: la ausencia de resultado también es un resultado, y una integración que espere un 404 para decidir «no encontrado» no lo va a recibir nunca. **La consulta del XML de un documento es la excepción**: esa sí responde 404, y tiene su propio diagrama.SÍNOLa consulta llega con susdatos en la rutaConsultaante la DIAN¿Hay registro?200Los datos encontrados200Los mismos campos,vacíosLEYENDAInicio y finPasoDecisión

Desliza el diagrama para verlo completo.

Ver la fuente Mermaid del diagrama 
flowchart TD
    A(["La consulta llega con sus datos en la ruta"]) --> B["Consulta ante la DIAN"]
    B --> C{"¿Hay registro?"}
    C -- Sí --> D(["200 · los datos encontrados"])
    C -- No --> E(["200 · los mismos campos, vacíos"])

Datos que recibe

Encabezado

DatoTipoDescripción
Authorization*string

Credencial de la petición, con el prefijo Bearer. En el sandbox la pone el portal por ti y la renueva antes de cada ejecución; en producción la controlas tú, con el JWT que genera tu integración a partir de sus credenciales — ver Credenciales y JWT.

Ejemplo:Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6...

Ruta

DatoTipoDescripción
uuid*string

CUFE de la factura sobre la que se consultan los eventos. Escribe el de tu propia factura, o carga una de las de habilitación que trae el portal: son facturas con eventos ya reportados, de modo que la respuesta llega con contenido en lugar de una lista vacía.

Ejemplo:3b101716f4fa0334bc3c9c12946d5989bd4ac2f2e4c2f301a5a84cab0cf7c47e33bfef68a6b3aaf3460e00e941c95f60

Ver los 2 ejemplos
  • 3b101716f4fa0334bc3c9c12946d5989bd4ac2f2e4c2f301a5a84cab0cf7c47e33bfef68a6b3aaf3460e00e941c95f60 · 01 · Factura electrónica de venta · Ejemplo 1
  • 744f70314fdf7288027ad5999415d2a68ca9edf6f3473216580005d05c6b06f3555889977706ba5f224980dd97360ef8 · 01 · Factura electrónica de venta · Ejemplo 2

 Lo que el sandbox fuerza

El sandbox resuelve toda consulta contra el ambiente de habilitación de la DIAN, de modo que solo ve lo que existe ahí. Lo que envíes en estos campos se recibe pero no se aplica: la ruta los declara para que la URL que integres hoy sea la misma de producción.

  • tdambiente
    2 — Pruebas (habilitación)

    El sandbox solo consulta el ambiente de habilitación, de modo que solo ve lo que existe ahí. El parámetro está en la ruta para que la URL que se integre hoy sea la misma de producción, pero aquí se recibe y no se aplica.

Ejecutar la función

Ambiente de habilitación de la DIAN · la consulta no modifica nada ni gasta consecutivos

 Lo que se envía

 Datos de la ruta
Obligatorio · escribe el tuyo o carga uno de los 2 documentos de habilitación

El detalle de cada dato, con sus valores admitidos, está en Datos que recibe.

Se enviara GET https://proveedortecnologico-sandbox.azurewebsites.net/api/documento/3b101716f4fa0334bc3c9c12946d5989bd4ac2f2e4c2f301a5a84cab0cf7c47e33bfef68a6b3aaf3460e00e941c95f60/eventos

Es la URL del sandbox y no corresponde a la etapa productiva de la integración. La URL base de producción se te entrega al adquirir el servicio. Lo que si es igual en los dos es la ruta.

 Respuesta

Aquí queda tu ejecución: la ruta que viajó, el cuerpo que enviaste, el código con el que respondió el sandbox y el tiempo discriminado. Un error también queda: es lo que se necesita junto al cuerpo que lo produjo.

 Exportar a Postman

Descarga esta función como colección de Postman, con los valores que tienes ahora en la barra y tu credencial vigente: se importa y se envía sin configurar nada.

Respuestas

  • 200 Entrega en respuesta.datos el arreglo de eventos, cada uno con su tdevento, ntdevento, fechadocumento y el tercero que lo reporto.
  • 400 No se envió el CUFE en la ruta.
  • 401 La credencial no llegó, ya venció, o la cuenta no tiene perfil registrado en el sandbox. En producción es además el código con el que se rechaza un emisor que la credencial no tiene autorizado — ver Credenciales y JWT.
  • 500 La DIAN no respondió la consulta.

Errores frecuentes

  • 400 Parámetro CUFE

    La ruta llego sin el UUID. Ocurre al construir la URL con un CUFE vacío.

  • 200 Arreglo vacío

    El documento no tiene eventos reportados, o el CUFE no existe en habilitación. Lo primero es lo normal en una factura recién emitida.

Ten en cuenta

  • En el sandbox la consulta solo ve documentos de habilitación: el CUFE de una factura de producción no devuelve nada. Lo natural es consultar el CUFE de una factura emitida antes desde el propio portal.
  • En producción la ruta lleva un {tdambiente?} al final —/api/documento/{uuid}/eventos/{tdambiente?}— con el que se decide contra qué ambiente se pregunta.