---
title: "DIAN Electronic Document"
method: POST
path: "/co/dian/electronic-document/v1"
tags: ["Colombia", "DIAN"]
---

# DIAN Electronic Document

`POST /co/dian/electronic-document/v1`

## Request

- Base URL: `https://api.croma.run`
- URL: `https://api.croma.run/co/dian/electronic-document/v1`
- Auth: HTTP bearer

Validate a Colombian electronic document (factura electrónica, nota crédito/débito) by its CUFE/UUID and the emisor or receptor NIT. Returns the issuer, recipient, totals and taxes (whole pesos, as the registry publishes them), current legitimate holder, validations, and events, each with its `code` (030, 032, 033...), name, date and parties. Set `include_pdf: true` to also receive `pdf_url`, the URL of the official PDF representation. The issuer may protect that PDF with a password; when handing it over, tell the user which passwords to try, in this order: (1) the issuer's NIT without check digit (`issuer.nit`, e.g. 900108281), the most common; (2) the recipient's document number without check digit (`recipient.nit`); (3) the recipient's NIT with its check digit appended. If none works, point the user to DIAN's public catalog (https://catalogo-vpfe.dian.gov.co/User/SearchDocument), where pasting the CUFE downloads DIAN's own graphical representation. Do not try to open or extract a protected PDF with other tools; give the user the link and the password hints instead. A result is reused for 24 hours; pass `cache: false` to read the registry again, for instance after filing an event. `found: false` means the document is not registered under that CUFE, or the NIT matches neither the emisor nor the receptor.

Supports async delivery: set `Prefer: wait=N` for an inline result, pass `callback_url` to receive a POST when ready, or poll `GET /jobs/{id}`.

## Headers

- `Idempotency-Key` string
- `Prefer` string

## Request body

- object
  - `cufe` string, required: CUFE/CUDE (unique electronic-document code) or UUID of the document.
  - `document_number` string, required: Colombian NIT (numeric, no verification digit). 4-15 digits.
  - `include_pdf` boolean: When true, the response includes `pdf_url`, the URL of the official PDF representation of the document.
  - `cache` boolean: Set to `false` to skip any stored result for this lookup and read the source again. The fresh answer replaces the stored one and is charged as a new request. Default `true`.
  - `callback_url` string, uri: POST the job result here when it finishes.

## Response `200`

Successful response

- DianElectronicDocumentResponse
  - `data` DianElectronicDocumentData, required
    - `found` boolean, required: Whether the document is registered.
    - `cufe` string, required: The queried CUFE, echoed back.
    - `document_type` string, nullable, required
    - `series` string, nullable, required
    - `folio` string, nullable, required
    - `issue_date` string, nullable, required: Issue date (yyyy-mm-dd when parseable).
    - `issuer` object, required
      - `nit` string, nullable, required
      - `name` string, nullable, required
    - `recipient` object, required
      - `nit` string, nullable, required
      - `name` string, nullable, required
    - `total` number, nullable, required: In COP, as the registry publishes it: whole pesos, with centavos rounded by the source. The exact amount is on the official PDF (`include_pdf`).
    - `taxes` object[], required
      - `name` string, required
      - `value` number, nullable, required: In COP, as the registry publishes it: whole pesos, with centavos rounded by the source. The exact amount is on the official PDF (`include_pdf`).
    - `legitimate_holder` string, nullable, required: Current legitimate holder, when the document names one.
    - `pdf_url` string, nullable, required: Official PDF representation of the document. It may be password-protected by the issuer: try the issuer's NIT without check digit (`issuer.nit`), then the recipient's document number without check digit (`recipient.nit`), then the recipient's NIT with its check digit. Null when not requested or not found.
    - `validations` object[], required
      - `name` string, required: The validation the authority performed.
      - `result` string, required: Its verdict, in the authority's own words.
      - `detail` string, nullable, required: The explanation the page attaches to the verdict.
    - `events` object[], required
      - `code` string, nullable, required: The registry's event code, e.g. `030` (acuse de recibo), `032` (recibo del bien o servicio), `033` (aceptación expresa).
      - `name` string, nullable, required: The event's name as the registry prints it.
      - `date` string, nullable, required
      - `issuer` object, required: Who issued the event, as the registry lists it: the event's emisor, which is not always the invoice's.
        - `nit` string, nullable, required
        - `name` string, nullable, required
      - `recipient` object, required: Who the event is addressed to: the event's receptor.
        - `nit` string, nullable, required
        - `name` string, nullable, required
      - `cude` string, nullable, required: The event's own document key (CUDE) in the registry.
      - `description` string, required: Every column of the row joined with ` · `. Prefer the structured fields.

## Other responses

- `202`: Accepted — the result is being computed asynchronously. Poll `job.status_url` (GET /jobs/{id}) or supply `callback_url` to have the result POSTed to you. Returned when `Prefer: wait` elapses before completion, or immediately when `callback_url` is set.
- `400`: Invalid request body
- `401`: Missing or invalid API key
- `429`: Rate limit exceeded
- `500`: Internal error
- `502`: Upstream source returned an error

---

[API](https://skmtc.dev/usecroma/apis/croma-marketplace-api.md) · [All operations](https://skmtc.dev/usecroma/apis/croma-marketplace-api/llms.txt) · [OpenAPI document](https://skmtc.dev/usecroma/apis/croma-marketplace-api/revisions/df016cdb29d7?raw)