Facturación electrónica DIAN

La DIAN (Dirección de Impuestos y Aduanas Nacionales) es la autoridad tributaria de Colombia, y cada factura electrónica, nota crédito y débito, documento soporte, documento de nómina y evento pasa por su sistema de facturación electrónica. Una cuenta allí guarda todo lo que la empresa o persona emitió y recibió. Estos endpoints leen esa cuenta con la conexión propia del contribuyente.

Conecta tu cuenta

El sistema de facturación electrónica de la DIAN no tiene contraseña: el acceso es un enlace que la DIAN envía al correo registrado en el RUT de quien lo solicita (para una empresa, su representante legal). Solicítalo con el endpoint de solicitudes de acceso de abajo, o en el sistema de facturación electrónica de la DIAN, y registra el enlace aquí dentro de los 60 minutos en que la DIAN lo acepta. La DIAN mantiene ese acceso abierto cerca de una hora, así que registra el enlace cuando vayas a consultar y corre lo que necesites en esa ventana. Después, las consultas responden 422 connection_rejected: solicita un enlace nuevo y regístralo otra vez, y se renueva la misma conexión, que conserva su id. POST /co/dian-facturacion/connections/v1 Registra una conexión una vez. Croma la verifica con la fuente antes de guardarla y responde con su id y un nombre enmascarado.

Campo	Tipo	Notas
`access_link`	string	Obligatorio. El enlace completo del correo de la DIAN, tal como llegó. La DIAN lo acepta por 60 minutos.
`authorized`	boolean	Obligatorio. `true`: confirmas que eres el titular de la cuenta o que tienes su autorización para usarla.

curl https://api.croma.run/co/dian-facturacion/connections/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "access_link": "<access link from the DIAN email>",
        "authorized": true
      }'

{
  "data": {
    "id": "conn_2f8Kq1xVb7Lm0Pz9Rt4Wc3",
    "source": "dian-facturacion",
    "status": "active",
    "display_name": "J*** P*** G***",
    "usage": {
      "sign_ins_today": 1,
      "daily_limit": null,
      "resets_at": "2026-10-01T05:00:00.000Z"
    },
    "available_again_at": null,
    "created_at": "2026-09-30T20:00:00.000Z",
    "last_used_at": "2026-09-30T20:00:00.000Z"
  }
}

Desde entonces, cada consulta corre como una de las conexiones de tu organización. Croma elige una, mantiene su sesión abierta entre consultas y pasa a la siguiente cuando una alcanza su cupo diario. Registra más de una para tener más capacidad al día. Para usar una en particular, envía su id como connection_id. Registrar una cuenta que ya está conectada la renueva: la conexión toma los nuevos valores, conserva su id y responde 200, así que nada que guarde el id tiene que cambiar. Cómo funciona el flujo, paso a paso: Conexiones. Lístalas y elimínalas:

curl https://api.croma.run/co/dian-facturacion/connections/v1 -H "Authorization: Bearer $CROMA_API_KEY"
curl -X DELETE https://api.croma.run/co/dian-facturacion/connections/v1/conn_2f8Kq1xVb7Lm0Pz9Rt4Wc3 -H "Authorization: Bearer $CROMA_API_KEY"

Por MCP, los mismos verbos son las herramientas dian_facturacion_connect, dian_facturacion_list_connections, dian_facturacion_delete_connection. Conectar desde un agente nunca pasa las credenciales por la conversación: el agente recibe un enlace seguro y el usuario ingresa los datos de la cuenta en la consola de Croma. Cuando una consulta no puede correr con ninguna conexión:

Estado	Código	Significado
409	`connection_required`	La organización aún no tiene una conexión para esta fuente.
422	`connection_rejected`	La fuente ya no acepta las credenciales de la conexión.
429	`connections_exhausted`	Todas las conexiones usaron su cupo diario. `Retry-After` indica cuándo vuelve a haber una disponible.
422	`connection_limit_reached`	La organización ya tiene 5 conexiones para esta fuente (al registrar).

Las credenciales se cifran en cuanto llegan a Croma, quedan ligadas a tu organización y solo puede abrirlas el servicio aislado que inicia sesión en la fuente en tu nombre. La API nunca las devuelve ni se muestran a nadie. Eliminar una conexión la destruye de forma permanente.

Solicitudes de acceso

POST /co/dian-facturacion/access-requests/v1 Live Haz que la DIAN envíe el enlace de acceso con el que se registra una conexión, sin salir de tu producto: la persona (o el representante legal de la empresa) lo recibe en el correo de su RUT.

Campo	Tipo	Notas
`document_type`	enum	El tipo de documento de la persona para quien es el acceso: `CC`, `CE`, `TI`, `RC`, `PA` o `NIT`. Por defecto `CC`.
`document_number`	string	Obligatorio. The document number of the person the access is for (the legal representative’s, for a company), without dots or commas. DIAN sends the link to the email registered in that person’s RUT.
`company_nit`	string	Optional. The NIT of the company the access is for, without the verification digit, dots or dashes; `document_number` is then its legal representative’s. Empty asks for the person’s own access.

