Como chamar a API REST do Protheus pelo Fluig

Integrar Fluig e Protheus por API REST envolve quatro partes: deixar o REST do Protheus acessível, cadastrar o serviço no Fluig, consultar dados por dataset e gravar por uma atividade de serviço. Este guia mostra cada uma, com os cuidados que evitam dor de cabeça em produção.

Se você procura a visão de negócio, leia antes como a integração entre BPM e ERP acaba com o retrabalho. Aqui o assunto é técnico.

1. Confira o REST do lado do Protheus

O REST é configurado no appserver.ini. A porta e os caminhos variam por ambiente, então use os valores do seu servidor, e não os de um exemplo.

Dois pontos costumam gerar erro:

PrepareIn no bloco [HTTPURI]. É ele que define em quais empresas e filiais o ambiente é aberto. Com PrepareIn=ALL, todos os grupos podem receber requisições.

O cabeçalho TenantId. A TOTVS orienta a informar empresa e filial nesse cabeçalho, no formato empresa,filial. Sem ele, a requisição roda na primeira filial válida.

Essa segunda regra merece atenção. A chamada não dá erro: ela funciona, mas na filial errada. O problema pode passar despercebido nos testes e aparecer só em produção.

2. Cadastre o serviço no Fluig

Com usuário administrador, acesse Painel de Controle → Desenvolvimento → Serviços. O cadastro guarda domínio e credenciais, e evita deixar senha no código.

A documentação de Serviços REST lista os tipos de autenticação disponíveis: OAuth 1, OAuth 2, Basic, Fluig API, Custom e None. Se usar Basic, combine com HTTPS, como a própria TOTVS recomenda.

O código informado no cadastro será o serviceCode usado nas chamadas. Neste guia, ele será protheus.

3. Consulte dados com um dataset

Para trazer informação do ERP para formulários, como clientes ou centros de custo, o caminho natural é um dataset customizado. Formulários e eventos consomem esse dataset sem saber que o dado vem do Protheus. Se o conceito é novo para você, comece pelo guia de dataset no Fluig.

function createDataset(fields, constraints, sortFields) {
    var dataset = DatasetBuilder.newDataset();
    dataset.addColumn("codigo");
    dataset.addColumn("nome");

    var clientService = fluigAPI.getAuthorizeClientService();
    var data = {
        companyId: getValue("WKCompany") + "",
        serviceCode: "protheus",
        endpoint: "/rest/SEU_ENDPOINT",
        method: "get",
        timeoutService: "30",
        headers: {
            TenantId: "01,0101"
        }
    };

    var vo = clientService.invoke(JSON.stringify(data));
    var retorno = JSON.parse(vo.getResult());

    for (var i = 0; i < retorno.items.length; i++) {
        dataset.addRow(new Array(retorno.items[i].codigo, retorno.items[i].nome));
    }

    return dataset;
}

Três observações sobre o código:

• /rest/SEU_ENDPOINT e a estrutura items são ilustrativos. Ajuste ao contrato da sua API.
• timeoutService é informado em segundos. Prefira um valor curto em consultas, porque tem gente esperando a tela.
• Para serviços HTTPS, a documentação indica informar useSSL: true na propriedade options.

Trate os filtros no próprio dataset e repasse-os ao Protheus. Trazer tudo para filtrar depois é uma causa clássica de lentidão.

4. Grave com uma atividade de serviço

Gravar no ERP, como incluir um pedido após a aprovação, é diferente de consultar. Evite fazer isso em um evento que o usuário fica esperando.

Modele uma Atividade de Serviço com execução Automatizada. Segundo a documentação de integração assíncrona, a solicitação entra em uma fila no servidor, o script é executado e, em caso de sucesso, ela avança sozinha. Se as tentativas se esgotarem, segue para o fluxo de erro.

function servicetask9(attempt, message) {
    var clientService = fluigAPI.getAuthorizeClientService();
    var data = {
        companyId: getValue("WKCompany") + "",
        serviceCode: "protheus",
        endpoint: "/rest/SEU_ENDPOINT",
        method: "post",
        timeoutService: "60",
        headers: {
            TenantId: "01,0101"
        },
        params: {
            numeroSolicitacao: getValue("WKNumProces") + "",
            cliente: hAPI.getCardValue("codigoCliente"),
            valor: hAPI.getCardValue("valorTotal")
        }
    };

    var vo = clientService.invoke(JSON.stringify(data));

    if (vo.getResult() == null || vo.getResult().isEmpty()) {
        throw "Protheus não retornou resposta.";
    }

    log.info("Solicitação " + getValue("WKNumProces") + ": " + vo.getResult());
    return true;
}

Não basta a chamada acontecer. Leia a resposta e confirme que o registro foi criado de fato, de acordo com o contrato da sua API. Uma resposta com erro de negócio não pode ser tratada como sucesso.

Na modelagem, desenhe o que acontece no fluxo de erro: quem recebe a tarefa, o que essa pessoa vê e como devolver a solicitação para nova tentativa. Sem isso, a falha fica parada onde ninguém olha.

5. Evite duplicidade desde o primeiro dia

A atividade de serviço tenta novamente em caso de erro, e isso é bom. Mas há um cenário perigoso: o Protheus grava o pedido, a resposta demora, o Fluig recebe timeout e tenta de novo. Resultado: dois pedidos.

Por isso, o exemplo envia numeroSolicitacao. Com essa referência, o Protheus pode verificar se aquela solicitação já foi processada antes de gravar. Explicamos o mecanismo completo em pedidos duplicados na integração.

Checklist antes de ir para produção

• O REST responde a partir do servidor do Fluig, com rede e certificado corretos.
• TenantId está sendo enviado e foi testado em mais de uma filial.
• Credenciais estão no cadastro de Serviços, não no código.
• Timeouts foram definidos para consulta e para gravação.
• A resposta é validada, e erro de negócio não é tratado como sucesso.
• O fluxo de erro existe e tem responsável.
• O log registra o número da solicitação e o retorno da API.
• A gravação suporta receber a mesma operação duas vezes.
• O cenário de ERP indisponível foi testado.

Perguntas frequentes

O que é TenantId no Protheus?

É o cabeçalho que informa em qual empresa e filial a requisição deve rodar, no formato empresa,filial.

Devo integrar em evento ou em atividade de serviço?

Para consultas rápidas, dataset. Para gravações ou chamadas demoradas, atividade de serviço, que não prende o usuário e tem tratamento de erro no próprio fluxo. Veja também a ordem dos eventos de processo.

Como descobrir por que a integração falhou?

Comece pelo histórico da solicitação, em que cada tentativa com erro gera um complemento. Depois cruze com o log do Fluig e o log do Protheus, usando o número da solicitação como referência.

A diferença entre uma integração que funciona na demonstração e uma que aguenta a operação está nesses detalhes. É o trabalho da MyQube. Se quiser uma avaliação da sua integração, vamos conversar.