Kit para a TI do cliente: ligar o ERP ao Softeum Pedidos

O Softeum Pedidos lê os pedidos de compra que chegam por e-mail, confere com o catálogo, as tabelas de preço e os cadastros, e entrega cada pedido aprovado ao ERP. Este kit diz à TI o que é preciso para ligar o ERP: o jeito de receber, a especificação, o teste, os acessos e quem testa o quê. O guia completo é o docs/api.md, no painel em Integração → Para a TI, com os arquivos de exemplo para baixar.

Suporte da Softeum: diiego.martins@softeum.com.br (dúvidas, o layout do arquivo, o teste). Senha, chave e segredo nunca vão por e-mail (seção 5 deste kit).

1. Escolha o jeito de receber

Na dúvida: com alguém para programar e o ERP na rede da empresa, a busca; sem ninguém para programar, o arquivo.

2. O caminho de cada ERP

SAP ECC e S/4HANA

• Pelo arquivo, com o IDoc. O modelo pronto SAP: IDoc de pedido (ORDERS05) grava um IDoc em XML por pedido na pasta que o SAP lê. A equipe SAP do cliente prepara:

  • o sistema lógico do Softeum (SOFTEUM, na BD54), a porta de arquivo (WE21) e o perfil de parceiro (WE20) com a mensagem ORDERS, o tipo ORDERS05 e o código de processo ORDE;
  • a leitura da pasta, pelo job da porta de arquivo ou pelo PI/PO, como a equipe já faz com outros IDocs;
  • no modelo, com a Softeum: as portas e os parceiros do EDI_DC40, o tipo de ordem, a organização de vendas, o canal e o setor de atividade;
  • no Softeum: os compradores com o número do cliente no SAP, com os 10 dígitos (0000100001), e os produtos com o número do material.

  O IDoc que o SAP não processa (status 51) aparece na WE02 do SAP, e não no Softeum: alguém da equipe SAP precisa acompanhar.

• Pelo arquivo, com o odv-mapping: o outro modelo pronto, para o SAP que usa essa interface (o cliente pelo CNPJ e o produto pelo EAN).

• Pela API, com o Integration Suite ou o PI/PO (S/4HANA). O fluxo de integração recebe o aviso (e confere a assinatura) ou busca na API, e cria a ordem pela API OData API_SALES_ORDER_SRV (POST /A_SalesOrder, com os itens em to_Item):

  • fixos: SalesOrderType, SalesOrganization, DistributionChannel e OrganizationDivision;
  • do pedido: SoldToParty = comprador.codigo_erp, PurchaseOrderByCustomer = numero_comprador, CustomerPurchaseOrderDate = data_pedido e RequestedDeliveryDate = data_entrega;
  • de cada item: Material = produto.codigo_erp, RequestedQuantity = quantidade_erp, RequestedQuantityUnit = unidade_erp e UnderlyingPurchaseOrderItem = linha;
  • confirme no Softeum com o número da ordem (SalesOrder) que a API devolve.

  Os nomes mudam com a versão e as extensões do SAP: confirme com a equipe SAP antes de começar.

TOTVS Protheus

• Pela API: a TI agenda a busca dos pedidos prontos (seção 13 do guia) e lança cada um pela rotina padrão do pedido de venda (MATA410, por MsExecAuto), confirmando no Softeum com o número do pedido de venda.
• Pelo arquivo: o modelo pronto TOTVS Protheus: pedido de venda (CSV), com os campos da SC5 e da SC6, e a rotina de importação da TI, também pelo MsExecAuto do MATA410.
• Nos dois: os compradores com o código e a loja do Protheus juntos (000123-01) e os produtos com o B1_COD.

Os outros ERPs

A seção 14 do guia diz a porta de entrada de pedido de cada ERP (Winthor, Datasul, RM, Business One, Sankhya, Senior, Omie, Bling, Tiny, Business Central, NetSuite, Odoo) e o que o lançamento precisa ter em mãos.

3. A especificação

• O pedido: seção 4 do guia (cada campo e onde ele entra no pedido de venda) e o contrato da API em openapi.json, no painel.
• O aviso: seções 3 (a requisição), 5 (a assinatura, com o vetor de teste) e 6 (a resposta).
• A API: seção 13 (buscar, confirmar, recusar, o documento do comprador e o envio dos cadastros).
• O arquivo: seção 15 (o modelo, a codificação e os layouts comuns).

Em qualquer jeito:

