Pontta Motor: importar o XML do Supplier Portal na revisão do pedido de venda (interno)

Nesse artigo você vai aprender

Como configurar o Pontta Motor para que o XML de um projeto vindo do Supplier Portal atualize o pedido de venda que já existe, por meio de uma nova revisão, em vez de criar um pedido novo. Também mostra o que o Motor faz em cada etapa, como acompanhar e reprocessar arquivos e o que conferir quando algo não funciona.

Nota: artigo de uso interno da equipe Pontta (implantação e suporte). A configuração é feita no computador onde o Pontta Motor está instalado, e não pelo cliente.

Descrição

O Pontta Motor é um aplicativo instalado em um computador do cliente. Ele fica rodando o tempo todo, monitora uma pasta e, a cada arquivo XML de projeto que chega nela, cria o pedido de venda no Pontta pela API, sem ninguém precisar digitar o pedido.

Na integração com o Supplier Portal, o caminho completo é este:

Pedido: a loja envia a proposta ao Supplier Portal. O Pontta recebe o aviso pelo webhook, cria o pedido de venda (ou uma nova versão, se o projeto já tiver pedido) e devolve o número do pedido ao Supplier Portal.
Projeto: o Supplier Portal gera o XML do projeto, que chega na pasta monitorada pelo Pontta Motor.
Itens: o Pontta Motor lê o XML. É aqui que entra o parâmetro deste artigo.

O Pontta Motor tem dois fluxos, e só um fica ativo por vez:

Criação de pedido (padrão): cada XML gera um pedido de venda novo.
Revisão do pedido (parâmetro sales-order-review ligado): o Motor usa o projectId do XML para achar o pedido de venda que já existe para aquele projeto, abre uma revisão nele, troca os itens pelos do XML e finaliza a revisão.

Com o fluxo de revisão, as atualizações do projeto ficam registradas como revisões do mesmo pedido, com histórico, em vez de pedidos duplicados.

Sumário

Utilize os links abaixo para ir diretamente à seção desejada:

Pré-requisitos
1. Preparar o Pontta
2. Configurar o motor.properties
3. Ligar o fluxo e testar
4. Acompanhar e reprocessar arquivos
O que acontece por baixo
Dúvidas frequentes

⚓

Pré-requisitos

Integração Supplier Portal configurada no Pontta, em Admin > Vendas > Integrações, com nome, unidades de negócio, Account ID e API Key.
Pontta Motor instalado no computador do cliente, em versão com o fluxo de revisão (entregue na BPT-3780).
Um usuário de integração com token gerado e com permissão de revisão de pedido de venda. O token age com as permissões desse usuário.
Pedido de venda já criado pela integração com o Supplier Portal para o projeto. Sem pedido para o projectId, não há o que revisar.

Consulte também: Token de integração

⚓

1. Preparar o Pontta

Na base do cliente, confira três configurações antes de mexer no Motor:

1 - Em Mais Opções > Vendas > Parâmetros, ligue Habilitar rascunho na revisão do pedido de venda. O Motor trabalha sobre o rascunho da revisão; sem esse parâmetro, o fluxo não funciona.

2 - Confira se o Leitor de Integração usado para o XML do Supplier Portal está ativo. É ele que transforma o XML nos itens da revisão. Os leitores ficam na área administrativa de Pedidos de Venda.

3 - Confira a REST Query usada pelo Pontta Motor. Os valores de businessUnit e integrationReader precisam ser os da base do cliente: a unidade de negócio dos pedidos e o leitor do passo anterior.

Nota: businessUnit e integrationReader são IDs da base. Se a REST Query veio de outra base (teste, homologação), os IDs não batem e o processamento falha.

Consulte também: REST Query (Interno)

⚓

2. Configurar o motor.properties

No computador do Pontta Motor, o arquivo motor.properties fica na pasta de instalação do Motor. As chaves usadas por este fluxo são:

