La respuesta debe analizarse en tres niveles:

1. El código HTTP de la petición.
2. El campo status incluido en el cuerpo JSON.
3. El resultado individual de cada servicio incluido en respuestaLista o errorLista.

Importante: los valores 205 y 206 se devuelven actualmente en el campo JSON status, mientras que el código HTTP de la petición permanece en 200.

Importante: los valores incluidos en errorLista[].errorCodigo corresponden a un servicio individual. No deben interpretarse como el código HTTP general de la petición.

1. Resumen del tratamiento de las respuestas

Diferencia entre código HTTP y status

Una respuesta parcial no se recibe como:

HTTP/1.1 206 Partial Content

La implementación actual responde:

HTTP/1.1 200 OK
Content-Type: application/json

con un cuerpo similar a:

{
  "status": 206,
  "respuestaLista": [],
  "errorLista": []
}

Por tanto, el sistema integrador no debe decidir el resultado del lote utilizando únicamente el código HTTP.

2. Respuesta HTTP 200

Una respuesta HTTP 200 indica que el servidor ha procesado el lote y ha podido generar un resultado.

El resultado final se determina mediante el campo status del cuerpo:

• 200: solo existen resultados correctos.
• 206: existen resultados correctos y errores o advertencias.
• 205: no existen elementos en respuestaLista; existen errores o advertencias.

El sistema integrador debe revisar siempre:

• status
• respuestaLista
• errorLista

3. Cuerpo con status: 200

El valor status: 200 indica que todos los servicios incluidos en la respuesta se han procesado correctamente.

Ejemplo:

{
  "status": 200,
  "respuestaLista": [
    {
      "albaran": "ALB-001",
      "albaranExterno": "PED-001",
      "uniqueId": "687000000000000000000001",
      "bultosLista": [
        {
          "barcode": "BULTO-001"
        }
      ]
    }
  ]
}

El sistema integrador debe:

1. Procesar todos los elementos de respuestaLista.
2. Almacenar el uniqueId de cada servicio.
3. Relacionar la respuesta con el documento correspondiente del ERP.
4. No volver a crear los servicios confirmados.

Campos habituales de respuestaLista

internalId y externalId no forman parte de la respuesta estándar de un servicio creado correctamente. Pueden aparecer dentro de errorLista cuando están disponibles.

4. Cuerpo con status: 206

El valor status: 206 indica que existen elementos en respuestaLista y también elementos en errorLista.

No significa necesariamente que todos los elementos de errorLista hayan fallado. La lista puede contener:

• Errores que impidieron crear un servicio.
• Duplicidades.
• Confirmaciones o resultados relacionados con servicios ya existentes.
• Advertencias posteriores a la creación.
• Situaciones que requieren revisión manual.

Ejemplo:

{
  "status": 206,
  "respuestaLista": [
    {
      "albaran": "ALB-001",
      "albaranExterno": "PED-001",
      "uniqueId": "687000000000000000000001",
      "bultosLista": []
    }
  ],
  "errorLista": [
    {
      "errorCodigo": 406,
      "errorDescripcion": "Reference already found",
      "albaran": "ALB-002",
      "albaranExterno": "PED-002"
    }
  ]
}

Tratamiento recomendado

1. Almacenar los identificadores de todos los elementos de respuestaLista.
2. No volver a enviar los servicios confirmados correctamente.
3. Analizar individualmente cada elemento de errorLista.
4. Comprobar errorCodigo, errorDescripcion y uniqueId.
5. Reenviar únicamente los elementos que realmente requieran una nueva creación.

No debe reenviarse el lote completo, porque algunos servicios ya pueden haberse creado correctamente.

5. Cuerpo con status: 205

El valor status: 205 indica que no existen elementos en respuestaLista y que la respuesta contiene elementos en errorLista.

Ejemplo:

{
  "status": 205,
  "errorLista": [
    {
      "errorCodigo": 400,
      "errorDescripcion": "Customer name and code cannot be empty at the same time",
      "albaran": "ALB-003"
    }
  ]
}

