A integração da sua loja com sistemas externos — ERP, CRM, marketplace, qualquer ferramenta de gestão — acontece por dois caminhos diferentes, e é importante entender a diferença entre eles:
a) Pelo caminho da API, é o seu sistema externo que toma a iniciativa: ele faz uma chamada para a plataforma pedindo ou enviando informação (cadastrar um cliente, consultar pedidos, atualizar estoque, e assim por diante).
b) Pelo caminho do webhook, é o contrário: a própria plataforma avisa o seu sistema automaticamente sempre que algo acontece por aqui, como o fechamento de um pedido ou o cadastro de um cliente novo. Ou seja, a API responde quando é chamada; o webhook chama por conta própria.
Os dois ficam configurados na mesma tela do painel.
Como acessar a tela
O painel administrativo, acesse Menu → Configurações → API.
A tela tem duas abas: Webhook, onde você habilita e configura os eventos que quer receber, e Configurações Avançadas, com parâmetros complementares da integração.
No topo da página também ficam o link para a documentação técnica (o Swagger, que reúne todos os recursos e exemplos de chamada para a sua equipe de integração consultar) e o token de acesso da sua loja, usado para autenticar as chamadas.
Só um usuário administrador Flexy pode gerar um novo token de acesso. Se isso for feito, o token anterior para de funcionar imediatamente. Caso precise alterar, entre em contato conosco através do e-mail suporte@flexy.com.br
Se sua conta for um marketplace, com mais de uma loja, cada loja tem o seu próprio token, visto em Shopping → Lojas → editar a loja → aba API.
Assim você consegue definir se o melhor é criar os produtos para o shopping (assim, informe o token do shopping na API) ou se o melhor é criar os produtos para os lojistas (assim, informe o token da loja na API)
Menu: Shopping > Lojas > Editar > Aba API
Como funciona
Pelo caminho *ERP → plataforma*, o sistema externo faz chamadas HTTP (GET, POST, PUT, PATCH ou DELETE, dependendo do recurso) autenticadas por um token de acesso.
- Pelo caminho *plataforma → ERP*, a própria plataforma dispara uma requisição HTTP para uma URL cadastrada pelo lojista, sempre que um dos eventos configurados ocorre.
❗ Diferença importante: a API é passiva (só responde quando é chamada); o webhook é ativo (a plataforma toma a iniciativa de avisar o sistema externo).
A API: enviando e consultando informações
A API vai bem além de clientes e pedidos. Hoje ela cobre produtos, estoque, categorias, notas fiscais, representantes, orçamentos, planos de pagamento, listas de preço e promoções (cupom, catálogo, carrinho, frete grátis etc.), cada um com seus próprios métodos disponíveis:
| Recurso | Métodos disponíveis |
| --- | --- |
| Clientes | GET, POST, PUT |
| Pedidos | GET, POST, PUT (status, rastreio, forma de envio), DELETE, captura/reembolso |
| Produtos | GET, POST, PUT, PATCH |
| Estoque | GET, PUT |
| Categorias | GET, POST, PUT, PATCH |
| Notas fiscais | GET, POST |
| Representantes | GET, POST, PUT, DELETE |
| Orçamentos, planos de pagamento, listas de preço | GET, POST, PUT |
| Promoções | GET, POST, PUT, DELETE |
Nem todo recurso aceita todos os métodos, então vale sempre confirmar no Swagger antes de programar uma chamada nova.
A autenticação é sempre pelo token de acesso da loja, junto com o código de referência da loja, e o mesmo token vale para tudo — não existe um token separado só para leitura.
Sobre o protocolo: recomendamos fortemente usar HTTPS em todas as chamadas, pela segurança dos dados. Se o seu ERP não for compatível com HTTPS, você vai precisar de um middleware que converta as chamadas antes de chegarem à plataforma.
Webhooks: quando a plataforma avisa você
Atualmente o sistema disponibiliza 12 eventos para disparo automático:
- Fechamento de pedido
- Alteração de status de pedido
- Cadastro de cliente
- Alteração de cliente
- Newsletter
- Processamento de imagem
- Mensagens/contato
- Atualização de estoque
- Atualização de preço
- Atualização de status de produto
- Loja criada (só em contas marketplace)
- Loja atualizada (só em contas marketplace)
Os dois últimos só aparecem na tela para contas do tipo marketplace; em uma loja única, eles ficam ocultos.
Para habilitar, acesse Menu → Configurações → API → aba Webhook, informe a URL de destino do evento que você quer acompanhar e habilite. Repita para cada evento que fizer sentido para a sua integração.
Quando o evento acontece, a plataforma tenta entregar a notificação na hora. Se a URL de destino não responder com sucesso dentro de 30 segundos, essa tentativa é considerada falha, e o sistema tenta de novo automaticamente — ao longo de até 3 dias, com um total de até 6 tentativas. Depois desse prazo, o disparo automático para, e qualquer nova tentativa só acontece se você reenviar manualmente.
Cada evento tem um formato de dado (JSON) próprio e fixo — não é possível personalizar o que é enviado em cada um.
Um ponto de atenção: a plataforma não valida o certificado SSL da URL de destino, então tecnicamente até uma URL HTTP simples funciona. Mesmo assim, recomendamos sempre usar HTTPS, para proteger os dados que estão sendo trafegados.
Autenticando o sistema que recebe o webhook
Se o sistema que recebe os avisos exigir autenticação para aceitar a notificação, isso é configurado na aba Configurações Avançadas, na mesma tela de API. Marque "Habilitar autenticação" e escolha uma das duas opções do campo "Selecione a autenticação":
Em Basic Auth, você informa o Client ID, o Client Secret e a Url de acesso ao token. Ao clicar em Autenticar, a plataforma já faz uma chamada de teste para esse endereço usando essas credenciais e confirma na hora se conseguiu obter um token válido.
Em OAuth2, além do Client ID e do Client Secret, você informa também a Url de autorização, a Url de proprietário do recurso e a Url de redirecionamento. Ao clicar em Autenticar, você é levado para a tela de login do próprio sistema externo; depois de autorizar o acesso, a plataforma recebe e guarda o token automaticamente.
Uma vez autenticado com sucesso, esse token passa a ir no cabeçalho Authorization de toda notificação de webhook enviada por aquela loja — vale para todos os eventos habilitados, não é possível configurar autenticação diferente por evento.
Se a autenticação nunca chegou a ser concluída com sucesso, ou o token não estiver mais válido no momento do disparo, o webhook ainda é enviado, só que sem esse cabeçalho preenchido. Caso o sistema externo recuse por isso, entra no mesmo fluxo de novas tentativas já descrito acima — não existe renovação automática de token, então se sua integração depende de autenticação, vale acompanhar o histórico de disparos de perto.
Acompanhando os disparos
Na tela de histórico, para cada URL configurada, o sistema exibe quantas vezes aquele webhook foi disparado, se o retorno foi de sucesso ou erro, quando o evento ocorreu e qual registro está relacionado (o CPF/CNPJ de um cliente, o número de um pedido, por exemplo). É o primeiro lugar para checar se uma integração está indo bem ou apresentando falhas recorrentes.
Entrando no histórico de uma URL específica, você chega ao log de disparos, com o detalhe de cada tentativa individual: o código HTTP retornado, se foi sucesso ou erro, e a data. A partir daqui, dois botões ajudam bastante na hora de investigar um problema: um mostra a requisição exata que foi enviada — o JSON completo, igual ao que o sistema externo recebeu — e outro mostra a resposta que voltou de lá.
E se o problema já foi resolvido do lado do sistema externo, não é preciso esperar a próxima tentativa automática nem recriar o evento na plataforma: dá para reenviar aquele disparo específico com um clique, direto dessa tela.
Importante
- Depois de 3 dias sem sucesso, um disparo de webhook para de ser retentado automaticamente — a partir daí, só reenvio manual.
Precisa de ajuda? Precisa de apoio para configurar ou tirar mais dúvidas? Fale com o CSM da sua conta ou entre em contato com suporte@flexy.com.br. |
Comentários
0 comentário
Por favor, entre para comentar.