Minha conta DIAN

A DIAN (Dirección de Impuestos y Aduanas Nacionales) é a autoridade tributária e aduaneira da Colômbia. A conta on-line de um contribuinte guarda o que a DIAN sabe do seu ano: as faturas eletrônicas emitidas a seu nome e a informação que terceiros reportaram (información exógena). Estes endpoints leem essa conta com a conexão própria do contribuinte, um ano gravável de cada vez.

Conecte sua conta

A DIAN só responde a uma pessoa com sessão iniciada: o tipo e número de documento e a senha da sua conta DIAN, usados em nome próprio. Cada consulta roda com a conexão própria da sua organização, então registre uma antes da sua primeira consulta. Registre a conta uma vez; a Croma mantém a sessão aberta e a reutiliza entre consultas. POST /co/dian-muisca/connections/v1 Registre uma conexão uma vez. A Croma a verifica com a fonte antes de salvá-la e responde com seu id e um nome mascarado.

Campo	Tipo	Notas
`document_type`	enum	O tipo de documento do titular da conta DIAN: `CC`, `CE`, `TI`, `RC`, `PA`, `PEP` ou `PPT`. Por padrão `CC`.
`document_number`	string	Obrigatório. The document number of the person whose DIAN account this is, without dots or commas.
`password`	string	Obrigatório. The password of that DIAN account.
`authorized`	boolean	Obrigatório. `true`: você confirma que é o titular da conta ou que tem a autorização do titular para usá-la.

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

A partir daí, cada consulta roda como uma das conexões da sua organização. A Croma escolhe uma, mantém sua sessão aberta entre as consultas e passa para a próxima quando uma atinge sua cota diária. Registre mais de uma para ter mais capacidade por dia. Para usar uma específica, envie seu id como connection_id. Como o fluxo funciona, passo a passo: Conexões. Liste e exclua:

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, os mesmos verbos são as ferramentas dian_muisca_connect, dian_muisca_list_connections, dian_muisca_delete_connection. Conectar a partir de um agente nunca passa as credenciais pela conversa: o agente recebe um link seguro e o usuário informa os dados da conta no console da Croma. Quando uma consulta não pode rodar com nenhuma conexão:

Status	Código	Significado
409	`connection_required`	A organização ainda não tem uma conexão para esta fonte.
422	`connection_rejected`	A fonte não aceita mais as credenciais da conexão.
429	`connections_exhausted`	Todas as conexões usaram sua cota diária. `Retry-After` indica quando uma volta a estar disponível.
409	`connection_exists`	A mesma conta já está conectada (ao registrar).
422	`connection_limit_reached`	A organização já tem 5 conexões para esta fonte (ao registrar).

As credenciais são criptografadas assim que chegam à Croma, ficam vinculadas à sua organização e só podem ser abertas pelo serviço isolado que faz login na fonte em seu nome. A API nunca as devolve nem as mostra a ninguém. Excluir uma conexão a destrói permanentemente.

Faturas eletrônicas

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

Campo	Tipo	Notas
`year`	integer	Obrigatório. O ano gravável, de 2023 ao último ano já encerrado. A DIAN publica um ano só depois que ele termina, então o ano em curso é rejeitado.
`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 }'

Resposta

Campo	Notas
`year`	Repete o ano gravável.
`cutoff_date`	A data de corte dos números da DIAN, `yyyy-mm-dd`, ou `null`.
`taxpayer`	O `document_number` e `name` do titular, como a DIAN os mostra.
`count`	Quantidade de faturas retornadas.
`totals`	Somas sobre as faturas retornadas, em COP.
`invoices[]`	Uma por fatura eletrônica (abaixo).

Cada fatura tem issuer_id, issuer_name, issued_on, o invoiced_amount com seus credit_notes_amount e debit_notes_amount, o net_amount e deductible_amount (COP), payment_method, invoice_number e 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 chamada lê a DIAN ao vivo com a sua conexão, então a resposta está atualizada e nunca é compartilhada entre organizações.

Esta consulta pode demorar mais que uma solicitação típica. É um trabalho assíncrono. Por padrão, a solicitação espera de forma síncrona e retorna { data }, ou você pode fazer polling / usar um callback_url.

Informação exógena

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

Campo	Tipo	Notas
`year`	integer	Obrigatório. O ano gravável, de 2018 ao último ano já encerrado. A DIAN publica um ano só depois que ele termina, então o ano em curso é rejeitado.
`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 }'

Resposta

Campo	Notas
`year`	Repete o ano gravável.
`cutoff_date`	A data de corte dos números da DIAN, `yyyy-mm-dd`, ou `null`.
`taxpayer`	O `document_number` e `name` do titular.
`thresholds[]`	O resumo da DIAN frente aos topes; vazio antes de 2023.
`count`	Quantidade de relatórios retornados.
`reports[]`	Um por linha que um terceiro reportou (abaixo).

Cada relatório tem reporter_id e reporter_name (quem reportou), reported_id e reported_name (como reportou; reported_id é null antes de 2023), concept, amount (COP), e 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 chamada lê a DIAN ao vivo com a sua conexão, então a resposta está atualizada e nunca é compartilhada entre organizações.

Referência completa

Esquemas, todos os campos de resposta e um playground interativo.

Primeiros passos

Tipos de solicitação

Monitores

Países

Conecte sua conta

Faturas eletrônicas

Resposta

Informação exógena

Resposta

Referência completa

​Conecte sua conta

​Faturas eletrônicas

​Resposta

​Informação exógena

​Resposta

Referência completa

Conecte sua conta

Faturas eletrônicas

Resposta

Informação exógena

Resposta