Integração SAP: como ligar o SAP à loja online, ao CRM e ao banco em Portugal

Resposta curta: integração SAP é ligar o SAP Business One ou o SAP S/4HANA aos outros sistemas da empresa, como a loja online, o CRM, o banco e as ferramentas de logística, para que encomendas, clientes, artigos, stocks, faturas e pagamentos circulem sozinhos, sem ninguém a copiar dados à mão. Em Portugal há uma regra extra: as faturas têm de sair de software certificado pela AT, com ATCUD e código QR, e os dados de faturação têm de poder ser exportados no ficheiro SAF-T (PT). Uma boa integração SAP respeita isso desde o primeiro desenho.

O que é integração SAP?

Um ERP como o SAP é o sítio onde a empresa guarda os dados que contam: clientes, artigos, preços, stocks, encomendas, faturas e contabilidade. O problema começa quando esses dados também vivem noutros sítios. A loja online tem as suas encomendas, o CRM tem os seus contactos, o banco tem os seus movimentos. Sem integração, alguém exporta, copia e corrige. Com integração, cada sistema fala com o SAP através de uma interface técnica (API) e os dados passam de um lado para o outro segundo regras definidas por si.

Na prática, uma integração SAP responde sempre a três perguntas:

• Que dados? Por exemplo encomendas, clientes, artigos, stock ou pagamentos.
• Em que direção? Da loja para o SAP, do SAP para a loja ou nos dois sentidos.
• Quando? Em tempo real, de hora a hora ou uma vez por noite.

Imagine uma PME de Aveiro que vende material de escritório numa loja WooCommerce e gere tudo no SAP Business One. Sem integração, a equipa passa as encomendas da loja para o SAP todas as manhãs e atualiza o stock da loja à mão. Com integração, a encomenda entra no SAP assim que é paga, o armazém vê-a de imediato e o stock da loja acompanha o do SAP. É este tipo de trabalho que fazemos em integração SAP e, de forma mais geral, em integração de sistemas.

O que se costuma ligar ao SAP

Se a loja online ainda está a ser escolhida, a forma como a plataforma se liga ao ERP deve entrar na decisão. Comparamos as duas opções mais comuns em Shopify ou WooCommerce, e o CRM tem um guia próprio na página sobre HubSpot.

SAP Business One: a Service Layer

Para o SAP Business One, a porta de entrada moderna é a Service Layer. A SAP descreve-a como uma API de extensão para consumir dados e serviços do SAP Business One, assente em HTTP e OData (SAP Help Portal). Suporta OData versão 3 e versão 4 (SAP Learning). Os pontos técnicos mais importantes:

• Endereço. A Service Layer funciona por HTTPS. O caminho /b1s/v1 usa OData v3 e /b1s/v2 usa OData v4 (SAP Help Portal).
• Sessão. A integração começa com um pedido de login e recebe um cookie B1SESSION, que tem de acompanhar cada pedido seguinte. No exemplo do manual, a sessão expira ao fim de 30 minutos sem atividade (SAP Help Portal).
• Operações em lote. Vários pedidos podem seguir juntos num único POST para $batch (SAP Help Portal).
• Paginação. As listas grandes chegam por páginas, e a integração tem de seguir a ligação para a página seguinte até ao fim, ou pedir com $top e $skip apenas o que precisa.

Um pedido simples para ler um cliente tem este aspeto:

GET https://servidor:50000/b1s/v2/BusinessPartners('C20000')
Cookie: B1SESSION=<id da sessão>

Além da Service Layer existe a DI API, usada por muitos add-ons. O manual da SAP inclui uma comparação entre as duas, útil para quem herda uma integração antiga (SAP Help Portal). Para integrações novas com lojas online, CRM ou ferramentas na cloud, a Service Layer é normalmente o ponto de partida, porque fala a mesma língua (HTTP e JSON) que esses sistemas.

SAP S/4HANA: APIs e acordos de comunicação

No SAP S/4HANA Cloud Public Edition, todas as APIs públicas estão no SAP Business Accelerator Hub, onde se podem descobrir, explorar e testar (SAP Help Portal). A SAP distingue:

