Sistemas

A API respondeu 200, mas o estoque não mudou: como investigar integrações com User Products

Uma resposta 200 não encerra o diagnóstico. Entenda o cenário de estoque multiorigem e como conferir resultados, com relatos reais de embalagem e conversão de variações.

Desenvolvedor compara uma confirmação verde na tela com produtos na prateleira, examinando uma caixa com uma lupa.
Ilustração conceitual sobre conferir o resultado real de uma integração. · Crédito: Ilustração gerada com inteligência artificial.

Tem uma mensagem que costuma trazer alívio para quem trabalha com integração: 200 OK.

A requisição terminou, a resposta chegou e o sistema aparentemente fez o que precisava. Dá vontade de marcar a tarefa como concluída e seguir para a próxima. Até alguém abrir o anúncio e perguntar: “Mas por que o estoque continua igual?”

Esse tipo de situação exige investigar o caminho inteiro. O código de resposta é uma evidência importante, mas precisamos entender qual operação foi executada e qual resultado estamos tentando confirmar.

Na Oombe, trabalho com integrações e rotinas como publicação e transferência de anúncios. Dois relatos da minha experiência ajudam a explicar essa preocupação: dados de embalagem que não permaneciam após uma atualização aceita pela API e uma cópia de anúncio em que 56 variações resultaram em 24 publicações da mesma família.

São situações diferentes, com causas ainda não confirmadas nos relatos. O que elas têm em comum é uma pergunta bastante prática: como demonstrar que o resultado esperado realmente aconteceu?

O que o 200 responde

A especificação HTTP define 200 como sucesso da requisição. Para interpretar o resultado, também precisamos considerar a operação e a resposta recebida. [1]

Na investigação, eu separaria três perguntas:

  • O pedido foi enviado como pretendíamos?
  • Qual operação o serviço informou ter realizado?
  • O estado observado atende ao objetivo do negócio?

Imagine um exemplo didático: o operador quer deixar dez unidades disponíveis em uma determinada origem. A aplicação envia uma alteração, recebe sucesso e mostra um aviso verde.

Para concluir que o objetivo foi atendido, ainda precisamos relacionar a solicitação à conta, ao produto e à localização corretos. Também precisamos considerar o que aconteceu entre a alteração e a consulta posterior.

O aviso verde pode estar correto sobre a requisição e incompleto sobre a operação comercial. A solução começa por tornar explícito o que cada mensagem confirma.

Existe um cenário documentado no Mercado Livre

A FAQ oficial informa que, em contas com estoque multiorigem, alterar available_quantity em /items pode retornar 200 sem modificar o estoque real. A orientação é verificar a configuração e usar o fluxo de estoque por localização apropriado. Esse comportamento não deve ser generalizado para toda conta. [2]

Essa delimitação é importante. Encontrar uma explicação possível na documentação ajuda a formular uma hipótese. Para aplicá-la a um caso concreto, ainda é necessário conferir se aquela conta está no cenário descrito.

Também convém distinguir as entidades. A documentação apresenta o item como publicação com condições de venda e o User Product como representação do produto físico no nível mais específico da variação. [3]

Eu começaria desenhando essas relações antes de mudar o código. Qual é o produto? Qual publicação estamos observando? De qual origem estamos falando? Qual informação deveria ser alterada?

A expressão “estoque do anúncio” parece simples na conversa. Para o sistema, precisamos localizar exatamente o estado que essa expressão representa naquele contexto.

O caso da embalagem: observar sem inventar a causa

Em um dos episódios que relatei, a atualização de informações de peso ou medidas da embalagem recebia resposta 200, mas os dados não permaneciam como esperado.

Esse relato descreve um resultado observado. Eu não tinha uma causa e uma correção comprovadas para apresentar. Também não há base para atribuí-lo automaticamente ao modelo de User Products.

O caminho de investigação que eu adotaria começaria preservando o valor anterior, a alteração pretendida, o conteúdo enviado, a resposta e as consultas posteriores. Sem isso, fica difícil distinguir “não foi alterado” de “foi alterado e depois mudou novamente”.

Depois, examinaria hipóteses separadas: o campo corresponde à informação desejada? A consulta posterior observa o mesmo objeto? Existe outra rotina autorizada a atualizar esses dados? Há alguma regra documentada aplicável à categoria ou ao modelo da conta?

São perguntas de diagnóstico, não conclusões sobre o episódio.

O detalhe faz diferença porque reenviar a mesma alteração dez vezes pode produzir dez respostas iguais e nenhuma explicação nova. A quantidade de tentativas não substitui uma trilha de evidências. Nem mesmo quando a décima tentativa vem acompanhada de uma conversa séria com o monitor.

O caso das 56 variações e das 24 publicações

