Mi cuenta DIAN

La DIAN (Dirección de Impuestos y Aduanas Nacionales) es la autoridad tributaria y aduanera de Colombia. La cuenta en línea de un contribuyente guarda lo que la DIAN sabe de su año: las facturas electrónicas emitidas a su nombre y la información que reportaron terceros (información exógena). Estos endpoints leen esa cuenta con la conexión propia del contribuyente, un año gravable a la vez.

Conecta tu cuenta

La DIAN solo responde a una persona con sesión iniciada: el tipo y número de documento y la contraseña de su cuenta DIAN, usados a nombre propio. Cada consulta corre con la conexión propia de tu organización, así que registra una antes de tu primera consulta. Registra la cuenta una vez; Croma mantiene la sesión abierta y la reutiliza entre consultas. POST /co/dian-muisca/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
`document_type`	enum	El tipo de documento del titular de la cuenta DIAN: `CC`, `CE`, `TI`, `RC`, `PA`, `PEP` o `PPT`. Por defecto `CC`.
`document_number`	string	Obligatorio. The document number of the person whose DIAN account this is, without dots or commas.
`password`	string	Obligatorio. The password of that DIAN account.
`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-muisca/connections/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "document_type": "CC",
        "document_number": "1234567890",
        "password": "your-dian-password",
        "authorized": true
      }'

{
  "data": {
    "id": "conn_2f8Kq1xVb7Lm0Pz9Rt4Wc3",
    "source": "dian-muisca",
    "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. Cómo funciona el flujo, paso a paso: Conexiones. Lístalas y elimínalas:

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

Por MCP, los mismos verbos son las herramientas dian_muisca_connect, dian_muisca_list_connections, dian_muisca_delete_connection, así un agente puede conectar la cuenta del usuario en la conversación. 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.
409	`connection_exists`	La misma cuenta ya está conectada (al registrar).
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.

Facturas electrónicas

POST /co/dian-muisca/electronic-invoices/v1

Campo	Tipo	Notas
`year`	integer	Obligatorio. El año gravable. La DIAN ofrece facturas electrónicas desde 2023.
`connection_id`	string	Optional. Run as this connection (`conn_…`). Empty lets Croma pick among your organization’s connections, moving to the next one when one reaches its daily allowance.

curl https://api.croma.run/co/dian-muisca/electronic-invoices/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "year": 2024 }'

Respuesta

Campo	Notas
`year`	Repite el año gravable.
`cutoff_date`	La fecha de corte de las cifras de la DIAN, `yyyy-mm-dd`, o `null`.
`taxpayer`	El `document_number` y `name` del titular, como los muestra la DIAN.
`count`	Cantidad de facturas devueltas.
`totals`	Sumas sobre las facturas devueltas, en COP.
`invoices[]`	Una por factura electrónica (abajo).

Cada factura tiene issuer_id, issuer_name, issued_on, el invoiced_amount con sus credit_notes_amount y debit_notes_amount, el net_amount y deductible_amount (COP), payment_method, invoice_number y cufe.

{
  "data": {
    "year": 2024,
    "cutoff_date": "2025-03-14",
    "taxpayer": { "document_number": "1234567890", "name": "JUAN PEREZ GOMEZ" },
    "count": 2,
    "totals": {
      "invoiced_amount": 1850000,
      "credit_notes_amount": 0,
      "debit_notes_amount": 0,
      "net_amount": 1850000,
      "deductible_amount": 1850000
    },
    "invoices": [
      {
        "issuer_id": "900123456",
        "issuer_name": "ALMACENES EXITO S.A.",
        "issued_on": "2024-02-10",
        "invoiced_amount": 1200000,
        "credit_notes_amount": 0,
        "debit_notes_amount": 0,
        "net_amount": 1200000,
        "deductible_amount": 1200000,
        "payment_method": "Electrónicos",
        "invoice_number": "FE-9912",
        "cufe": "a1b2c3d4e5f6..."
      }
    ]
  }
}

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.

Información exógena

POST /co/dian-muisca/third-party-reports/v1

Campo	Tipo	Notas
`year`	integer	Obligatorio. El año gravable. Los reportes de terceros llegan hasta 2018.
`connection_id`	string	Optional. Run as this connection (`conn_…`). Empty lets Croma pick among your organization’s connections, moving to the next one when one reaches its daily allowance.

curl https://api.croma.run/co/dian-muisca/third-party-reports/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "year": 2024 }'

Respuesta

Campo	Notas
`year`	Repite el año gravable.
`cutoff_date`	La fecha de corte de las cifras de la DIAN, `yyyy-mm-dd`, o `null`.
`taxpayer`	El `document_number` y `name` del titular.
`thresholds[]`	El resumen de la DIAN frente a los topes; vacío antes de 2023.
`count`	Cantidad de reportes devueltos.
`reports[]`	Uno por línea que reportó un tercero (abajo).

Cada reporte tiene reporter_id y reporter_name (quién reportó), reported_id y reported_name (cómo lo reportó; reported_id es null antes de 2023), concept, amount (COP), y suggested_use e additional_info (null antes de 2023).

{
  "data": {
    "year": 2024,
    "cutoff_date": "2025-03-14",
    "taxpayer": { "document_number": "1234567890", "name": "JUAN PEREZ GOMEZ" },
    "thresholds": [
      { "name": "Tope 1 - Ingresos", "amount": 59000000 }
    ],
    "count": 1,
    "reports": [
      {
        "reporter_id": "890900608",
        "reporter_name": "BANCOLOMBIA S.A.",
        "reported_id": "1234567890",
        "reported_name": "JUAN PEREZ GOMEZ",
        "concept": "Saldo cuentas bancarias",
        "amount": 4200000,
        "suggested_use": "Patrimonio",
        "additional_info": "Cuenta de ahorros ****1234"
      }
    ]
  }
}

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.

Referencia completa

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

Primeros pasos

Tipos de solicitud

Monitores

Países

Conecta tu cuenta

Facturas electrónicas

Respuesta

Información exógena

Respuesta

Referencia completa

​Conecta tu cuenta

​Facturas electrónicas

​Respuesta

​Información exógena

​Respuesta

Referencia completa

Conecta tu cuenta

Facturas electrónicas

Respuesta

Información exógena

Respuesta