Errores y Validación

Entiende las respuestas de error y las reglas de validación.

Qué significa la respuesta

La carga pasa por dos etapas, y solo la primera contesta en la misma llamada:

Validación del archivo (inmediata). Fibek revisa el archivo fila por fila. Si algo no cumple, responde success: false con el detalle por fila y no se procesa nada.
Procesamiento (asíncrono). Si el archivo pasa la validación, queda en cola y se procesa después. Lo que ocurra ahí —filas descartadas porque el cliente o la factura no existen, deduplicaciones, o un fallo del archivo completo— no aparece en la respuesta.

Es decir: success: true significa “el archivo fue aceptado y quedó en cola”, no “todos los datos quedaron cargados”. Cada página de entidad indica qué se descarta en la segunda etapa.

Formato de Respuesta

Todos los endpoints devuelven la misma estructura de respuesta.

Respuesta Exitosa

Código HTTP 201.

{
  "success": true,
  "warnings": {
    "customers": ["File does not have .csv extension"]
  }
}

warnings es opcional y no impide la carga: avisa de cosas como una extensión distinta de .csv, un archivo con encabezado y sin filas, un tipo de contenido distinto de text/csv, un document_type desconocido o una factura CASH abierta con saldo pendiente.

Respuesta de Error de Validación

También llega con código 201: el resultado se lee en success.

{
  "success": false,
  "errors": {
    "customers": [
      {
        "rowIndex": 2,
        "messages": [
          "Field \"nit\" is required.",
          "Field \"email\" must have a valid email format."
        ]
      }
    ]
  }
}

rowIndex cuenta las líneas del archivo incluyendo el encabezado, así que la primera fila de datos es la 2. Un rowIndex en 0 corresponde a un error del archivo completo y no de una fila.

Códigos de Estado HTTP

Código	Nombre	Descripción	Acción
201	Creado	Solicitud procesada — el resultado está en el campo `success`	Verificar `success` y, si viene, `errors`
400	Solicitud Incorrecta	Falta el archivo en el formulario	Enviar el archivo en el campo correcto (por ejemplo `customersFile`)
401	No Autorizado	API Key inválida, revocada o ausente	Verificar la API Key o crear una nueva
403	Prohibido	La API Key no tiene permiso para cargar integraciones	Usar una API Key creada en Integración por API
404	No Encontrado	La URL del endpoint no existe	Verificar la ruta y la URL base
500	Error Interno del Servidor	Error inesperado	Reintentar más tarde

Reglas de Validación Comunes

Regla	Descripción
Campos requeridos	El campo debe venir y no puede estar vacío
Nombres de columna	Exactos y en minúsculas; los espacios alrededor del nombre se ignoran, pero no se aceptan otras variantes
Formato de email	Estructura de email válida
Formato de fecha	`YYYY-MM-DD`; otros formatos se rechazan. Una celda vacía se acepta salvo donde se indique lo contrario
Números	Punto como separador decimal y sin separador de miles (`1000000.00`, no `1.000.000,00`)
Valores booleanos	Solo `1` o `0`
Codificación	UTF-8

IDs sin ceros a la izquierda. Al procesar el archivo, un id que sea solo números se interpreta como número: 00123 queda como 123. Si el mismo cliente o factura viene escrito distinto en dos archivos, las filas no se cruzan y se descartan sin aviso. Use ids sin ceros a la izquierda o con algún carácter no numérico.