Integrar o SAP Business One com o BigCommerce é ligar o ERP da empresa a uma loja em SaaS: o Business One guarda artigos, preços, stock e documentos, e o BigCommerce vende e envia as encomendas de volta. A ligação faz-se entre o Service Layer do Business One, que é uma API REST com OData, e as APIs REST e os webhooks do BigCommerce.
Para uma PME, a vantagem é evitar o trabalho manual: encomendas reintroduzidas no ERP, stock atualizado por ficheiro e preços que mudam num sítio e não no outro. O ponto de atenção é o contrário do habitual, porque o BigCommerce tem limites de pedidos por janela de tempo que a integração tem de respeitar. Tratamos estes projetos dentro da nossa área de integração de SAP com ecommerce.
Neste guia vê quando compensa integrar, como se liga cada lado, que fluxos montar, o que dizem as regras de limites e de webhooks do BigCommerce e uma lista de verificação antes de arrancar.
Quando compensa ligar o Business One ao BigCommerce?
Compensa quando o ERP já é a fonte de verdade e a loja deixou de ser um canal de teste. Os sinais mais claros são estes:
- As encomendas online são digitadas no Business One.
- O stock da loja é atualizado uma ou duas vezes por dia, e há vendas sem disponibilidade.
- Há listas de preços ou descontos por cliente no ERP que a loja devia refletir.
- O catálogo cresce e a atualização manual deixou de ser viável.
Se a loja vende poucas referências com preço único, uma importação por ficheiro pode chegar durante algum tempo. A integração automática paga-se quando os erros manuais começam a custar vendas ou horas de equipa.
Como se liga o Business One ao BigCommerce
A ligação mais segura usa uma camada intermédia entre os dois sistemas, que recebe, transforma, guarda em fila e reenvia. É nela que se vê o que falhou, e é ela que respeita os limites de cada lado.
O lado do Business One
O Service Layer exige um início de sessão com a base de dados da empresa, o utilizador e a palavra-passe, e devolve uma sessão que acompanha os pedidos seguintes. A sessão expira por inatividade, por isso a integração deve reutilizá-la e autenticar de novo quando necessário. Cada sessão pertence a uma só base de dados.
Como o Business One está muitas vezes instalado na rede da empresa, é preciso decidir como a camada de integração lá chega: VPN, lista de endereços permitidos ou proxy inverso. Os campos personalizados (prefixo U_) são diferentes em cada empresa e devem ser levantados logo no início.
O lado do BigCommerce
O BigCommerce disponibiliza APIs REST para catálogo, encomendas e clientes, e webhooks para avisar a integração de eventos da loja. Segundo a documentação, o webhook envia um payload leve, que no caso de uma encomenda traz apenas o identificador; para obter os dados completos, a integração chama depois a API da encomenda.
Limites do BigCommerce que condicionam o desenho
Cada pedido à API consome uma unidade de uma quota partilhada por todas as aplicações da loja. Segundo a documentação do BigCommerce, a quota das aplicações OAuth renova a cada 30 segundos e varia por plano: para os planos Growth e Core, são 150 pedidos por 30 segundos, e para o Scale, 450. Os planos Performance variam por plano e recurso.
| Situação | O que a documentação indica | O que fazer |
|---|---|---|
| Quota esgotada | Resposta 429 | Esperar o tempo indicado |
| Cabeçalhos de limite | X-Rate-Limit-* | Ajustar o ritmo ao restante |
| Várias aplicações | Quota partilhada | Reservar margem |
| Carga alta na loja | 429 sem cabeçalhos | Tentar mais tarde |
Em caso de 429, a documentação manda esperar os milissegundos indicados no cabeçalho X-Rate-Limit-Time-Reset-Ms antes de repetir, aumentando a espera se os limites continuarem a ser atingidos. Na prática, isto significa que uma carga inicial do catálogo deve ser distribuída no tempo e feita em fila.
Que fluxos montar
| Fluxo | Sentido | Mecanismo | Cuidado |
|---|---|---|---|
| Artigos e preços | Business One para loja | Lotes em fila | Quota da API |
| Stock | Business One para loja | Eventos e lotes | Stock vendável |
| Encomendas | Loja para Business One | Webhook mais consulta | Duplicados |
| Estados e faturas | Business One para loja | Eventos | Avisos ao cliente |
Para as encomendas, o desenho natural é receber o webhook, gravar o identificador numa fila e processá-lo depois. A documentação pede que o destino responda logo com HTTP 200, sem tarefas lentas, porque uma resposta fora desse intervalo conta como não recebida.
Webhooks: o que acontece quando falham
Se o destino não confirmar, o BigCommerce volta a tentar em intervalos crescentes. Segundo a documentação, a primeira repetição acontece ao fim de 60 segundos e a última cerca de 48 horas depois da primeira tentativa. Se continuar a falhar, o webhook é desativado e é enviado um email para o endereço da aplicação.
- Se a taxa de sucesso do destino cair abaixo de 90% numa janela de dois minutos, o domínio fica bloqueado durante três minutos.
- Um webhook também é desativado após 90 dias sem atividade, e reativa-se com is_active igual a true.
- Os webhooks não substituem a reconciliação: convém comparar periodicamente as encomendas da loja com as do ERP.
Passo a passo de um arranque seguro
Numa loja em SaaS com um ERP interno, o arranque deve ser gradual e começar por leitura.
- Levantar no Business One os artigos, listas de preços, armazéns e campos personalizados que a loja vai usar.
- Criar as credenciais da integração nos dois lados com permissões mínimas, guardadas num cofre.
- Carregar um subconjunto do catálogo, em lotes distribuídos no tempo, e comparar com o ERP.
- Registar os webhooks de encomendas e validar que o destino responde de imediato.
- Enviar encomendas de teste e confirmar o documento criado: linhas, IVA, portes e condições de pagamento.
- Simular indisponibilidade do ERP e verificar que a fila guarda e reenvia sem duplicar.
Só depois de estes passos estarem estáveis vale a pena passar a produção, com um relatório diário de diferenças nas primeiras semanas.
Riscos mais comuns
- Cargas de catálogo sem controlo de ritmo, que esgotam a quota e atrasam outras aplicações.
- Webhooks desativados por falhas e ninguém dar por isso.
- Encomendas duplicadas por reenvio sem chave única.
- Campos personalizados do Business One diferentes entre testes e produção.
- Sessões do Service Layer expiradas a meio de uma carga.
Lista de verificação antes de contratar
- Está definido o que manda em artigos, preços, stock e clientes.
- O acesso da camada de integração ao Business One está resolvido e seguro.
- O plano do BigCommerce e a respetiva quota de pedidos são conhecidos.
- Há fila e controlo de ritmo nas cargas e nas atualizações.
- Existe alerta para webhooks desativados ou com falhas repetidas.
- Os campos personalizados do Business One estão documentados.
- Há reconciliação periódica de encomendas e de stock.
- Alguém é responsável pela ligação depois da entrada em produção.
Como trabalhamos na Avafa
Começamos por mapear dados, responsáveis e casos de erro, e só depois escolhemos a camada de ligação. Pode ver como organizamos estes projetos na nossa página de integração de SAP com ecommerce.
Outras combinações com SAP
- SAP Business One com Salesforce Commerce Cloud
- SAP Business One e SAP Commerce Cloud
- SAP Business One e Adobe Commerce
- SAP S/4HANA com BigCommerce
- SAP Business One e WooCommerce
Perguntas frequentes
O BigCommerce tem ligação pronta com o SAP Business One?
Não é algo que se possa assumir. Em regra faz-se com uma camada intermédia que fala com o Service Layer de um lado e com as APIs do BigCommerce do outro.
O que é uma resposta 429?
É o aviso de que a quota de pedidos se esgotou. A integração deve esperar o tempo indicado no cabeçalho de resposta e só então repetir.
Posso receber toda a encomenda no webhook?
Não. O payload é leve e traz o identificador; os dados completos obtêm-se depois, chamando a API da encomenda.
Como evito encomendas duplicadas?
Enviando cada encomenda ao ERP com uma chave única e fazendo a camada de integração recusar repetições dessa chave.
Qual é o primeiro fluxo a automatizar?
O stock e as encomendas, porque são os que mais erros visíveis causam e permitem validar a ligação antes de tratar clientes e preços especiais.