> ## 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.

# Mi cuenta DIAN

> Lee los registros tributarios de una persona en la DIAN: las facturas electrónicas emitidas a su nombre y la información que terceros reportaron sobre ella, por año gravable.

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. |

```bash theme={"dark"}
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
      }'
```

```json theme={"dark"}
{
  "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](/es/connections).

Lístalas y elimínalas:

```bash theme={"dark"}
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](/es/mcp-server), 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). |

<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.
</Note>

## 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. |

```bash theme={"dark"}
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`.

```json theme={"dark"}
{
  "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..."
      }
    ]
  }
}
```

<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>

<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`.
</Note>

## 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. |

```bash theme={"dark"}
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).

```json theme={"dark"}
{
  "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"
      }
    ]
  }
}
```

<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>

<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`.
</Note>

<Card title="Referencia completa" icon="code" href="/es/api-reference/overview">
  Esquemas, todos los campos de respuesta y un playground interactivo.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.