No debe asumirse automáticamente que todos los servicios pueden reenviarse.

errorLista puede contener:

• Errores de datos.
• Referencias duplicadas.
• Servicios ya existentes.
• Advertencias.
• Errores temporales.

El sistema integrador debe clasificar cada elemento antes de decidir si debe corregirse, omitirse o reintentarse.

6. Respuesta HTTP 204 - No Content

Una respuesta HTTP 204 indica que no se ha encontrado una lista reconocida con elementos para procesar o que la lista estaba vacía.

Debe comprobarse:

• Que el cuerpo contenga un JSON válido.
• Que se utilice el listado público pedidosLista.
• Que pedidosLista sea un array.
• Que el array contenga al menos un servicio.
• Que el encabezado Content-Type sea application/json.
• Que la serialización no haya eliminado el contenido.

Ejemplo válido:

{
  "pedidosLista": [
    {
      "albaran": "ALB-001",
      "actividad": 2,
      "cliente": {
        "clienteCodigo": "CLI-001",
        "clienteNombre": "Cliente de ejemplo",
        "direccion": "Calle Mayor 1",
        "codigoPostal": "28001",
        "ciudad": "Madrid"
      }
    }
  ]
}

Un JSON mal formado puede producir un error HTTP 420, no necesariamente un 204.

Los clientes HTTP pueden no exponer un cuerpo en las respuestas 204. No debe dependerse de un JSON de respuesta para este código.

7. Respuesta HTTP 401 - Unauthorized

Una respuesta HTTP 401 indica un problema de autenticación o autorización.

Puede producirse cuando:

• apiKey o userId no se han enviado.
• Las credenciales tienen un formato no válido.
• Las credenciales no corresponden a un usuario autorizado.
• El usuario está inactivo.
• La empresa no está disponible.
• La cuenta está cancelada.
• Se están utilizando credenciales de otro entorno.

Debe comprobarse:

• Que apiKey y userId sean correctos.
• Que se envíen en las cabeceras HTTP acordadas.
• Que el entorno sea el correcto.
• Que el usuario y la empresa estén activos.

No debe realizarse un reintento continuo con las mismas credenciales.

Ejemplo:

{
  "status": 401
}

8. HTTP 406 no forma parte de las validaciones generales de este endpoint

El endpoint no utiliza HTTP 406 como respuesta general para errores de estructura, campos obligatorios ausentes o duplicidades.

Existe una validación específica y privada para una integración concreta que puede devolver:

HTTP/1.1 406 Not Acceptable

{
  "status": 406
}

Esta regla no forma parte del contrato público de la API y no debe utilizarse como referencia para integraciones generales.

No debe confundirse con errorCodigo: 406 dentro de errorLista, que sí forma parte del comportamiento general del endpoint y representa una referencia principal ya existente.

9. Respuesta HTTP 420 - Method Failure

420 es un código no estándar utilizado por la API para indicar un error general durante la interpretación o el procesamiento de la petición.

Puede producirse, por ejemplo, cuando:

• El JSON no puede interpretarse.
• La estructura enviada provoca una excepción.
• Se produce un error general durante el procesamiento del lote.

La respuesta puede incluir un campo message:

{
  "status": 420,
  "message": "Detalle del error"
}

El sistema debe:

1. Registrar el cuerpo completo de la respuesta.
2. Registrar message cuando esté disponible.
3. Determinar si el error está relacionado con los datos o con un problema temporal.
4. Corregir la petición cuando el mensaje identifique un formato o valor incorrecto.
5. Reintentar únicamente cuando existan indicios de un problema temporal.

No se recomienda realizar reintentos automáticos indefinidos para respuestas 420.

10. Respuesta HTTP 429 - Too Many Requests

Una respuesta HTTP 429 indica que se ha superado el límite de llamadas permitido.

La aplicación del rate limit puede depender del entorno y de la configuración activa. En particular, las pruebas de 429 deben realizarse únicamente en un entorno en el que el limitador esté habilitado; no debe asumirse que un entorno de desarrollo o pruebas reproducirá el mismo comportamiento que producción.

