Sistemas

La API respondió 200, pero el inventario no cambió: cómo investigar integraciones con User Products

Una respuesta 200 no cierra el diagnóstico. Entiende el escenario multiorigen y cómo verificar resultados, con experiencias reales de embalaje y conversión de variantes.

Un desarrollador compara una confirmación verde en la pantalla con productos en un estante y examina una caja con una lupa.
Ilustración conceptual sobre la comprobación del resultado real de una integración. · Crédito: Ilustração gerada com inteligência artificial.

Hay un mensaje que suele traer alivio a quienes trabajamos con integraciones: 200 OK.

La solicitud terminó, llegó la respuesta y el sistema aparentemente hizo lo que debía. Dan ganas de marcar la tarea como completada y pasar a la siguiente. Hasta que alguien abre la publicación y pregunta: “¿Por qué el inventario sigue igual?”

Este tipo de situación exige investigar todo el recorrido. El código de respuesta es una evidencia importante, pero debemos entender qué operación se ejecutó y qué resultado estamos intentando confirmar.

En Oombe, trabajo con integraciones y rutinas como creación y transferencia de publicaciones. Dos experiencias que relaté ayudan a explicar esta preocupación: datos de embalaje que no permanecían después de una actualización aceptada por la API y una copia de publicación en la que 56 variantes dieron lugar a 24 publicaciones de la misma familia.

Son situaciones diferentes, con causas todavía no confirmadas en esos relatos. Lo que tienen en común es una pregunta muy práctica: ¿cómo demostrar que el resultado esperado realmente ocurrió?

Qué responde el 200

La especificación HTTP define 200 como éxito de la solicitud. Para interpretar el resultado, también necesitamos considerar la operación y la respuesta recibida. [1]

Durante la investigación, separaría tres preguntas:

  • ¿La solicitud se envió como pretendíamos?
  • ¿Qué operación informó haber realizado el servicio?
  • ¿El estado observado satisface el objetivo del negocio?

Imaginemos un ejemplo didáctico: el operador quiere dejar diez unidades disponibles en una determinada ubicación. La aplicación envía una modificación, recibe una respuesta exitosa y muestra un aviso verde.

Para concluir que se alcanzó el objetivo, todavía debemos relacionar la solicitud con la cuenta, el producto y la ubicación correctos. También debemos considerar qué ocurrió entre la modificación y la consulta posterior.

El aviso verde puede ser correcto respecto de la solicitud e incompleto respecto de la operación comercial. La solución empieza por hacer explícito qué confirma cada mensaje.

Existe un escenario documentado en Mercado Livre

La FAQ oficial informa que, en cuentas con inventario multiorigen, modificar available_quantity mediante /items puede devolver 200 sin actualizar el inventario real. Recomienda verificar la configuración y utilizar el flujo apropiado por ubicación. Este comportamiento no debe generalizarse a todas las cuentas. [2]

Esta delimitación importa. Encontrar una explicación posible en la documentación ayuda a formular una hipótesis. Para aplicarla a un caso concreto, todavía es necesario comprobar si la cuenta encaja en el escenario descrito.

También conviene distinguir las entidades. La documentación presenta el item como una publicación con condiciones de venta y el User Product como la representación del producto físico en el nivel más específico de la variante. [3]

Empezaría dibujando esas relaciones antes de modificar el código. ¿Qué producto es? ¿Qué publicación estamos observando? ¿De qué ubicación hablamos? ¿Qué información debería cambiar?

La expresión “inventario de la publicación” parece sencilla en una conversación. Para el sistema, debemos localizar exactamente el estado que esa expresión representa en ese contexto.

El caso del embalaje: observar sin inventar la causa

En uno de los episodios que relaté, la actualización de información sobre peso o medidas del embalaje recibía una respuesta 200, pero los datos no permanecían como se esperaba.

Ese relato describe un resultado observado. No tenía una causa y una corrección comprobadas para presentar. Tampoco hay base para atribuirlo automáticamente al modelo de User Products.

La investigación que seguiría empezaría por conservar el valor anterior, el cambio pretendido, el contenido enviado, la respuesta y las consultas posteriores. Sin eso, resulta difícil distinguir entre “no cambió” y “cambió y después volvió a cambiar”.

Luego examinaría hipótesis por separado: ¿el campo corresponde a la información deseada? ¿La consulta posterior observa el mismo objeto? ¿Existe otra rutina autorizada para actualizar esos datos? ¿Hay alguna regla documentada aplicable a la categoría o al modelo de la cuenta?

Son preguntas de diagnóstico, no conclusiones sobre el episodio.

La diferencia importa porque reenviar la misma modificación diez veces puede producir diez respuestas iguales y ninguna explicación nueva. La cantidad de intentos no sustituye un registro de evidencias. Ni siquiera cuando el décimo intento viene acompañado de una conversación seria con el monitor.

