- Blog da Bruxel.AI
- Integrações da Bruxel: API pública, webhooks, Adobe Commerce e domínio próprio
Integrações da Bruxel: API pública, webhooks, Adobe Commerce e domínio próprio
Por Manuel Mattar4 min de leitura
Em resumo
A Bruxel se conecta aos seus sistemas por quatro caminhos: uma API REST com chaves por permissões, webhooks assinados que avisam quando algo muda, um módulo de Adobe Commerce que recebe o conteúdo publicado e a opção de entrar por um subdomínio da sua empresa. Cada chamada e cada aviso ficam registrados.
O problema: o PIM que ninguém vê
Um catálogo bem trabalhado serve de pouco se chega tarde à loja, se alguém tem que entrar para ver se um lote terminou ou se o ERP fica sabendo das mudanças por um arquivo enviado na sexta-feira. Integrar não é luxo: é o que faz o trabalho da equipe chegar aonde se vende.
O módulo Integrações da Bruxel reúne as peças para isso, no menu Canais: Sistemas conectados, Webhooks, Chaves de API e Domínio próprio.
Como funciona na Bruxel, passo a passo
1. A API pública
A API é REST e está documentada no portal de desenvolvedores, com referência, exemplos em curl, Python e JavaScript e um registro de mudanças. Com ela, o seu sistema pode enviar produtos, ler e escrever atributos, gerar descrições —uma a uma ou em lotes assíncronos com chave de idempotência—, exportar o catálogo em CSV por idioma, ler os canais e saber se um produto sai completo em cada um.
Cada chamada leva uma chave de API como token Bearer. As chaves são criadas em Canais → Chaves de API, por um administrador ou pelo proprietário; aparecem uma única vez, e cada uma leva só as permissões (scopes) de que precisa: ler o catálogo, escrevê-lo, gerar, exportar, ler canais. Sem a permissão, a API responde 403. Em cada chave, o registro de chamadas mostra o que ela pediu ou escreveu sobre cada produto.
2. Webhooks
Um webhook é um endereço seu ao qual a Bruxel avisa quando algo acontece: uma descrição ficou pronta, uma ficha mudou. Ao registrá-lo você escolhe quais eventos ouvir, e cada aviso vai assinado com um segredo que aparece uma única vez; se ele se perder, você o rotaciona e o anterior deixa de valer.
Se o seu endereço não responde, a Bruxel tenta de novo, e cada webhook mostra seu último sucesso, seu último erro e quantas falhas seguidas tem. A vista de entregas mostra cada tentativa: o que foi enviado, o que o seu endereço respondeu e quanto demorou, com o que parece uma credencial mascarado antes de guardar. «Reenviar» manda de novo o mesmo aviso. O guia de webhooks tem os detalhes.
3. Sistemas conectados
Em «Sistemas conectados» você registra os sistemas da sua operação —sua loja, seu ERP, seu armazém— com a chave com que chamam e o endpoint ao qual a Bruxel avisa. A tela diz quando cada um chamou pela última vez, quantos avisos estão por entregar e se o canal dele está saudável. Os fluxos da Bruxel os reconhecem pela chave. Quem vê é de operador para cima, e é uma função ativada por conta.
4. Adobe Commerce com Bruxel_Sync
Se a sua loja roda Adobe Commerce ou Magento Open Source 2.4.7, 2.4.8 ou 2.4.9, o módulo Bruxel_Sync é instalado com Composer e configurado no painel do Magento. O módulo chama a Bruxel; a Bruxel nunca entra na sua loja. A loja envia SKU, nome, categoria e os atributos que você escolher; a Bruxel devolve o conteúdo já publicado, na visão de loja de cada idioma.
A primeira sincronização é o momento delicado, e por isso o módulo vem com dois freios de fábrica: um modo de teste que mostra o que mudaria sem escrever nada, e uma opção que não sobrescreve os campos com texto que a Bruxel nunca tocou. Antes de escrever um campo pela primeira vez, ele guarda o valor anterior, e um comando o restaura. O guia de Adobe Commerce conta os quatro passos de configuração.
5. Domínio próprio
Sua equipe e seus fornecedores podem entrar por um subdomínio da sua empresa, como pim.suaempresa.com, com o seu logo na entrada e os links dos e-mails apontando para lá. Você pede à equipe da Bruxel pela central de ajuda; depois cria dois registros de DNS (um CNAME e um TXT) e clica em «Verificar agora». Custa 100 créditos por mês por domínio. O guia de domínio próprio explica cada registro.
Para quem é
Um exemplo hipotético: uma distribuidora com a loja em Adobe Commerce e um ERP próprio. A loja recebe as descrições assim que são publicadas pelo Bruxel_Sync, o ERP ouve um webhook e relê a ficha quando ela muda, e os fornecedores entram pelo subdomínio da distribuidora.
Serve a equipes que já têm sistemas e alguém técnico que possa conectá-los.
O que você precisa para começar
- Alguém com papel de administrador ou proprietário para criar chaves e registrar webhooks.
- Uma pessoa técnica do lado do seu sistema: para a API, para receber avisos ou para instalar o módulo no Magento.
- Para o domínio próprio, acesso ao DNS da sua empresa e saldo de créditos.
Limites honestos
- As chaves de API não são limitadas por marca nem por categoria: autorizam por permissões. Uma chave com permissão de escrever atributos escreve em todo o catálogo.
- Um webhook se desliga sozinho depois de várias falhas seguidas; é preciso reativá-lo.
- O Bruxel_Sync não cobre lojas com vários sites sem revisar o mapeamento à mão, nem o Adobe Commerce as a Cloud Service. As imagens não viajam para a loja, e o webhook do módulo é registrado à mão nesta versão.
- Se você usa Content Staging, uma campanha programada sobrescreve o que a Bruxel escreveu; é preciso publicar de novo depois.
- O domínio próprio é cadastrado pela equipe da Bruxel por enquanto, e a API pública e as páginas públicas ficam em bruxel.ai.
Para ver o módulo completo, abra a página de Integrações.
Perguntas frequentes
Quem pode criar uma chave de API?
Um administrador ou o proprietário da organização. A chave aparece uma única vez ao ser criada; a Bruxel guarda só o seu hash, então se ela se perder você a revoga e cria outra.
O que acontece se o meu sistema não responder a um webhook?
A Bruxel tenta de novo. Depois de várias falhas seguidas o webhook se desliga sozinho, e você o reativa na mesma tela quando o destino já responde.
O módulo de Adobe Commerce pode apagar minhas descrições?
Não. Ele nunca apaga nem escreve a URL do produto, e de fábrica não sobrescreve os campos que já têm texto. Além disso traz um modo de teste que mostra o que mudaria sem escrever nada.
Posso usar meu domínio raiz como domínio próprio?
Não. Funciona com um subdomínio, como pim.suaempresa.com. Um domínio raiz sozinho não pode ser usado.
Fontes
Sobre o autor
Manuel Mattar
Fundador da Bruxel.AI
Fundou em 2014 a Wolf Sellers, agência de comércio eletrônico na Cidade do México, e depois a Bruxel.AI, o PIM com IA.
Ver todos os artigos de Manuel MattarExperimente com o seu catálogo
Crie sua conta grátis e experimente a Bruxel com seus próprios produtos usando os créditos de boas-vindas.
Continue lendo
· 4 min de leitura
Canais e modelos de marketplace na Bruxel: um arquivo pronto por destino
Como funcionam os canais da Bruxel: colunas, valores por destino, modelos de Walmart México e Mercado Libre, o que falta a cada produto e feeds assinados.
· 4 min de leitura
Imagens por destino na Bruxel: uma foto, o formato de cada marketplace
Como a Bruxel prepara as fotos dos seus produtos para cada marketplace: tamanho, fundo, peso e nome, com um assistente de três passos e uma fila de revisão.
· 4 min de leitura
Conteúdo com IA na Bruxel: voz da marca, gerar e traduzir
Como a Bruxel gera as fichas de produto: a voz da marca que você configura, quanto custa gerar um ou em lote, como corrigir um dado errado e como traduz.