> ## 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. # Minha conta DIAN > Leia os registros tributários de uma pessoa na DIAN da Colômbia: as faturas eletrônicas emitidas a seu nome e o que terceiros reportaram sobre ela, por ano gravável. 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. | ```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" } } ``` 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](/pt/connections). Liste e exclua: ```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](/pt/mcp-server), 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](https://platform.usecroma.com/connections). 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. | ```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 }' ``` ## 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`. ```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..." } ] } } ``` 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](/pt/async-jobs). 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. | ```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 }' ``` ## 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). ```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" } ] } } ``` 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](/pt/async-jobs). Por padrão, a solicitação espera de forma síncrona e retorna `{ data }`, ou você pode fazer polling / usar um `callback_url`. Esquemas, todos os campos de resposta e um playground interativo. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.