El caso de las 56 variantes y las 24 publicaciones

En el otro caso, la intención era copiar una publicación con 56 variantes, convirtiendo su estructura en publicaciones bajo el modelo de User Products. El resultado observado fue de 24 publicaciones de la misma familia. Faltaban 32 con respecto al resultado esperado.

La cuenta identifica la diferencia, pero todavía no revela dónde surgió.

Necesitaría comprobar qué variantes entraron en la operación, cuáles se prepararon para enviar, cuáles tuvieron un intento registrado y qué resultados pudieron localizarse después.

Una lista de 56 entradas no demuestra que se hicieron 56 solicitudes. Del mismo modo, ver 24 resultados en una consulta no demuestra, por sí solo, que no existan otros. Hay que validar el alcance de la consulta y la correspondencia entre origen y destino.

Prepararía una fila por variante de origen, con una identidad estable y su resultado conocido. Así podría localizar el primer punto en que cada una de las 32 pendientes dejó de tener una evidencia correspondiente.

La causa de ese caso tampoco estaba confirmada. Podría haber explicaciones diferentes para distintos grupos de pendientes. Antes de volver a intentarlo, buscaría separar lo rechazado, lo que nunca llegó a enviarse y lo que todavía debía localizarse.

Antes de corregir, identifica qué estás comparando

En la práctica, prepararía una ficha breve de la operación: cuenta, producto, publicación, variante cuando corresponda, ubicación y objetivo de la modificación.

Esos identificadores necesitan funciones claras. Usar únicamente el título de la publicación para relacionar resultados es una elección frágil: los títulos pueden parecerse y una misma descripción puede servir a variantes distintas.

También registraría la configuración relevante de la cuenta y el modelo logístico comprobados en la documentación vigente. La presencia de un identificador de User Product, por sí sola, no sería mi única evidencia para elegir un flujo de inventario.

Otra pregunta necesaria es quién mantiene la información que estamos leyendo. Podemos estar comparando una intención local con una pantalla que todavía muestra datos anteriores, o con una consulta cuyo alcance es distinto del que imaginábamos. Eso debe investigarse en cada caso.

Para mí, una corrección empieza a resultar convincente cuando puedo completar la frase: “Queríamos cambiar este estado, en este objeto, bajo estas condiciones, y verificamos el resultado de esta manera”.

Sin esa frase, es muy fácil corregir el lugar equivocado y celebrar demasiado pronto.

Aceptar, confirmar y conciliar son etapas distintas

Diseñaría la operación con estados que representen lo que realmente sabemos. “Enviado” indica un intento. “Respuesta recibida” registra un retorno. “Confirmado” exige evidencia compatible con el objetivo.

Cuando falta esa evidencia, prefiero un estado pendiente explícito. Esto evita que la ausencia de información se transforme en éxito o fracaso por comodidad.

El razonamiento podría aparecer en este pseudocódigo didáctico:

intencion = registrar_objetivo_e_identidades()
respuesta = ejecutar_flujo_compatible()
guardar_evidencias(intencion, respuesta)

si respuesta_indica_rechazo:
    marcar_rechazado_con_motivo()
si_no:
    actual = consultar_estado_relevante()

    si objetivo_cumplido(intencion, actual):
        marcar_confirmado()
    si_no:
        marcar_pendiente_de_conciliacion()

Las funciones representan responsabilidades por implementar. La elección de los recursos reales depende de la cuenta, de la operación y de la documentación correspondiente.

“Objetivo cumplido” también necesita una definición cuidadosa. Para una publicación, puede implicar encontrar la correspondencia correcta. Para inventario, exige considerar ubicación, momento de la consulta y eventos posteriores. Comparar dos números sin ese contexto puede llevar a un diagnóstico equivocado.

El tiempo también participa en la investigación

Supongamos que, en un escenario ficticio, la operación pretende dejar diez unidades disponibles. Se realiza la actualización y, poco después, una venta reduce la disponibilidad a nueve.

Una consulta posterior que encuentra nueve no demuestra, por sí sola, que la actualización falló. Puede estar observando un cambio legítimo ocurrido después. Para entender el resultado, necesitaría relacionar horarios, eventos y reglas de la operación.

La situación inversa también merece cuidado. Encontrar la cifra esperada no demuestra automáticamente que aquel intento la produjo; el estado podría haber sido igual antes.

Por eso conservaría el estado anterior y evitaría tratar una consulta aislada como la historia completa.

También existe control de concurrencia. En los recursos de inventario distribuido documentados, Mercado Livre utiliza x-version; una versión desactualizada puede generar un conflicto 409, que exige una nueva consulta antes de continuar. [4]

Ese caso es diferente de recibir 200 sin observar el cambio pretendido. Cada síntoma debe mantener su propia línea de investigación. Mezclarlos todos en “la API está rara” acorta la conversación y alarga bastante el diagnóstico.