curl https://api.croma.run/co/dian-facturacion/access-requests/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "document_type": "CC",
        "document_number": "1234567890",
        "company_nit": "900123456"
      }'

Respuesta

sent es true cuando la DIAN aceptó la solicitud y envió el enlace al correo del RUT de la persona; message es la respuesta de la DIAN. El enlace sirve por expires_in_minutes (60). Regístralo como conexión dentro de ese tiempo.

Esta llamada corre sin conexión: es como se empieza una. Se cobra como cualquier otra llamada.

Documentos emitidos

POST /co/dian-facturacion/issued-documents/v1 Live

Campo	Tipo	Notas
`from_date`	string	Obligatorio. Primera fecha de emisión a incluir, `yyyy-mm-dd`.
`to_date`	string	Obligatorio. Última fecha de emisión a incluir, `yyyy-mm-dd`, máximo un año después de `from_date`. Para un periodo más largo, llama una vez por año.
`connection_id`	string	La conexión con la que se consulta. Cada conexión lee los documentos de su propia cuenta, así que con más de una en tu organización es obligatorio; sin él la llamada responde `409 connection_id_required`.

curl https://api.croma.run/co/dian-facturacion/issued-documents/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from_date": "2026-01-01", "to_date": "2026-06-30" }'

Respuesta

Campo	Notas
`from_date`, `to_date`	Repiten el rango.
`taxpayer`	El `nit` y el `name` de la cuenta.
`count`	Cantidad de documentos devueltos.
`by_type[]`	Cantidad y `total` sumado por tipo de documento.
`documents[]`	Uno por documento electrónico (abajo).

Cada documento tiene su cufe (la llave), document_type_code y document_type, series y number, issued_on y received_at, el issuer y el recipient (nit, name), currency, payment_form y payment_method (códigos de la DIAN), cada impuesto que la DIAN totaliza en taxes y las withholdings (ReteIVA, ReteRenta, ReteICA), el total, el status de validación de la DIAN y su radian_status como título valor. Además de facturas, las listas traen notas crédito y débito, documentos soporte, nómina y los eventos (application responses) que la cuenta emitió o recibió.

{
  "data": {
    "from_date": "2026-01-01",
    "to_date": "2026-06-30",
    "taxpayer": { "nit": "900123456", "name": "EJEMPLO S.A.S" },
    "count": 1,
    "by_type": [{ "document_type": "Factura electrónica", "count": 1, "total": 1190000 }],
    "documents": [
      {
        "cufe": "a1b2c3d4e5f60718...",
        "document_type_code": "01",
        "document_type": "Factura electrónica",
        "series": "FE",
        "number": "27",
        "issued_on": "2026-03-09",
        "received_at": "2026-03-09T09:45:16-05:00",
        "issuer": { "nit": "900123456", "name": "EJEMPLO S.A.S" },
        "recipient": { "nit": "860000001", "name": "CLIENTE S.A.S" },
        "currency": "COP",
        "payment_form": "2",
        "payment_method": "42",
        "taxes": { "iva": 190000, "ica": 0, "ic": 0, "inc": 0, "timbre": 0, "inc_bolsas": 0, "in_carbono": 0, "in_combustibles": 0, "ic_datos": 0, "icl": 0, "inpp": 0, "ibua": 0, "icui": 0 },
        "withholdings": { "rete_iva": 0, "rete_renta": 0, "rete_ica": 0 },
        "total": 1190000,
        "status": "Aprobado con notificación",
        "radian_status": "Factura Electrónica"
      }
    ]
  }
}

Cada llamada lee la DIAN en vivo con tu conexión, así que la respuesta está al día y nunca se comparte entre organizaciones.

Esta consulta puede tardar más que una solicitud típica. Es un trabajo asíncrono. Por defecto la solicitud espera en línea y devuelve { data }, o puedes hacer polling / usar un callback_url.

Documentos recibidos

POST /co/dian-facturacion/received-documents/v1 Live La misma forma que los documentos emitidos.

Campo	Tipo	Notas
`from_date`	string	Obligatorio. Primera fecha de emisión a incluir, `yyyy-mm-dd`.
`to_date`	string	Obligatorio. Última fecha de emisión a incluir, `yyyy-mm-dd`, máximo un año después de `from_date`. Para un periodo más largo, llama una vez por año.
`connection_id`	string	La conexión con la que se consulta. Cada conexión lee los documentos de su propia cuenta, así que con más de una en tu organización es obligatorio; sin él la llamada responde `409 connection_id_required`.

curl https://api.croma.run/co/dian-facturacion/received-documents/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from_date": "2026-01-01", "to_date": "2026-06-30" }'

Cada llamada lee la DIAN en vivo con tu conexión, así que la respuesta está al día y nunca se comparte entre organizaciones.

Esta consulta puede tardar más que una solicitud típica. Es un trabajo asíncrono. Por defecto la solicitud espera en línea y devuelve { data }, o puedes hacer polling / usar un callback_url.

