Gestión de errores de la API: códigos de estado HTTP y mensajes de error

Cuando surge un problema, la API de faktoora devuelve códigos de estado HTTP estandarizados y mensajes de error descriptivos. Este artículo le ayuda a comprender y solucionar los errores más habituales.

HTTP 404: factura no encontrada

Si intenta obtener o modificar una factura a través de la API y recibe un error 404, significa que no se ha encontrado el recurso solicitado.

Causas habituales:

• faktooraId incorrecto: compruebe que utiliza el faktooraId correcto. Este se devolvió en la respuesta de creación de la factura, en faktooraId.
• Creación asíncrona de facturas: si desea obtener una factura con GET inmediatamente después de crearla, puede producirse un 404. La API responde a las solicitudes POST con 202 Accepted y un faktooraId. La factura se procesa de forma asíncrona y es posible que durante un breve tiempo no se pueda obtener. Utilice el faktooraId indicado para consultar el estado o utilice webhooks para recibir una notificación cuando finalice el procesamiento.
• La factura se ha eliminado: la factura solicitada ya no existe en el sistema.

Solución:

Valide el faktooraId de su solicitud. Para facturas recién creadas: espere unos segundos o compruebe el estado de procesamiento con GET /invoices/{faktooraId}/status antes de acceder al registro completo de la factura.

HTTP 400: solicitud incorrecta

Un error HTTP 400 indica un problema de validación en la solicitud enviada. Es el error más frecuente en la integración con la API.

Parámetros obligatorios incorrectos o ausentes

Causas:

• Faltan campos obligatorios (p. ej., invoiceNumber, issueDate, buyer, seller)
• Los formatos de los campos son incorrectos (p. ej., la fecha no tiene el formato YYYYMMDD)
• Valores desconocidos o no válidos en campos enumerados (p. ej., invoiceTypeCode)

Solución:

Consulte la documentación de la API o el esquema OpenAPI para conocer los campos obligatorios y sus rangos de valores válidos. La respuesta de error contiene indicaciones sobre el campo incorrecto.

Error de validación en números decimales: "must be multiple of 0.01"

Si transmite importes en el array allowance (descuentos o recargos) o en otros campos monetarios, todos los números decimales deben limitarse a un máximo de 2 decimales.

El error se produce con:

• allowance[].amount con más de 2 decimales (p. ej., 10.005 en lugar de 10.00)
• Problemas similares con otros campos de importes monetarios

Solución:

Redondee todos los importes monetarios a 2 decimales. Ejemplo:

{
  "allowance": [
    {
      "indicator": "discount",
      "reason": "Mengenrabatt",
      "amount": 10.50,
      "taxes": [
        {
          "typeCode": "VAT",
          "categoryCode": "S",
          "rate": 19
        }
      ]
    }
  ]
}

HTTP 400: "Docx template is disabled"

Este mensaje de error significa que ha intentado utilizar una plantilla DOCX o Typst al crear la factura, pero la función de plantillas no está activada.

Causas:

• Su cuenta no tiene activadas las funciones de plantillas
• Transmite el campo template en la solicitud aunque la función no está habilitada

Solución:

Hay dos posibilidades:

1. Omitir el campo de plantilla: elimine el objeto template de la solicitud para utilizar la plantilla de factura estándar.
2. Activar la función: póngase en contacto con el soporte de faktoora para habilitar las funciones de plantillas (plantillas DOCX o Typst) en su cuenta.

Cuando las funciones estén activadas, podrá indicar el nombre de su plantilla personalizada con el parámetro template.label.

El descuento o recargo (allowance) no se muestra en el PDF

Si transmite datos de allowance en la API, pero no aparecen en el PDF de la factura generado o no se descuentan del importe total, puede haber varias causas.

Causas habituales:

• Faltan tipos impositivos: cada entrada de allowance requiere un array taxes con al menos una entrada VAT. Sin una configuración fiscal correcta, es posible que se ignore la allowance.
• El formato de factura no admite allowances: no todos los formatos de factura (p. ej., las facturas PDF simples en formato simple) admiten allowances. Las allowances se procesan correctamente en los formatos estructurados (ZUGFeRD, XRechnung).

Solución:

Asegúrese de que:

1. Cada entrada de allowance contiene un array taxes con al menos una entrada:

"taxes": [
  {
    "typeCode": "VAT",
    "categoryCode": "S",
    "rate": 19
  }
]

2. Utiliza un formato de factura estructurado que admita allowances (format: "zf:2" o format: "xrechnung").

HTTP 500: error interno del servidor

Un error 500 significa que se ha producido un error inesperado en el servidor. El error Cannot read properties of undefined indica un error similar a un puntero nulo en el código.

Causas habituales:

• Estructuras de datos no válidas o incoherentes: los campos están presentes, pero su contenido no cumple lo esperado.
• Faltan vinculaciones necesarias: si hace referencia a un objeto (p. ej., a un cliente mediante buyer.faktooraCustomerId), es posible que la referencia no se resuelva.
• Error temporal: los errores 500 ocasionales también pueden deberse a interrupciones técnicas del servidor.

Solución:

1. Compruebe que su solicitud esté completa y sea válida, en especial las referencias a recursos externos (ID de clientes, ID de plantillas).
2. Vuelva a enviar la solicitud pasado un breve tiempo.
3. Si el error persiste, póngase en contacto con el soporte de faktoora e indique:
   • La solicitud exacta a la API (sin claves ni datos sensibles)
   • La marca de tiempo del error
   • La respuesta o el mensaje de error que ha recibido

Buenas prácticas para una integración con la API sin errores

• Valide localmente: compruebe sus datos antes de enviarlos a la API: formatos, campos obligatorios, restricciones de longitud.
• Utilice el entorno de demostración: pruebe primero con https://api.demo.faktoora.com/api/v1 en lugar del entorno de producción https://api.faktoora.com/api/v1.
• Gestione el procesamiento asíncrono: la creación de facturas es asíncrona. No consulte el estado inmediatamente después; utilice webhooks o consultas periódicas (polling) con un intervalo.
• Registre las respuestas: guarde la respuesta completa de la API, especialmente en errores 400 y 500; contiene la indicación del campo incorrecto.
• Consulte la documentación: la documentación OpenAPI contiene todos los requisitos de cada endpoint.