Preguntas Frecuentes (FAQ)

¿Cómo obtengo mis credenciales de API?

Para obtener tus credenciales de API, primero debes registrarte utilizando el endpoint /api/v1/auth/register. Este proceso te proporcionará un API key y un API secret para cada sucursal que registres. Estas credenciales son únicas y no deben ser compartidas.

¿Cuánto tiempo dura el token JWT?

La duración del token JWT está determinada por el campo token_lifetime que especificaste durante el registro. El valor predeterminado es de 30 días, pero puedes configurarlo entre 1 y 90 días. Se recomienda renovar el token unos días antes de su expiración para evitar interrupciones.

¿Puedo tener múltiples tokens activos simultáneamente?

Sí, el sistema permite tener múltiples tokens activos para diferentes dispositivos o servicios. Cada token es independiente y tiene su propio tiempo de expiración. Esto es útil si necesitas integrar la API en múltiples sistemas o aplicaciones.

¿Debo crear una sucursal para cada punto de venta?

No es obligatorio. Puedes tener múltiples puntos de venta (POS) dentro de una misma sucursal utilizando el campo pos_code. Sin embargo, si los puntos de venta están en diferentes ubicaciones físicas, es recomendable crear sucursales separadas para mantener un mejor control.

¿Qué sucede si hay un error al emitir un documento?

Si hay errores de validación, el sistema responderá con un código 400 y detalles específicos sobre el error. Si hay problemas de conexión con Hacienda, el sistema entrará automáticamente en modo contingencia. En cualquier caso, el sistema proporciona información detallada para identificar y solucionar el problema.

¿Puedo emitir documentos sin conexión a Internet?

Sí, el sistema cuenta con un modo de contingencia que permite emitir documentos cuando no hay conexión disponible. Estos documentos se guardan localmente y se transmiten a Hacienda una vez se restablezca la conexión. Los documentos emitidos en contingencia son completamente válidos fiscalmente.

¿Es necesario calcular manualmente el IVA para cada ítem?

Sí, debes calcular y proporcionar el valor de IVA para cada ítem a través del campo iva_item. El cálculo debe ser exactamente el 13% sobre la base imponible (precio unitario menos descuento dividido entre 1.13). El sistema validará estos cálculos para asegurar su precisión.

¿Cómo manejo las operaciones exentas o no sujetas?

Para operaciones exentas, utiliza el campo exempt_sale en lugar de taxed_sale. Para operaciones no sujetas, utiliza non_subject_sale. Recuerda que un ítem solo puede tener un tipo de venta (gravada, exenta o no sujeta). No debes incluir impuestos para ítems exentos o no sujetos.

Recibo el error "InvalidTotalAmount", ¿qué significa?

Este error indica que los montos calculados no coinciden con los totales declarados. Debes verificar que:

1. La suma de taxed_sale de todos los items coincida con total_taxed
2. El cálculo de impuestos sea exactamente 13% de la base imponible
3. La suma de pagos sea igual al total a pagar

¿Por qué recibo "InvalidDocumentNumber" al registrar un cliente?

Este error ocurre cuando el formato del número de documento no es válido. Asegúrate de que:

• DUI: Formato correcto con guión (00000000-0)
• NIT: 14 dígitos, puede incluir guión
• Otros documentos: Entre 3 y 20 caracteres

¿Por qué recibo el error "InvalidPaymentTotal"?

Este error indica que la suma de los montos en el campo payment_types no coincide con el total_to_pay. Verifica que la suma de todos los pagos declarados sea exactamente igual al total a pagar. Los valores deben coincidir hasta el último centavo.

Recibo "AUTH_TOKEN_EXPIRED" aunque acabo de obtener el token

Este problema generalmente se debe a diferencias en la zona horaria entre tu servidor y el servidor de la API. Asegúrate de que la hora de tu servidor esté correctamente sincronizada con un servidor NTP. Si el problema persiste, verifica que estés utilizando el token más reciente y que el valor de token_lifetime sea adecuado.

¿Puedo invalidar un documento después de 24 horas?

Depende del tipo de documento. Las facturas (código 01) pueden invalidarse hasta 3 meses después de su emisión. Para otros documentos, el límite es de 24 horas. Esta restricción está establecida por normativa del Ministerio de Hacienda.

¿Cuál es la diferencia entre los tipos de invalidación?

• Tipo 1: Sustitución por error - Requiere un documento de reemplazo
• Tipo 2: Anulación simple - No requiere documento de reemplazo
• Tipo 3: Anulación por motivo específico - Requiere documento de reemplazo y justificación detallada

¿Qué sucede con las notas de crédito si la factura original es invalidada?

Si una factura es invalidada, todas las notas de crédito asociadas a ella deben ser invalidadas también. Esto es responsabilidad del emisor. La API no invalida automáticamente los documentos relacionados, por lo que debes gestionar manualmente la invalidación de todos los documentos afectados.

¿Dónde encuentro los códigos de municipio válidos?

Los códigos de municipio se encuentran en el catálogo CAT-013. Debes usar el código correspondiente al departamento indicado en CAT-012. La combinación de departamento y municipio debe ser válida según estos catálogos oficiales del Ministerio de Hacienda.

¿Qué códigos de impuestos debo usar para diferentes tipos de productos?

• Productos estándar: código "20" (IVA 13%)
• Exportaciones: código "C3" (IVA 0%)
• Servicios turísticos: código "59" (5%)
• Combustibles: códigos "D1" (FOVIAL) y "C8" (COTRANS)

Estos códigos se encuentran en el catálogo CAT-015 Tributos.

¿Qué unidades de medida son válidas?

Las unidades de medida válidas están definidas en el catálogo CAT-014. Las más comunes son:

• 59: Unidad
• 58: Docena
• 23: Litro
• 22: Galón
• 36: Libra
• 34: Kilogramo

Para productos tipo servicio o impuesto, se recomienda usar 59 (Unidad).

¿Cómo sé si estoy en modo contingencia?

El sistema entra automáticamente en modo contingencia cuando detecta problemas de conexión. La respuesta incluirá tipoContingencia con un valor del 1 al 5 y tipoTransmision con valor 2. Además, el campo estado tendrá el valor "PENDING" en lugar de "RECEIVED".

¿Los documentos emitidos en contingencia son válidos fiscalmente?

Sí, los documentos emitidos en contingencia son completamente válidos. La única diferencia es que no tendrán el sello de recepción inmediato, pero se obtendrá posteriormente cuando se transmitan a Hacienda. La normativa del Ministerio de Hacienda reconoce explícitamente la validez de estos documentos.

¿Qué ocurre si el sistema de Hacienda no se restablece durante varios días?

El sistema mantendrá los documentos en estado "PENDING" y continuará intentando transmitirlos periódicamente. No hay límite de tiempo para la transmisión posterior, aunque se recomienda mantener respaldos adicionales en casos extremos. Una vez restablecido el servicio, los documentos se enviarán automáticamente.

¿La API tiene algún límite de tasa (rate limit)?

Sí, la API tiene límites de tasa para garantizar la estabilidad del servicio. Por defecto, el límite es de 60 solicitudes por minuto por cliente. Si superas este límite, recibirás un error 429 (Too Many Requests). Si necesitas un límite mayor.

¿La API soporta webhooks para notificaciones?

Actualmente no, pero estamos trabajando en implementar un sistema de webhooks que permitirá recibir notificaciones en tiempo real sobre eventos importantes, como la transmisión exitosa de documentos en contingencia o alertas de errores recurrentes.