Crear Doc. Soporte

Método: POST

Endpoint

Sandbox

https://api-sandbox.factus.com.co/v2/support-documents/validate

Producción

https://api.factus.com.co/v2/support-documents/validate

Nota

Es necesario el envío del token de acceso <access_token> para hacer uso de este endpoint. Para ver cómo generar el token, vea Cómo generar un token de acceso .
Recuerde: El token de acceso caduca cada hora.

Encabezados de la Solicitud

Para realizar la solicitud es necesario incluir los siguientes encabezados:

Content-Type : application/json Indica que los datos se envían en formato JSON.

Authorization Bearer token_de_acceso Token de autenticación necesario para acceder al recurso. Ver Cómo generar token

Accept : application/json Indica que la respuesta debe estar en formato JSON.

Nota: Reemplaza token_de_acceso con el token proporcionado tras autenticarte.

---

Tener en cuenta

• Si envía un reference_code ya procesado, recibirá los datos correspondientes al documento soporte existente.
• Si el endpoint responde con, Se encontró un documento soporte pendiente por enviar a la DIAN. Error 409 Conflict, debe Eliminar el documento soporte usando la referencia, y proceder con la creación de un nuevo documento soporte. Puede guiarse por el campo is_validated del documento soporte: true validado, false sin validar.

---

Ver aquí la descripción de los campos.

Parámetros Documento Soporte
reference_code string Código único que sirve para identificar cada documento soporte de manera unívoca en el sistema y garantizar que no haya duplicados. Esto nos ayuda a prevenir que se genere más de un documento soporte con la misma información.
created_time string opcional Fecha y hora de creación del documento soporte en formato `HH:mm:ss`.
observation string opcional Agrega una observación del documento soporte. No debe tener más de 250 caracteres.
payment_details array Este es un array de objetos para los medios de pago. Se debe enviar un objeto por cada medio de pago utilizado para pagar el documento soporte.
payment_details.*.payment_form string Código de la forma de pago. Formas de pago disponibles
payment_details.*.payment_method_code string Código del método de pago. Métodos de pago disponibles.
payment_details.*.reference_code string opcional Código de referencia del pago.
payment_details.*.amount string Monto pagado por ese medio y método de pago.
payment_details.*.due_date string opcional Fecha de vencimiento del documento soporte, en formato YYYY-MM-DD. Requerido solo cuando la forma de pago (payment_form) contiene el valor de 2 (pago a crédito).
cash_rounding_amount string opcional Ajuste opcional que reconcilia la diferencia entre la suma de los montos en ⁠payment_details y el total del documento soporte, causada por las limitaciones de denominación de la moneda local. Acepta valores negativos (redondeo hacia abajo) o positivos (redondeo hacia arriba). El valor máximo permitido es ±500.00.
establishment object opcional Este es un objeto que contendrá la información sobre el establecimiento. Úsalo cuando manejes más de un establecimiento y necesites que los datos correspondientes se reflejen en el documento soporte. Si envías el campo establishment los campos internos son obligatorios.
establishment.name string Nombre del establecimiento.
establishment.address string Dirección del establecimiento.
establishment.phone_number string Número telefónico del establecimiento.
establishment.email string Correo electrónico del establecimiento.
establishment.municipality_code string Código que corresponda al municipio donde se encuentra el establecimiento. Municipios disponibles.
provider object Este es un objeto que contendrá la información del proveedor del documento soporte.
provider.identification_document_code string Código que corresponde al tipo de identificación. Tipos de documentos de identidad disponibles
provider.identification string Número de identificación del proveedor.
provider.dv string opcional Dígito de verificación del proveedor. Requerido ya que el proveedor debe identificarse con NIT, sin embargo, si no se envía el API lo calcula automáticamente.
provider.trade_name string opcional Nombre comercial del proveedor.
provider.names string Nombre del proveedor.
provider.address string Dirección del proveedor.
provider.country_code string Código del país del proveedor. Países disponibles
provider.municipality_code string Código del municipio del proveedor. Municipios disponibles
provider.legal_organization_code string Código de la organización legal del proveedor. Tipos de organización legal disponibles
provider.email string opcional Dirección del correo electrónico del proveedor.
provider.phone string opcional Número de teléfono del proveedor.
items array Este es un array de objetos (items) que corresponde a los productos o servicios del documento soporte, se debe enviar un objeto por cada producto o servicio.
items.*.note string opcional Añade información adicional del producto o servicio.
items.*.code_reference string Código de referencia del producto o servicio.
items.*.name string Nombre del producto o servicio.
items.*.quantity string Cantidad del producto o servicio (máximo dos decimales).
items.*.discount_rate string Porcentaje del descuento del producto o servicio (máximo dos decimales).
items.*.price string Precio por unidad del producto o servicio sin impuestos incluidos ni descuentos, valor neto (máximo dos decimales).
items.*.unit_measure_code string Código que corresponda a la unidad de medida del item. Unidades de medida disponibles
items.*.standard_code string Código que corresponde al estándar que se adopta para los productos o servicios. Códigos de estándar disponibles.
items.*.withholding_taxes array opcional Este es un array de objetos para informar las retenciones que se aplican al producto o servicio. Por cada retención que apliques al proveedor, debes enviar un objeto.
items.*.withholding_taxes.*.code string Código de la retención aplicada al producto o servicio. Códigos retenciones disponibles.
items.*.withholding_taxes.*.rate string Porcentaje de la retención aplicada al producto o servicio (máximo dos decimales).

Ejemplo de Solicitud

201 - Documento Soporte

