Pular para o conteúdo
Hotel das Lojas Blog
Marketplaces e integrações

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.

Lojista e desenvolvedor discutem um fluxo de integração desenhado no papel no escritório da loja
Compartilhe
Neste artigo
  1. API ecommerce em linguagem de lojista
  2. REST e webhooks: as duas formas de conversa
  3. Casos de uso da API ecommerce no dia a dia
  4. Um fluxo real, do pedido pago à porta do cliente
  5. Segurança da chave de acesso: o cuidado que não pode faltar
  6. Passo a passo para tirar uma integração do papel
  7. A API ecommerce do Hotel das Lojas e a documentação
  8. Quando você não precisa de API (e tudo bem)
  9. Como o Hotel das Lojas ajuda a integrar sem dor de cabeça
  10. 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ísticaAPI RESTWebhook
Quem iniciaO sistema externoA loja
Quando usarConsultar, cadastrar, atualizar dadosReagir a um evento assim que ele acontece
ExemploAtualizar o estoque de 300 produtosAvisar o ERP que um pagamento foi aprovado
VantagemControle total sobre o que buscarRapidez, 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.

  1. 14h02: a cliente finaliza a compra com Pix. A loja registra o pedido como aguardando pagamento.
  2. 14h03: o pagamento é confirmado. A loja dispara um webhook de "pagamento aprovado" para o endereço do sistema de expedição.
  3. 14h03: o sistema de expedição confere a assinatura da mensagem, para ter certeza de que veio da loja, e responde que recebeu.
  4. 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.
  5. 14h05: o pedido aparece na tela da equipe do estoque, já com a lista de separação.
  6. 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.
  7. 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

  1. Descreva o problema em uma frase. Exemplo: "quero que os pedidos pagos entrem no meu sistema de expedição sem digitação".
  2. 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.
  3. Defina os dados e os eventos. Quais informações precisam ir e voltar, e em que momento.
  4. Crie uma chave com o escopo certo e entregue ao desenvolvedor por um canal seguro.
  5. Peça para o desenvolvedor começar pelo guia rápido e testar em pedidos de teste antes de ligar na operação real.
  6. 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.
  7. 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.

Compartilhe
Marcelo F., CEO Hotel das Lojas

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.

Criar minha loja

Continue lendo