Ejemplo:

{
  "status": 429
}

La implementación no garantiza que la respuesta incluya una cabecera Retry-After.

El sistema integrador debe aplicar una estrategia de espera progresiva, por ejemplo:

Primer reintento: 2 segundos
Segundo reintento: 5 segundos
Tercer reintento: 10 segundos
Cuarto reintento: 30 segundos

Estos tiempos son una recomendación del integrador, no una política garantizada por la API.

También se recomienda:

• Limitar el número máximo de reintentos.
• Añadir una pequeña variación aleatoria a la espera.
• Agrupar servicios en una misma petición cuando corresponda.
• Evitar llamadas duplicadas.
• Evitar que varios procesos reintenten el mismo lote simultáneamente.
• Registrar el número de intentos.

11. Respuesta HTTP 500 - Internal Server Error

Una respuesta HTTP 500 indica un error interno inesperado o que el endpoint ha alcanzado su respuesta de fallback.

Ejemplo:

{
  "status": 500
}

El sistema integrador debe registrar:

• Fecha y hora.
• Endpoint utilizado.
• Entorno.
• Cuerpo de la petición.
• Código HTTP.
• Cuerpo completo de la respuesta.
• Referencias de los servicios afectados.
• Número de intento.

Puede realizarse un número limitado de reintentos cuando se considere un problema temporal.

Si el error persiste, debe facilitarse la información registrada al equipo de soporte.

12. Campos de errorLista

Cada elemento de errorLista puede incluir:

Ejemplo:

{
  "errorCodigo": 201,
  "errorDescripcion": "OK, but driver not found",
  "albaran": "ALB-004",
  "albaranExterno": "PED-004",
  "uniqueId": "687000000000000000000004"
}

La disponibilidad de los campos depende del momento en el que se haya producido el resultado.

La presencia de uniqueId puede indicar que:

• El servicio se creó.
• El servicio ya existía.
• El procesamiento alcanzó el punto en el que pudo identificarse la expedición.

Por tanto, antes de reenviar un elemento de errorLista debe comprobarse si ya existe un servicio asociado.

13. Códigos individuales de errorLista

Los siguientes códigos pertenecen a errorLista[].errorCodigo. No son códigos HTTP generales de la petición.

El catálogo exacto puede depender de la configuración y del flujo de creación utilizado. El integrador debe conservar siempre errorCodigo y errorDescripcion.

La implementación contiene una rama interna asociada a 409, pero el flujo normal para una pareja exacta de referencias ya existente devuelve la expedición como resultado correcto e idempotente. Por ello, 409 no se documenta como un resultado público esperado.

14. errorCodigo: 400 — Cliente sin identificar

Mensaje habitual:

Customer name and code cannot be empty at the same time

En la implementación actual, esta validación se produce cuando tanto el código como el nombre del cliente están vacíos y, por tanto, no existe información suficiente para identificar al cliente o destinatario.

Esta validación del backend no debe confundirse con los campos definidos como obligatorios por el contrato público de la API. El contrato puede exigir información adicional, pero la ausencia de esos otros campos no implica necesariamente que se devuelva este errorCodigo: 400.

Tratamiento recomendado

• Corregir los datos de identificación del cliente.
• Reenviar solamente el elemento afectado.
• No modificar automáticamente otros clientes.
• Validar el contrato de la petición antes de realizar la llamada.

15. errorCodigo: 406 — Referencia principal existente

Mensaje habitual:

Reference already found

Una referencia principal que ya existe puede producir errorCodigo: 406.

No obstante, el tratamiento de duplicados depende de la combinación de referencias enviada:

• Si la referencia principal ya existe y la petición no identifica de forma inequívoca la misma expedición mediante la segunda referencia, puede devolverse errorCodigo: 406.
• Si la referencia principal y la referencia externa/pedido identifican conjuntamente la misma expedición existente, el flujo normal es idempotente: no crea un duplicado y devuelve la expedición existente como resultado correcto.
• Si ambas referencias existen pero pertenecen a expediciones distintas, puede devolverse errorCodigo: 408.