{
  "reference_code": "DS-2026-v2-0001",
  "created_time": "15:30:00",
  "observation": "",
  "payment_details": [
    {
      "payment_form": "1",
      "payment_method_code": "42",
      "reference_code": "pago-002",
      "amount": "40000"
    },
    {
      "payment_form": "2",
      "payment_method_code": "10",
      "reference_code": "pago-003",
      "amount": "40000",
      "due_date": "2026-05-25"
    }
  ],
  "cash_rounding_amount": "0.00",
  "establishment": {
    "name": "nombre establecimiento",
    "address": "direccion del establecimiento",
    "phone_number": "1234567890",
    "email": "establecieminto@tuempresa.com",
    "municipality_code": "91263"
  },
  "provider": {
    "identification_document_code": "31",
    "identification": "2343543",
    "dv": "7",
    "names": "Pepito Perez",
    "address": "calle 4",
    "country_code": "CO",
    "municipality_code": "68679",
    "legal_organization_code": "1"
  },
  "items": [
    {
      "code_reference": "12345",
      "name": "producto de prueba",
      "quantity": "2.00",
      "discount_rate": "20.00",
      "price": "50000.00",
      "unit_measure_code": "94",
      "standard_code": "999",
      "withholding_taxes": [
        {
          "code": "06",
          "rate": "3.50"
        }
      ]
    }
  ]
}

Ejemplo de respuesta

status 201 - Documento Soporte

{
  "status": "Created",
  "message": "Documento con el código de referencia f2e681aa-d244-4b2a-99a4-0d8de434cfb7 registrado y validado con éxito",
  "data": {
    "reference_code": "f2e681aa-d244-4b2a-99a4-0d8de434cfb7",
    "number": "SEDS984000003",
    "payment_details": [
      {
        "payment_form": {
          "code": "1",
          "name": "Pago de contado"
        },
        "payment_method": {
          "code": "42",
          "name": "Consignación"
        },
        "reference_code": "pago-002",
        "amount": "40000.00",
        "due_date": null
      },
      {
        "payment_form": {
          "code": "2",
          "name": "Pago a crédito"
        },
        "payment_method": {
          "code": "10",
          "name": "Efectivo"
        },
        "reference_code": "pago-003",
        "amount": "40000.00",
        "due_date": "25-05-2026"
      }
    ],
    "is_validated": true,
    "validated_at": "05-05-2026 11:46:43 AM",
    "errors": [
      "Regla: RUT01, Notificación: La validación del estado del RUT próximamente estará disponible."
    ],
    "observation": null,
    "created_at": "05-05-2026 11:40:00 AM",
    "numbering_range": {
      "prefix": "SEDS",
      "from": 984000000,
      "to": 985000000,
      "resolution_number": "18760000001",
      "start_date": "01-01-2026",
      "end_date": "31-12-2026",
      "months": 11
    },
    "company": {
      "url_logo": "https://api-sandbox.factus.com.co/storage/images/logos/T3RWMJn0HDi6Uy4UTIOpi2vqw4qbEumeFiB5kt21.png",
      "nit": "1000789002",
      "dv": "2",
      "economic_activity": "1084",
      "establishment": {
        "name": "FACTUS V2",
        "address": "calle 11 8 84",
        "phone_number": "3161331234",
        "email": "factus@tudominio.com",
        "municipality": {
          "code": "68679",
          "name": "San Gil",
          "department": {
            "code": "68",
            "name": "Santander"
          }
        }
      }
    },
    "provider": {
      "identification_document": {
        "code": "31",
        "name": "NIT"
      },
      "identification": "2343543",
      "dv": "7",
      "graphic_representation_name": "Alan Turing",
      "trade_name": null,
      "names": "Alan Turing",
      "address": "calle 4",
      "email": null,
      "phone": null,
      "legal_organization": {
        "code": "2",
        "name": "Persona Natural"
      },
      "tribute": {
        "code": "ZZ",
        "name": "No aplica"
      },
      "municipality": {
        "code": "68679",
        "name": "San Gil",
        "department": {
          "code": "68",
          "name": "Santander"
        }
      }
    },
    "items": [
      {
        "code_reference": "12345",
        "name": "producto de prueba",
        "quantity": "2.00",
        "unit_measure": {
          "code": "94",
          "name": "unidad"
        },
        "standard_code": {
          "code": "999",
          "name": "Estándar de adopción del contribuyente"
        },
        "discount_rate": "20.00",
        "discount": "20000.00",
        "gross_value": "30000.00",
        "withholding_taxes": [
          {
            "tribute_code": "06",
            "name": "ReteRenta",
            "value": "2800.00",
            "rates": [
              {
                "code": "06",
                "name": "ReteRenta",
                "rate": "3.50"
              }
            ]
          }
        ],
        "price": "50000.00",
        "total": "80000.00"
      }
    ],
    "withholding_taxes": [
      {
        "tribute_code": "06",
        "name": "ReteRenta",
        "value": "2800.00"
      }
    ],
    "totals": {
      "gross_amount": "80000.00",
      "total": "80000.00"
    },
    "related_notes": {
      "adjustment_notes": []
    },
    "cuds": "cb5d9821c0decb13992f2b78a1e04ee7da5b4d9770ac42d4524d268241515f3daddd7ada665c0e44eac8e7f6b4788f83",
    "links": {
      "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=cb5d9821c0decb13992f2b78a1e04ee7da5b4d9770ac42d4524d268241515f3daddd7ada665c0e44eac8e7f6b4788f83"
    }
  }
}

Status 409

{
  "status": "Conflict",
  "message": "Se encontró un documento soporte por enviar a la DIAN"
}

Status 422

{
  "status": "Validation error",
  "message": "Error de validación",
  "data": {
    "message": "Error de validación",
    "errors": {
      "reference_code": [
        "El campo código de referencia es obligatorio."
      ],
      "provider.address": [
        "El campo dirección es obligatorio."
      ]
    }
  }
}