• Serviços de entrada e de saída. De entrada quando outro sistema chama o S/4HANA, de saída quando é o S/4HANA a chamar outro sistema.
• Serviços síncronos e assíncronos. No síncrono, quem pede espera pela resposta. No assíncrono, só espera pela confirmação de receção, o que deixa os sistemas menos dependentes um do outro (SAP Help Portal).
• Acordos de comunicação. Para haver comunicação segura entre sistemas é preciso criar um acordo de comunicação (communication arrangement), baseado num cenário de comunicação que agrupa as APIs a usar (SAP Help Portal).

O acordo de comunicação é, na prática, a lista de autorizações da integração: que sistema externo, com que utilizador técnico, pode usar que conjunto de APIs. Vale a pena tratá-lo como um tema de segurança e não só como um passo técnico. Em instalações on-premise ou na edição privada as opções podem ser diferentes, por isso confirme sempre a documentação da sua versão.

Faturação em Portugal: o que a integração tem de respeitar

Esta é a parte que distingue uma integração SAP portuguesa de uma integração feita noutro país. Não substitui o parecer do seu contabilista certificado, mas mostra as regras que mexem com o desenho técnico.

• Software certificado. O Decreto-Lei n.º 28/2019 obriga os sujeitos passivos com sede, estabelecimento estável ou domicílio em Portugal a usar exclusivamente programas de faturação certificados pela AT, nas condições que o diploma define (Diário da República). A AT mantém uma lista pública dos programas e versões certificados (Portal das Finanças). Essa lista inclui entradas da SAP Portugal para o SAP Business One e para o SAP S/4HANA, mas o que conta é a versão e a localização que a sua empresa usa, por isso confirme-a com o seu parceiro SAP.
• Séries comunicadas à AT. As séries de faturas e de outros documentos fiscalmente relevantes têm de ser comunicadas eletronicamente à AT antes de serem usadas. Por cada série, a AT atribui um código de validação que integra o código único do documento (Diário da República).
• ATCUD. A Portaria n.º 195/2020 define o formato ATCUD:CodigodeValidação-NumeroSequencial. O código de validação tem pelo menos oito carateres, e o ATCUD tem de constar em todas as páginas do documento, imediatamente acima do código QR quando este existe (Portal das Finanças).
• Código QR. As faturas e outros documentos fiscalmente relevantes emitidos por programas certificados têm de ter um código QR, feito segundo as especificações técnicas publicadas pela AT (Portal das Finanças). A AT reúne a informação sobre séries, ATCUD e código QR numa página própria (Portal das Finanças).
• SAF-T (PT). Todos os programas certificados têm de exportar o ficheiro XML SAF-T (PT), e os contribuintes de IRC e IRS que usam programas certificados são obrigados a exportar o ficheiro relativo à faturação (Portal das Finanças).
• Comunicação à AT. Os programas de faturação podem comunicar os elementos dos documentos à AT em tempo real por webservice, identificando-se com um certificado digital assinado pela AT (Autoridade Tributária e Aduaneira).
• Faturas a entidades públicas. Quem fornece o Estado, autarquias, hospitais ou outras entidades públicas no âmbito de contratos públicos tem de faturar em formato eletrónico. A eSPap coordena essa implementação e publica os prazos e as normas técnicas, como a CIUS-PT (eSPap).

A consequência para o desenho é simples: a loja online, o CRM ou a ferramenta de integração não devem emitir faturas por conta própria. Criam a encomenda e os dados do cliente, com o NIF correto. A fatura nasce no programa certificado, seja o SAP ou outro software de faturação, que trata da série, do ATCUD, do código QR, da comunicação e do SAF-T. Se a loja tem de mostrar a fatura ao cliente, vai buscar o PDF ao programa certificado depois de emitido. As regras e os prazos mudam com alguma frequência, por isso consulte sempre as páginas da AT sobre faturação e certificação de programas antes de fechar o desenho.

Primavera, PHC, Moloni e InvoiceXpress

