Glossário de integrações e e-commerce: API, webhook, hub e OMS

O que é. API REST é um estilo de interface entre sistemas que usa requisições HTTP (GET, POST, PUT, DELETE) sobre recursos identificados por URLs, geralmente trocando dados em JSON. É o padrão dominante para integrar ERP, loja virtual e marketplaces porque é simples, sem estado e fácil de consumir em qualquer linguagem. No varejo, é a API REST que um ERP chama para criar um pedido, consultar o saldo de um produto ou atualizar um preço em um canal de venda. Cada chamada é independente: o cliente envia tudo o que o servidor precisa para responder, sem guardar sessão entre uma requisição e outra.

O que é. GraphQL é uma linguagem de consulta para APIs em que o cliente especifica exatamente quais campos quer receber em uma única requisição, evitando o excesso ou a falta de dados típicos de várias chamadas REST. Em vez de muitos endpoints, há geralmente um só, e o consumidor monta a consulta. No varejo, é útil para uma vitrine headless que precisa, numa única ida ao servidor, trazer nome, preço, fotos e saldo de um produto sem disparar quatro chamadas diferentes. Reduz tráfego em telas complexas, mas exige cuidado com consultas pesadas e com o controle de profundidade para não sobrecarregar o servidor.

O que é. Webhook é uma notificação automática que um sistema envia para uma URL do seu sistema assim que um evento acontece, sem que você precise ficar perguntando. É o modelo push: o marketplace avisa na hora que houve um novo pedido, em vez de o ERP consultar a cada minuto. No varejo, um webhook de "pedido pago" pode disparar a emissão da nota fiscal e a reserva de estoque em segundos. Boas práticas de 2026 mandam responder rápido com 2xx, validar a assinatura do payload e processar o trabalho pesado de forma assíncrona, porque a maioria dos provedores espera resposta em poucos segundos.

O que é. É a escolha entre receber eventos por push (webhook, o sistema avisa) ou por pull (polling, você pergunta de tempos em tempos). Polling é simples mas desperdiça chamadas: estima-se que apenas cerca de 1,5% das consultas de polling encontram algo novo. Webhook entrega quase em tempo real e gera muito menos tráfego, mas exige assinatura, retry e idempotência. No varejo, o padrão recomendado em 2026 é híbrido: webhook como canal principal para capturar pedidos na hora e um polling periódico de reconciliação como rede de segurança, para recuperar eventos que se perderam por instabilidade ou indisponibilidade.

O que é. Rate limit é o teto de requisições que uma API aceita por intervalo de tempo (por exemplo, 120 chamadas por minuto). Ao estourar o limite, o servidor responde com erro 429 Too Many Requests e geralmente indica quando tentar de novo. No varejo, isso aparece quando uma integração tenta atualizar o estoque de milhares de SKUs de uma vez em vários marketplaces e começa a ser bloqueada. O tratamento correto envolve respeitar os cabeçalhos de limite, aplicar espera com recuo exponencial (backoff) e enfileirar as atualizações em vez de disparar tudo simultaneamente.

O que é. Sandbox é o ambiente de testes isolado, com dados fictícios, que reproduz a API de produção para você validar uma integração sem afetar pedidos, estoque ou cobranças reais. No Brasil, marketplaces, adquirentes e a própria emissão de nota fiscal eletrônica costumam exigir uma fase de homologação antes de liberar o ambiente de produção. No varejo, é onde você testa a criação de um pedido, a baixa de estoque e a emissão de NF-e simuladas antes de ligar tudo de verdade. Pular essa etapa é a causa mais comum de falhas que só aparecem com clientes reais.

O que é. Hub de integração (ou hub de marketplaces) é uma camada central que conecta um ERP a vários canais de venda de uma só vez, traduzindo os formatos de cada um para um padrão único. Em vez de manter dezenas de integrações ponto-a-ponto, a loja liga uma vez ao hub e o hub fala com Mercado Livre, Shopee, Amazon e outros. No varejo, é o hub que recebe pedidos de todos os canais, devolve atualização de estoque para todos eles e centraliza o de-para de produtos. Reduz drasticamente o custo de manutenção quando o número de marketplaces cresce.