Tratamiento recomendado

• Comprobar si el servicio ya fue creado.
• Buscar o consultar el servicio por sus referencias.
• Revisar si una llamada anterior pudo completarse.
• No generar automáticamente una referencia diferente.
• No reenviar hasta confirmar qué expedición corresponde.
• Almacenar el uniqueId cuando esté disponible.

16. errorCodigo: 407 — Referencia externa existente

Mensaje habitual:

Order Reference already found

Este error puede producirse cuando el valor enviado como referencia principal coincide con una referencia externa ya existente, sin coincidir con una referencia principal existente.

Ejemplo conceptual:

1. Existe previamente un servicio con:

Referencia principal: REF-A
Referencia externa: ORDER-A

2. Se intenta crear otro servicio enviando:

Referencia principal: ORDER-A
Referencia externa: ORDER-A

El resultado esperado es:

HTTP/1.1 200 OK

{
  "status": 205,
  "errorLista": [
    {
      "errorCodigo": 407,
      "errorDescripcion": "Order Reference already found"
    }
  ]
}

Tratamiento recomendado

• Revisar si el ERP está reutilizando una referencia externa como referencia principal.
• Comprobar la relación entre la referencia principal y la referencia externa.
• No reenviar automáticamente hasta resolver la duplicidad.
• Utilizar el servicio existente cuando corresponda.

17. errorCodigo: 408 — Referencias en expediciones diferentes

Mensaje habitual:

Reference and Order Reference already found on different expeditions

La referencia principal y la referencia externa existen, pero están asociadas a expediciones diferentes.

Esto indica una inconsistencia entre las referencias utilizadas por el ERP.

Tratamiento recomendado

• Revisar las dos expediciones.
• Confirmar qué referencia corresponde al servicio.
• No modificar automáticamente ninguna referencia.
• No realizar un reintento automático.
• Resolver manualmente la relación entre ERP y Logístiko.

18. Idempotencia — Ambas referencias pertenecen a la misma expedición

Cuando la referencia principal y la referencia externa/pedido ya existen y ambas pertenecen a la misma expedición, el flujo normal no crea un nuevo servicio.

Aunque la implementación contiene internamente una rama asociada al código 409, el comportamiento normal del endpoint transforma este caso en un resultado correcto e idempotente y devuelve la expedición existente.

Por tanto, los integradores no deben depender de errorCodigo: 409 como respuesta pública esperada para este escenario.

El resultado normal es:

HTTP/1.1 200 OK

con un cuerpo con status: 200 y la expedición existente dentro de respuestaLista, incluyendo su uniqueId cuando corresponda.

Tratamiento recomendado

• Considerar la operación como procesada correctamente.
• Almacenar el uniqueId y los identificadores devueltos.
• No crear una nueva referencia.
• No volver a crear el servicio.
• Continuar las futuras operaciones sobre la expedición existente.

19. errorCodigo: 499 — Máximo de elementos superado

Mensaje habitual:

Max items exceeded

Se ha superado el número máximo de servicios permitido por la integración o por el proceso de creación.

Tratamiento recomendado

• Dividir el listado en peticiones más pequeñas.
• Mantener un identificador de lote.
• Procesar cada lote de forma independiente.
• No modificar individualmente los servicios.
• No asumir un tamaño máximo concreto sin confirmarlo con Logístiko.

Ejemplo conceptual:

Lote original: 1.000 servicios

Petición 1: primer bloque
Petición 2: segundo bloque
Petición 3: tercer bloque
Petición 4: cuarto bloque

El tamaño exacto de cada bloque debe acordarse o validarse para la integración.

20. errorCodigo: 201 — Servicio creado con advertencia

Mensaje habitual:

OK, but driver not found

Este código representa una advertencia, no un fallo completo de creación.

