> ## 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. # Faturamento eletrônico DIAN > Leia o faturamento eletrônico de uma empresa ou pessoa na DIAN da Colômbia: os documentos que emitiu e recebeu, cada documento completo, o relatório mensal da DIAN e o perfil da conta. A DIAN (Dirección de Impuestos y Aduanas Nacionales) é a autoridade tributária da Colômbia, e cada fatura eletrônica, nota de crédito e débito, documento de suporte, documento de folha de pagamento e evento passa pelo seu sistema de faturamento eletrônico. Uma conta ali guarda tudo o que a empresa ou pessoa emitiu e recebeu. Estes endpoints leem essa conta com a conexão própria do contribuinte. ## Conecte sua conta O sistema de faturamento eletrônico da DIAN não tem senha: o acesso é um link que a DIAN envia ao e-mail registrado no RUT de quem o solicita (para uma empresa, seu representante legal). Solicite-o com o endpoint de solicitações de acesso abaixo, ou no sistema de faturamento eletrônico da DIAN, e registre o link aqui dentro dos 60 minutos em que a DIAN o aceita. A DIAN mantém esse acesso aberto por cerca de uma hora, então registre o link quando for consultar e rode o que precisar nessa janela. Depois, as consultas respondem `422 connection_rejected`: solicite um link novo e registre-o de novo, e a mesma conexão é renovada, mantendo seu id. `POST /co/dian-facturacion/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 | | - | - | - | | `access_link` | string | **Obrigatório.** O link completo do e-mail da DIAN, como chegou. A DIAN o aceita por 60 minutos. | | `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-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" } } ``` 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`. Registrar uma conta que já está conectada a renova: a conexão recebe os novos valores, mantém seu id e responde `200`, então nada que guarde o id precisa mudar. Como o fluxo funciona, passo a passo: [Conexões](/pt/connections). Liste e exclua: ```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](/pt/mcp-server), os mesmos verbos são as ferramentas `dian_facturacion_connect`, `dian_facturacion_list_connections`, `dian_facturacion_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. | | 422 | `connection_limit_reached` | A organização já tem 5 conexões para esta fonte (ao registrar). | > [!NOTE] > > 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. ## Solicitações de acesso `POST /co/dian-facturacion/access-requests/v1` [Live](/pt/live-lookups) Faça a DIAN enviar o link de acesso com que uma conexão é registrada, sem sair do seu produto: a pessoa (ou o representante legal da empresa) o recebe no e-mail do seu RUT. | Campo | Tipo | Notas | | - | - | - | | `document_type` | enum | O tipo de documento da pessoa para quem é o acesso: `CC`, `CE`, `TI`, `RC`, `PA` ou `NIT`. Por padrão `CC`. | | `document_number` | string | **Obrigatório.** 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" }' ``` ## Resposta `sent` é `true` quando a DIAN aceitou a solicitação e enviou o link ao e-mail do RUT da pessoa; `message` é a resposta da DIAN. O link vale por `expires_in_minutes` (60). Registre-o como conexão dentro desse tempo. > [!NOTE] > > Esta chamada roda sem conexão: é assim que uma começa. É cobrada como qualquer outra chamada. ## Documentos emitidos `POST /co/dian-facturacion/issued-documents/v1` [Live](/pt/live-lookups) | Campo | Tipo | Notas | | - | - | - | | `from_date` | string | **Obrigatório.** Primeira data de emissão a incluir, `yyyy-mm-dd`. | | `to_date` | string | **Obrigatório.** Última data de emissão a incluir, `yyyy-mm-dd`, no máximo um ano depois de `from_date`. Para um período mais longo, chame uma vez por ano. | | `connection_id` | string | A conexão com que se consulta. Cada conexão lê os documentos da própria conta, então com mais de uma na sua organização é obrigatório; sem ele a chamada 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" }' ``` ## Resposta | Campo | Notas | | - | - | | `from_date`, `to_date` | Repetem o intervalo. | | `taxpayer` | O `nit` e o `name` da conta. | | `count` | Quantidade de documentos retornados. | | `by_type[]` | Quantidade e `total` somado por tipo de documento. | | `documents[]` | Um por documento eletrônico (abaixo). | Cada documento tem seu `cufe` (a chave), `document_type_code` e `document_type`, `series` e `number`, `issued_on` e `received_at`, o `issuer` e o `recipient` (`nit`, `name`), `currency`, `payment_form` e `payment_method` (códigos da DIAN), cada imposto que a DIAN totaliza em `taxes` e as `withholdings` (ReteIVA, ReteRenta, ReteICA), o `total`, o `status` de validação da DIAN e seu `radian_status` como título-valor. Além de faturas, as listas trazem notas de crédito e débito, documentos de suporte, folha de pagamento e os eventos (application responses) que a conta emitiu ou recebeu. ```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 chamada lê a DIAN ao vivo com a sua conexão, então a resposta está > atualizada e nunca é compartilhada entre organizações. > [!NOTE] > > 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`. ## Documentos recebidos `POST /co/dian-facturacion/received-documents/v1` [Live](/pt/live-lookups) A mesma forma que os documentos emitidos. | Campo | Tipo | Notas | | - | - | - | | `from_date` | string | **Obrigatório.** Primeira data de emissão a incluir, `yyyy-mm-dd`. | | `to_date` | string | **Obrigatório.** Última data de emissão a incluir, `yyyy-mm-dd`, no máximo um ano depois de `from_date`. Para um período mais longo, chame uma vez por ano. | | `connection_id` | string | A conexão com que se consulta. Cada conexão lê os documentos da própria conta, então com mais de uma na sua organização é obrigatório; sem ele a chamada 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 chamada lê a DIAN ao vivo com a sua conexão, então a resposta está > atualizada e nunca é compartilhada entre organizações. > [!NOTE] > > 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`. ## Um documento `POST /co/dian-facturacion/document/v1` [Live](/pt/live-lookups) | Campo | Tipo | Notas | | - | - | - | | `cufe` | string | **Obrigatório.** CUFE/CUDE (unique electronic-document code) or UUID of the document. | | `issued_on` | string | **Obrigatório.** The document's issue date, `yyyy-mm-dd`, as the issued or received documents list it (`issued_on`). | | `connection_id` | string | A conexão com que se consulta. Cada conexão lê os documentos da própria conta, então com mais de uma na sua organização é obrigatório; sem ele a chamada 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" }' ``` ## Resposta `found` diz se a conta tem o documento nessa data; quando é `false` o resto vem vazio. Caso contrário, você recebe o cabeçalho do documento (`document_type`, `series`, `number`, `issued_on`, `issued_at`, `due_on`, `issuer`, `recipient`, `currency`, `payment_form`, `payment_method`, `notes`), suas `lines` (`description`, `quantity`, `unit`, `unit_price`, `line_total` e os `taxes` de cada linha), seus próprios `totals`, os `taxes` e o `total` como o registro da DIAN os mostra, o `legitimate_holder`, as `validations` da DIAN, seus `events` (acuse de recibo, recibo del bien, aceptación, endoso...) e os arquivos originais: `xml` (UBL 2.1) e `pdf_base64`. Folha de pagamento, documentos de suporte e eventos não trazem linhas nem arquivos aqui; seu cabeçalho, validações e eventos sim. > [!NOTE] > > Pegue `cufe` e `issued_on` de uma linha dos documentos emitidos ou recebidos. > [!NOTE] > > 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`. ## Relatório mensal `POST /co/dian-facturacion/monthly-reports/v1` [Live](/pt/live-lookups) A DIAN o emite às contas que faturam eletronicamente, normalmente nas primeiras semanas do mês seguinte. | Campo | Tipo | Notas | | - | - | - | | `year` | integer | **Obrigatório.** The report's year. | | `month` | integer | **Obrigatório.** The report's month, 1 to 12. | | `connection_id` | string | A conexão com que se consulta. Cada conexão lê os documentos da própria conta, então com mais de uma na sua organização é obrigatório; sem ele a chamada 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 }' ``` ## Resposta `available` diz se a DIAN emitiu um relatório para o mês; quando é `false` o resto vem vazio. Um relatório traz sua `reference`, `dated_on`, `cutoff_date` e `replaces_previous`; `documents[]` com, por tipo de documento, o `issued` e o `received` (`month_count`, `month_amount`, `year_count`, `year_amount`); e `indicators[]` do mês e dos dois anteriores (`count`, `daily_average_count`, `amount`, `daily_average_amount`, emitidos e recebidos). > [!NOTE] > > 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`. ## Perfil `POST /co/dian-facturacion/profile/v1` [Live](/pt/live-lookups) | Campo | Tipo | Notas | | - | - | - | | `connection_id` | string | A conexão com que se consulta. Cada conexão lê os documentos da própria conta, então com mais de uma na sua organização é obrigatório; sem ele a chamada 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 '{}' ``` ## Resposta O `nit`, `name`, `business_name` e `email` da conta, seu `status` no sistema de faturamento eletrônico da DIAN, o `reception_email` onde recebe faturas, seus `legal_representatives`, seus `operation_modes` (software próprio, de um provedor tecnológico ou o da DIAN) e os `numbering_ranges` associados ao seu software (`prefix`, `resolution`, `from_number`, `to_number`, `associated_on`, `expires_on`). > [!NOTE] > > 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`. > **[Referência completa](/pt/api-reference/overview)** > > 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.