Un documento

POST /co/dian-facturacion/document/v1 Live

Campo	Tipo	Notas
`cufe`	string	Obligatorio. CUFE/CUDE (unique electronic-document code) or UUID of the document.
`issued_on`	string	Obligatorio. The document’s issue date, `yyyy-mm-dd`, as the issued or received documents list it (`issued_on`).
`connection_id`	string	La conexión con la que se consulta. Cada conexión lee los documentos de su propia cuenta, así que con más de una en tu organización es obligatorio; sin él la llamada responde `409 connection_id_required`.

curl https://api.croma.run/co/dian-facturacion/document/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "cufe": "a1b2c3d4e5f60718a1b2c3d4e5f60718a1b2c3d4e5f60718a1b2c3d4e5f60718a1b2c3d4e5f60718a1b2c3d4e5f60718",
        "issued_on": "2026-03-09"
      }'

Respuesta

found dice si la cuenta tiene el documento en esa fecha; cuando es false el resto viene vacío. Si no, recibes el encabezado del documento (document_type, series, number, issued_on, issued_at, due_on, issuer, recipient, currency, payment_form, payment_method, notes), sus lines (description, quantity, unit, unit_price, line_total y los taxes de cada línea), sus propios totals, los taxes y el total como los muestra el registro de la DIAN, el legitimate_holder, las validations de la DIAN, sus events (acuse de recibo, recibo del bien, aceptación, endoso…) y los archivos originales: xml (UBL 2.1) y pdf_base64. Nómina, documentos soporte y eventos no traen líneas ni archivos aquí; su encabezado, validaciones y eventos sí.

Toma cufe e issued_on de una fila de los documentos emitidos o recibidos.

Esta consulta puede tardar más que una solicitud típica. Es un trabajo asíncrono. Por defecto la solicitud espera en línea y devuelve { data }, o puedes hacer polling / usar un callback_url.

Reporte mensual

POST /co/dian-facturacion/monthly-reports/v1 Live La DIAN lo emite a las cuentas que facturan electrónicamente, normalmente en las primeras semanas del mes siguiente.

Campo	Tipo	Notas
`year`	integer	Obligatorio. The report’s year.
`month`	integer	Obligatorio. The report’s month, 1 to 12.
`connection_id`	string	La conexión con la que se consulta. Cada conexión lee los documentos de su propia cuenta, así que con más de una en tu organización es obligatorio; sin él la llamada responde `409 connection_id_required`.

curl https://api.croma.run/co/dian-facturacion/monthly-reports/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "year": 2025, "month": 12 }'

Respuesta

available dice si la DIAN emitió un reporte para el mes; cuando es false el resto viene vacío. Un reporte trae su reference, dated_on, cutoff_date y replaces_previous; documents[] con, por tipo de documento, lo issued y lo received (month_count, month_amount, year_count, year_amount); e indicators[] del mes y los dos anteriores (count, daily_average_count, amount, daily_average_amount, emitidos y recibidos).

Esta consulta puede tardar más que una solicitud típica. Es un trabajo asíncrono. Por defecto la solicitud espera en línea y devuelve { data }, o puedes hacer polling / usar un callback_url.

Perfil

POST /co/dian-facturacion/profile/v1 Live

Campo	Tipo	Notas
`connection_id`	string	La conexión con la que se consulta. Cada conexión lee los documentos de su propia cuenta, así que con más de una en tu organización es obligatorio; sin él la llamada responde `409 connection_id_required`.

curl https://api.croma.run/co/dian-facturacion/profile/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Respuesta

El nit, name, business_name y email de la cuenta, su status en el sistema de facturación electrónica de la DIAN, el reception_email donde recibe facturas, sus legal_representatives, sus operation_modes (software propio, de un proveedor tecnológico o el de la DIAN) y los numbering_ranges asociados a su software (prefix, resolution, from_number, to_number, associated_on, expires_on).

Esta consulta puede tardar más que una solicitud típica. Es un trabajo asíncrono. Por defecto la solicitud espera en línea y devuelve { data }, o puedes hacer polling / usar un callback_url.

Referencia completa

Esquemas, todos los campos de respuesta y un playground interactivo.

Primeros pasos

Tipos de solicitud

Monitores

Países

Facturación electrónica DIAN

Conecta tu cuenta

Solicitudes de acceso

Respuesta

Documentos emitidos

Respuesta

Documentos recibidos

Un documento

Respuesta

Reporte mensual

Respuesta

Perfil

Respuesta

Referencia completa

​Conecta tu cuenta

​Solicitudes de acceso

​Respuesta

​Documentos emitidos

​Respuesta

​Documentos recibidos

​Un documento

​Respuesta

​Reporte mensual

​Respuesta

​Perfil

​Respuesta

Referencia completa

Conecta tu cuenta

Solicitudes de acceso

Respuesta

Documentos emitidos

Respuesta

Documentos recibidos

Un documento

Respuesta

Reporte mensual

Respuesta

Perfil

Respuesta