Troubleshooting

”Recibo 401 Unauthorized”

1. Verificar que el header sea X-Api-Key (no Authorization).
2. La key completa, sin espacios al inicio/final.
3. Comienza con lxs_live_.
4. No está revocada (debe consultarse al administrador).

”Recibo 403 Forbidden”

La key no tiene el scope. El mensaje de error nombra cuál falta. Debe solicitarse al administrador que lo agregue:

• facturas:read para GET sobre /facturas.
• facturas:write para POST /facturas con tipo FE o TE.
• notas:write para POST /facturas con tipo NC o ND.
• facturas:anular para DELETE /facturas/{clave}.
• facturas-compra:write para POST /facturas-compra.
• facturas-compra:read para GET /facturas-compra/{clave} y /pdf.

”Recibo 400 al emitir una NC o ND y el mensaje no dice qué falta”

Lo primero a revisar es el código de motivo de la referencia. El sistema espera un código de 2 dígitos del catálogo en referencias[0].codigo o en referencias[0].razon. Una referencia con solo texto libre en ambos campos no emite:

"referencias": [
  { "tipoDocumento": "01", "numero": "5062508…", "razon": "Cargo por interés moratorio" }
]

El mensaje del 400 lista los códigos que acepta el tenant. Con el código presente en cualquiera de los dos campos, la emisión pasa:

"referencias": [
  { "tipoDocumento": "01", "numero": "5062508…", "codigo": "10", "razon": "Cargo por interés moratorio" }
]

Lo segundo es el idUsuario: debe existir en el tenant. Los ejemplos de esta documentación usan 7, pero cada tenant tiene sus propios ids — el que corresponda lo entrega el administrador junto con la API key.

”Pedí moneda: CRC y el comprobante salió en USD”

No es un error del request. Si el tenant no está habilitado para multi-moneda, el comprobante se emite en su moneda principal aunque se pida otra, y la respuesta devuelve la moneda con la que realmente se emitió. Hay que solicitar al administrador que habilite multi-moneda en el tenant.

En una NC o ND hay además una regla propia: hereda la moneda del documento que referencia, porque Hacienda exige que coincidan. Ver multi-moneda.

”El monto salió mucho más bajo de lo esperado”

Probablemente la línea se emitió sin precioUnitario en una moneda distinta a la del catálogo del tenant. El precio de lista se convierte con el tipo de cambio, pero conviene enviar precioUnitario explícito cuando el sistema del integrador ya maneja sus propios precios: es la forma más predecible de integrar.

Si el monto quedó en cero al consultar un comprobante que se emitió con un monto correcto, revisar si se le emitió una nota de crédito: una NC total deja el documento acreditado en cero.

”Recibo 400 con Producto X no encontrado”

El producto no existe en el catálogo del tenant. Soluciones:

1. Crear el producto en el POS.
2. Usar otro idProducto válido.
3. Verificar que se está apuntando al tenant correcto (prefijo de la key).

”Mi comprobante se queda en procesando por horas”

Causas posibles:

1. Hacienda saturada (cierre de mes, declaraciones).
2. Certificado P12 expirado en el tenant.
3. Credenciales Hacienda incorrectas.

Si transcurren más de 30 minutos, debe escalarse a soporte.

”Hacienda rechaza con código 9015”

Es un fallo de validación contra los catálogos oficiales. Debe revisarse que los siguientes campos estén dentro de los valores permitidos por Hacienda:

• condicionVenta.
• medioPago.
• tipoIdentificacion del cliente.

”Mi webhook no llega”

Debe revisarse la sección de webhooks: verificar que el webhookUrl esté configurado, que el endpoint receptor responda 2xx con prontitud y que no esté bloqueado por firewall.

”Recibo 429 constantemente”

Se está excediendo el límite de 120/min. Soluciones:

1. Implementar rate-limiting del lado del integrador.
2. Distribuir la carga en múltiples keys (si se administran varios tenants).
3. Solicitar a soporte un aumento del límite.