No outro caso, a intenção era copiar um anúncio com 56 variações, convertendo a estrutura para publicações no modelo de User Products. O resultado observado foi de 24 anúncios da mesma família. Faltavam 32 publicações em relação ao resultado esperado.

Essa conta identifica a diferença, mas ainda não revela onde ela surgiu.

Eu precisaria conferir quais variações entraram na operação, quais foram preparadas para envio, quais tiveram tentativa registrada e quais resultados puderam ser localizados depois.

Uma lista de 56 entradas não prova que 56 solicitações foram feitas. Da mesma forma, enxergar 24 resultados em uma consulta não prova, sozinho, que nenhum outro resultado existe. É preciso validar o alcance da consulta e a correspondência entre origem e destino.

Eu montaria uma linha por variação de origem, com uma identidade estável e seu resultado conhecido. Assim, seria possível localizar o primeiro ponto em que cada uma das 32 pendências deixou de ter uma evidência correspondente.

A causa desse caso também não estava confirmada. Poderia haver explicações diferentes para grupos diferentes de pendências. Antes de tentar novamente, eu procuraria separar o que foi rejeitado, o que nem chegou a ser enviado e o que ainda precisava ser localizado.

Antes de corrigir, identifique o que está comparando

Na prática, eu prepararia uma ficha curta da operação: conta, produto, publicação, variação quando aplicável, localização e objetivo da alteração.

Esses identificadores precisam ter funções claras. Usar apenas o título do anúncio para relacionar resultados é uma escolha frágil: títulos podem ser parecidos, e uma mesma descrição pode servir a variantes diferentes.

Também registraria a configuração relevante da conta e o modelo logístico verificados na documentação vigente. A presença de um identificador de User Product, isoladamente, não seria minha única evidência para escolher um fluxo de estoque.

Outra pergunta necessária é quem mantém a informação que estamos lendo. Podemos estar comparando uma intenção local com uma tela que ainda exibe dados anteriores, ou com uma consulta cujo escopo difere do que imaginávamos. Isso precisa ser investigado em cada caso.

Para mim, uma correção começa a ficar convincente quando consigo completar a frase: “Queríamos alterar este estado, neste objeto, sob estas condições, e verificamos o resultado desta forma.”

Sem essa frase, é muito fácil corrigir o lugar errado e comemorar cedo.

Aceitar, confirmar e conciliar são etapas diferentes

Eu desenharia a operação com estados que representem o que realmente sabemos. “Enviado” indica uma tentativa. “Resposta recebida” registra um retorno. “Confirmado” exige evidência compatível com o objetivo.

Quando falta essa evidência, prefiro um estado explícito de pendência. Isso evita que a ausência de informação seja transformada em sucesso ou fracasso por conveniência.

O raciocínio poderia aparecer neste pseudocódigo didático:

intencao = registrar_objetivo_e_identidades()
resposta = executar_fluxo_compativel()
guardar_evidencias(intencao, resposta)

se resposta_indica_rejeicao:
    marcar_rejeitado_com_motivo()
senao:
    atual = consultar_estado_relevante()

    se objetivo_atendido(intencao, atual):
        marcar_confirmado()
    senao:
        marcar_pendente_de_conciliacao()

As funções representam responsabilidades a implementar. A escolha dos recursos reais depende da conta, da operação e da documentação correspondente.

“Objetivo atendido” também precisa de uma definição cuidadosa. Para uma publicação, pode envolver encontrar a correspondência correta. Para estoque, exige considerar localização, momento da consulta e eventos posteriores. Comparar dois números sem esse contexto pode levar a um diagnóstico errado.

O tempo também participa da investigação

Suponha que, em um cenário fictício, a operação pretende deixar dez unidades disponíveis. A atualização acontece e, logo depois, uma venda reduz a disponibilidade para nove.

Uma consulta posterior que encontra nove não demonstra, por si só, que a atualização falhou. Ela pode estar observando uma mudança legítima ocorrida depois. Para entender o resultado, eu precisaria relacionar horários, eventos e regras da operação.

A situação inversa também merece cuidado. Encontrar o número esperado não prova automaticamente que aquela tentativa o produziu; o estado poderia já ser igual antes.

Por isso, eu preservaria o estado anterior e evitaria tratar uma consulta isolada como história completa.

Há ainda controle de concorrência. Nos recursos de estoque distribuído documentados, o Mercado Livre utiliza x-version; uma versão desatualizada pode gerar conflito 409, exigindo nova consulta antes de prosseguir. [4]

Esse caso é diferente de receber 200 sem observar a mudança pretendida. Cada sintoma precisa manter sua própria linha de investigação. Misturar todos eles em “a API está estranha” torna a conversa mais curta e o diagnóstico bem mais longo.

Conciliação significa fechar as correspondências

