Enviar nota crédito
Disminuye o anula una factura ya reportada. Devuelve su CUDE.
/api/DocumentoFE Disminuye o anula una factura ya reportada: tddocumentoelectronico en 91. Una factura que llegó a la DIAN no se modifica ni se borra — se ajusta con una nota.
La factura afectada va en docsreferencia, identificada por su CUFE, y el motivo en datosnota.tdmotivonota. Su identificador es un CUDE, no un CUFE.
Cómo resuelve el sandbox esta función
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.
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
Cuerpo
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.
tdambiente2 — 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.nitNIT de la empresa de pruebasEs el único NIT que el sandbox tiene habilitado ante la DIAN: un emisor distinto se rechaza antes de firmar el documento. El resto del emisor —razón social, tipo de persona, ubicación— viaja como lo envíes: si no corresponde al NIT habilitado, la DIAN puede rechazar el documento.
receptor.nitNIT de InSoftPor seguridad, el sandbox no permite emitir documentos 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 documento 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.
resolucionLa del sandbox — el bloque entero, siempreNo se conserva nada de la que envíes: el sandbox reemplaza el bloque completo antes de verificar el documento. La factura numera con la resolución de facturación que tiene registrada y el documento soporte con la del documento soporte; las notas crédito, débito y de ajuste no consumen resolución y reciben solo su prefijo, uno por tipo. En la generación del XML no se reemplaza nada: ahí la resolución es la que envíes.
numerodocumentoPrefijo de la resolución más el siguiente consecutivoSolo cuando llega con el valor
<auto>, que es lo que hacen los ejemplos. Cualquier otro valor viaja tal como lo escribas —y entonces respondes tú por que el consecutivo esté dentro del rango y no se repita: un número ya reportado responde409con la regla 90 de la DIAN—. No depende de la resolución que envíes, porque esa se reemplaza igual.
Ejecutar la función
Ambiente de habilitación de la DIAN · los documentos son reales pero no tienen efectos tributarios Lo que se envía
Anula por completo una factura ya emitida. Motivo `2` y referencia al CUFE original.
POST https://proveedortecnologico-sandbox.azurewebsites.net/api/DocumentoFE Respuesta
Exportar a Postman
Respuestas
-
200La DIAN recibió el documento. Enrespuestaviajan el UUID generado (CUFE o CUDS), el estado de la DIAN y sus mensajes de validación. -
400El documento no paso las validaciones del PT o de la DIAN. El mensaje indica la regla incumplida. -
401La 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. -
500Falla al firmar o al comunicarse con la DIAN.
Errores frecuentes
-
400El documento referenciado no existe en la DIANEl CUFE de
docsreferenciano corresponde a un documento reportado en ese ambiente. Una nota de habilitación solo puede referenciar facturas de habilitación. -
401El desarrollador autenticado no tiene un perfil registrado en el sandboxLa cuenta se autenticó pero nunca completó el registro de desarrollador. Se resuelve diligenciando el perfil desde el portal.
-
401Token de autenticación no válidoLa credencial del sandbox venció —dura una hora—. El portal la renueva sola; con peticiones propias hay que pedir una nueva. En producción la vigencia es la de tu JWT — ver Credenciales y JWT.
-
400El total del documento no corresponde con la suma de sus líneastotalapagarno cuadra con los items, los tributos y los descuentos. Lo más simple es omitir el campo y dejar que el PT lo calcule. -
400Regla AJ** de la DIANAlguna de las más de setenta validaciones de la DIAN sobre el documento. El mensaje trae el código de la regla; el código de municipio de la ubicación y el correo del receptor son las causas más frecuentes.
-
500El sandbox no tiene registrada la configuración SANDBOX - EMPRESAEs un problema de montaje del ambiente, no de la petición. Hay que reportarlo al equipo de InSoft.
Ten en cuenta
- En el sandbox el CUFE que se referencia debe ser el de una factura emitida antes desde el propio sandbox: es la única que existe en habilitación bajo la empresa de pruebas.
- Una nota sin referencia a factura (
tddocumentonotaen22) no llevadocsreferencia, pero la DIAN la admite solo en los casos que la norma contempla. - La ubicación, las responsabilidades fiscales, el tributo responsable, la actividad económica y el contacto del emisor y del receptor no se reemplazan: son parte del caso de prueba y viajan tal como se envien.
- Los items, los tributos, los descuentos, los anticipos, los medios de pago y los totales viajan sin modificación. Ahí es donde se prueba de verdad la integración.
- 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.