«Os dois sistemas têm API. Dá para integrar?» É uma pergunta frequente, mas a resposta não depende apenas de ambos disponibilizarem uma interface de programação de aplicações (API).
Uma API permite consultar dados ou executar determinadas operações através de regras definidas. A compatibilidade real depende do que é possível fazer, do significado dos dados e das regras do processo que se pretende automatizar. Dois sistemas podem trocar informações corretamente e, mesmo assim, produzir encomendas incompletas, preços errados ou registos duplicados.
Primeiro, definir o que a integração deve fazer
«Integrar WooCommerce com um ERP» identifica as plataformas, mas não esclarece a operação pretendida. Um objetivo mais concreto seria: quando uma encomenda de uma loja WooCommerce cumpre as condições definidas pela empresa, criar o registo correspondente no ERP, com cliente, produtos, quantidades, descontos, impostos, portes e método de pagamento.
Este cenário obriga a esclarecer quando ocorre o envio. Uma encomenda criada não é necessariamente uma encomenda paga: o momento correto pode depender do meio de pagamento, do estado da encomenda e do processo comercial. Também é preciso decidir se o ERP devolve atualizações de stock, faturação ou expedição e o que acontece em caso de cancelamento ou reembolso.
Quanto mais concreto for o fluxo, mais cedo se identificam funcionalidades necessárias, limitações e dependências do fornecedor.
Os dados existem, mas podem não ser compatíveis
Ler e escrever são capacidades diferentes
Uma API pode permitir consultar produtos, clientes e encomendas sem permitir criá-los ou alterá-los. Mesmo quando existe um recurso «Produtos», isso não significa que exponha todos os dados necessários: stock, EAN, categorias, imagens ou preços específicos para clientes empresariais podem não estar disponíveis naquela operação.
O mesmo acontece com os campos de escrita. Se o ERP exige NIF ou centro de custo para aceitar uma encomenda, não basta conseguir enviar nome, email e morada. É necessário verificar os campos obrigatórios, as operações suportadas e a possibilidade de extensões ou mecanismos alternativos.
No WordPress e no WooCommerce, a documentação distingue operações de consulta e alteração, bem como permissões associadas. Numa integração concreta, é indispensável fazer a mesma verificação nos dois sistemas, e não presumir que a existência de um endpoint permite todas as ações.
Os mesmos nomes podem representar conceitos diferentes
Considere este exemplo hipotético de uma loja WooCommerce ligada a um ERP:
| Diferença entre sistemas | Regra a definir |
|---|---|
| Cliente: pesquisa por email na loja e identificação por código interno no ERP | Associar os registos sem criar duplicados |
Produto: SKU ABC-123 e referência ERP ART-009872 | Estabelecer correspondências estáveis, incluindo variantes |
| Preço: valor final na loja e tabela de preços com descontos no ERP | Definir o valor válido e o tratamento de descontos e IVA |
| Stock: quantidade física e quantidade disponível para venda | Escolher o valor a sincronizar |
| Encomenda: «em processamento» na loja e validação, preparação e expedição no ERP | Relacionar estados e transições |
Esta correspondência entre campos e conceitos chama-se mapeamento de dados. Inclui os identificadores, mas também o significado de cada valor. O nome de um produto, por exemplo, não é uma chave fiável: pode mudar ou repetir-se. Pode ser necessário manter uma tabela de correspondência entre os identificadores internos de cada sistema.
Há ainda diferenças de formato que exigem conversão, como datas (2026-10-07 ou 07/10/2026), códigos de país (PT ou PRT) e valores monetários representados em euros ou cêntimos. Isoladamente, estas diferenças são geralmente resolúveis; em conjunto, aumentam a lógica e os testes necessários.
Quem decide qual é o dado correto?
Uma integração também precisa de definir o sistema de referência para cada informação. Numa arquitetura possível, o ERP determina preços e stock, o WooCommerce mantém descrições comerciais e cria encomendas, e o ERP gere a preparação e a faturação. Noutro negócio, as responsabilidades podem ser diferentes.
Sem estas regras, os sistemas podem atualizar o mesmo campo em sentidos opostos ou desencadear alterações sucessivas. Os estados merecem atenção especial: «em processamento», «validada», «expedida» e «faturada» não são equivalentes automáticos. É necessário definir que alterações são transmitidas, em que direção e com que consequências.
Autenticação, permissões e capacidade também contam
A integração precisa de conseguir aceder às operações de forma autorizada e segura. As APIs podem utilizar chaves, tokens, OAuth ou outros mecanismos. A REST API do WordPress suporta, entre outros métodos, Application Passwords para aplicações externas; o WooCommerce permite criar chaves com permissões de leitura, escrita ou ambas, sujeitas também às permissões do utilizador associado.
Devem ser concedidas apenas as permissões necessárias e previsto o armazenamento seguro, a renovação e a revogação de credenciais. Uma integração que só consulta stock não deve exigir acesso de escrita a encomendas sem justificação.
A capacidade é igualmente relevante. Muitas APIs devolvem resultados paginados, e algumas impõem limites ao número de pedidos. Uma sincronização que funciona com 20 artigos pode revelar problemas com 20 000. É preciso conhecer o número de registos por pedido, a forma de percorrer páginas, os limites aplicáveis e a possibilidade de processar alterações incrementais ou operações em lote ou de cache temporária, quando apropriado.
Estes fatores condicionam o tempo e o custo de sincronização; não podem ser avaliados apenas pela velocidade da ligação à internet.
Webhooks, consultas periódicas e «tempo real»
Se a empresa pretende atualizar o stock após cada venda, convém saber como o sistema identifica e comunica uma alteração.
Um webhook pode avisar outro sistema quando ocorre um evento, por exemplo a criação de uma encomenda. Em alternativa, a integração pode consultar periodicamente a API (polling) para procurar alterações. Nenhum dos métodos é universalmente superior: a escolha depende dos eventos disponíveis, do volume de dados e do atraso aceitável.
O WooCommerce disponibiliza webhooks para determinados eventos, mas isso não dispensa verificar quais interessam ao processo, os dados enviados, a autenticidade das notificações e o que acontece quando a entrega falha. Mesmo com webhooks, pode ser necessária uma reconciliação periódica para detetar alterações não processadas.
Se a integração consulta o ERP de 15 em 15 minutos, não deve ser apresentada como atualização instantânea. «Tempo real» precisa de ser traduzido num requisito mensurável: segundos, minutos ou outro intervalo aceitável para a operação.
Uma integração tem de funcionar também quando há erros
Imagine que o WooCommerce envia uma encomenda ao ERP. O ERP cria-a, mas a resposta perde-se por uma falha de comunicação. O WooCommerce ou o sistema intermédio tenta novamente e pode acabar por criar uma segunda encomenda.
Este risco exige mecanismos de idempotência ou prevenção de duplicados: usar um identificador externo estável, verificar se o registo já existe e, quando a API o suportar, utilizar uma chave de idempotência. Não se deve presumir que todas as APIs oferecem esta proteção automaticamente.
A gestão de erros também tem de distinguir situações diferentes. Uma indisponibilidade temporária ou um limite de pedidos pode justificar uma nova tentativa, com intervalo adequado. Já a falta de um campo obrigatório exige corrigir os dados; repetir o pedido não resolve o problema.
Registos de execução, alertas e possibilidade de retomar operações interrompidas são parte da solução. Sem estes mecanismos, a integração pode parecer funcional até ocorrer a primeira falha silenciosa.
Documentação e testes antes de fechar o projeto
Uma API bem documentada permite confirmar operações, campos, formatos, autenticação, respostas de erro e versões. Documentação incompleta, campos não descritos ou dependência exclusiva do apoio do fornecedor aumentam a incerteza e podem alterar o orçamento.
Também importa saber se existe um ambiente de testes onde seja possível criar clientes e encomendas fictícios sem afetar a operação real. Quando não existe, os testes devem ser planeados com especial cuidado, sobretudo se envolverem faturação, stock ou comunicações com clientes.
Perante dúvidas relevantes, uma pequena prova de conceito pode validar a autenticação, a leitura de produtos, a criação controlada de uma encomenda, a atualização de um estado e a resposta a uma falha. O objetivo não é construir toda a integração: é descobrir cedo se as operações críticas são possíveis.
Finalmente, é necessário considerar a manutenção. As APIs evoluem, podem mudar de versão ou deixar de suportar determinadas operações. Convém confirmar como o fornecedor comunica alterações e quem ficará responsável por acompanhar a integração.
O que verificar antes de dizer «é possível integrar»
Antes de escolher um plugin, uma integração própria ou uma plataforma intermédia, as respostas a estas perguntas devem estar suficientemente claras:
- Processo: o que desencadeia a integração, que dados circulam, em que direção e com que atraso máximo?
- Operações e campos: as duas APIs permitem ler e escrever tudo o que é obrigatório para o processo?
- Correspondências: existem identificadores estáveis e regras para preços, impostos, stock, formatos e estados?
- Responsabilidades: qual é o sistema de referência de cada dado e quem pode alterá-lo?
- Acesso e escala: que autenticação, permissões, paginação e limites se aplicam ao volume previsto?
- Sincronização: existem webhooks adequados ou serão necessárias consultas periódicas?
- Falhas: como se detetam erros, se repetem operações e se evitam duplicados?
- Validação e manutenção: a documentação é suficiente, existe ambiente de testes e foi possível comprovar os pontos críticos?
Se uma resposta essencial estiver em aberto, a conclusão correta pode ser «é potencialmente viável, mas ainda não está demonstrado que cumpra o processo necessário». É preferível assumir essa incerteza antes de fixar prazos e custos.
Conclusão
Ter uma API é uma vantagem, não uma garantia de compatibilidade. A viabilidade depende de operações disponíveis, dados coerentes, regras de negócio, segurança e comportamento perante falhas.
Uma boa integração não se limita a transportar informação entre plataformas. Faz com que os dois sistemas executem o processo pretendido de forma consistente, verificável e sustentável.