O que é. Integração ponto-a-ponto é a ligação direta entre dois sistemas, feita sob medida para aquele par específico (ERP ↔ um marketplace). É rápida de montar quando há poucos sistemas, mas vira um emaranhado conforme os canais aumentam: cada novo marketplace exige uma integração nova, e qualquer mudança em um deles pode quebrar várias outras. No varejo, é comum começar assim com um ou dois canais e depois sentir a dor da manutenção. A partir de um certo número de conexões, hub de integração ou iPaaS passam a ser a escolha mais barata de operar.

O que é. iPaaS (Integration Platform as a Service) é uma plataforma em nuvem para criar, executar e monitorar integrações entre aplicações, com conectores prontos, mapeamento de dados e orquestração de fluxos, sem precisar manter servidores próprios. No varejo, um iPaaS pode orquestrar o caminho pedido → ERP → estoque → transportadora → financeiro com regras visuais e tratamento de erros. O mercado cresce rápido: projeções para 2026 colocam o iPaaS global na casa das dezenas de bilhões de dólares, com o varejo entre os segmentos que mais adotam para unir e-commerce, estoque e pagamentos. Difere de um hub por ser mais genérico e configurável.

O que é. Middleware é o software intermediário que fica entre dois ou mais sistemas e cuida da comunicação entre eles: traduz formatos, transforma dados, controla filas e trata erros, sem que as pontas precisem conhecer os detalhes uma da outra. Hub de integração e iPaaS são tipos de middleware. No varejo, é a camada que recebe o pedido bruto do marketplace, normaliza os campos para o formato do ERP e devolve o status atualizado ao canal. Um bom middleware desacopla os sistemas, de modo que trocar um marketplace ou um ERP não obrigue a reescrever todas as integrações.

O que é. Conector é um componente pré-construído que sabe falar com um sistema específico — um marketplace, uma adquirente, um ERP — encapsulando autenticação, endpoints e formatos daquele parceiro. Em um hub ou iPaaS, você não programa a integração do zero: ativa o conector daquele canal e configura o de-para. No varejo, ter um conector pronto para um marketplace popular reduz semanas de desenvolvimento a horas de configuração. A qualidade de um hub se mede em boa parte pela quantidade e pela manutenção dos conectores, já que as APIs dos parceiros mudam com frequência.

O que é. Fila é uma estrutura onde mensagens (pedidos, atualizações, eventos) ficam aguardando para serem processadas em ritmo controlado, em vez de tudo de uma vez. Processamento assíncrono significa aceitar a tarefa, responder rápido e fazer o trabalho pesado depois, em segundo plano. No varejo, em um pico de vendas o webhook de pedidos joga cada evento numa fila; os trabalhadores consomem um a um, emitem nota e baixam estoque sem travar. Filas absorvem picos, isolam falhas e permitem reprocessar mensagens. Mensagens com defeito vão para uma fila morta (dead-letter queue) para análise, sem bloquear o restante.

O que é. ERP (Enterprise Resource Planning) é o sistema de gestão que centraliza as operações da empresa — estoque, compras, vendas, financeiro, fiscal — numa base de dados única. No varejo, é o ERP que guarda o cadastro de produtos, controla o saldo real de estoque, calcula impostos e emite a nota fiscal. Em uma operação com múltiplos canais, o ERP costuma ser a fonte da verdade: o hub de integração lê dele o estoque e o preço e devolve para ele os pedidos capturados nos marketplaces. Sem um ERP bem integrado, cada canal vira uma ilha de dados desencontrados.

O que é. OMS (Order Management System) é o sistema que gerencia o ciclo de vida do pedido de ponta a ponta: captura em todos os canais, alocação de estoque, roteamento para o ponto de separação ou loja, faturamento, expedição e pós-venda. No varejo omnichannel, é o OMS que decide se um pedido do site sai do centro de distribuição ou de uma loja física mais próxima (ship-from-store) e consolida o status para o cliente. Difere do ERP por focar na orquestração do pedido entre canais e estoques, enquanto o ERP cuida da gestão geral. Os dois costumam trabalhar integrados.

O que é. PIM (Product Information Management) é o sistema que centraliza e padroniza todas as informações de catálogo — descrições, atributos, fotos, dimensões, categorização — para distribuí-las de forma consistente a cada canal. No varejo, é o PIM que garante que o mesmo produto apareça com ficha completa e correta no site, no marketplace e na loja, cada um com suas regras de campo. Em 2026, com agentes de IA decidindo o que entra na consideração de compra, um catálogo limpo, estruturado e enriquecido no PIM virou vantagem competitiva: dados pobres deixam o produto invisível para a busca por IA.

