Consultar estado y descargar

Cuándo consultar

• El envío fue asíncrono (recibiste ZipKey / trackId y aún no el resultado final).
• Quieres reconsultar la DIAN con el CUFE.
• Necesitas el PDF/XML después de emitir.

Regla rápida

• Estado del ZIP → usa el ZipKey (XmlDocumentKey / trackId de lote).
• Estado del documento / eventos → usa el CUFE (UUID de 96 caracteres).

Endpoints autenticados (recomendados)

Base: {{base_url}}/api/ubl2.1
Header: Authorization: Bearer <token_empresa>

Estado por ZipKey

POST /api/ubl2.1/status/zip/{ZipKey}
Authorization: Bearer <token>

Estado por CUFE

POST /api/ubl2.1/status/document/{CUFE}
Authorization: Bearer <token>

Eventos RADIAN del documento

POST /api/ubl2.1/status/events-document/{CUFE}
Authorization: Bearer <token>

XML por trackId

POST /api/ubl2.1/xml/document/{trackId}
Authorization: Bearer <token>

Descargar archivo (PDF / XML / ZIP)

GET /api/ubl2.1/download/{nit}/{nombre_archivo}
Authorization: Bearer <token>

El nombre_archivo es el que devolvió la emisión (p. ej. fv…pdf, fv…xml).
También puedes regenerar representación gráfica:

POST /api/ubl2.1/regeneratepdf
Authorization: Bearer <token>
Content-Type: application/json

o por URL:

POST /api/ubl2.1/regeneratepdf/{prefix}/{number}/{cufe}

Endpoints legacy (sin Bearer, con certificado)

Útiles si trabajas a bajo nivel (mismo SOAP DIAN). Body típico:

{
  "certificate": "<base64_p12>",
  "password": "clave_certificado",
  "ambiente": "PRODUCCION",
  "zipkey": "…",
  "cufe": "…"
}

Ruta	Usa
POST /api/ubl2.1/statuszip	campo zipkey
POST /api/ubl2.1/statusdocument	campo cufe

ambiente: HABILITACION (Sandbox) o PRODUCCION.

Flujo práctico tras emitir

1. Guarda de la respuesta: cufe, ZipKey / XmlDocumentKey, nombres de PDF/XML.
2. Si IsValid ya viene true → listo; descarga con /download/....
3. Si quedó pendiente → poll status/zip/{ZipKey} cada 5–15 s (máx. unos minutos).
4. Con CUFE puedes siempre reconsultar status/document/{CUFE}.

Utilidades relacionadas

Endpoint	Uso
POST /api/ubl2.1/next-consecutive	Siguiente consecutivo sugerido
GET /api/ubl2.1/invoice/current_number/{type}/{prefix?}	Consecutivo actual por tipo
POST /api/ubl2.1/numbering-range	Rangos DIAN de numeración
GET /api/ubl2.1/SearchCompany/{nit}	Buscar razón social
POST /api/ubl2.1/join-pdfs	Unir varios PDF

Qué no hay (aún)

GridBilling no envía webhooks a tu sistema cuando DIAN responde. Debes consultar (poll) estado o confiar en la respuesta síncrona del POST de emisión.

Más ejemplos: colección Postman · carpeta 03.