file_dir: pasta monitorada, onde chegam os XMLs.
pontta_server_url: endereço do Pontta que o Motor chama.
pontta_auth_token: token de integração do usuário do passo de pré-requisitos.
file_last_hours: mantenha o valor da instalação (no plano de teste da BPT-3780, 24).
sales-order-review: true liga o fluxo de revisão. Comentada (#) ou ausente, o Motor segue criando pedidos novos.

Exemplo com o fluxo de revisão ligado:

file_dir=C:\pontta-motor\entrada
pontta_server_url=https://app.pontta.com
pontta_auth_token=<TOKEN_DE_INTEGRACAO>
file_last_hours=24
sales-order-review=true

Nota: o token é uma credencial. Não cole o arquivo motor.properties em tickets, chats ou issues sem apagar o valor de pontta_auth_token.

⚓

3. Ligar o fluxo e testar

1 - Pare o Pontta Motor.

2 - No motor.properties, grave sales-order-review=true.

3 - Inicie o Pontta Motor de novo.

4 - Coloque na pasta de file_dir um XML cujo projectId seja o mesmo de um pedido já criado pela integração.

5 - No Pontta, abra esse pedido de venda e, no menu de três pontos, clique em Revisões do pedido. Deve aparecer uma revisão nova, já com Revisado: Sim.

Para voltar ao fluxo antigo, comente a linha (#sales-order-review=true), reinicie o Motor e confira que um XML novo gera um pedido de venda novo.

Consulte também: Revisão de pedido de venda

⚓

4. Acompanhar e reprocessar arquivos

A tela do Pontta Motor mostra os arquivos do dia, os processados e os que falharam. Com o fluxo de revisão ligado, essas listas passam a mostrar o processamento das revisões, e não mais o de criação de pedidos.

1 - Na lista de falhas, veja o arquivo e a mensagem de erro.

2 - Corrija a causa (configuração, leitor, pedido inexistente para o projeto).

3 - Selecione o arquivo e use Ctrl+Delete para reprocessar.

O Motor também tenta de novo sozinho, de tempos em tempos, os arquivos que falharam. O reprocessamento retoma da etapa em que o arquivo parou, sem refazer as anteriores.

⚓

O que acontece por baixo

Com sales-order-review ligado, cada XML passa por estas etapas, e cada uma fica registrada no Motor:

1 - Lê o projectId do XML.

2 - Procura o pedido de venda ligado a esse projeto pela referência de integração. Se já existir uma revisão para o projeto, usa ela; se não, cria uma revisão nova.

3 - Inicia o rascunho da revisão, em nome do usuário do token.

4 - Remove os itens atuais do rascunho.

5 - Importa o XML no rascunho pelo Leitor de Integração.

6 - Finaliza a revisão.

Alguns efeitos que vale saber:

O pedido não muda: o valor do pedido continua o mesmo. A diferença entre o vendido e o revisado aparece no resumo das revisões, como em qualquer revisão.
Os itens são trocados, não somados: o Motor remove os itens do rascunho e importa o projeto inteiro do XML.
Um fluxo por vez: o reprocessamento automático e a lista de arquivos seguem só o fluxo ligado. Arquivos que falharam no fluxo de criação não são reprocessados pelo fluxo de revisão, e vice-versa.

⚓

Dúvidas frequentes

Liguei o sales-order-review e o Motor continua criando pedidos novos.

Reinicie o Pontta Motor depois de alterar o motor.properties. Confira também se a linha não ficou com # na frente e se o valor é exatamente true.

O arquivo falha na busca do pedido de venda.

Não existe pedido de venda ligado ao projectId do XML. Ou o pedido não foi criado pela integração com o Supplier Portal, ou o XML é de outro projeto. Com o fluxo de revisão ligado, o Motor não cria pedido novo nesse caso.

O arquivo falha ao iniciar o rascunho ou ao importar os itens.

Confira, nesta ordem: o parâmetro Habilitar rascunho na revisão do pedido de venda, se o usuário do token tem permissão de revisão, se o Leitor de Integração está ativo e se a REST Query aponta para o leitor e a unidade de negócio da base certa.

Apareceu uma revisão finalizada que ninguém da fábrica fez.

É o Pontta Motor. Com o fluxo de revisão ligado, ele cria e finaliza a revisão sozinho quando chega um XML de um projeto que já tem pedido, em nome do usuário do token de integração.

Reprocessei e a revisão não foi duplicada. Está certo?

Sim. O Motor guarda em que etapa cada arquivo parou e retoma dali, reaproveitando a revisão que já tinha criado.

Olá, como podemos ajudar você?