O que é. SKU (Stock Keeping Unit) é o código único que identifica cada variação vendável de um produto — uma camiseta azul tamanho M é um SKU diferente da mesma camiseta tamanho G. É a unidade pela qual se controla estoque, preço e vendas. No varejo multicanal, cada marketplace pode ter seu próprio código para o mesmo item, o que torna o SKU interno a chave que amarra tudo. Confundir variações no nível de SKU é uma das principais causas de venda do produto errado e de erro de saldo, daí a importância de um cadastro de SKUs disciplinado e do de-para entre canais.

O que é. SKU mapping, ou de-para, é a tabela que relaciona o código interno de cada produto com o código que cada marketplace usa para o mesmo item. É o que permite ao hub saber que o "MLB-12345" do marketplace corresponde ao SKU "CAM-AZ-M" do ERP. No varejo, um de-para correto é o que garante que o pedido capturado baixe estoque do produto certo e que a atualização de saldo chegue ao anúncio certo. Falhas de de-para causam overselling, expedição trocada e divergência de estoque — por isso o mapeamento precisa ser validado a cada novo anúncio ou variação.

O que é. É o catálogo de produtos estruturado e exposto por API de forma que agentes de IA consigam descobrir, comparar e até comprar itens em nome do consumidor. No comércio agêntico que avança em 2026, a API deixa de ser camada de integração e passa a ser a própria vitrine: se um agente não consegue ler preço, atributos e disponibilidade em tempo real, o produto sequer entra na consideração de compra. No varejo, isso exige dados limpos no PIM, sinais em tempo real de estoque e preço, e respostas consistentes entre sistemas — os mesmos fundamentos que sustentam boas integrações já viram requisito para ser encontrado por IA.

O que é. Sincronização de estoque é o processo de manter o saldo de cada produto igual em todos os canais a partir de uma fonte única, geralmente o ERP. Quando uma venda ocorre em qualquer marketplace, o saldo é abatido e a nova quantidade é propagada a todos os anúncios. No varejo, é o que evita vender o último item simultaneamente em dois canais. A sincronização pode ser por evento (webhook a cada venda) ou por lote periódico, e em operações grandes costuma combinar as duas. Latência alta de sincronização é a causa direta do overselling e da insatisfação do cliente.

O que é. Overselling é vender mais unidades de um produto do que existem em estoque, em geral porque a sincronização entre canais atrasou e dois pedidos consumiram o mesmo saldo. No varejo, leva a cancelamentos, custo de reembolso, punição no ranking do marketplace e perda de reputação. As defesas combinam sincronização de estoque de baixa latência, reserva de saldo no momento da captura do pedido e, às vezes, um colchão de segurança que esconde as últimas unidades. É um dos problemas que mais justifica investir em hub de integração com atualização por evento em vez de lotes lentos.

O que é. ETL (Extract, Transform, Load) é o processo de extrair dados de uma origem, transformá-los para um formato padrão e carregá-los em um destino — tipicamente em lote e em horários programados. No varejo, um ETL pode consolidar todas as vendas do dia de vários marketplaces, padronizar os campos e carregar num data warehouse para relatórios e conciliação. Difere da integração por evento (webhook) por trabalhar em blocos e não em tempo real. Variações modernas incluem o ELT, em que a transformação ocorre depois da carga, aproveitando o poder de processamento do destino.

O que é. Idempotência é a propriedade de uma operação que pode ser executada várias vezes produzindo sempre o mesmo resultado, sem efeitos duplicados. É essencial em integrações porque praticamente todo provedor entrega eventos "ao menos uma vez", nunca "exatamente uma vez": o mesmo webhook de pedido pode chegar duas vezes. No varejo, sem idempotência um pedido repetido viraria nota duplicada, baixa de estoque dobrada ou cobrança em dobro. A solução é usar uma chave de idempotência (um identificador único do evento) e registrar o que já foi processado, ignorando repetições. É a viga mestra de qualquer integração de produção confiável.

O que é. Marketplace API é a interface que cada canal de venda (Mercado Livre, Shopee, Amazon e outros) expõe para que sistemas externos publiquem anúncios, recebam pedidos, atualizem estoque e preço e consultem status. Cada uma tem suas regras de autenticação, limites e formatos, o que torna trabalhoso integrar muitos canais um a um — daí o valor de hubs e conectores. No varejo brasileiro, onde os dez maiores e-commerces concentram cerca de 62% do faturamento, dominar bem as APIs dos principais marketplaces define o alcance da operação. As mudanças frequentes nessas APIs exigem manutenção contínua dos conectores.

