Passo a Passo Detalhado: Configurar TOTVS iPaaS e Protheus para Integração de Pedido de Venda
- Eloy Vanço
- 8 de mai.
- 8 min de leitura
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.
Exemplo de URL: http://localhost:8088/rest/pedidos (usando o exemplo acima) .
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.
Arraste o componente Webhook para o início do seu diagrama no Builder.
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.
Defina o método HTTP esperado (geralmente POST).
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.
Arraste o componente HTTP Request para o seu diagrama, após o Webhook.
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).
Utilize os componentes de Transformação de Dados ou Funções do iPaaS Builder.
Acesse o payload do Webhook (ex: trigger.body ou similar, dependendo da sintaxe do iPaaS).
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).
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).
Utilize um componente de Condição para verificar o status da resposta (ex: response.statusCode == 201 para sucesso).
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).
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.
Comments