top of page
Buscar

Passo a Passo Detalhado: Configurar TOTVS iPaaS e Protheus para Integração de Pedido de Venda


Este guia detalhado destina-se a usuários com conhecimento avançado em desenvolvimento e Protheus, focando na configuração da integração de Pedidos de Venda entre o Protheus e outros sistemas via TOTVS iPaaS. Ele complementa o guia geral fornecido anteriormente, aprofundando nos aspectos práticos do Protheus.

Cenário Típico: Um sistema externo (E-commerce, CRM, App Mobile) precisa enviar dados de um novo pedido de venda para ser cadastrado no Protheus.

Parte 1: Preparação e Configuração do Ambiente Protheus para Expor APIs REST

O TOTVS iPaaS geralmente se comunicará com o Protheus através de APIs REST. Se o seu Protheus já possui as APIs necessárias para Pedido de Venda expostas e prontas, você pode pular para a Parte 2. Caso contrário, siga estes passos para configurar o serviço REST no Protheus.

1.1. Verificar Versão e Componentes do Protheus:

  • Certifique-se de que sua versão do Protheus e o AppServer Lobo Guará (ou superior) suportam adequadamente os serviços REST. Consulte a documentação da TOTVS para os requisitos mínimos de build e LIB.

  • Verifique se os componentes necessários para REST (HTTP/HTTPS) estão ativos e configurados no seu ambiente.

1.2. Configurar um Ambiente AppServer Dedicado para REST (Recomendado):

  • Para evitar conflitos e otimizar performance, é altamente recomendado criar uma instância do AppServer Protheus dedicada para os serviços REST. Copie a pasta appserver do seu ambiente Protheus para um novo local (ex: appserver_rest).

  • Não misture serviços REST e SOAP na mesma instância/porta do AppServer.

1.3. Ajustar o appserver.ini da Instância REST: Abra o arquivo appserver.ini da sua nova instância appserver_rest e configure as seções relevantes para HTTP e REST. Abaixo um exemplo básico (consulte a documentação do TDN "Configuração do REST Protheus para uso com os aplicativos Mobile" - pageId=519719292 - para detalhes e mais opções):

ini

[General]
MAXSTRINGSIZE=10 ; (ou valor adequado ao seu ambiente)

[HTTPV11]
Enable=1
Sockets=HTTPREST

[HTTPREST]
Port=8088       ; Escolha uma porta livre para o serviço REST. Ex: 8080, 8088, etc.
IPsBind=        ; Deixe em branco para escutar em todos os IPs ou especifique um IP.
URIs=HTTPURI
Security=1      ; 1 = Habilita autenticação. Essencial para produção.
                ; 0 = Desabilita (NÃO RECOMENDADO para produção, apenas para testes iniciais).
Instances=2,5,1,1 ; Ajuste conforme a necessidade de threads (MinDefault,MaxDefault,MinLimit,MaxLimit)
CORSEnable=1    ; Habilita CORS para permitir requisições de diferentes origens (ex: do iPaaS).
AllowOrigin=*   ; Permite qualquer origem. Em produção, restrinja para os IPs/domínios do iPaaS se possível.
Timeout=120     ; Timeout da requisição em segundos.

