API ecommerce na prática: chaves, webhooks e integrações da loja
Entenda a API REST e os webhooks da loja virtual sem jargão. Veja os principais casos de uso, como proteger a chave de acesso e por onde começar uma integração.
Neste artigo
- API ecommerce em linguagem de lojista
- REST e webhooks: as duas formas de conversa
- Casos de uso da API ecommerce no dia a dia
- Um fluxo real, do pedido pago à porta do cliente
- Segurança da chave de acesso: o cuidado que não pode faltar
- Passo a passo para tirar uma integração do papel
- A API ecommerce do Hotel das Lojas e a documentação
- Quando você não precisa de API (e tudo bem)
- Como o Hotel das Lojas ajuda a integrar sem dor de cabeça
- Conclusão: integre o que toma seu tempo
Em algum momento, toda loja que cresce esbarra na mesma pergunta: como fazer os sistemas conversarem sozinhos? O estoque está no ERP, os pedidos estão na loja, a planilha de vendas está no computador do financeiro e alguém passa horas copiando dados de um lado para o outro. É aí que entra a API ecommerce: o canal pelo qual a sua loja virtual troca informações com outros programas, sem ninguém digitar nada.
Muito lojista acha que API é assunto só para programador. A parte de escrever código, sim, fica com quem desenvolve. Mas entender o que a API faz, o que dá para automatizar e como proteger o acesso é decisão do dono da loja. É você quem define o que vai ser integrado, quem recebe a chave e o que acontece quando chega um pedido.
Neste artigo você vai ver, numa linguagem de lojista, o que são API REST e webhooks, os casos de uso mais comuns (ERP, estoque, pedidos, relatórios), como cuidar da segurança da chave de acesso e como usar a documentação da API do Hotel das Lojas para tirar uma integração do papel.
API ecommerce em linguagem de lojista
API é a sigla em inglês para "interface de programação de aplicações". Na prática, é um conjunto de portas que a plataforma deixa abertas, com regras claras, para que outro sistema possa pedir informações ou enviar instruções para a sua loja.
Pense num restaurante. O cliente não entra na cozinha: ele faz o pedido ao garçom, que leva à cozinha e volta com o prato. A API é o garçom. O sistema externo (um ERP, um painel de relatórios, um aplicativo) faz o pedido seguindo o cardápio, que é a documentação, e recebe a resposta organizada.
Com uma API, outro sistema consegue, por exemplo:
- Consultar a lista de pedidos de um período.
- Atualizar o estoque de um produto ou de uma variação.
- Cadastrar ou alterar produtos em quantidade.
- Ler dados de clientes para um sistema de atendimento.
- Mudar a etapa de um pedido, como "enviado".
REST e webhooks: as duas formas de conversa
Quando se fala em API de loja virtual, aparecem quase sempre dois termos: REST e webhook. Eles se complementam.
API REST: o sistema pergunta
REST é um padrão de comunicação pela internet em que cada tipo de informação tem um endereço, e o sistema usa ações como "buscar", "criar", "alterar" e "apagar". As respostas vêm num formato organizado (normalmente JSON), fácil de ler por qualquer linguagem de programação. É o sistema externo que toma a iniciativa: "me mostre os pedidos de hoje".
Webhook: a loja avisa
Webhook é o caminho inverso. Em vez de o ERP perguntar a cada cinco minutos se chegou pedido novo, a loja avisa na hora que algo aconteceu, enviando uma mensagem para um endereço definido por você. Exemplos de eventos: pedido criado, pagamento aprovado, pedido enviado.
| Característica | API REST | Webhook |
|---|---|---|
| Quem inicia | O sistema externo | A loja |
| Quando usar | Consultar, cadastrar, atualizar dados | Reagir a um evento assim que ele acontece |
| Exemplo | Atualizar o estoque de 300 produtos | Avisar o ERP que um pagamento foi aprovado |
| Vantagem | Controle total sobre o que buscar | Rapidez, sem consultas repetidas |
As melhores integrações usam os dois juntos: o webhook avisa que o pedido foi pago e o sistema usa a API para buscar os detalhes completos. Para entender os eventos em mais profundidade, leia o nosso artigo sobre webhooks para automatizar ações a cada pedido.
Casos de uso da API ecommerce no dia a dia
Integração com ERP
É o caso mais comum. O ERP centraliza estoque, financeiro e notas fiscais. A integração faz o pedido da loja entrar no ERP sozinho, a nota ser emitida e o estoque voltar atualizado. Para os ERPs mais usados, nem é preciso programar: o Hotel das Lojas já tem aplicativos prontos, como o aplicativo do Bling. A API entra quando você usa um sistema próprio ou menos comum. O artigo sobre quando a loja precisa de um ERP ajuda a decidir esse passo.
Estoque compartilhado com outros canais
Quem vende na loja física, em feiras ou por um sistema de terceiros precisa que o estoque fique igual em todos os lugares. Uma rotina que atualiza as quantidades pela API evita vender o que já saiu.
Pedidos e logística
Um operador logístico ou um sistema de expedição pode ler os pedidos pagos, gerar etiquetas e devolver o código de rastreio para a loja, que avisa o cliente.
Relatórios e BI
Para quem quer cruzar dados de vendas com custos, campanhas e metas, a API alimenta planilhas ou ferramentas de análise com pedidos e produtos, sem exportar arquivo à mão todo dia.
Automação de atendimento
Um sistema de atendimento pode consultar o status do pedido pela API e responder ao cliente que pergunta "cadê minha encomenda?".
Um fluxo real, do pedido pago à porta do cliente
Para visualizar como API e webhooks trabalham juntos, acompanhe um exemplo ilustrativo de uma loja de suplementos que usa um sistema próprio de expedição.
- 14h02: a cliente finaliza a compra com Pix. A loja registra o pedido como aguardando pagamento.
- 14h03: o pagamento é confirmado. A loja dispara um webhook de "pagamento aprovado" para o endereço do sistema de expedição.
- 14h03: o sistema de expedição confere a assinatura da mensagem, para ter certeza de que veio da loja, e responde que recebeu.
- 14h04: com o número do pedido em mãos, o sistema consulta a API e busca os itens, as quantidades, o endereço e o frete escolhido.
- 14h05: o pedido aparece na tela da equipe do estoque, já com a lista de separação.
- 16h30: a caixa é fechada e a etiqueta é gerada. O sistema usa a API para mudar a etapa do pedido para "enviado" e informar o código de rastreio.
- 16h31: a cliente recebe o aviso por e-mail com o rastreio, sem que ninguém tenha digitado nada.
Repare em três detalhes. Primeiro, o webhook só avisa; os dados completos vêm da API, o que deixa a mensagem leve e segura. Segundo, a assinatura é conferida antes de qualquer ação. Terceiro, se o sistema de expedição estivesse fora do ar às 14h03, uma boa integração consultaria a API depois, buscando os pedidos pagos que ainda não processou. É esse cuidado que separa uma integração confiável de uma que perde pedido em dia de promoção.
Segurança da chave de acesso: o cuidado que não pode faltar
Para usar a API, o sistema externo precisa de uma credencial, normalmente uma chave ou token. Quem tem essa chave consegue ler e, conforme as permissões, alterar dados da sua loja. Por isso, trate a chave como trata a senha do banco.
- Uma chave por integração. Se o ERP e o painel de relatórios usam chaves diferentes, você revoga uma sem derrubar a outra.
- Permissões mínimas. Use escopos: um painel de relatórios só precisa ler pedidos, não alterar produtos. A página de escopos da API mostra como limitar cada chave.
- Nunca em código público, planilhas compartilhadas, e-mails ou mensagens de WhatsApp.
- Revogue ao encerrar um contrato com desenvolvedor ou fornecedor.
- Confira a assinatura dos webhooks, para garantir que a mensagem veio mesmo da loja e não de alguém tentando se passar por ela.
Dica de especialista: mantenha uma lista simples com cada chave criada, para qual sistema ela serve, quem é o responsável e a data de criação. Quando algo estranho acontecer, essa lista economiza horas de investigação.
Passo a passo para tirar uma integração do papel
- Descreva o problema em uma frase. Exemplo: "quero que os pedidos pagos entrem no meu sistema de expedição sem digitação".
- Verifique se já existe aplicativo pronto. Muitas integrações não exigem programação; veja a página de integrações do Hotel das Lojas.
- Defina os dados e os eventos. Quais informações precisam ir e voltar, e em que momento.
- Crie uma chave com o escopo certo e entregue ao desenvolvedor por um canal seguro.
- Peça para o desenvolvedor começar pelo guia rápido e testar em pedidos de teste antes de ligar na operação real.
- Combine o tratamento de erros: o que acontece se o outro sistema estiver fora do ar? A integração precisa tentar de novo, e não perder pedidos.
- Acompanhe a primeira semana conferindo por amostragem se os dados batem dos dois lados.
A API ecommerce do Hotel das Lojas e a documentação
O Hotel das Lojas tem uma API REST com webhooks, documentada em docs.hoteldaslojas.com.br. A documentação foi organizada para o desenvolvedor começar rápido e para o lojista entender o que está sendo feito:
- Guia rápido para fazer a primeira chamada.
- Autenticação da API, explicando como a chave deve ser enviada.
- Escopos, paginação e erros, para integrações bem comportadas.
- Limites de requisições, que protegem a estabilidade de todas as lojas.
- Webhooks, com a lista de eventos e a verificação de assinatura.
- Scripts de teste e changelog, para acompanhar mudanças.
Do lado do painel, o tutorial API e webhooks: conectar ERPs e outros sistemas mostra onde criar as chaves e cadastrar os endereços que vão receber os avisos.
Quando você não precisa de API (e tudo bem)
API é poderosa, mas não é obrigatória. Muitas necessidades se resolvem com recursos prontos:
- Para cadastrar ou atualizar muitos produtos de uma vez, a importação por planilha resolve sem programação.
- Para vender em marketplaces, existem aplicativos de Mercado Livre, Shopee, Amazon e outros.
- Para ERPs como Bling, Tiny e Omie, a integração é ativada no painel no plano Crescer.
- Para relatórios do dia a dia, o painel já mostra faturamento, ticket médio e horários de pico.
A regra prática: procure primeiro o aplicativo pronto; use a API quando o seu processo for único.
Como o Hotel das Lojas ajuda a integrar sem dor de cabeça
Além da API, a plataforma oferece um conjunto de recursos que reduz a necessidade de desenvolvimento sob medida. São 85 aplicativos e integrações ativados no painel, cobrindo pagamentos, frete, ERPs, notas fiscais, marketplaces e marketing. Todos os planos têm produtos ilimitados e nenhuma comissão sobre as vendas.
Para lojas de tecnologia, onde integrações com distribuidores são comuns, temas como o tema Circuito para informática já trazem a vitrine pronta, e a API cuida da parte invisível: preços e estoques atualizados a partir do fornecedor.
E se a dúvida for sobre qual caminho seguir, a Central de Ajuda e o suporte orientam antes de você contratar um desenvolvedor.
Conclusão: integre o que toma seu tempo
Uma API ecommerce bem usada tira da rotina o trabalho repetitivo de copiar dados entre sistemas. Entenda a diferença entre API REST e webhook, comece pelos casos de uso que mais consomem horas, proteja cada chave com escopos e revogação e prefira aplicativos prontos quando eles existirem.
Quer explorar na prática? Crie sua loja no Hotel das Lojas com o teste grátis de 15 dias, sem cartão de crédito, e passe a documentação para o seu desenvolvedor testar com pedidos de verdade.
Perguntas frequentes
O que é API em uma loja virtual?
É um conjunto de acessos que a plataforma oferece para que outros sistemas leiam ou alterem dados da loja, como pedidos, produtos, estoque e clientes, seguindo regras documentadas. Com ela, ERPs, sistemas de logística e ferramentas de relatório trocam informações com a loja sem digitação.
Qual a diferença entre API e webhook?
Na API, o sistema externo toma a iniciativa e pede dados ou envia alterações. No webhook, é a loja que avisa outro sistema assim que algo acontece, como um pedido pago. As integrações mais eficientes usam os dois juntos.
Preciso saber programar para usar a API da loja?
Para criar uma integração própria, sim, ou contar com um desenvolvedor. Mas muitas necessidades já têm aplicativos prontos, como integração com ERPs e marketplaces, que são ativados no painel sem programação.
Como proteger a chave da API da minha loja?
Crie uma chave para cada integração, dê apenas as permissões necessárias, nunca compartilhe a chave em e-mails, mensagens ou código público e revogue o acesso quando encerrar o trabalho com um fornecedor. Verifique também a assinatura dos webhooks.
Escrito por
Marcelo F.
CEO Hotel das Lojas
Marcelo F. é CEO do Hotel das Lojas, plataforma brasileira de lojas virtuais, e tem 13 anos de experiência com vendas pela internet e plataformas de e-commerce. Acompanha de perto o dia a dia de milhares de lojistas e escreve sobre como criar, gerenciar e fazer crescer um e-commerce: da escolha do tema à primeira venda, de pagamentos e frete a marketing, SEO e marketplaces.
Crie sua loja virtual no Hotel das Lojas
Teste grátis por 15 dias, sem cartão. Planos a partir de R$ 99/mês, produtos e visitas ilimitados e sem comissão sobre vendas.
Continue lendo
Webhooks: como automatizar ações a cada pedido da loja
E se cada pedido pago disparasse sozinho a produção, a planilha e o aviso para a equipe? Veja como webhooks funcionam e receitas práticas de automação para lojistas.
API de e-commerce: o que é e para que serve na sua loja
API parece assunto só de programador, mas é ela que faz a loja conversar com ERP, planilhas e outros sistemas. Entenda o conceito com exemplos do dia a dia de quem vende.
Vender no Magalu: como entrar no marketplace do Magazine Luiza
O caminho do produto até a vitrine do Magazine Luiza: requisitos do cadastro, padrões de catálogo que evitam reprovação, integração por plataforma ou ERP e os cuidados de atendimento.