Pular para o conteúdo principal

Preparação do SAP S/4HANA Cloud

Introdução​

Este artigo mostra o que preparar no SAP S/4HANA Cloud Public Edition do cliente para o Invent Apps se conectar ao SAP e automatizar o recebimento de documentos fiscais de entrada. Não é preciso conhecer o Invent Apps nem ser especialista em integração SAP.

O Invent Apps recebe o XML do documento fiscal do fornecedor (NF-e, CT-e ou NFS-e), encontra o pedido de compra correspondente no SAP e registra automaticamente as etapas de recebimento: entrada de mercadoria ou registro de serviço, fatura do fornecedor e nota fiscal. Quando não existe pedido, ele também pode criar o pedido de compra. O módulo Master Data mantém os cadastros de parceiros e itens sincronizados a partir do SAP (veja Sincronização de cadastros).

O essencial

No SAP S/4HANA Cloud Public Edition, toda API é liberada por um Communication Arrangement (acordo de comunicação), sempre baseado num cenário pronto da SAP identificado por um código SAP_COM_xxxx. O parceiro cria três coisas, todas por apps Fiori, sem transação no SAP GUI: um usuário de comunicação, um sistema de comunicação que representa o Invent Apps e um acordo para cada cenário usado.

Se o cliente usa SAP S/4HANA Private Edition, inclusive via RISE with SAP, a liberação é diferente. Siga a Preparação do SAP S/4HANA Private.

Público:

QuemO que faz com este artigo
Parceiro SAP ou administrador do tenantExecuta a preparação: usuário e sistema de comunicação, acordos de comunicação, autenticação e endereço de acesso.
Parceiro SAP (MM e Fiscal) e key usersLeem Como funciona, Campos customizados e Tipos de nota fiscal e tomam as decisões de processo: campos da chave de acesso, tipos de nota fiscal e uso de folha de serviço.
Consultor Invent SoftwareConduz o alinhamento com o parceiro e confere o checklist antes do teste de conexão.

Conceitos​

TermoO que significa na prática
SAP S/4HANA Cloud Public EditionERP da SAP em nuvem compartilhada, com duas atualizações por ano feitas pela SAP e configuração padronizada. Endereço típico: myXXXXXX.s4hana.cloud.sap.
APIPorta de entrada padronizada para outro sistema ler ou gravar dados no SAP sem usar a tela. Cada API cuida de um objeto: pedido de compra, fatura, nota fiscal.
Communication Scenario (cenário de comunicação)Pacote pronto da SAP que agrupa uma ou mais APIs e as autorizações necessárias. Tem um código, como SAP_COM_0053 para pedido de compra.
Communication User (usuário de comunicação)Usuário técnico usado só por sistemas, nunca por pessoas. É com ele que o Invent Apps se identifica.
Communication System (sistema de comunicação)Cadastro que representa o sistema externo, no caso o Invent Apps, e diz qual usuário de comunicação ele usa.
Communication Arrangement (acordo de comunicação)Liga um cenário a um sistema de comunicação e libera as APIs daquele cenário para o Invent Apps. Um acordo por cenário.
TenantCada ambiente do cliente no Public, normalmente teste e produção. Os acordos de comunicação são criados em cada tenant e não são transportados.
Chave de acessoNúmero de 44 dígitos que identifica uma NF-e ou um CT-e. O Invent Apps grava essa chave no SAP para evitar lançamento em duplicidade.
Tipo de nota fiscalConfiguração fiscal brasileira do SAP que define como a nota fiscal de entrada é registrada (modelo, impostos, escrituração).

Como funciona​

Cada tipo de documento fiscal segue um caminho no SAP. Todos começam pelo mesmo passo: o Invent Apps lê o pedido de compra para vincular a nota a ele.

NF-e de material (modelo 55)​

  1. O fornecedor emite a NF-e e o Invent Apps captura o XML.
  2. O Invent Apps identifica o fornecedor pelo CNPJ (API de Parceiro de Negócio) e consulta o pedido de compra (API de Pedido de Compra).
  3. Registra a entrada de mercadoria com referência ao pedido, equivalente ao app Post Goods Movement (MIGO), pela API de Documento de Material.
  4. Registra a fatura do fornecedor com referência ao pedido, equivalente ao app Create Supplier Invoice (MIRO), já com os dados da nota fiscal brasileira (veja Tipos de nota fiscal).

