O SAP S/4HANA disponibiliza APIs REST nativas (OData) para operações de cadastro de Business Partner — diferente das versões anteriores, que exigem uma camada intermediária para expor os dados. Isso abre dois caminhos arquiteturais para a integração com a Linkana, descritos abaixo.
Como funciona
Arquitetura 1 — Via camada intermediária do cliente
O comportamento é idêntico ao descrito no artigo Implementando a integração com o SAP (versões anteriores ao S/4HANA): a Linkana envia o payload ao endpoint da camada intermediária do cliente (SAP CPI ou equivalente), que orquestra as chamadas ao SAP internamente.
Esta arquitetura é indicada quando o cliente já possui uma camada de integração operacional, por exemplo, ou possui a opção de manter a orquestração sob sua responsabilidade.
Arquitetura 2 — Consumo direto da API do S/4HANA
Neste modelo, a Linkana consome diretamente as APIs OData do S/4HANA, sem camada intermediária. A Linkana é responsável por toda a orquestração das chamadas ao ERP.
Acesso às APIs
Para que este modelo funcione, a Linkana precisa ter acesso de rede às APIs OData do S/4HANA. Como o SAP costuma estar em ambiente on-premise ou em rede privada, é necessário que o cliente disponibilize um ponto de acesso externo — seja por meio de uma camada de exposição transparente (proxy reverso, API gateway ou equivalente), seja por liberação direta de rede. Sem esse acesso, a integração neste modelo não é viável.
Criação do fornecedor
Aprovação do fornecedor na Linkana dispara o envio ao SAP.
A Linkana autentica via OAuth 2.0 (ou outro método disponível) e verifica se o fornecedor já existe no SAP, consultando pelo CNPJ/tax ID.
Caso não exista, a Linkana cria o Business Partner com os dados cadastrais, endereço, contato, dados bancários, inscrições fiscais e vínculos alinhados no escopo do projeto.
O BP Number retornado pelo SAP é registrado no painel da Linkana e utilizado nas integrações subsequentes.
Atualização do fornecedor
Aprovação de formulário de atualização cadastral na Linkana dispara o envio ao SAP.
A Linkana autentica via OAuth 2.0, localiza o Business Partner pelo BP Number armazenado e recupera os dados atuais do registro.
Os dados são atualizados por meio de chamadas sequenciais às APIs correspondentes: dados gerais do BP, dados do supplier, endereço, dados bancários, de contato e demais informações, conforme alinhamento do projeto.
Como escolher entre as arquiteturas
Arquitetura 1 — Camada intermediária | Arquitetura 2 — API direta | |
Pré-requisito técnico | Endpoint exposto na camada do cliente | Acesso de rede às APIs SAP + credenciais OAuth |
Responsabilidade pela orquestração | Cliente | Linkana |
Complexidade de implantação | Menor (cliente já domina a camada) | Maior (requer acesso de rede, detalhamento técnico completo e suporte ativo do cliente) |
Dependência de terceiros | Camada intermediária do cliente | Camada de exposição de rede (se aplicável) |
A Arquitetura 2 é viável quando o cliente consegue garantir acesso de rede às APIs, fornecer documentação detalhada dos endpoints, credenciais de acesso e suporte técnico durante o desenvolvimento. Sem esses elementos, a Arquitetura 1 tende a resultar em menor prazo e menor risco.
Dados enviados ao SAP
Os dados enviados pela Linkana incluem, de forma geral:
Dados cadastrais do fornecedor (razão social, nome fantasia, CNPJ/CPF)
Endereço completo
Dados de contato comercial
Dados bancários
Dados fiscais (estadual e municipal)
Informações complementares constantes na base da RFB (natureza jurídica, regime tributário, etc)
Informações preenchidas em campos personalizados e formulários, conforme regras de negócio definidas
O mapeamento exato de cada campo para os campos do SAP é definido na planilha De-para durante a fase de validação de escopo, e pode variar de acordo com a configuração do ambiente SAP do cliente.
Pré-requisitos específicos
Arquitetura 1
Os mesmos descritos no artigo de versões anteriores: endpoint exposto pela camada intermediária, credenciais de acesso e documentação do comportamento de upsert.
Arquitetura 2
Acesso de rede externo às APIs OData do S/4HANA, viabilizado pelo cliente (proxy reverso, API gateway ou liberação direta). Este é um pré-requisito bloqueante: sem acesso, o desenvolvimento não pode ser iniciado.
URL base da API OData do S/4HANA
Credenciais OAuth 2.0 (client ID e client secret) para os ambientes de testes e produção
Definição dos campos e funções da API que devem ser utilizados pela Linkana. A API OData do S/4HANA é extensa e seu consumo depende da configuração específica de cada implementação — campos obrigatórios, valores aceitos e entidades disponíveis variam entre clientes. O responsável técnico do cliente deve mapear e documentar claramente quais campos devem ser preenchidos, quais endpoints devem ser consumidos e quais parâmetros se aplicam ao seu ambiente antes do início do desenvolvimento.
Definição dos company codes, organizações de compras e demais campos parametrizáveis ou selecionáveis de cadastro
Mapeamento de campos Linkana → SAP
Disponibilidade do responsável técnico do cliente durante o desenvolvimento e testes
Bloqueio e desbloqueio de fornecedores
O status de bloqueio do fornecedor no SAP pode ser gerenciado pela Linkana. Quando um fornecedor é bloqueado ou desbloqueado na Linkana, a integração dispara automaticamente a atualização correspondente no SAP, sem necessidade de intervenção manual no ERP, desde que a API disponibilizada permita a ação. As regras de negócio que definem como um fornecedor deve ser bloqueado ou desbloqueado são alinhadas durante o escopo do projeto.