Respuestas y errores

Éxito típico (emisión)

{
  "message": "Documento generado con éxito",
  "send_email_success": true,
  "cufe": "…",
  "responseDian": {
    "IsValid": "true",
    "StatusCode": "00",
    "StatusDescription": "Procesado Correctamente",
    "XmlDocumentKey": "…",
    "XmlFileName": "…"
  }
}

Guarda siempre: CUFE, ZipKey / XmlDocumentKey, nombres de PDF/XML.

Header de ambiente

Todas las respuestas llevan:

X-GridBilling-Environment: sandbox

o production. Verifica también: GET /api/ubl2.1/environment.

Errores HTTP frecuentes

HTTP	Causa típica	Qué hacer
401	Token ausente / inválido / de otro ambiente	Usa el Bearer del mismo host
403	Sin permiso (ruta admin, etc.)	Revisa si el endpoint es de integrador
404	Recurso no encontrado	Ruta o ID incorrecto
422	Validación Laravel / regla de negocio	Lee errors / message del JSON
429	Throttle (p. ej. registro)	Espera y reintenta
5xx	Error servidor / DIAN caído	Reintenta; si persiste, WhatsApp con NIT + ambiente

Error DIAN (IsValid = false)

"responseDian": {
  "IsValid": "false",
  "StatusCode": "…",
  "StatusDescription": "…",
  "ErrorMessage": ["…"]
}

Checklist rápido:

1. Resolución vigente y prefijo correcto
2. Consecutivo dentro del rango
3. Certificado no vencido (PUT /api/ubl2.1/certificate-end-date)
4. Software ID / PIN correctos
5. Municipio, impuestos y totales coherentes
6. En Sandbox: ambiente DIAN = habilitación

Luego reconsulta con Consultar estado.

Cupo agotado (producción / integradores)

Si tu cuenta es integrador con paquete y docs_left = 0, la emisión se rechaza hasta comprar más documentos.

• Ver cupo: GET /api/ubl2.1/plan/infoplanuser
• Comprar: Alta y cupos

Empresas internas GridPOS sin paquete de integrador no aplican este límite.

Token / host cruzados

Síntoma clásico: 401 o comportamientos raros.

Host	Token
sandbox-api.gridbilling.gridsoft.co	Solo Sandbox
api.gridbilling.gridsoft.co	Solo Producción

No hay webhooks hacia tu app

La API no llama a tu servidor cuando DIAN termina. Debes usar la respuesta síncrona o hacer poll de estado.

Cómo pedir ayuda rápido

Incluye en WhatsApp:

• NIT
• Ambiente (sandbox / production)
• Endpoint
• StatusCode / mensaje ( sin pegar el Bearer completo )

WhatsApp soporte