• o mesmo pedido nunca entra duas vezes: guarde o pedido.id no ERP, com restrição de unicidade (seção 6);
• quantidade e preço na mesma unidade: quantidade_erp com o preço por unidade do ERP (seção 4.4);
• o desconto já vem no preço: o preco_unitario é o líquido. Na indústria que lê o desconto de cada item (a Softeum liga), o item traz também desconto, com o percentual e o tipo (comercial, especial ou promocional) escritos no pedido: o ERP que lança o desconto item a item usa o preço de tabela com ele; o que lança o preco_unitario não lança o desconto. Nunca os dois (seção 4.7);
• confirme com o número do ERP; o que o ERP não aceitar, recuse com o motivo, e o pedido volta para o time;
• numero_comprador e linha vão para a nota fiscal (xPed e nItemPed, seção 4.9).

4. O teste

O Softeum não tem um ambiente separado: o teste é com a empresa do cliente no Softeum e o ERP de homologação.

1. Sem o Softeum: o simulador do aviso (simular-aviso.mjs, seção 7 do guia), o pedido de exemplo dos receptores e dos clientes de busca.
2. No painel: o Enviar teste do aviso, o Testar conexão do SFTP e a prévia do arquivo com os últimos pedidos (a Softeum monta o layout). Na busca pela API, o Criar pedido de teste (Integração → Como o ERP recebe → O ERP busca os pedidos, só o Administrador): um pedido pronto, montado com os compradores e os produtos do cadastro, que a busca traz com "teste": true. Todo ERP que busca os pedidos da empresa o recebe, com qualquer chave: crie só com o ERP de homologação ligado. Ele não entra na cobrança, nunca vai pelo aviso nem pelo arquivo e é apagado em até 7 dias (seção 8 do guia).
3. Com o ERP de homologação: aponte a busca, o endereço do aviso ou a pasta do SFTP para a homologação. Na busca, primeiro o pedido de teste: com o cliente de busca rodando com SOFTEUM_HOMOLOGACAO=1, lance e confirme um, e recuse outro com o motivo. Depois, nos três jeitos, mande um pedido por e-mail, de um vendedor cadastrado, aprove na Revisão e confira no ERP. A ordem importa: depois que o ERP recebe o primeiro pedido de verdade (mesmo o da homologação), o painel não cria mais o pedido de teste; para testar de novo, fale com o suporte da Softeum.
4. Para a produção: antes de apontar a busca para o ERP de produção, confirme ou recuse na homologação os pedidos de teste que ainda estão prontos, e confira que o cliente de busca da produção roda sem SOFTEUM_HOMOLOGACAO: ele recusa o pedido com "teste": true. Troque para o ERP de produção. A chave da API é uma por ambiente; o endereço do aviso é um só por empresa (troque o de homologação pelo de produção, e o segredo continua o mesmo).

5. Os acessos

Senha, chave e segredo nunca passam por e-mail nem por conversa com a Softeum: quem digita é o próprio cliente, no painel dele, ou a TI, no ERP.

O servidor SFTP que só aceita endereços liberados: a entrega ainda não sai por um endereço fixo (seção 15 do guia). Fale com o suporte da Softeum (diiego.martins@softeum.com.br) antes de montar o servidor.

6. Quem testa o quê

O roteiro do teste:

• Na busca pela API, antes do primeiro pedido de verdade: o pedido de teste do painel (Criar pedido de teste) entra no ERP de homologação e aparece confirmado no painel, com o número do ERP; outro, recusado com o motivo, aparece com erro e o motivo.
• No ERP de produção, o pedido com "teste": true é recusado com o motivo, e não lançado.
• Um pedido mandado por e-mail entra no ERP com o cliente, os itens, as quantidades, os preços, a condição, a entrega e o número do pedido do comprador, e aparece confirmado no painel, com o número do ERP.
• O mesmo pedido de novo (o reenvio, ou o aviso repetido) não duplica: o ERP devolve o mesmo número.
• Um pedido que o ERP não aceita (um produto que ele não tem) volta para o time com o motivo e entra depois de corrigido e reenviado.
• Com o ERP parado, nada se perde: os pedidos esperam e entram quando ele volta.
• O pedido grande (muitos itens) e o item vendido por peso (a quantidade com casas) entram certos.
• Alguém recebe o alerta quando a entrega para: o IDoc com erro no SAP, o 5xx no aviso, a busca parada.

Antes de ligar em produção, a lista da seção 11 do guia.

7. Os arquivos

Tudo na página do guia (Integração → Para a TI), menos os modelos do arquivo, que ficam na entrega por SFTP: