Enviar eventos por tipo

Reporta a la DIAN un evento sobre una factura electrónica: acuse, reclamo, recibo o aceptación.

POST /api/DocumentoDE

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 Eventos de la DIAN, donde se explica qué documentos existen, cómo se arma el JSON y qué valida el servidor antes de que ejecutes nada.

Es la forma en que el receptor de una factura le reporta a la DIAN que la recibió, que la reclama o que la acepta: tddocumentoelectronico en 96. El evento no modifica la factura, la acompaña, y genera su propio CUDE.

El tipo va en tdevento y es lo único que cambia entre uno y otro: los cinco comparten estructura. El reclamo (031) es el único que exige un dato adicional, tdreclamo, con el motivo. Qué es cada evento, en qué orden los espera la DIAN y por qué convierten la factura en título valor está en el concepto del grupo.

Cómo resuelve el sandbox esta función

Emisión de un documento a la DIAN

Lo primero que se mira es la numeración del documento. Si nunca se reportó, el documento sigue el proceso completo. Si ya se reportó, se compara con el que está guardado: llegando igual responde 200 con el estado del documento, su UUID y el documento adjunto, sin volver a reportarlo ni gastar otro consecutivo; llegando con datos distintos responde 409 con la regla 90 de la DIAN y entrega el XML del documento que sí quedó reportado. Para el documento nuevo siguen las validaciones: un incumplimiento responde 400 con una entrada por regla, cada una con su código de la DIAN, su código de InSoft y su mensaje. Solo cuando las pasa se construye el documento electrónico, se firma, se reporta a la DIAN y se espera su respuesta. Si la DIAN lo rechaza, el 400 trae sus mensajes; si no se pudo establecer conexión con ella, responde también 400 pidiendo reintentar más tarde, y en ese caso el documento no quedó reportado. Las validaciones van antes de construir, así que un documento que no va a ser aceptado se rechaza sin gastar un consecutivo.

Emisión de un documento a la DIANLo primero que se mira es la numeración del documento. Si nunca se reportó, el documento sigue el proceso completo. Si ya se reportó, se compara con el que está guardado: llegando igual responde 200 con el estado del documento, su UUID y el documento adjunto, sin volver a reportarlo ni gastar otro consecutivo; llegando con datos distintos responde 409 con la regla 90 de la DIAN y entrega el XML del documento que sí quedó reportado. Para el documento nuevo siguen las validaciones: un incumplimiento responde 400 con una entrada por regla, cada una con su código de la DIAN, su código de InSoft y su mensaje. Solo cuando las pasa se construye el documento electrónico, se firma, se reporta a la DIAN y se espera su respuesta. Si la DIAN lo rechaza, el 400 trae sus mensajes; si no se pudo establecer conexión con ella, responde también 400 pidiendo reintentar más tarde, y en ese caso el documento no quedó reportado. Las validaciones van antes de construir, así que un documento que no va a ser aceptado se rechaza sin gastar un consecutivo.SÍNOSÍNONOSÍNOSÍEl documento llega en JSON¿Ya se reportó esanumeración?¿Llega igualque antes?¿Cumple las reglas?200Estado, UUID y documentoadjunto, sin volvera reportarlo409Regla 90 · entrega el XMLdel documentoConstruye el documentoy lo firma, lo reportay espera a la DIAN400Una entrada por reglaincumplida, con su códigoDIAN y su código InSoft¿La DIAN lo aceptó?400El rechazo de la DIAN, o«intente más tarde» sino hubo conexión200Estado del documento, su UUIDy el documento adjuntoLEYENDAInicio y finPasoDecisiónError

Desliza el diagrama para verlo completo.

Ver la fuente Mermaid del diagrama
flowchart TD
    A(["El documento llega en JSON"]) --> B{"¿Ya se reportó esa numeración?"}
    B -- Sí --> G{"¿Llega igual que antes?"}
    G -- Sí --> R0(["200 · estado, UUID y documento adjunto,<br/>sin volver a reportarlo"])
    G -- No --> R1(["409 · regla 90, entrega el XML del documento"])
    B -- No --> C{"¿Cumple las reglas?"}
    C -- No --> R2(["400 · una entrada por regla incumplida,<br/>con su código DIAN y su código InSoft"])
    C -- Sí --> D["Construye el documento y lo firma,<br/>lo reporta y espera a la DIAN"]
    D --> E{"¿La DIAN lo aceptó?"}
    E -- No --> R3(["400 · el rechazo de la DIAN, o «intente más tarde»<br/>si no hubo conexión"])
    E -- Sí --> H(["200 · estado del documento, su UUID<br/>y el documento adjunto"])

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...

Cuerpo

DatoTipoDescripción
tddocumentoelectronicostring

Siempre 96 (Eventos). El sandbox lo fuerza, de modo que no hace falta enviarlo.

Ejemplo:96

tdevento*string

Evento que se reporta sobre el documento referenciado.

Ver los 5 valores admitidos
  • 030 · Acuse de recibo de la factura electrónica de venta
  • 031 · Reclamo de la factura electrónica de venta
  • 032 · Recibo del bien o prestación del servicio
  • 033 · Aceptación expresa
  • 034 · Aceptación tácita
tdreclamostring

Motivo del reclamo. Obligatorio cuando tdevento es 031; se omite en el resto.

Ver los 4 valores admitidos
  • 01 · Documento con inconsistencias
  • 02 · Mercancía no entregada
  • 03 · Mercancía entregada parcialmente
  • 04 · Servicio no prestado
