--- title: "Endpoint para emitir un documento soporte electrónico a la DIAN" method: POST path: "/support-documents" tags: ["Documentos Soporte Electrónicos"] --- # Endpoint para emitir un documento soporte electrónico a la DIAN `POST /support-documents` ## Request - Base URL: `https://sandbox-api.alegra.com/e-provider/col/v1` - URL: `https://sandbox-api.alegra.com/e-provider/col/v1/support-documents` - Auth: HTTP bearer Este endpoint permite emitir un documento soporte electrónico a la DIAN. Recuerda visitar previamente las guías de [Inicio](https://e-provider-docs.alegra.com/docs/gu%C3%ADa-creaci%C3%B3n-de-una-compa%C3%B1%C3%ADa-asociada) y la guía de [Habilitación en la DIAN - Documento Soporte Electrónico](https://e-provider-docs.alegra.com/docs/gu%C3%ADa-del-proceso-de-habilitaci%C3%B3n-en-la-dian-documento-soporte-electr%C3%B3nico) ## Parameters - `#/paths/~1events/post/parameters/0` (unresolved $ref) ## Request body - object - `documentCurrency` object: La divisa aplicable al documento soporte debe enviarse a través de este objeto. Si no se incluye, se utilizará COP (Peso Colombiano) como moneda predeterminada. - `code` string, required: Código de moneda de la transacción. Ver el listado disponible en la tabla DIAN - Monedas (`currencies`) Esta moneda se aplica a todo el documento.
Campo oficial DIAN <@currencyID> - `rateValue` number, float, required: Valor de la tasa de cambio de la moneda utilizada en el documento en el campo 'currencyCode' a Pesos Colombianos.
Campo oficial DIAN <CalculationRate> - `rateDate` string, date, required: Fecha en la que se fijó o acordó la tasa de cambio.
Campo oficial DIAN <Date> - `issueDate` string, date: Fecha de generación del documento soporte en adquisiciones efectuadas a sujetos no obligados a expedir factura o documento equivalente. Campo oficial DIAN <IssueDate> - `number` number, double, required: Número del documento soporte electrónico - `resolution` object, required: Objeto que contiene la información de la resolución asociada al emisor del documento soporte electrónica en formato JSON según el estándar de la DIAN.
Grupo de información oficial DIAN <InvoiceControl> - `resolutionNumber` string, required: Número de Resolución o de Autorización: Número del código de la resolución otorgada para la numeración.
Campo oficial DIAN <InvoiceAuthorization> - `prefix` string: Prefijo de la Resolución o Autorización.
Campo oficial DIAN <Prefix> - `minNumber` number, required: Valor inicial del rango de numeración.
Campo oficial DIAN <From> - `maxNumber` number, required: Valor final del rango de numeración.
Campo oficial DIAN <To> - `startDate` string, date, required: Fecha de inicio de la autorización de la numeración.
Campo oficial DIAN <StartDate> - `endDate` string, date, required: Fecha final de la autorización de la numeración.
Campo oficial DIAN <EndDate> - `company` object, required: Objeto que contiene la información del obligado a facturar o emisor del documento electrónico.
Grupo de información oficial DIAN <AccountingSupplierParty> - `id` string, required: Id de la empresa. Id único generado por la API - `organizationType` 1 | 2: Identificador de tipo de organización jurídica de la persona o empresa. Se debe colocar el Código que corresponda de la tabla de tipos de organización jurídica de la DIAN.
Campo oficial DIAN <AdditionalAccountID> - `identificationNumber` string: Número de identificación o NIT del emisor, sin guiones ni DV.
Campo oficial DIAN <CompanyID> - `dv` string: DV del NIT del emisor. Es obligatorio si identificationType = 31.
Campo oficial DIAN <@schemeID> - `name` string: Nombre (Razón Social) del Emisor. Si no se envía, se tomará el Nombre/Razón Social de la compañía.
Campo oficial DIAN <RegistrationName> - `regimeCode` string: Régimen o tipo de obligación o responsabilidad del emisor. Se debe colocar el Código que corresponda de la tabla de tipos de régimen/responsabilidades fiscales de la DIAN. Para reportar varias obligaciones / responsabilidades, se deben reportar separando cada uno de los valores de la lista con ';'. Ejemplo O‐13;O‐15;
Campo oficial DIAN <TaxLevelCode> - `taxCode` object, required: Objeto que contiene el grupo de detalles tributarios del Emisor.
Campo oficial DIAN <TaxScheme> - `id` '01' | 'ZZ', required: Identificador del tributo. Se debe colocar el Código que corresponda de la tabla de tipos de tributos de la DIAN.
Campo oficial DIAN <ID> - `supplier` object, required: Objeto que contiene la información del proveedor del documento electrónico - `name` string, required: Nombre del proveedor - `origin` '10' | '11': Indicador de procedencia del vendedor (Residente fiscal en Colombia [`10`] o No residente fiscal [`11`]). Se debe colocar el Código que corresponda de la tabla de tipos de procedencia del vendedor de la DIAN - `organizationType` 1 | 2, required: Tipo de organización jurídica. Se debe colocar el Código que corresponda de la tabla de tipos de organización jurídica de la DIAN - `identificationType` '21' | '22' | '31' | '41' | '42' | '47' | '50', required: Tipo de documento de identificación del proveedor. Se debe colocar el Código que corresponda de la tabla de tipos de identificación de la DIAN - `identificationNumber` string, required: Número de indentificación del proveedor - `dv` string: DV del NIT del proveedor. Es obligatorio si identificationType = 31 - `regimeCode` string: Régimen al que pertenece el proveedor. Se debe colocar el Código que corresponda de la tabla de tipos de régimen/responsabilidades fiscales de la DIAN. Para reportar varias obligaciones / responsabilidades, se deben reportar separando cada uno de los valores de la lista con ';'. Ejemplo O‐13;O‐15; - `taxCode` '01' | 'ZZ': Identificador del tributo. Se debe colocar el Código que corresponda de la tabla de tipos de tributos de la DIAN. Valores posibles: `ZZ`: 'No Aplica'(Valor default), `01`: IVA.
Campo oficial DIAN <TaxScheme> - `address` object, required: Objeto que contiene la información relacionada a la dirección.
Grupo de información oficial DIAN <RegistrationAddress | PhysicalLocation> - `address` string, required: Dirección del lugar fisico.
Campo oficial DIAN <Line> - `city` string, required: Código de la Ciudad. Se debe colocar el Código que corresponda de la tabla de municipios disponibles de la DIAN. Se debe informar cuando el código del País es 'CO'. En caso de que sea un país diferente a Colombia se puede enviar el nombre de la ciudad.
Campo oficial DIAN <CityName> - `postalCode` string: Código Postal del lugar físico del proveedor. Obligatorio cuando `origin` = `10` (Residente fiscal en Colombia).
Campo oficial DIAN <PostalZone> - `country` string: Código identificador del País. Se debe colocar el código que corresponda de la tabla de países disponibles de la DIAN. Por defecto 'CO'. Es obligatorio cuando no es un Residente fiscal ( `origin` = 11 )
Campo oficial DIAN <IdentificationCode> - `items` object[], required: Array que contiene el listado de articulos y/o servicios - `standardCode` object, required: Este grupo de datos se utiliza para identificar el artículo o servicio de acuerdo con un estándar establecido.
Grupo de información oficial DIAN <StandardItemIdentification> - `identificationId` string, required: Código de artículo de acuerdo al estándar utilizado.
Campo oficial DIAN <ID> - `id` '001' | '010' | '020' | '999': Código del estándar. Deberá contener uno de los siguientes valores posibles de acuerdo al código utilizado para identificar el ítem en el elemento `identificationId`:`001`: UNSPSC-Colombia Compra Eficiente; `010` GTIN-Números Globales de Identificación de Productos – GTIN; `020` Partida arancelaria según estatus tributario;`999` Estándar de adopción del contribuyente.
Campo oficial DIAN <schemeID> - `invoicePeriod` object - `descriptionCode` 1 | 2, required: Este campo permite indicar la forma de generación y transmisión de la información, utilizando los siguientes códigos: 1 = Por operación o 2 = Acumulado semanal.
Grupo de información oficial DIAN <DescriptionCode> - `startDate` string, date: Aplica para las compras con reporte semanal. Indica la fecha en la que se realizó la transacción, y se incluirá dentro del acumulado correspondiente al reporte semanal. Este campo pasa a ser obligatorio cuando `descriptionCode` es igual a `2`.
Grupo de información oficial DIAN <StartDate> - `sellersItemIdentification` object: Grupo de datos de identificación del artículo o servicio de acuerdo con el vendedor.
Grupo de información oficial DIAN <SellersItemIdentification> - `id` string, required: Código del artículo o servicio de acuerdo con el vendedor.
Campo oficial DIAN <ID> - `extendedId` string: Código del artículo o servicio de acuerdo con el vendedor.
Campo oficial DIAN <ExtendedID> - `description` string, required: Nombre y descripción del articulo y/o servicio que se está vendiendo en esta linea del documento.
Campo oficial DIAN <Description> - `price` number, float, required: Precio del articulo y/o servicio.
Campo oficial DIAN <PriceAmount> - `discount` number, float: Porcentaje de descuento del articulo y/o servicio. Se debe informar a nivel de ítem, si y solamente si el descuento afecta la base gravable del ítem.
Campo oficial DIAN </cac:AllowanceCharge/cbc:MultiplierFactorNumeric> - `discountAmount` number, float: Valor de descuento del articulo y/o servicio. Se debe informar a nivel de ítem, si y solamente si el descuento afecta la base gravable del ítem.
Campo oficial DIAN </cac:AllowanceCharge/cbc:Amount> - `charge` number, float: Porcentaje de cargo adicional aplicado articulo y/o servicio - `chargeAmount` number, float: Valor del cargo adicional del articulo y/o servicio - `quantity` number, float, required: Cantidad del articulo y/o servicio.
Campo oficial DIAN <InvoicedQuantity> - `unitCode` string, required: Código de Unidad de medida del articulo y/o servicio. Se debe colocar el Código que corresponda de la tabla de unidades de la DIAN.
Campo oficial DIAN <@unitCode> - `note` string: Información Adicional o texto libre para añadir información del articulo y/o servicio.
Campo oficial DIAN <Note> - `subtotal` number, float, required: Subtotal del articulo y/o servicio. El subtotal de la línea es igual a la Cantidad x Precio Unidad menos Descuentos más Recargos que apliquen al articulo y/o servicio.
Campo oficial DIAN <LineExtensionAmount> - `taxAmount` number, float, required: Valor total de los impuestos aplicados al articulo y/o servicio. - `taxes` object[]: Array que contiene el listado de tributos/impuestos que aplican al articulo y/o servicio - `taxCode` '01', required: Código o identificador del impuesto. Se debe colocar el Código que corresponda de la tabla de tipos de tributos/impuestos disponibles de la DIAN.
Campo oficial DIAN <ID> - `taxAmount` number, float, required: Valor y/o importe del impuesto.
Campo oficial DIAN <TaxAmount> - `taxPercentage` '0' | '5' | '19' | '0.0' | '5.0' | '19.0' | '0.00' | '5.00' | '19.00', required: Porcentaje o tarifa de impuesto. Ejemplo: Para indicar la tarifa general asociada al impuesto de IVA, se debe enviar un porcentaje de 19.
Campo oficial DIAN <Percent> - `taxableAmount` number, float, required: Base Imponible sobre la que se calcula el valor del impuesto.
Campo oficial DIAN <TaxableAmount> - `withholdings` object[]: Array con las retenciones practicadas sobre el ítem. Para reportar retenciones a nivel general del documento, use el objeto `withholdingTaxTotal`. Si se informan en ambos niveles, la API consolida los valores por tipo de retención y tarifa en el total del documento enviado a la DIAN. Dentro de un mismo ítem no se permiten dos retenciones con el mismo `taxCode` y `taxPercentage`. Si un ítem tiene varias tarifas de un mismo tipo de retención, la API las agrupa en un solo bloque por tipo, con un subtotal por tarifa.
Grupo de información oficial DIAN <InvoiceLine/WithholdingTaxTotal> - `taxCode` '05' | '06', required: Código o identificador del impuesto. Se debe colocar el Código que corresponda de la tabla de tipos de tributos/impuestos disponibles de la DIAN.
Campo oficial DIAN <ID> - `taxAmount` number, float, required: Valor y/o importe del impuesto.
Campo oficial DIAN <TaxAmount> - `taxPercentage` '0.10' | '0.50' | '1.00' | '1.50' | '2.00' | '2.50' | '3.00' | '3.50' | '4.00' | '6.00' | '7.00' | '10.00' | '11.00' | '15.00' | '20.00' | '100.00', required: Tarifa de la retención. ReteIVA (`05`): `15.00` o `100.00`. ReteRenta (`06`): tarifa según la tabla DIAN de retención en la fuente.
Campo oficial DIAN <Percent> - `taxableAmount` number, float, required: Base sobre la que se calcula la retención. ReteIVA (`05`): valor del IVA del ítem. ReteRenta (`06`): subtotal del ítem.
Campo oficial DIAN <TaxableAmount> - `packSize` number: Número de productos por empaque.
Campo oficial DIAN <PackSizeNumeric> - `brandName` string: Marca del artículo.
Campo oficial DIAN <BrandName> - `modelName` string: Modelo del artículo.
Campo oficial DIAN <ModelName> - `withholdingTaxTotal` object[]: En este objeto el emisor puede reportar las autorretenciones/retenciones a nivel general del documento, como ReteIVA o ReteRenta. Para reportarlas por línea, use el objeto `withholdings` dentro de `items`.
⚠️ Si se envía información en ambos niveles, la API consolida los valores por tipo de retención y tarifa, y envía la suma a la DIAN en el grupo de totales del documento. Para no duplicar una retención, repórtela en un solo nivel.
Las retenciones no afectan los valores de `totalAmounts`.
Grupo de información oficial DIAN <WithholdingTaxTotal> - `taxCode` '05' | '06', required: Tipo de retención. Acepta una de las siguientes opciones: `05` ReteIVA, `06` ReteRenta.
Campo oficial DIAN <TaxScheme/ID> - `taxPercentage` '0.10' | '0.50' | '1.00' | '1.50' | '2.00' | '2.50' | '3.00' | '3.50' | '4.00' | '6.00' | '7.00' | '10.00' | '11.00' | '15.00' | '20.00' | '100.00', required: Tarifa de la retención. ReteIVA (`05`): `15.00` o `100.00`. ReteRenta (`06`): tarifa según la tabla DIAN de retención en la fuente, por ejemplo `2.50`, `4.00`, `11.00`.
Campo oficial DIAN <Percent> - `taxableAmount` number, float, required: Base sobre la que se calcula la retención. ReteIVA (`05`): valor del IVA. ReteRenta (`06`): valor de la operación antes de impuestos.
Campo oficial DIAN <TaxableAmount> - `taxAmount` number, float, required: Valor de la retención. Debe ser igual a `taxableAmount` × `taxPercentage` / 100.
Campo oficial DIAN <TaxAmount> - `payments` object[], required: Array con el listado de pagos. Grupo de campos para información relacionadas con el pago de la factura.
Grupo de información oficial DIAN <PaymentMeans> - `paymentForm` '1' | '2', required: Forma de pago. Se debe colocar el Código que corresponda de la tabla de formas de pago disponibles de la DIAN.
Campo oficial DIAN <ID> - `paymentMethod` string, required: Medio de pago. Se debe colocar el Código que corresponda de la tabla de métodos de pago disponibles de la DIAN.
Campo oficial DIAN <PaymentMeansCode> - `paymentDueDate` string, date: Fecha de vencimiento de la factura. Si Forma de Pago es igual a 2, este valor debe ser enviado.
Campo oficial DIAN <PaymentDueDate> - `paymentID` string: Texto libre para informar datos adicionales sobre el medio de pago.
Campo oficial DIAN <PaymentID> - `discountsAndCharges` object[]: Descuentos Descuentos o cargos a nivel del DSE, estos descuentos o cargos no afectan las bases gravables. Si se desea agregar un descuento o cargo que afecte la base gravable se debe informan a nivel de items en el elemento `discountAmount`.
Grupo de información oficial DIAN <AllowanceCharge> - `isCharge` boolean, required: Cargo es true, aumenta el valor del DSE; Descuento es false, disminuye el valor del DSE.
Campo oficial DIAN <ChargeIndicator> - `reason` string: Texto libre para informar la razón del cargo o descuento aplicado al documento.
Campo oficial DIAN <AllowanceChargeReason> - `percentageAmount` number, float, required: Porcentaje a aplicar.
Campo oficial DIAN <MultiplierFactorNumeric> - `amount` number, float, required: Valor total del cargo o descuento.
Campo oficial DIAN <Amount> - `baseAmount` number, float, required: Valor Base para calcular el descuento o el cargo.
Campo oficial DIAN <BaseAmount> - `totalAmounts` object, required: Objeto que contiene la información de totales relacionados con el documento - `grossTotal` number, float, required: Total valor bruto antes de tributos. Suma de todos los subtotales correspondientes a los árticulos y/o servicios.
Campo oficial DIAN <LegalMonetaryTotal> - `taxableTotal` number, float, required: Total valor base imponible. Base imponible para el cálculo de los tributos.
Campo oficial DIAN <TaxExclusiveAmount> - `taxTotal` number, float, required: Total del valor de los tributos (IVA). No incluye retenciones (`withholdings` / `withholdingTaxTotal`).
Valor asociado en el calculo del campo oficial DIAN <TaxInclusiveAmount> - `discountTotal` number, float: Total valor descuentos. Suma de todos los descuentos aplicados al total de la factura.
Campo oficial DIAN <AllowanceTotalAmount> - `chargeTotal` number, float: Total valor cargos. Suma de todos los cargos aplicados al total de la factura.
Campo oficial DIAN <ChargeTotalAmount> - `payableTotal` number, float, required: Total valor factura. Valor total de ítems (incluyendo cargos y descuentos a nivel de ítems) + valor tributos + valor cargos – valor descuentos.
Campo oficial DIAN <PayableAmount> - `notes` string[]: Lista de información adicional: Texto libre, relativo al documento.
Campo oficial DIAN <Note> - `orderReference` object: **Grupo de campos para la información de la orden de pedido**: Este grupo contiene los campos que describen una orden de compra/pedido asociada al Documento Soporte Electrónico (DSE). Incluye detalles como el número de la orden, la fecha de emisión, y cualquier referencia adicional que sea relevante para el documento.
Campo oficial DIAN <OrderReference> - `id` string, required: Prefijo y Número del documento orden referenciado en el DSE.
Campo oficial DIAN <ID> - `issueDate` string, date: Corresponde a la fecha en que se generó la orden de compra/pedido.
Campo oficial DIAN <ID> - `billingReference` object: Exclusivo para referenciar la Nota de Ajuste que dio origen al presente Documento Soporte Electrónico (DSE). Incluye los datos clave de la Nota de Ajuste, como el número, la fecha de emisión y el motivo del ajuste.
Campo oficial DIAN <BillingReference> - `id` string: Id registrado por la API E-providers, en caso de que el documento de referencia haya sido emitido a través de E-providers solo se necesita este dato para identificar el documento, de lo contratrio deben enviarse los campos `fullNumber`, `cuds` y `date`. - `fullNumber` string: Prefijo + Número de la nota de ajuste referenciada.
Campo oficial DIAN <ID> - `cuds` string: CUDS de la nota de ajuste relacionada.
Campo oficial DIAN <UUID> - `date` string, date: Fecha de generación de la nota de ajuste relacionada.
Campo oficial DIAN <ID> ## Response `200` Objeto que representa la respuesta cuando se envía un documento soporte electrónico a la DIAN - object - `supportDocument` object - `id` string: Id del documento soporte electrónico - `date` string, date-time: Fecha de emisión del documento soporte electrónico - `status` 'REGISTERED' | 'RETRYING_SEND' | 'WAITING_RESPONSE' | 'FAILED' | 'SENT' | 'CANCELED' | 'REPLACED': Estado del documento soporte electrónico - `legalStatus` 'ACCEPTED' | 'ACCEPTED_WITH_OBSERVATIONS' | 'REJECTED': Estado legal deL documento soporte electrónico ante la DIAN - `companyIdentification` string: Identificación de la empresa empleadora - `supplierIdentification` string: Identificación del proveedor - `cuds` string: Código único del documento soporte electrónico asignado para el documento - `prefix` string: Prefijo del documento soporte electrónico - `number` number, double: Número del documento soporte electrónico - `fullNumber` string: Número del documento soporte electrónico (Incluye prefijo y número) - `xmlFileName` string: Nombre del archivo XML que se envió a la DIAN - `zipFileName` string: Nombre del archivo Zip que se envió a la DIAN - `governmentResponse` object: Objeto con información de la respuesta de la DIAN - `code` string: Código de respuesta de la DIAN - `message` string: Mensaje de respuesta de la DIAN - `errorMessages` string[]: Array con mensajes de error devueltos por la DIAN - `errors` object[]: Array con mensajes de error generados en el sistema - `code` string: Código de error - `message` string: Mensaje de error - `files` object - `xml` string, nullable: Link de descarga a el XML que se envia a la DIAN. Este enlace solo dura por 60 minutos, para renovar el link solicite nuevamente el documento. Puede ser null si la generación del enlace de descarga falla; el documento sí fue emitido y puede consultarse nuevamente para obtener el enlace. - `applicationResponse` string, nullable: Link de descarga a el ApplicationResponse obetenido como respuesta de al DIAN al enviar el archivo XML. Este campo solo se añade al tener una respuesta de la DIAN. Este enlace solo dura por 60 minutos, para renovar el link solicite nuevamente el documento. Puede ser null si la generación del enlace de descarga falla; el documento sí fue emitido y puede consultarse nuevamente para obtener el enlace. ## Other responses - `400`: Objeto que representa una respuesta de error por validaciones - `404`: Objeto que representa una respuesta de error por qué no se ha encontrado el recurso al que se intenta acceder - `409`: Objeto que representa una respuesta de error por un conflicto sobre la `Idempotency-Key` enviada. Código `IDEMPOTENCY_REQUEST_IN_PROGRESS` cuando una petición con la misma llave sigue en proceso: reintenta en unos segundos. Código `IDEMPOTENCY_OUTCOME_INDETERMINATE` cuando no fue posible establecer el resultado de la petición original: consulta el estado del documento con el endpoint `GET` o el webhook antes de reintentar con una llave nueva - `422`: Objeto que representa una respuesta de error por reutilizar una `Idempotency-Key` con un cuerpo de petición diferente al de la petición original. Código `IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_PAYLOAD`. La operación no se ejecuta: usa una llave nueva si realmente se trata de una operación distinta - `500`: Objeto que representa una respuesta de error por qué ha ocurrido un error interno en el sistema ## Changes - **2026-11-03** `2bc52ab55c2b`: 2 breaking, 4 info - the response property `files/applicationResponse` became nullable for the status `200` - the response property `files/xml` became nullable for the status `200` - added the new optional `header` request parameter `Idempotency-Key` - added the new optional request property `withholdingTaxTotal` - …2 more [Operation history](https://skmtc.dev/alegra/apis/api-alegra-proveedor-electr-nico-colombia/changes/support-documents/post.md) --- [API](https://skmtc.dev/alegra/apis/api-alegra-proveedor-electr-nico-colombia.md) - [All operations](https://skmtc.dev/alegra/apis/api-alegra-proveedor-electr-nico-colombia/llms.txt) - [OpenAPI document](https://skmtc.dev/alegra/apis/api-alegra-proveedor-electr-nico-colombia/revisions/2bc52ab55c2b?raw)