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

  1. Webhook (Wikipedia, em inglês)
  2. Representational state transfer (Wikipedia, em inglês)
  3. CNAME record (Wikipedia, em inglês)

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 Mattar

Experimente 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

Integrações da Bruxel: API pública, webhooks, Adobe Commerce e domínio próprio