CT-e de frete (modelo 57)​

O frete pode estar no SAP de duas formas, e o parceiro MM precisa informar qual delas o cliente usa:

  • Frete previsto no pedido do material (custo de entrega planejado): o CT-e é lançado como fatura com referência ao pedido do material, na parte de custos de frete.
  • Pedido de compra específico de frete (pedido de serviço): o Invent Apps lança a fatura com referência a esse pedido, com ou sem folha de registro de serviço (veja Folha de serviço).

NFS-e e serviços em geral​

  1. O Invent Apps consulta o pedido de compra de serviço.
  2. Somente se o cliente exigir folha de serviço para aquele item, registra a folha de registro de serviço (app Manage Service Entry Sheets - Lean Services).
  3. Registra a fatura do fornecedor com referência à folha de serviço ou, quando não houver folha, direto ao pedido, com o número e o código de verificação da NFS-e.

Nota sem pedido​

Quando a regra do cliente permitir, o Invent Apps cria o pedido de compra pela API de Pedido de Compra e segue o fluxo correspondente acima.

Folha de serviço, conforme a política do cliente​

A folha de registro de serviço faz, para serviços, o papel da entrada de mercadoria: confirma que o serviço foi prestado antes de a fatura ser lançada. No Public, a folha segue o modelo Lean Services e pode ser exigida ou dispensada item a item do pedido. O Invent Apps suporta os dois caminhos.

CaminhoQuando costuma ser usadoO que o cliente ganha ou abre mão
Com folha (pedido, folha e fatura)Serviços medidos, de valor variável, por etapa ou que exigem aceite do solicitante (obras, consultoria, manutenção)Ganha confirmação de quem recebeu o serviço, conferência em três vias, despesa no mês da prestação e trilha de auditoria. Se houver aprovação na folha, a fatura espera o aceite do gestor.
Direto (pedido e fatura)Serviços recorrentes de valor fixo (aluguel, licenças, limpeza, segurança) e freteFluxo mais simples e rápido. Abre mão da confirmação de recebimento, e a despesa só é registrada quando a fatura é lançada.

O SAP decide o caminho pelo indicador de entrada de mercadoria (recebimento) no item do pedido de compra. Com o indicador marcado, a fatura exige folha. Desmarcado, a fatura é lançada direto contra o pedido. A definição por tipo de serviço cabe à controladoria do cliente.

Materiais controlados em estoque ficam fora dessa escolha: para eles, a entrada de mercadoria é sempre obrigatória antes da fatura.

Sincronização de cadastros (Master Data)​

Além do recebimento de notas, o módulo Master Data do Invent Apps consulta o SAP periodicamente e inclui ou atualiza no Invent Apps os parceiros de negócio (fornecedores e clientes) e os itens (materiais e serviços).

TemaComo funciona
O que é lidoParceiros de negócio pela API API_BUSINESS_PARTNER (dados gerais, CNPJ ou CPF, inscrições, endereço, dados de fornecedor e cliente) e itens pela API CE_PRODUCT_0002 (descrição, tipo, unidade, NCM, origem e utilização por centro).
Somente leituraNesta fase, o Invent Apps não cria nem altera parceiros ou itens no SAP.
Carga inicialNa ativação, o Invent Apps lê todo o cadastro do escopo, em lotes. Informe a quantidade aproximada de parceiros e itens e a melhor janela de horário para essa carga.
Atualização contínuaDepois da carga, o Invent Apps consulta periodicamente só o que foi criado ou alterado, pela data de alteração do cadastro, e faz reconciliações completas de tempos em tempos.
Acesso necessárioOs acordos SAP_COM_0008 e SAP_COM_0009, já previstos em APIs e cenários, cobrem a leitura. Não há acordo novo a criar.
ServiçosNo Public, serviços são cadastrados como produto do tipo serviço, e a API de Produto cobre.

APIs e cenários de comunicação​

O Invent Apps usa as APIs abaixo. Todas são oficiais da SAP, com status ativo no catálogo do SAP Business Accelerator Hub. A coluna Cenário a criar indica qual acordo de comunicação libera cada uma.