El servicio puede haberse creado aunque no se haya podido asignar correctamente el conductor.

Tratamiento recomendado

• No volver a crear el servicio.
• Almacenar uniqueId cuando esté disponible.
• Revisar conductorCodigo.
• Confirmar que el conductor existe en el mismo entorno.
• Corregir o crear el conductor.
• Asignar posteriormente el servicio cuando corresponda.

La implementación realiza comprobaciones y puede intentar crear conductores recibidos por API. La aparición exacta de esta advertencia puede depender de la configuración y del punto en el que falle la creación o asignación del conductor.

21. errorCodigo: 500 — Error individual

Un errorCodigo: 500 indica que se ha producido un error inesperado al procesar un servicio concreto.

No debe confundirse con una respuesta HTTP 500 del lote completo.

Tratamiento recomendado

• Registrar el servicio afectado.
• Registrar el cuerpo completo de la respuesta.
• Comprobar si otros servicios del lote fueron procesados.
• Reintentar únicamente el servicio afectado.
• Limitar el número de reintentos.
• Contactar con soporte si el problema se repite.

22. Clasificación para el tratamiento automático

Respuestas HTTP que pueden reintentarse

Errores individuales que requieren corregir datos

Resultados que normalmente no deben volver a crearse

La decisión final debe considerar también:

• La presencia de uniqueId.
• La existencia del elemento en respuestaLista.
• El contenido de errorDescripcion.
• El estado actual del servicio en Logístiko.

23. Estrategia recomendada de reintentos

Los reintentos deben ser selectivos.

Flujo recomendado

1. Enviar la petición.
2. Revisar el código HTTP.
3. Si el código HTTP es 200, revisar el campo status del cuerpo.
4. Procesar todos los elementos de respuestaLista.
5. Almacenar los uniqueId devueltos.
6. Analizar individualmente cada elemento de errorLista.
7. Clasificar cada elemento:
   - Creado correctamente.
   - Creado con advertencia.
   - Ya existente.
   - Requiere corrección.
   - Error temporal.
   - Revisión manual.
8. Reenviar solamente los elementos que correspondan.

Número máximo de reintentos

Se recomienda:

• Establecer un máximo de reintentos automáticos.
• Aplicar una espera progresiva.
• Enviar el elemento a revisión manual después del último intento.
• No reintentar indefinidamente.
• No reintentar automáticamente errores de duplicidad o inconsistencias de referencias.

24. Prevención de duplicados

Antes de reenviar un servicio debe comprobarse si la primera llamada pudo crearlo aunque el ERP no recibiera correctamente la respuesta.

Se recomienda utilizar:

• uniqueId, cuando esté disponible.
• La referencia principal.
• La referencia externa.
• El control de idempotencia del ERP.
• La consulta del servicio existente cuando sea necesaria.

Nunca debe generarse automáticamente una referencia diferente para evitar un error de duplicidad sin verificar previamente qué servicio existe.

Comportamiento idempotente cuando ambas referencias identifican el mismo servicio

Cuando la referencia principal y la referencia externa enviadas ya pertenecen a la misma expedición existente, el flujo normal no devuelve errorCodigo: 409.

El comportamiento esperado es:

HTTP/1.1 200 OK

con:

{
  "status": 200,
  "respuestaLista": [
    {
      "uniqueId": "<identificador-del-servicio-existente>"
    }
  ]
}

La API devuelve la expedición existente como resultado correcto y no crea un duplicado.

Por tanto:

• No debe documentarse 409 como un error público esperable de este endpoint.
• No debe pedirse al integrador que pruebe 409.
• El integrador debe tratar la repetición exacta de ambas referencias como una operación idempotente cuando la respuesta confirma el servicio existente.

25. Registro recomendado

Para facilitar el soporte y la resolución de errores, se recomienda almacenar:

• Fecha y hora de la petición.
• Endpoint utilizado.
• Entorno.
• Identificador interno del ERP.
• Número de albarán o pedido.
• Referencia externa.
• Cuerpo enviado.
• Código HTTP recibido.
• Campo status del cuerpo.
• Respuesta completa.
• errorCodigo.
• errorDescripcion.
• Número de intento.
• Estado final del elemento.
• uniqueId, cuando esté disponible.