[HTTPURI]
URL=/rest       ; Define o path base para suas APIs REST (ex: http://seuprotheus:8088/rest) .
PrepareIn=ALL   ; Ou especifique as empresas/filiais que o serviço atenderá (ex: T1, D MG 01).
                ; Consome uma licença TOTVS i por thread/empresa-filial.
Instances=2,2   ; (Opcional, pode herdar de [HTTPREST])

[HTTPJOB]
MAIN=HTTP_START
ENVIRONMENT=seu_environment ; Nome do seu ambiente Protheus.

[ONSTART]
jobs=HTTPJOB
RefreshRate=30

Observações Importantes no appserver.ini:

  • Port: Certifique-se de que a porta escolhida não está em uso e está liberada no firewall.

  • Security=1: É crucial para ambientes produtivos. O iPaaS precisará se autenticar no Protheus.

  • PrepareIn: Se não for ALL, defina corretamente as empresas/filiais que o serviço REST atenderá.

  • CORSEnable=1 e AllowOrigin: Necessários para que o iPaaS (que roda em um domínio diferente) possa fazer requisições ao seu Protheus.

1.4. Desenvolver ou Utilizar APIs REST para Pedido de Venda no Protheus: O Protheus pode expor funcionalidades de Pedido de Venda (MATA410) via APIs REST de algumas formas:

  • APIs Padrão da TOTVS: Verifique se sua versão do Protheus já oferece APIs REST padrão para inclusão/consulta de Pedidos de Venda. Consulte o Catálogo de APIs da TOTVS (api.totvs.com.br) ou a documentação específica do seu módulo de Faturamento.

  • Desenvolvimento de APIs Customizadas em ADVPL: Se não houver APIs padrão ou se precisar de uma lógica específica, você precisará desenvolver suas próprias User Functions (UFs) em ADVPL e expô-las como serviços REST. Utilize as classes FWRest e FWHttpServer.

 **Exemplo Conceitual de uma UF para criar Pedido de Venda (simplificado):**

 ```advpl
 // Exemplo de User Function para ser exposta como REST
 // U_CRIAORCVENDA(cJsonPedido)
 User Function U_CRIAORCVENDA()
   Local cJsonPedido := FWRestRequest():GetContent() // Pega o JSON do corpo da requisição
   Local oJson       := JsonObject():New()
   Local oRetJson    := JsonObject():New()
   Local aCabec      := {}
   Local aItens      := {}
   Local lOk         := .T.
   Local cNumPed     := ""
   Local cMsgErro    := ""

   oJson:FromJson(cJsonPedido)

   // TODO: Validar o JSON recebido (oJson)
   // TODO: Transformar o JSON nos arrays aCabec e aItens para a MATA410
   // Ex: aCabec := { {"C5_CLIENTE", oJson["cliente_id"], Nil}, ... }
   //     aItens := { { {"C6_PRODUTO", oJson["itens"][1]["produto_id"], Nil}, ... }, ... }

   If lOk
     Begin Transaction
       MsExecAuto({|x,y| MATA410(x,y)}, aCabec, aItens, 3) // 3 = Inclusão
       If !Alltrim(RetCodUsr(1)) == ""
         cNumPed := Alltrim(RetCodUsr(1)) // Supondo que RetCodUsr(1) retorna o número do pedido
         lOk := .T.
         Commit
       Else
         lOk := .F.
         cMsgErro := "Erro ao incluir pedido: " + RetCodUsr(2) // Supondo que RetCodUsr(2) retorna a msg de erro
         Rollback
       Endif
     End Transaction
   Endif

   If lOk
     oRetJson["sucesso"] := .T.
     oRetJson["numero_pedido_protheus"] := cNumPed
     FWRestResponse():SetStatus(201) // Created
   Else
     oRetJson["sucesso"] := .F.
     oRetJson["mensagem_erro"] := cMsgErro
     FWRestResponse():SetStatus(400) // Bad Request ou 500 Internal Server Error
   Endif

   FWRestResponse():SetContentType("application/json")
   FWRestResponse():SetResult(oRetJson:ToJson())
 Return
 ```

  • Configurar o Serviço REST no Protheus (restcfg.json ou via Configurador): Após criar a UF, você precisa mapeá-la para um endpoint REST. Isso pode ser feito editando o arquivo restcfg.json na pasta protheus_data/config ou através do módulo Configurador (SIGACFG), dependendo da sua versão do Protheus.

  **Exemplo de entrada no `restcfg.json`:**

  ```json
  {
    "name": "PedidoDeVendaAPI",
    "version": "1.0.0",
    "description": "API para Pedidos de Venda",
    "methods": [
      {
        "method": "POST",
        "path": "/pedidos",
        "function": "U_CRIAORCVENDA",
        "description": "Cria um novo pedido de venda.",
        "input": "JSON com dados do pedido",
        "output": "JSON com resultado da operação"
      }
      // Outros métodos como GET para consultar pedidos, etc.
    ]
  }
  ```

1.5. Iniciar e Testar o Serviço REST do Protheus:

  • Inicie a instância do AppServer dedicada ao REST.

  • Verifique o console do AppServer por mensagens de erro na inicialização do serviço HTTP.

  • Utilize uma ferramenta como Postman, Insomnia ou curl para testar suas APIs REST do Protheus localmente antes de tentar integrar com o iPaaS. Verifique a autenticação, o envio de dados e as respostas.

Parte 2: Configuração no TOTVS iPaaS

Com as APIs REST do Protheus para Pedido de Venda prontas e testadas, vamos configurar o fluxo no iPaaS.

2.1. Acessar o TOTVS iPaaS e Criar Projeto/Diagrama:

  • Siga os passos 1, 2 e 3 do guia geral anterior para acessar o iPaaS, criar um projeto (ex: "Integracao_Protheus_Pedidos") e um novo diagrama (ex: "Receber_Pedido_Ecommerce_Para_Protheus").

2.2. Configurar o Trigger (Componente de Início):

  • Webhook: Este é o mais comum para receber pedidos de sistemas externos.

    1. Arraste o componente Webhook para o início do seu diagrama no Builder.

    2. Configure o Webhook. O iPaaS fornecerá uma URL única. Esta URL será chamada pelo sistema externo (E-commerce, CRM) sempre que um novo pedido de venda precisar ser enviado ao Protheus.

    3. Defina o método HTTP esperado (geralmente POST).

    4. Configure a autenticação para o Webhook no iPaaS (ex: API Key, Basic Auth), se necessário, para proteger seu endpoint no iPaaS.

2.3. Configurar o Conector para Chamar a API REST do Protheus:

  • Conector HTTP Request (Genérico): Este é o conector mais flexível para chamar qualquer API REST.

    1. Arraste o componente HTTP Request para o seu diagrama, após o Webhook.

    2. Configuração da Conexão/Serviço:

      • URL: Informe a URL completa da sua API REST de Pedido de Venda no Protheus (ex: http://ip_do_seu_protheus:8088/rest/pedidos) .

        • Importante: O servidor Protheus precisa estar acessível pela internet ou pela rede onde o agente do iPaaS (se houver um agente on-premise) está rodando.

      • Método: POST (para criar o pedido).

      • Headers:

        • Content-Type: application/json

        • Authorization: Configure o header de autorização conforme a Security=1 do seu Protheus (geralmente Basic Auth: Basic base64(usuario:senha)). Armazene credenciais de forma segura usando as variáveis de ambiente/conexão do iPaaS.

      • Body (Corpo da Requisição): Aqui você passará o JSON com os dados do pedido de venda. Este JSON virá do payload do Webhook (passo 2.2).

2.4. Mapeamento e Transformação de Dados:

  • O sistema externo enviará os dados do pedido para o Webhook do iPaaS (provavelmente em formato JSON).

  • Você precisará transformar este JSON de entrada no formato esperado pela sua API REST do Protheus (U_CRIAORCVENDA).

    1. Utilize os componentes de Transformação de Dados ou Funções do iPaaS Builder.

    2. Acesse o payload do Webhook (ex: trigger.body ou similar, dependendo da sintaxe do iPaaS).

    3. Mapeie os campos do JSON de entrada para os campos do JSON que sua API Protheus espera.

      • Ex: Se o e-commerce envia {"customer_id": "123", "products": [{"sku": "P001", "quantity": 2}]}

      • E sua API Protheus espera {"cliente_id_protheus": "000123", "filial_cliente": "01", "itens_pedido": [{"codigo_produto": "PRD001", "quantidade_vendida": 2.00}]}

      • Você precisará fazer esse de-para, incluindo lógicas como buscar o código do cliente Protheus a partir do customer_id do e-commerce (pode envolver uma chamada REST adicional ao Protheus para consulta de clientes, se necessário, ou uma tabela de-para no iPaaS/banco auxiliar).

    4. O resultado dessa transformação será usado como o Body do componente HTTP Request (passo 2.3).

2.5. Tratamento da Resposta do Protheus:

  • Após a chamada à API REST do Protheus, o componente HTTP Request receberá uma resposta (status HTTP e corpo JSON, conforme definido na sua UF U_CRIAORCVENDA).

    1. Utilize um componente de Condição para verificar o status da resposta (ex: response.statusCode == 201 para sucesso).

    2. Fluxo de Sucesso:

      • Extraia informações da resposta do Protheus (ex: response.body.numero_pedido_protheus).

      • Logue o sucesso.

      • Opcionalmente, envie uma confirmação de volta para o sistema de origem (se o Webhook for síncrono ou se houver outro mecanismo de callback).

    3. Fluxo de Erro:

      • Extraia a mensagem de erro (ex: response.body.mensagem_erro).

      • Logue o erro detalhadamente.

      • Envie uma notificação para administradores.

      • Implemente uma política de retry, se aplicável e seguro (cuidado com duplicidade de pedidos).

2.6. Salvar, Validar e Publicar o Diagrama no iPaaS:

  • Siga as instruções do guia geral para salvar, validar e publicar seu diagrama de integração de pedido de venda.

Parte 3: Testes e Monitoramento

3.1. Testar o Fluxo de Ponta a Ponta:

  • Utilize uma ferramenta como Postman para simular o sistema externo, enviando um JSON de pedido de venda para a URL do Webhook do seu diagrama no iPaaS.

  • Verifique no Monitoramento do iPaaS se a integração foi executada.

  • Analise os logs de cada etapa no iPaaS.

  • Confirme se o pedido de venda foi criado corretamente no Protheus (consulte a MATA410 ou relatórios).

  • Teste cenários de erro (dados inválidos, Protheus indisponível) para verificar o tratamento de falhas.

3.2. Monitoramento Contínuo:

  • Após a implantação, utilize as ferramentas de monitoramento do iPaaS para acompanhar a saúde e o desempenho da integração.

  • Configure alertas para falhas críticas.

Considerações Adicionais para Pedido de Venda:

  • Consistência de Dados: Garanta que dados como código de cliente, código de produto, condição de pagamento, etc., estejam consistentes entre o sistema de origem e o Protheus. Pode ser necessário manter tabelas De-Para (mapping tables) no iPaaS ou em um banco de dados auxiliar.

  • Performance: Para alto volume de pedidos, otimize as chamadas ao Protheus e o processamento no iPaaS.

  • Transacionalidade: A inclusão de um pedido de venda no Protheus é uma operação crítica. Sua API REST no Protheus (U_CRIAORCVENDA) deve ser transacional (usar Begin Transaction/Commit/Rollback). O iPaaS em si pode não garantir transações distribuídas entre o iPaaS e o Protheus; a atomicidade deve ser tratada na API do Protheus.

  • Segurança: Utilize HTTPS para todas as comunicações. Proteja as credenciais de acesso ao Protheus e ao iPaaS.

Este passo a passo fornece uma estrutura detalhada. A implementação exata dependerá das especificidades do seu ambiente Protheus, do sistema externo e das funcionalidades da sua versão do TOTVS iPaaS. Consulte sempre a documentação oficial da TOTVS para obter as informações mais atualizadas.

 
 
 

Posts recentes

Ver tudo
Exemplo de busca campo MEMO Oracle

SELECT     B1_COD,     B1_DESC,     REPLACE(REPLACE(utl_raw.cast_to_varchar2(DBMS_LOB.SUBSTR(SB1.B1_X_OBS ,1024,1)),chr(13),''),chr(10),'...

 
 
 

Comments

Precisa de mais informações?

Estamos aqui para ajudá-lo. Entre em contato por telefone, email ou redes sociais.

  • Black Facebook Icon
  • Black Twitter Icon
  • Black LinkedIn Icon
end_rodape_edited_edited_edited.jpg

© 2017 por EPV Consulting

bottom of page