#API (nome técnico)Para que o Invent Apps usaCenário a criarUsada em
1Pedido de compra, OData V4 CE_PURCHASEORDER_0001 (grupo API_PURCHASEORDER_2)Consultar pedidos para vincular à nota; criar e alterar pedidos quando necessárioSAP_COM_0053 Purchase Order IntegrationTodos
2Parceiro de negócio, OData V2 API_BUSINESS_PARTNERLocalizar o fornecedor pelo CNPJ e sincronizar o cadastro de parceiros no Master Data (somente leitura)SAP_COM_0008 Business Partner, Customer and Supplier IntegrationTodos
3Documento de material, OData V2 API_MATERIAL_DOCUMENT_SRVRegistrar a entrada de mercadoria com referência ao pedido e estornar, se necessárioSAP_COM_0108 Material Document IntegrationNF-e
4Fatura de fornecedor, OData V2 API_SUPPLIERINVOICE_PROCESS_SRVRegistrar a fatura com referência a pedido, entrada ou folha de serviço, com os dados da nota fiscal brasileira, e estornarSAP_COM_0057 Supplier Invoice IntegrationTodos
5Folha de serviço, OData V4 CE_SERVICEENTRYSHEET_0001 ou V2 API_SERVICE_ENTRY_SHEET_SRVRegistrar a folha de registro de serviço antes da fatura. Só é necessária se o cliente usar folhaSAP_COM_0146 Service Entry Sheet IntegrationServiços e frete com folha
6Nota fiscal Brasil, OData V2 API_LOGBR_NOTAFISCAL_SRVConsultar e completar a nota fiscal gerada (dados adicionais, referências)SAP_COM_0387 Logistics - Brazil Nota Fiscal IntegrationTodos
7Produto, OData V4 CE_PRODUCT_0002 (grupo API_PRODUCT)Conferir material, NCM e origem, e sincronizar o cadastro de itens no Master Data (somente leitura)SAP_COM_0009 Product IntegrationNF-e
Duas escolhas

Pedido de compra: o Invent Apps usa a API V4 CE_PURCHASEORDER_0001. A API V2 antiga API_PURCHASEORDER_PROCESS_SRV está descontinuada pela SAP. As duas vêm no mesmo cenário SAP_COM_0053, então não há nada extra a fazer, mas a V2 não deve ser usada em integrações novas.

Folha de serviço (API 5): crie o acordo SAP_COM_0146 só se o cliente usar folha de serviço em algum tipo de serviço (veja Folha de serviço).

Usuário e sistema de comunicação​

Tempo estimado: 1 a 2 horas, feito por um administrador do tenant com acesso aos apps de Communication Management. Execute primeiro no tenant de teste e repita no tenant de produção: os acordos não são transportados entre tenants.

Passo 1: criar o usuário de comunicação​

  1. Abra o app Fiori Maintain Communication Users (Manter usuários de comunicação).
  2. Clique em Novo. Informe o nome, por exemplo INVENT_APPS, e uma descrição como "Integração Invent Apps".
  3. Clique em Propor senha (Propose Password) ou defina uma senha forte. Copie a senha nesse momento, porque depois ela não é exibida de novo.
  4. Salve.
Como enviar a senha para a Invent

Nunca envie a senha por e-mail, chat ou junto com o checklist. Combine com o consultor Invent um canal seguro (cofre de senhas ou link de uso único). Na Invent, a credencial fica guardada em cofre de segredos e não aparece em telas nem em registros do sistema.

Passo 2: criar o sistema de comunicação​

  1. Abra o app Communication Systems (Sistemas de comunicação) e clique em Novo.
  2. Informe o ID e o nome do sistema, por exemplo INVENT_APPS.
  3. Em Nome do host (Host Name), informe o endereço que o consultor Invent fornecer. O Invent Apps só chama o SAP (comunicação de entrada), então esse campo é apenas cadastral.
  4. Preencha Sistema lógico (Logical System) e Sistema empresarial (Business System) com o mesmo ID, por exemplo INVENT_APPS. O cenário de parceiro de negócio (SAP_COM_0008) exige esses dois campos.
  5. Na seção Usuários para comunicação de entrada (Users for Inbound Communication), clique em +, escolha o método Nome de usuário e senha (User Name and Password) e selecione o usuário criado no passo 1.
  6. Salve. Não é preciso cadastrar usuário de comunicação de saída.

