Imagine uma fábrica que opera uma linha de montagem automatizada. Cada peça entra por um lado da esteira e passa por várias etapas de ajuste, inspeção e montagem, até sair do outro lado como um produto pronto. Tudo parece fluido, até que uma peça chega torta, com uma cor incorreta ou um formato não previsto. Nesse momento, o fluxo para e nada mais segue adiante.
Com essa metáfora, conseguimos visualizar como funciona o caminho dos dados em uma integração entre ERP, hub e marketplace.
O produto nasce no ERP como um conjunto de informações brutas: nome, SKU, preço, estoque e descrições ainda sem tratamento. Esse material é então colocado na esteira do hub, que tem a função de organizar, ajustar e enviar esses dados de acordo com as regras de cada canal.
Mas essa linha de dados não é infalível. Um token expirado pode impedir a entrada de pedidos. Um título mal formatado pode travar a saída de um produto. Uma categoria incorreta pode levar à rejeição sem aviso claro. E, assim como em uma linha física, muitas vezes o erro visível é apenas a consequência de um desvio ocorrido em uma etapa anterior.
Neste artigo, vamos percorrer esse fluxo digital, entendendo como os dados percorrem APIs, requisições, endpoints e formatos até chegarem corretamente ao marketplace. A ideia não é ensinar a programar, mas mostrar como conhecer esse caminho ajuda o lojista e o operador a interpretar falhas, tomar decisões mais conscientes e manter a operação fluindo.
O caminho dos dados
Para começarmos a falar do caminho dos dados, precisamos entender o que são APIs.
Uma API é uma interface de comunicação disponibilizada pelo canal para que ações sejam realizadas nele. Pense nela como um caixa eletrônico. Você não conversa com um atendente, mas interage com um sistema que disponibiliza funções específicas: consultar saldo, sacar dinheiro ou transferir valores.
Para isso você precisa:
– Inserir seu cartão;
– Informar sua senha;
– Escolher uma operação válida;
– Digitar os dados corretamente.
Se qualquer uma dessas etapas estiver errada – senha inválida, saldo insuficiente, número de conta inexistente -, o sistema bloqueia a operação ou retorna uma mensagem de erro.
Com as APIs é a mesma coisa: através delas, o hub informa os dados para o marketplace, escolhe a operação (como publicar um produto ou consultar um pedido), e espera uma resposta estruturada. Se o token estiver vencido, o SKU incorreto ou o formato dos dados inválido, o canal recusa a ação – às vezes com uma mensagem clara, às vezes com um código, e outras vezes (para o nosso terror) com silêncio.
E assim como caixas eletrônicos de bancos diferentes têm regras, menus, operações e layout diferentes, cada marketplace tem sua própria API, com seu próprio jeito de funcionar. Entender como interagir corretamente com cada um deles é essencial para a operação funcionar com segurança e fluidez.
Por isso, os canais disponibilizam documentações técnicas para que os hubs se integrem corretamente. Elas funcionam como manual de instruções, que orientam os integradores sobre quais os dados exigidos, quais formatos devem ser respeitados e quais operações podem ser realizadas. Um hub não escolhe como enviar as informações do produto, mas se adequa às exigências do marketplace.
As APIs seguem padrões como REST, que garante que a comunicação entre integrador e marketplace ocorra de forma fluida, segura e previsível. Podemos compará-lo à gramática da linguagem humana: para que duas pessoas se entendam, é necessário seguir regras gramaticais. Com os sistemas não é diferente: o padrão REST define como os dados devem ser organizados e enviados.
Dentro desse padrão, temos métodos (que definem o tipo da ação que está sendo executada). Vejamos alguns:
– POST (usado para criação/cadastro)
– PUT (usado para atualização)
– GET (usado para consulta)
Além disso, precisamos de um endpoint, que é a rota disponibilizada pelo marketplace para acessar determinado recurso. Por exemplo:
– Recurso: produtos.
-> Endpoint (rota de acesso): http://marketplace.com.br/api/v1/products
E como os dados do meu produto são enviados? Conforme o padrão REST, os dados do produto devem ser enviados como um JSON estruturado (exemplo: {“sku”: “ABC123”, “price”: 199.90, “stock”: 5}). Chamamos esses dados de body request (corpo da requisição). Em uma requisição de criação de produto, existe um corpo que contém os dados do seu produto.
Cada interação que ocorre entre o hub e a API acontece por meio de uma request (requisição). É como enviar uma mensagem formal dizendo: “Quero que você (marketplace) execute uma ação com esses dados que estou te enviando.
”Exemplo: “enviar uma request de criação de produto” significa requisitar à API que cadastre um novo produto no canal.
Recapitulando: através do endpoint (rota), eu consigo acessar o recurso “produto”. Com o método, defino qual ação será executada – como criar, consultar ou atualizar. E com o preenchimento do body request, envio os dados necessários para que essa ação seja realizada corretamente. Toda essa interação é uma requisição que será enviada ao canal.
Como cadastrar um novo produto no marketplace
Como meu hub se comunica com a API?
– Seleciona o método POST;
– Verifica qual o endpoint disponibilizado pelo marketplace para acessar os produtos;
– Prepara os dados do produto no body request;
– Envia essa solicitação para a API através do endpoint com as suas credenciais;
– Recebe a resposta da API com o resultado da request.
Vamos tentar imaginar o processo como uma operação nos Correios. Pense no hub como um atendente de balcão: ele não cria o conteúdo da encomenda, mas é o responsável por preparar e despachar da forma correta.
O ERP entrega os dados do produto como um pacote bruto (como se você chegasse com uma caixa ainda sem etiqueta ou nota fiscal). O hub atua como o atendente, responsável por:
– Selecionar o serviço certo (no hub, seleciona o método POST para criar);
– Definir o endereço correto (no hub, seleciona o endpoint correto da API);
– Preencher a documentação obrigatória (no hub, a estruturação do body com dados em JSON);
– Apresentar identificação válida (no hub, o token de autenticação enviado com a requisição).
Se faltar alguma informação ou o formato estiver incorreto, o canal recusa o pacote – muitas vezes sem explicação clara. Por isso, entender como funciona essa “postagem digital” ajuda o lojista a interpretar falhas, agir rápido e manter a operação rodando com eficiência.