O que é. Gateway de pagamento é a camada que conecta a loja às adquirentes e bandeiras, transmitindo de forma segura os dados da transação para autorização e captura. É a ponte entre o checkout e o dinheiro: recebe o pedido de pagamento, encaminha à instituição financeira e devolve a resposta de aprovação ou recusa. No varejo, é o gateway que processa Pix, cartão e boleto e dispara o webhook de "pagamento aprovado" que destrava a emissão da nota e a separação. Costuma trabalhar junto com antifraude e tokenização, e a integração com o ERP é o que permite conciliar o que entrou de fato.

O que é. Antifraude é o conjunto de regras e modelos que analisa cada transação para estimar o risco de fraude antes de aprová-la, considerando histórico, comportamento, dispositivo e padrões suspeitos. No varejo online, fica no fluxo de pagamento e pode aprovar, recusar ou enviar o pedido para análise manual. Uma boa integração liga o resultado do antifraude ao status do pedido no ERP, segurando a expedição até a liberação. O ajuste é sempre um equilíbrio: regras muito rígidas barram clientes legítimos e geram falsos positivos; regras frouxas aumentam chargebacks. Aqui o foco é proteção de transação de venda, não verificação cadastral de identidade.

O que é. Tokenização é a substituição de um dado sensível, como o número do cartão, por um token sem valor fora do contexto autorizado. A loja guarda e usa o token; os dados reais ficam no ambiente seguro do provedor de pagamento. No varejo, isso permite oferecer compra com um clique e cobranças recorrentes sem que o sistema da loja precise armazenar números de cartão, reduzindo o escopo de conformidade com o padrão PCI DSS. Em integrações, o token viaja entre checkout, gateway e ERP no lugar do dado original, diminuindo a superfície de risco caso algum sistema seja comprometido.

O que é. Split de pagamento é a divisão automática do valor de uma transação entre vários recebedores no momento da liquidação — por exemplo, parte para o lojista, parte para o marketplace e parte para um parceiro logístico. No varejo de marketplace e em modelos de plataforma, o split evita repasses manuais e reduz erro de acerto financeiro. A integração precisa registrar com precisão quanto coube a cada parte para que a conciliação feche. É um conceito de meios de pagamento; não confundir com o futuro mecanismo fiscal de recolhimento na liquidação previsto na reforma tributária brasileira.

O que é. Conciliação automática é o cruzamento, feito por software, entre o que foi vendido, o que as adquirentes e marketplaces informam ter recebido e o que efetivamente caiu na conta, identificando divergências como taxas, antecipações, estornos e repasses pendentes. No varejo multicanal, fazer isso à mão é inviável: são milhares de transações com regras de tarifa diferentes por canal. A integração entre gateway, marketplace e ERP alimenta a conciliação com os dados certos, permitindo detectar rapidamente um repasse a menor ou uma taxa cobrada errada. É o que transforma o financeiro de reativo em controlado.

O que é. Headless commerce é a arquitetura em que a vitrine (a "cabeça", o front-end que o cliente vê) é separada do motor de comércio (back-end de catálogo, carrinho, pedidos), que se comunicam por API. Isso permite trocar ou ter vários front-ends — site, app, totem, assistente de voz — sem mexer no núcleo. No varejo, dá liberdade para criar experiências sob medida e responder mais rápido a novos canais. O mercado de headless cresce em ritmo acelerado, na casa de 22% ao ano, impulsionado pela busca por flexibilidade e pela necessidade de expor o catálogo a novos pontos de contato, inclusive agentes de IA.

O que é. API-first é a abordagem de projetar a API antes da interface, tratando-a como o produto principal: toda funcionalidade nasce acessível por API, e qualquer canal — incluindo sistemas externos e agentes de IA — consome a mesma camada. É um dos pilares da arquitetura MACH (microsserviços, API-first, nuvem nativa e headless). No varejo, ser API-first significa que o catálogo, o estoque e os pedidos estão disponíveis programaticamente desde o início, o que facilita integrar marketplaces, abrir novos front-ends e, em 2026, ser encontrado por agentes de IA que leem catálogos por API. Reduz retrabalho e prepara a operação para canais ainda não previstos.