Acordos de comunicação​

Passo 3: criar um acordo para cada cenário​

Repita este passo para cada cenário da tabela de APIs e cenários: SAP_COM_0053, SAP_COM_0008, SAP_COM_0108, SAP_COM_0057, SAP_COM_0387, SAP_COM_0009 e, se houver folha de serviço, SAP_COM_0146.

  1. Abra o app Communication Arrangements (Acordos de comunicação) e clique em Novo.
  2. Em Cenário (Scenario), escolha o código, por exemplo SAP_COM_0053. O SAP sugere o nome do acordo; mantenha ou ajuste, por exemplo INVENT_APPS_0053.
  3. Em Sistema de comunicação (Communication System), escolha INVENT_APPS. O usuário de entrada é preenchido automaticamente.
  4. Confira a lista Serviços de entrada (Inbound Services). Ela mostra as APIs liberadas e o endereço de cada uma. O Invent Apps usa só as APIs de APIs e cenários.
  5. Salve. A liberação vale a partir desse momento.

Cuidado com o cenário de parceiro de negócio (SAP_COM_0008)​

O cenário SAP_COM_0008 foi feito para replicação de cadastro nos dois sentidos e por isso tem serviços de saída (envio do SAP para fora). O Invent Apps só lê fornecedores. Ao criar esse acordo:

  • Desative todos os serviços de saída (Outbound Services), marcando-os como inativos. Sem isso, o SAP pode tentar enviar cadastros para o Invent Apps ou pedir configurações de saída que não se aplicam.
  • Confirme que o sistema de comunicação tem Sistema lógico e Sistema empresarial preenchidos (passo 2). Sem esses campos, o acordo não salva.
  • Os serviços de entrada via IDoc ou SOAP podem ficar ativos. O Invent Apps não os usa.

Esse cuidado apareceu na validação do Invent Apps em tenant Public. Os demais cenários deste artigo são só de entrada e salvam sem ajuste.

O que o acordo libera​

No Public não existe criação manual de perfil de acesso (role) para integrações: o próprio cenário traz as autorizações das APIs dele. O acesso do Invent Apps fica limitado às APIs dos acordos criados. Se a política do cliente exigir restringir dados, por exemplo por empresa, veja no acordo se o cenário oferece restrições. Nem todos oferecem.

Autenticação​

Autenticação é como o Invent Apps prova ao SAP quem está chamando as APIs. O usuário de comunicação do Public aceita estas formas:

FormaComo funcionaUso pelo Invent Apps
Usuário e senha (Basic Authentication)A cada chamada, o Invent Apps envia o usuário de comunicação e a senha por um canal criptografado (HTTPS).Forma adotada. É a suportada pelo Invent Apps hoje e já validada em tenant Public.
Certificado digital (X.509)O Invent Apps apresenta um certificado digital, e o usuário de comunicação é cadastrado com esse certificado em vez de senha.Evolução prevista. Quando estiver disponível, a Invent comunica e fornece o certificado.
OAuth 2.0Autorização por token, configurada no usuário e no acordo de comunicação.Não suportado pelo Invent Apps no momento.

Se o cliente trocar a senha do usuário de comunicação, combine a data com o consultor Invent, para atualizar a credencial no Invent Apps no mesmo dia. Enquanto a senha nova não for atualizada, as chamadas voltam com erro de autenticação.

Endereço de acesso das APIs​

No Public, a SAP já publica as APIs na internet com certificado HTTPS reconhecido. Não há exposição de rede nem certificado a providenciar, mas o endereço tem um detalhe importante:

ItemO que fazerPor quê
Usar o endereço com -apiInforme à Invent o endereço de APIs do tenant, que tem o sufixo -api no host: https://myXXXXXX-api.s4hana.cloud.sap. Não é o endereço usado para abrir o Fiori (https://myXXXXXX.s4hana.cloud.sap).É o endereço que aceita autenticação por usuário e senha do usuário de comunicação. Validado na prática pelo Invent Apps.
Um endereço por tenantInforme o endereço do tenant de teste e, depois, o de produção.Cada tenant tem seus próprios acordos e seu próprio endereço.
MandanteNada a fazer.No Public, cada tenant tem um único mandante.

Campos customizados da chave de acesso​