Eu usaria uma tabela de conciliação para ligar cada intenção ao resultado conhecido. Não precisa começar com uma ferramenta sofisticada. O essencial é conseguir responder o que falta e por quê.

Situação observada Como eu trataria
Resultado encontrado e compatível com a intenção Registrar a evidência e concluir aquela unidade
Rejeição identificada Corrigir a causa demonstrada antes de nova tentativa
Tentativa registrada, resultado desconhecido Investigar o destino antes de repetir
Entrada sem tentativa registrada Verificar por que o processamento não chegou até ela

No caso das variações, a unidade seria cada variação de origem e sua correspondência esperada. No caso da embalagem, seria a alteração solicitada e as evidências do estado observado.

A tabela também ajuda a evitar uma armadilha: repetir toda uma operação porque parte dela ficou pendente. Os resultados já confirmados precisam ser preservados.

Reprocessar somente o que foi identificado como necessário depende de um bom histórico. Sem ele, a aplicação fica tentando adivinhar o que já aconteceu, e essa costuma ser uma maneira cara de economizar no registro de informações.

O que vale guardar para conseguir explicar o problema

Eu priorizaria registros que permitam reconstruir a operação: identificador interno da tentativa, horário, identidades envolvidas, objetivo, conteúdo relevante enviado e resposta recebida.

Na leitura posterior, guardaria o recurso consultado, o momento da consulta e o estado encontrado. Quando houver um identificador de requisição fornecido pelo serviço, ele também pode ajudar a relacionar evidências em uma investigação.

Esses registros precisam excluir credenciais e limitar dados pessoais ao que for necessário. Um histórico útil deve permitir entender o problema sem transformar o diagnóstico em uma cópia desnecessária da conta inteira.

Também separaria fatos de hipóteses. “Recebemos 200 e a consulta seguinte mostrou o valor anterior” é uma observação. “O marketplace apagou o dado” já propõe uma explicação que exige evidência adicional.

Essa diferença melhora tanto a investigação interna quanto um eventual chamado de suporte. Quanto mais claramente conseguimos mostrar o que sabemos, mais fácil fica identificar o que ainda falta descobrir.

Como eu validaria uma correção

Depois de encontrar uma causa demonstrável, escolheria um caso controlado e um objetivo verificável. A mudança deveria responder à hipótese investigada, sem alterar várias partes do fluxo ao mesmo tempo.

Eu compararia o estado anterior, a execução e o resultado. Depois, observaria se a correção continua válida nas configurações às quais ela se destina.

Também incluiria um caso em que o comportamento antigo deve continuar funcionando. Uma correção para conta multiorigem não deveria ser espalhada indiscriminadamente para configurações diferentes.

Para publicação, verificaria correspondências e integridade do resultado, não apenas o total. Conseguir 56 resultados com duas entradas repetidas e duas ausentes continuaria sendo um problema, mesmo que o contador exibisse um número bonito.

Esses são critérios que eu adotaria para validar uma solução. Uma correção só estaria demonstrada quando esse conjunto de evidências fechasse a explicação do caso.

O melhor resultado é conseguir demonstrar o que aconteceu

A experiência com integrações me faz valorizar uma habilidade pouco vistosa: explicar uma operação do começo ao fim.

Um bom diagnóstico mostra o que se pretendia, qual caminho foi usado, quais respostas chegaram e como o resultado foi verificado. Isso também permite reconhecer quando ainda não temos evidência suficiente para encerrar o assunto.

User Products e estoque multiorigem deixam essa necessidade especialmente visível, porque a configuração da conta e a relação entre entidades fazem parte do problema. Mas o raciocínio serve para muitas integrações.

Na evolução de sistemas como a Oombe, eu considero esse cuidado fundamental para transformar ações em resultados que possam ser conferidos. O operador precisa entender se algo foi enviado, confirmado ou continua pendente.

O 200 OK continua sendo uma boa notícia. Eu apenas gosto de acompanhá-lo de uma informação ainda melhor: “Conferimos o resultado, e aqui está a evidência.”

Fontes

[1] IETF — RFC 9110, seção 15.3.1: 200 OK. Semântica HTTP.

[2] Mercado Livre Developers — Gestão de estoque multiorigem / User Products. Cenário de atualização de estoque em contas multiorigem.

[3] Mercado Livre Developers — User Products. Definição das entidades item e User Product.

[4] Mercado Livre Developers — Estoque distribuído. Controle de versão e tratamento de conflitos nos recursos documentados.

EN

Ernani Nascimento

Desenvolvimento de sistemas, inteligência artificial, automações, dados e jogos. Um espaço para compartilhar experiências e aprendizados construindo projetos reais.

Conheça o autor ↗

Continue explorando.

DA IDEIA À PRÁTICA

Tem algo em mente?
Vamos construir.

Vamos conversar ↗