Conciliar significa completar las correspondencias

Usaría una tabla de conciliación para vincular cada intención con su resultado conocido. No hace falta comenzar con una herramienta sofisticada. Lo esencial es poder responder qué falta y por qué.

Situación observada Cómo la trataría
Resultado encontrado y compatible con la intención Registrar la evidencia y completar esa unidad
Rechazo identificado Corregir la causa demostrada antes de otro intento
Intento registrado, resultado desconocido Investigar el destino antes de repetir
Entrada sin intento registrado Verificar por qué el procesamiento no llegó hasta ella

En el caso de las variantes, la unidad sería cada variante de origen y su correspondencia esperada. En el del embalaje, sería el cambio solicitado y las evidencias del estado observado.

La tabla también ayuda a evitar una trampa: repetir toda una operación porque una parte quedó pendiente. Los resultados ya confirmados deben preservarse.

Volver a procesar únicamente lo que se identificó como necesario depende de un buen historial. Sin él, la aplicación termina adivinando lo que ya ocurrió, y esa suele ser una manera costosa de ahorrar en el registro de información.

Qué conviene guardar para explicar el problema

Priorizaría registros que permitan reconstruir la operación: identificador interno del intento, horario, identidades involucradas, objetivo, contenido relevante enviado y respuesta recibida.

En la lectura posterior, guardaría el recurso consultado, el momento de la consulta y el estado encontrado. Cuando el servicio proporcione un identificador de solicitud, también puede ayudar a relacionar evidencias durante la investigación.

Esos registros deben excluir credenciales y limitar los datos personales a lo necesario. Un historial útil debe permitir entender el problema sin convertir el diagnóstico en una copia innecesaria de toda la cuenta.

También separaría los hechos de las hipótesis. “Recibimos 200 y la siguiente consulta mostró el valor anterior” es una observación. “El marketplace borró el dato” ya propone una explicación que exige evidencia adicional.

Esta diferencia mejora tanto la investigación interna como un eventual caso de soporte. Cuanto más claramente podamos mostrar lo que sabemos, más fácil será identificar lo que todavía falta descubrir.

Cómo validaría una corrección

Después de encontrar una causa demostrable, elegiría un caso controlado y un objetivo verificable. El cambio debería responder a la hipótesis investigada, sin modificar varias partes del flujo al mismo tiempo.

Compararía el estado anterior, la ejecución y el resultado. Después observaría si la corrección sigue siendo válida en las configuraciones a las que está destinada.

También incluiría un caso en el que el comportamiento anterior deba seguir funcionando. Una corrección para una cuenta multiorigen no debería extenderse indiscriminadamente a configuraciones distintas.

Para la publicación, verificaría las correspondencias y la integridad del resultado, no solo el total. Obtener 56 resultados con dos entradas repetidas y dos ausentes seguiría siendo un problema, aunque el contador mostrara una cifra bonita.

Estos son los criterios que adoptaría para validar una solución. Una corrección solo estaría demostrada cuando ese conjunto de evidencias completara la explicación del caso.

El mejor resultado es poder demostrar qué ocurrió

La experiencia con integraciones me hace valorar una habilidad poco vistosa: explicar una operación de principio a fin.

Un buen diagnóstico muestra qué se pretendía, qué camino se utilizó, qué respuestas llegaron y cómo se verificó el resultado. También permite reconocer cuándo todavía no tenemos evidencia suficiente para cerrar el asunto.

User Products y el inventario multiorigen hacen especialmente visible esa necesidad, porque la configuración de la cuenta y la relación entre entidades forman parte del problema. Pero el razonamiento sirve para muchas integraciones.

En la evolución de sistemas como Oombe, considero este cuidado fundamental para transformar acciones en resultados verificables. El operador necesita entender si algo fue enviado, confirmado o sigue pendiente.

El 200 OK continúa siendo una buena noticia. Simplemente me gusta acompañarlo de una información todavía mejor: “Comprobamos el resultado y aquí está la evidencia”.

Fuentes

[1] IETF — RFC 9110, sección 15.3.1: 200 OK. Semántica HTTP.

[2] Mercado Livre Developers — Gestión de inventario multiorigen / User Products. Actualización de inventario en cuentas multiorigen.

[3] Mercado Livre Developers — User Products. Definición de las entidades item y User Product.

[4] Mercado Livre Developers — Inventario distribuido. Control de versiones y tratamiento de conflictos en los recursos documentados.

EN

Ernani Nascimento

Desarrollador, emprendedor y administrador de empresas. Creo sistemas y comparto lo que aprendo en el camino.

Conoce al autor ↗

Sigue explorando.

DE LA IDEA A LA PRÁCTICA

¿Tienes algo en mente?
Vamos a construirlo.

Conversemos ↗