Para não lançar a mesma nota duas vezes, o Invent Apps grava a chave de acesso nos documentos do SAP e a consulta antes de cada lançamento. As APIs padrão de entrada de mercadoria e de fatura não têm esse campo, então é preciso criar dois campos customizados.

  1. Abra o app Fiori Custom Fields (Campos customizados).
  2. Crie um campo de texto para a chave de acesso no contexto de negócio do item do documento de material (entrada de mercadoria).
  3. Crie outro campo de texto para a chave de acesso no contexto de negócio do cabeçalho da fatura de fornecedor.
  4. Use pelo menos 44 posições, porque a chave tem 44 dígitos.
  5. Nas abas de uso do campo, habilite o uso nas APIs API_MATERIAL_DOCUMENT_SRV e API_SUPPLIERINVOICE_PROCESS_SRV.
  6. Publique os campos e anote o nome técnico gerado pelo SAP, que começa com YY1_. Informe esses nomes à Invent.

Exemplo de nomes validados em outro cliente Public: YY1_ChavedeAcesso_MMI (entrada de mercadoria) e YY1_ChaveAcessoNF_MIH (fatura). Os nomes podem mudar de um cliente para outro, porque o Invent Apps permite configurar o nome por cliente.

Tipos de nota fiscal​

No Public, a API de fatura de fornecedor (API_SUPPLIERINVOICE_PROCESS_SRV) aceita os dados da nota fiscal brasileira junto com a fatura: tipo de nota fiscal, número e código de verificação da NFS-e, número do protocolo de autorização, data e hora de processamento, número aleatório da chave e tipo de emissão. A fatura e a nota fiscal nascem juntas, como quando o usuário preenche a aba de nota fiscal na tela de fatura.

O parceiro fiscal define e informa à Invent:

DocumentoO que informarExemplo
NF-e de material (modelo 55)Tipo de nota fiscal usado na entrada de mercadoria com pedidoTipo configurado para NF-e de entrada
CT-e (modelo 57)Tipo de nota fiscal usado para freteTipo configurado para CT-e de entrada
NFS-eTipo de nota fiscal usado para serviçosTipo configurado para NFS-e de entrada
Casos especiaisDevolução, importação, remessa para industrialização ou outras operações que o cliente useUm tipo por operação
Decida cedo

Os tipos de nota fiscal definem impostos e escrituração da entrada. Eles precisam estar configurados e testados no tenant de teste antes dos primeiros lançamentos pelo Invent Apps.

Checklist do parceiro SAP​

ItemResponsável
Usuário de comunicação INVENT_APPS criado e senha guardada (passo 1)Administrador
Sistema de comunicação criado, com sistema lógico, sistema empresarial e usuário de entrada (passo 2)Administrador
Acordos criados: SAP_COM_0053, SAP_COM_0008, SAP_COM_0108, SAP_COM_0057, SAP_COM_0387, SAP_COM_0009 (passo 3)Administrador
No acordo SAP_COM_0008, serviços de saída desativados (cuidado com o SAP_COM_0008)Administrador
Se houver folha de serviço: acordo SAP_COM_0146 criadoAdministrador
Endereço com -api do tenant informado (endereço de acesso)Administrador
Campos customizados da chave de acesso criados, liberados nas APIs e publicados (campos customizados)Key user MM
Escopo do Master Data definido: grupos de parceiros, empresas e centros, com volume e janela da carga inicial (Master Data)MM e Basis
Informado se o cliente usa SAP MDG para governança de cadastrosMM ou Dados Mestres
Política de folha de serviço definida por tipo de serviço: com folha ou direto (folha de serviço)Controladoria e MM
Forma de frete confirmada: no pedido do material ou pedido de frete (CT-e de frete)MM
Tipos de nota fiscal definidos para NF-e, CT-e e NFS-e (tipos de nota fiscal)Fiscal
Mesmos passos repetidos no tenant de produção, na data combinadaAdministrador

Informações para devolver à Invent​

