Apariencia
Errores
Las respuestas de error son JSON con success: false y un message que explica la causa. Cuando hay varios errores de validación en una misma solicitud, suelen venir juntos en message, separados por espacios (algunas operaciones los devuelven en un arreglo; ver cada página).
json
{
"success": false,
"message": "El campo Correo del Cliente en la guía 123456 es obligatorio."
}Códigos HTTP
| HTTP | Significado |
|---|---|
200 | Solicitud procesada. En las operaciones por lote puede haber documentos rechazados (por ejemplo, duplicados): revisa la lista de errores de la respuesta. |
400 | Datos inválidos o faltantes. message indica el campo. |
401 | Token ausente, inválido o vencido. Pide un token nuevo. |
404 | La operación no existe (URL mal escrita), o no se encontró el negocio, la factura o el cliente indicados. |
409 | Conflicto: el número de documento ya está registrado (o todo el lote lo estaba), no quedan números de control, se alcanzó el límite del plan, u otra emisión del mismo tipo está en curso (reintenta en unos segundos). |
412 | El token no corresponde al negocio. |
500 | Error al guardar o error interno. Si se repite, contacta a soporte con la hora y la operación. |
Regla práctica
Considera exitosa una solicitud solo si el HTTP es 200 y success es true, y revisa las listas de errores por documento que traen las operaciones por lote. Ante un 4xx/5xx, lee igualmente el cuerpo JSON: message explica la causa.
Autenticación
| HTTP | Mensaje | Causa |
|---|---|---|
| 400 | El token de autorización es obligatorio. | Falta el encabezado Authorization. |
| 400 | El formato del token es inválido. | El encabezado no tiene la forma Bearer <token>. |
| 401 | Usuario no autorizado. | El token no es válido para ningún negocio. |
| 401 | Token expirado | El token venció (dura una hora). Pide uno nuevo. |
| 401 | Firma del token inválida | El token fue modificado o no lo emitió este servicio. Pide uno nuevo. |
| 401 | Token inválido o ausente. | Variante usada por Enviar documento, Anular factura y Anular retención. |
| 412 | Documento rif incorrecto | El token no corresponde al RIF del negocio. |
INFO
Algunas respuestas traen además la clave antigua status (errores de token, métodos de pago, bancos, facturas, códigos ISLR) o Mensaje (emisión de retenciones). Todas incluyen también success y message con el mismo valor: usa siempre success/message.
Al pedir el token (Solicitar token):
| HTTP | Mensaje |
|---|---|
| 401 | No introdujo usuario y/o Contraseña. |
| 401 | No existe coincidencia de usuario en la Base de Datos. |
Negocio emisor
| Mensaje | Causa |
|---|---|
Tipo de contribuyente no establecido. Para continuar con la emisión de documentos fiscales, es necesario establecer el tipo de contribuyente… | El negocio no tiene configurado su tipo de contribuyente. Contacta a soporte de CG Imprenta Digital. |
No se encontró el negocio asociado al usuario. | El usuario de API no tiene un negocio activo. |
No existe un número de control asociado al comercio. · El comercio no posee más números de control activos. · No hay números de control disponibles. | (409) Se agotaron los números de control del negocio. Hay que adquirir más antes de emitir. |
Cuerpo de la solicitud
| Mensaje (ejemplos) | Causa |
|---|---|
Json de facturas no enviado. · Json de guías de despacho no enviado. | (400) El cuerpo llegó vacío. Verifica Content-Type: application/json. |
El JSON enviado es inválido o está mal formado. | JSON con comas sobrantes, comillas faltantes, etc. |
El campo … es obligatorio. | Falta un campo obligatorio; el mensaje indica cuál y en qué documento. |
Cantidad de Facturas Incorrecta. | (400) El campo de cantidad no coincide con la cantidad de documentos enviados en el lote. |