No deben almacenarse credenciales, claves o tokens sin las medidas de seguridad adecuadas.

26. Ejemplo de respuesta parcial

Se envían tres servicios:

ALB-001
ALB-002
ALB-003

El servidor responde HTTP 200:

{
  "status": 206,
  "respuestaLista": [
    {
      "albaran": "ALB-001",
      "uniqueId": "687000000000000000000001",
      "bultosLista": []
    },
    {
      "albaran": "ALB-002",
      "uniqueId": "687000000000000000000002",
      "bultosLista": []
    }
  ],
  "errorLista": [
    {
      "errorCodigo": 400,
      "errorDescripcion": "Customer name and code cannot be empty at the same time",
      "albaran": "ALB-003"
    }
  ]
}

Tratamiento correcto

• Almacenar los identificadores de ALB-001.
• Almacenar los identificadores de ALB-002.
• No volver a enviar ALB-001.
• No volver a enviar ALB-002.
• Corregir los datos de cliente de ALB-003.
• Reenviar únicamente ALB-003.

27. Ejemplo de servicio creado con advertencia

El servidor responde HTTP 200:

{
  "status": 206,
  "respuestaLista": [
    {
      "albaran": "ALB-004",
      "uniqueId": "687000000000000000000004",
      "bultosLista": []
    }
  ],
  "errorLista": [
    {
      "errorCodigo": 201,
      "errorDescripcion": "OK, but driver not found",
      "albaran": "ALB-004",
      "uniqueId": "687000000000000000000004"
    }
  ]
}

Tratamiento correcto

• Considerar que ALB-004 se ha creado.
• Almacenar su uniqueId.
• No volver a crear el servicio.
• Revisar o corregir conductorCodigo.
• Asignar posteriormente el conductor correcto.

28. Ejemplo de petición idempotente sobre un servicio existente

Supongamos que ya existe una expedición identificada por:

albaran: ALB-005
albaranExterno: PED-005

Si se vuelve a enviar una creación con la misma pareja de referencias, el comportamiento normal es no crear una nueva expedición y devolver la existente como resultado correcto.

El servidor responde HTTP 200 con un cuerpo similar a:

{
  "status": 200,
  "respuestaLista": [
    {
      "albaran": "ALB-005",
      "albaranExterno": "PED-005",
      "uniqueId": "687000000000000000000005",
      "bultosLista": []
    }
  ]
}

Tratamiento correcto

• Considerar la operación como correcta.
• No crear una referencia nueva.
• No reenviar el servicio para intentar crear otro.
• Almacenar el uniqueId devuelto.
• Continuar las actualizaciones utilizando la expedición existente.

29. Checklist de gestión de errores

• Se diferencia el código HTTP del campo JSON status.
• Se sabe que 205 y 206 pueden recibirse dentro de una respuesta HTTP 200.
• Se procesan por separado respuestaLista y errorLista.
• No se reenvía el lote completo cuando existen resultados correctos.
• Se almacenan los uniqueId devueltos.
• Se comprueba uniqueId antes de reenviar un elemento de errorLista.
• errorCodigo: 201 se trata como advertencia.
• Una pareja exacta de referencias ya existente se trata como una operación idempotente y no se espera errorCodigo: 409 en el flujo normal.
• Los errores 400, 406 y 408 requieren revisión de datos; 407 se trata según el flujo concreto en el que aparezca.
• Los resultados 499 se gestionan dividiendo el lote.
• Existe una espera progresiva para HTTP 429.
• HTTP 420 se procesa según message.
• HTTP 500 y errorCodigo: 500 se distinguen correctamente.
• Los errores temporales tienen un límite de reintentos.
• Se registran las peticiones y respuestas.
• No se realizan reintentos indefinidos.
• Los errores no recuperables se envían a revisión manual