InformaçãoExemploObservação
Endereço de APIs do tenanthttps://myXXXXXX-api.s4hana.cloud.sapCom o sufixo -api; um por tenant
Usuário de comunicaçãoINVENT_APPSA senha vai por canal seguro, nunca junto
Acordos criadosSAP_COM_0053, SAP_COM_0008 e os demaisLista dos cenários ativos
Nomes dos campos da chave de acessoYY1_... (entrada) e YY1_... (fatura)Veja campos customizados
Política de folha de serviçoCom folha para obras e consultoria; direto para aluguel e licençasPor tipo de serviço
Forma de freteNo pedido do material ou pedido de freteDefine o fluxo do CT-e
Tipos de nota fiscalUm por documento e operaçãoVeja tipos de nota fiscal
Escopo do Master DataGrupos de parceiros, empresas e centrosVeja Master Data
Volume e janela da carga inicial12 mil parceiros, 30 mil itens; sábado à noiteValores aproximados bastam
Uso de SAP MDGSim ou nãoInfluencia a futura criação de parceiros pelo Invent Apps
ContatosAdministrador do tenant, MM e FiscalNome e e-mail de cada responsável

Diagnóstico​

O teste de conexão é feito no painel de acordos do Invent Apps, serviço por serviço. O teste é somente leitura e não grava nada no SAP. Só avance para os testes com documentos reais depois que todos os serviços estiverem disponíveis.

ResultadoO que significa
DisponívelPronto.
Falha de autenticação (401)Usuário ou senha incorretos, ou endereço sem -api.
Acesso negado (403)Falta o acordo do cenário daquela API.
InalcançávelEndereço digitado errado.

O cuidado com o SAP_COM_0008 e o endereço com -api são as duas causas mais comuns de atraso.

Dúvidas frequentes​

Preciso ativar serviço em /IWFND/MAINT_SERVICE ou criar role na PFCG?

Não. No Public, essas transações não estão disponíveis ao cliente. O acordo de comunicação ativa as APIs e concede as autorizações do cenário automaticamente.

Posso usar um único usuário de comunicação para todos os acordos?

Sim, e é o recomendado. Todos os acordos apontam para o mesmo sistema de comunicação, que usa o mesmo usuário. Se a política do cliente exigir, dá para separar usuários por cenário: o Invent Apps aceita credenciais diferentes por serviço.

Os acordos criados no tenant de teste vão para produção?

Não. Acordos de comunicação são criados em cada tenant. Repita os passos 1 a 3 em produção, com uma senha própria.

A folha de serviço é obrigatória?

Não. É uma escolha de controle interno do cliente, feita item a item no pedido de compra. A folha traz confirmação do serviço prestado, conferência em três vias e despesa no mês certo. O lançamento direto (pedido e fatura) é mais simples e comum para serviços recorrentes de valor fixo e para frete. O Invent Apps suporta os dois caminhos.

As atualizações semestrais da SAP podem quebrar a integração?

As APIs usadas seguem a política formal de estabilidade e descontinuação da SAP: uma API descontinuada continua funcionando por um período e ganha uma sucessora antes de ser removida. A Invent acompanha essas mudanças.

O Invent Apps cria ou altera parceiros de negócio ou itens no SAP?

Não nesta fase. Para parceiros e itens, o Invent Apps só lê. A criação e a alteração de parceiros estão em estudo, e a Invent comunica antes de liberar. O acordo SAP_COM_0008 já contempla gravação, mas o Invent Apps não a usa hoje. Se o cliente usar SAP MDG, a gravação vai ter que respeitar o fluxo de aprovação do MDG.

O Invent Apps altera configuração do SAP?

Não. Ele só lê e grava documentos de negócio (pedido, entrada, folha de serviço, fatura e nota fiscal) dentro do que os acordos permitem.

Referências oficiais​

  • SAP Business Accelerator Hub, SAP S/4HANA Cloud Public Edition: páginas das APIs API_BUSINESS_PARTNER, CE_PURCHASEORDER_0001, API_MATERIAL_DOCUMENT_SRV, API_SUPPLIERINVOICE_PROCESS_SRV, CE_SERVICEENTRYSHEET_0001, API_LOGBR_NOTAFISCAL_SRV e CE_PRODUCT_0002 (abas Overview e Configuration Details, com o cenário de comunicação de cada uma).
  • SAP Help Portal, SAP S/4HANA Cloud Public Edition: Communication Management (usuários, sistemas e acordos de comunicação).
  • SAP API Deprecation Policy: api.sap.com, seção Resources.

Em caso de dúvida, fale com o consultor Invent Software responsável pelo projeto.