Ir al contenido

Consultar documento

GET
/v1/documents/{id}
curl --request GET \
--url https://example.com/v1/documents/example \
--header 'Authorization: Bearer <token>'
id
required
string

Id del documento

X-Tenant-Id
string

Id o NIT del facturador. Obligatorio con llaves de cuenta; ignorado con llaves restringidas.

El documento

Media typeapplication/json
object
data
required

El documento

object
id
required

Id del documento

string
kind
required

Tipo de documento

string
Allowed values: invoice credit_note debit_note support_document support_document_adjustment pos_document pos_credit_adjustment pos_debit_adjustment payroll payroll_adjustment radian_event
status
required

Pending → sent → accepted / rejected; retrying y failed cuando la DIAN no responde

string
Allowed values: pending sent retrying accepted rejected failed
environment
required

Ambiente DIAN: 1 = producción, 2 = habilitación (pruebas)

string
Allowed values: 1 2
sandbox
required

True cuando se emitió con una API key de sandbox (DIAN simulada, sin consumir bolsa)

boolean
number
required

Número completo (prefijo + consecutivo)

string
prefix
required

Prefijo del rango de numeración (puede estar vacío)

string
consecutive
required

Consecutivo dentro del rango

integer
>= -9007199254740991 <= 9007199254740991
uniqueCode
required

CUFE, CUDE, CUDS o CUNE

string
uniqueCodeScheme
required

Tipo y algoritmo del código único, ej. CUFE-SHA384

string
issuedAt
required

Cuándo se emitió; la fecha y hora del XML son este instante en hora de Bogotá

string format: date-time
summary
required

Sus valores y su contraparte

object
total
required

Valor del documento: el total a pagar, o el total de la nómina

string
subtotal

Valor antes de impuestos (en nómina, los devengados)

string
taxes

Impuestos (en nómina, las deducciones)

string
currency
required

Moneda, ISO 4217

string
counterpartyId

Número de identificación de la contraparte: el comprador, el vendedor o el empleado

string
counterpartyName

Nombre de la contraparte

string
qrData
required

Contenido del código QR de la representación gráfica

string
dian
required

Lo que respondió la DIAN

object
statusCode
required

Último código de estado de la DIAN: 00 procesado correctamente, 99 rechazado (null: aún sin respuesta)

string | null
statusMessage
required

Último texto de estado de la DIAN (null: aún sin respuesta)

string | null
errors
required

Reglas de validación que la DIAN reportó

Array<string>
zipKey
required

Llave de seguimiento de la DIAN (ZipKey), para documentos enviados al set de pruebas (null en los demás)

string | null
attempts
required

Cuántas veces se envió o se consultó su estado

integer
>= -9007199254740991 <= 9007199254740991
nextAttemptAt
required

Cuándo toca el próximo envío o consulta (null: ninguno pendiente)

Any of:

Fecha y hora en UTC (ISO 8601)

string format: date-time
lastError
required

Último error transitorio (la DIAN caída, un timeout); null una vez pasa

string | null
referencedDocumentId
required

Documento al que hace referencia: una nota, a su factura; un ajuste, a su nómina (null: ninguno)

string | null
acceptedAt
required

Cuándo lo aceptó la DIAN (null: no aceptado)

Any of:

Fecha y hora en UTC (ISO 8601)

string format: date-time
createdAt
required

Cuándo se creó

string format: date-time
updatedAt
required

Cuándo cambió por última vez

string format: date-time

Example

{
"data": {
"kind": "invoice",
"status": "pending",
"environment": "1",
"issuedAt": "2026-01-15T15:30:00.000Z",
"nextAttemptAt": "2026-01-15T15:30:00.000Z",
"acceptedAt": "2026-01-15T15:30:00.000Z",
"createdAt": "2026-01-15T15:30:00.000Z",
"updatedAt": "2026-01-15T15:30:00.000Z"
}
}

La petición no cumple el esquema (VALIDATION_ERROR, con details por campo)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}

Falta la credencial o no es válida (UNAUTHORIZED)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}

La llave no puede hacer esto (FORBIDDEN)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}

No existe, o no es de esta cuenta (NOT_FOUND)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}

Conflicto con el estado actual (CONFLICT, INVALID_STATE)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}

Regla de negocio (VALIDATION_ERROR, NUMBERING_*, CERTIFICATE_UNAVAILABLE…)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}

Demasiadas peticiones para esta cuenta (RATE_LIMITED; vea X-RateLimit-* y Retry-After)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}

Error del servicio o de la DIAN (DIAN_UNAVAILABLE, DIAN_PROTOCOL_ERROR)

Media typeapplication/json

Un error: un código estable para los programas y un mensaje para los desarrolladores

object
error
required

El error

object
code
required

Código estable (VALIDATION_ERROR, NOT_FOUND, INSUFFICIENT_BALANCE…)

string
message
required

Qué salió mal, para desarrolladores (puede cambiar; compare por code)

string
details

Datos que lo explican (el campo, el valor esperado…); en un error de esquema, los campos que fallaron y por qué

requestId

Id de la petición, para soporte

string

Example generated

{
"error": {
"code": "example",
"message": "example",
"details": "example",
"requestId": "example"
}
}