numerodocumento*string

Consecutivo del evento dentro de la numeración propia del emisor del evento. No requiere resolución.

Ejemplo:1

fechadocumentodate-time

Fecha y hora en que ocurre el evento. Es opcional: si no la envías, el PT le asigna la de ahora, el momento en que recibe el documento, y es lo que hacen los ejemplos. Si la envías, va en ISO 8601 con zona (2026-08-07T08:00:00-05:00) y no puede ser anterior a la de la factura.

Ejemplo:2026-08-07T08:00:00-05:00

docreferencia*TDocumentoElectronico

Factura sobre la que aplica el evento.

docreferencia.uuid*string

CUFE de la factura. Es el dato con el que la DIAN localiza el documento afectado.

docreferencia.numerodocumento*string

Número de la factura afectada, tal como se emitió.

emisor*TTercero

Quien emite el evento — normalmente el receptor de la factura. En el sandbox su identidad se reemplaza por la de la empresa de pruebas.

receptor*TTercero

Quien recibe el evento — normalmente el emisor de la factura. Mismo tratamiento en el sandbox.

usuario*TUsuario

Persona natural que suscribe el evento, con su tipo y número de documento, nombres, apellidos, cargo y departamento.

usuario.tddocumento*number

Tipo de identificación de quien suscribe.

Ver los 4 valores admitidos
  • 13 · Cedula de ciudadanía
  • 22 · Cedula de extranjería
  • 31 · NIT
  • 41 · Pasaporte
notasArray<string>

Observaciones libres. En el reclamo es donde se detalla la inconsistencia.

Lo que el sandbox fuerza

El sandbox emite con una integración y una empresa de pruebas compartidas por todos los desarrolladores. Lo que envíes en estos campos no se usa: se sustituye antes de reportar el documento a la DIAN. Todo lo demás viaja tal como lo dejes.

  • tddocumentoelectronico
    96 — Eventos

    Todo lo que entra por este endpoint es un ApplicationResponse: el sandbox lo fija para que no dependa de que el documento lo traiga.

  • tdambiente
    2 — Pruebas (habilitación)

    El sandbox solo emite contra el ambiente de habilitación de la DIAN, sin importar lo que llegue en el documento.

  • emisor.nit
    NIT de la empresa de pruebas

    Es el único NIT que el sandbox tiene habilitado ante la DIAN. El resto del emisor viaja como lo envíes.

  • receptor.nit
    NIT de InSoft

    Por seguridad, el sandbox no permite reportar eventos a un tercero distinto de InSoft: el receptor se impone siempre, sin importar el que envíes. Así ninguna prueba puede reportar a la DIAN un evento a nombre de alguien que no la autorizó. Es también el NIT que el catálogo de la DIAN te pide para buscar el documento.

Ejecutar la función

Ambiente de habilitación de la DIAN · los documentos son reales pero no tienen efectos tributarios

Antes de ejecutar esta función hace falta una factura sobre la que reportar. El uuid de docreferencia es el CUFE de una factura que exista en habilitación, y ahí solo existen las emitidas desde el propio sandbox. El orden es enviar una factura electrónica, tomar el uuid que traiga su respuesta y pegarlo aquí. Y ojo con repetir: la DIAN no admite dos veces el mismo evento sobre la misma factura, de modo que cada envío que salga mal quema esa factura para ese evento — para ensayar sin gastarla está generar el XML sin reportarlo.

Lo que se envía

Caso base del acuse de recibo, con todos los datos diligenciados. Por aquí conviene empezar.

Documento que se envía — editalo para armar tu caso de prueba
Se enviara POST https://proveedortecnologico-sandbox.azurewebsites.net/api/DocumentoDE

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 La DIAN recibió el evento. En respuesta viajan el CUDE generado, el estado de la DIAN y sus mensajes de validación.
  • 400 El evento no paso las validaciones del PT o de la DIAN. El mensaje indica la regla incumplida.
  • 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 Falla al firmar o al comunicarse con la DIAN.

Errores frecuentes

  • 400 El documento referenciado no existe en la DIAN

    El CUFE de docreferencia no corresponde a una factura reportada en ese ambiente. En el sandbox debe ser el de una factura emitida antes desde el propio sandbox.

  • 400 El evento ya fue reportado para el documento

    La DIAN no admite dos veces el mismo evento sobre la misma factura. Para repetir la prueba hay que emitir una factura nueva.

  • 400 El motivo del reclamo es obligatorio

    Se envió tdevento en 031 sin tdreclamo.

  • 401 El desarrollador autenticado no tiene un perfil registrado en el sandbox

    La cuenta se autenticó pero nunca completó el registro de desarrollador. Se resuelve diligenciando el perfil desde el portal.

Ten en cuenta

  • El usuario que suscribe el evento es una persona natural, no la empresa: es quien firma que recibió o que aceptó, y va con su tipo y número de documento, sus nombres y su cargo.
  • El evento 034 (aceptación tácita) lo genera la DIAN de forma automática cuando pasan tres días hábiles sin reclamo. Se puede reportar de forma explícita, pero no es lo habitual.
  • El sandbox reporta cada evento de forma individual, sin set de prueba, igual que los documentos.
  • Para consultar los eventos que ya tiene una factura está la función Eventos de un documento, que no está expuesta en el sandbox.
  • El sandbox emite con una integración compartida por todos los desarrolladores. El token con el que se reporta a la DIAN lo abre el propio servicio y nunca sale hacia el navegador.