Muitas empresas portuguesas não têm tudo no SAP. É comum encontrar o SAP numa empresa-mãe ou numa área do negócio e, ao lado, Primavera, PHC ou Sage noutra, ou uma loja online que fatura com Moloni ou InvoiceXpress. Nesses casos a pergunta passa a ser: qual dos sistemas é o dono de cada dado?

• Um só sistema emite faturas por série. Se o InvoiceXpress fatura as vendas online e o SAP fatura as vendas por grosso, cada um tem as suas séries comunicadas à AT. A integração leva os documentos já emitidos para o SAP, para controlo de crédito e relatórios, sem os voltar a emitir.
• Ferramentas locais com API. O Moloni tem uma API documentada que devolve dados em JSON e usa autenticação oAuth (Moloni), e o InvoiceXpress publica a documentação da sua API v2 (InvoiceXpress). Isso facilita ligá-los ao SAP sem exportações manuais.
• Contabilidade separada. Quando o contabilista trabalha noutro programa, o ficheiro SAF-T (PT) e os relatórios do SAP continuam a ser a base. Combine com ele o formato e a frequência antes de automatizar.

Três caminhos para fazer a integração SAP

1. Conector pronto. Existem conectores comerciais entre o SAP Business One e as lojas online e CRM mais usados. São o caminho mais rápido quando o fluxo é padrão, por exemplo levar encomendas da Shopify para o SAP e devolver o stock. Confirme se o conector já foi usado com a localização portuguesa e como trata o NIF, as taxas de IVA e as séries.

2. Plataforma de integração. Ferramentas como o n8n, o Make ou a SAP Integration Suite ligam vários sistemas com fluxos visuais, chamadas HTTP e tratamento de erros. Servem bem quando há três ou quatro sistemas e regras moderadas. Explicamos o n8n em o que é o n8n.

3. Integração à medida. Um serviço próprio fala diretamente com a Service Layer ou com as APIs do S/4HANA. Compensa quando as regras são únicas, os volumes são altos ou os conectores não tratam as exceções, como preços por cliente, vários armazéns, artigos com lotes ou clientes com condições de pagamento especiais.

Erros comuns

• Faturas emitidas no sítio errado. Um plugin da loja que gera "faturas" fora do programa certificado cria documentos sem valor fiscal e uma confusão difícil de desfazer. Defina logo no início quem emite o quê.
• Encomendas duplicadas. A mesma notificação da loja chega duas vezes e cria duas encomendas no SAP. Guarde o identificador da encomenda de origem e ignore repetições.
• NIF e moradas incompletos. Um cliente empresarial sem NIF válido dá problemas na fatura e no SAF-T. Valide o NIF à entrada e decida o que acontece às vendas a consumidor final.
• IVA mal mapeado. Taxas do continente, da Madeira e dos Açores, isenções e vendas intracomunitárias têm de bater com os códigos de IVA do SAP. Peça ao contabilista que valide o mapeamento antes de ligar em produção.
• Sessões que expiram. Na Service Layer, uma integração que ignora o fim da sessão começa a falhar sem aviso. Trate o erro de sessão inválida e volte a fazer login automaticamente.
• Ninguém é dono do fluxo. Decida quem recebe o alerta quando uma sincronização falha e onde ficam os registos de cada envio.

Como começar

1. Desenhe os fluxos numa página. Que dados, em que direção, com que frequência e qual o sistema que manda em cada um.
2. Confirme a parte fiscal. Que programa certificado emite cada tipo de documento, que séries existem e como o SAF-T (PT) é gerado.
3. Escolha o caminho. Conector, plataforma ou integração à medida, conforme o quadro acima.
4. Teste num ambiente de testes. Com encomendas reais anonimizadas, devoluções, notas de crédito e os casos estranhos que a sua equipa conhece de cor.
5. Arranque por partes. Primeiro clientes e artigos, depois encomendas, depois pagamentos.

Se a integração faz parte de um projeto maior, como uma nova loja, veja também quanto custa uma loja online, porque a ligação ao ERP pesa no orçamento.