Faturamento eletrônico DIAN

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.

curl https://api.croma.run/co/dian-facturacion/connections/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "access_link": "<access link from the DIAN email>",
        "authorized": true
      }'

{
  "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. Liste e exclua:

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

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

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.

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

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

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.

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

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.

Documentos recebidos

POST /co/dian-facturacion/received-documents/v1 Live 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`.

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

Cada chamada lê a DIAN ao vivo com a sua conexão, então a resposta está atualizada e nunca é compartilhada entre organizações.

Um documento

POST /co/dian-facturacion/document/v1 Live

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

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.

Pegue cufe e issued_on de uma linha dos documentos emitidos ou recebidos.

Relatório mensal

POST /co/dian-facturacion/monthly-reports/v1 Live 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`.

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

Perfil

POST /co/dian-facturacion/profile/v1 Live

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

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

Referência completa

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

Primeiros passos

Tipos de solicitação

Monitores

Países

Faturamento eletrônico DIAN

Conecte sua conta

Solicitações de acesso

Resposta

Documentos emitidos

Resposta

Documentos recebidos

Um documento

Resposta

Relatório mensal

Resposta

Perfil

Resposta

Referência completa

​Conecte sua conta

​Solicitações de acesso

​Resposta

​Documentos emitidos

​Resposta

​Documentos recebidos

​Um documento

​Resposta

​Relatório mensal

​Resposta

​Perfil

​Resposta

Referência completa

Conecte sua conta

Solicitações de acesso

Resposta

Documentos emitidos

Resposta

Documentos recebidos

Um documento

Resposta

Relatório mensal

Resposta

Perfil

Resposta