> ## Documentation Index > Fetch the complete documentation index at: https://docs.usecroma.com/llms.txt > Use this file to discover all available pages before exploring further. # Facturación electrónica DIAN > Lee la facturación electrónica de una empresa o persona en la DIAN: los documentos que emitió y recibió, cada documento completo, el reporte mensual de la DIAN y el perfil de la cuenta. 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. | ```bash theme={"dark"} curl https://api.croma.run/co/dian-facturacion/connections/v1 \ -H "Authorization: Bearer $CROMA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "access_link": "", "authorized": true }' ``` ```json theme={"dark"} { "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](/es/connections). Lístalas y elimínalas: ```bash theme={"dark"} 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](/es/mcp-server), 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](https://platform.usecroma.com/connections). 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). | > [!NOTE] > > 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](/es/live-lookups) 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. | ```bash theme={"dark"} 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. > [!NOTE] > > 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](/es/live-lookups) | 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`. | ```bash theme={"dark"} 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ó. ```json theme={"dark"} { "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" } ] } } ``` > [!NOTE] > > 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. > [!NOTE] > > Esta consulta puede tardar más que una solicitud típica. Es un > [trabajo asíncrono](/es/async-jobs). 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](/es/live-lookups) 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`. | ```bash theme={"dark"} 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" }' ``` > [!NOTE] > > 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. > [!NOTE] > > Esta consulta puede tardar más que una solicitud típica. Es un > [trabajo asíncrono](/es/async-jobs). 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](/es/live-lookups) | 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`. | ```bash theme={"dark"} 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í. > [!NOTE] > > Toma `cufe` e `issued_on` de una fila de los documentos emitidos o recibidos. > [!NOTE] > > Esta consulta puede tardar más que una solicitud típica. Es un > [trabajo asíncrono](/es/async-jobs). 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](/es/live-lookups) 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`. | ```bash theme={"dark"} 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). > [!NOTE] > > Esta consulta puede tardar más que una solicitud típica. Es un > [trabajo asíncrono](/es/async-jobs). 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](/es/live-lookups) | 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`. | ```bash theme={"dark"} 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`). > [!NOTE] > > Esta consulta puede tardar más que una solicitud típica. Es un > [trabajo asíncrono](/es/async-jobs). Por defecto la solicitud espera en línea y > devuelve `{ data }`, o puedes hacer polling / usar un `callback_url`. > **[Referencia completa](/es/api-reference/overview)** > > Esquemas, todos los campos de respuesta y un playground interactivo. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.