# 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

| Jeito | Para que ERP | O que a TI faz | Ponto de partida |
|---|---|---|---|
| **A busca pela API** | ERP dentro da rede da empresa, sem endereço público | Agenda a busca dos pedidos prontos, lança no ERP e confirma (ou recusa com o motivo) | `buscar-pedidos.mjs` e `buscar_pedidos.py` |
| **O aviso no endereço** | ERP, ou a ferramenta de integração dele, com um endereço HTTPS público | Recebe o `POST` assinado de cada pedido, lança e responde com o número do ERP | `receptor.mjs`, `receptor.py`, `receptor.php`, `Program.cs` e o simulador `simular-aviso.mjs` |
| **O arquivo por SFTP** | ERP que importa pedido de uma pasta | Dá o acesso ao servidor SFTP e liga a importação do ERP; a Softeum monta o arquivo no layout do ERP | Os modelos prontos: XML, CSV, TXT de largura fixa, SAP (`odv-mapping` e IDoc ORDERS05) e Protheus (CSV) |

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 quê | Quem cria | Onde fica |
|---|---|---|
| A chave da API (`sp_live_...`) | O Administrador do cliente, no painel (aparece uma vez só) | No cofre de senhas do ERP |
| O endereço do aviso e o segredo (`whsec_...`) | A TI dá o endereço; o Administrador cadastra no painel e copia o segredo | O segredo, no cofre do ERP |
| O servidor SFTP (endereço, porta, usuário, senha ou chave, pasta) | A TI | Digitado pelo Administrador no painel; guardado cifrado, não aparece de novo |
| O SAP: o sistema lógico, a porta e o perfil de parceiro | A equipe SAP do cliente | No SAP |
| Os códigos do ERP de compradores, produtos e vendedores | A TI ou o cadastro do cliente | No Softeum: pela planilha, na tela ou pela API (seção 13.4) |

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ê

| Quem | O que faz |
|---|---|
| **A Softeum** | Cadastra o cliente, monta e publica o layout do arquivo (SFTP), acompanha as entregas em **Integração → Entregas** e ajuda com a leitura dos pedidos. |
| **A TI do cliente** | Prepara o ERP (o lançamento, o serviço, o servidor SFTP), roda os testes sem o Softeum e confere os pedidos no ERP de homologação. |
| **O faturamento do cliente** (quem revisa) | Manda pedidos por e-mail para o teste, aprova na **Revisão** e confere no ERP o cliente, os itens, as quantidades, os preços, a condição e a entrega. |

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:

| O quê | Onde |
|---|---|
| O guia completo de integração e o contrato da API (`openapi.json`) | A página do guia e o botão **Arquivo OpenAPI** |
| Este kit, os receptores do aviso, o simulador e os clientes de busca | **Arquivos de exemplo** |
| Os modelos prontos do arquivo: XML, CSV, TXT de largura fixa, SAP (`odv-mapping` e IDoc ORDERS05) e Protheus (CSV) | **Integração → Como o ERP recebe → Arquivo na pasta do ERP** |