Conectar o Epicor Kinetic: receber pedidos e clientes, consultar estoque
Crie uma conta de serviço e uma API Key no Epicor Kinetic, preencha a URL base do servidor, o Company ID, o usuário, a senha e a API Key no Integration, teste, mapeie e ative.
O conector do Epicor Kinetic traz pedidos de venda e clientes do seu ERP Epicor Kinetic para este sistema e pode consultar as quantidades de estoque mantidas no Epicor. Ele lê dados do Epicor: não devolve alterações de estoque ao Epicor. Cada solicitação usa duas credenciais juntas, a conta de serviço para o acesso Basic e a API Key, então ambas são sempre obrigatórias. Uma conexão por instância do Epicor e empresa.
Pré-requisitos#
- Uma instância do Epicor Kinetic à qual você consiga entrar e seu endereço base do servidor: na nuvem, uma forma como https://mycompany.epicorsaas.com/MyInstance; numa instalação local, https://<servidor>/<nome da instância>.
- Seu Company ID, por exemplo EPIC06. É o segmento de empresa no endereço OData v2, então deve corresponder exatamente à empresa da qual você quer trazer dados.
- Uma conta de serviço dedicada do Epicor, criada no User Account Security Maintenance, com acesso a essa empresa. Seu usuário e senha são metade das credenciais.
- Permissão para criar uma chave no API Key Maintenance e para dar a essa chave um Access Scope que cubra Erp.BO.SalesOrderSvc, Erp.BO.CustomerSvc e Erp.BO.PartSvc.
Obter credenciais#
- Crie ou confirme a conta de serviço dedicada no User Account Security Maintenance e garanta que ela tem acesso à empresa da qual você trará dados. Anote seu usuário e deixe a senha pronta.
- Abra Epicor Kinetic → API Key Maintenance → New Key e crie uma nova API Key.
- Dê à chave um Access Scope que cubra os três serviços: Erp.BO.SalesOrderSvc, Erp.BO.CustomerSvc e Erp.BO.PartSvc. Uma chave cujo escopo omite um serviço não consegue ler esse tipo de dado.
- Copie a API Key no momento em que ela é exibida: ela é exibida uma única vez. Se perdê-la, crie uma nova chave em vez de procurar a antiga.
- Anote ao mesmo tempo os outros dois valores: o endereço base do servidor, sem nenhum sufixo /api, e o Company ID, por exemplo EPIC06.
Preencher no Integration#
- Abra Integration → Marketplace → Epicor Kinetic → Nova conexão.
- base_url, obrigatório, URL base do servidor Epicor: o endereço da sua instância, por exemplo https://mycompany.epicorsaas.com/MyInstance. Não adicione um sufixo /api: o sistema monta o restante do endereço.
- company, obrigatório, Company ID: o segmento de empresa, por exemplo EPIC06. Deve ser a empresa à qual a conta de serviço consegue acessar.
- username, obrigatório, usuário da conta de serviço: o usuário da conta de serviço dedicada do User Account Security Maintenance.
- password, obrigatório, senha da conta de serviço: a senha dessa mesma conta de serviço. É um campo do tipo senha e é guardado como segredo.
- api_key, obrigatório, chave da API REST: cole a API Key copiada de API Key Maintenance → New Key, com seu Access Scope cobrindo Erp.BO.SalesOrderSvc, Erp.BO.CustomerSvc e Erp.BO.PartSvc. É um campo do tipo senha e é guardado como segredo.
Testar a conexão#
Clique em Testar a conexão. O teste primeiro verifica se os cinco campos estão preenchidos: se base_url estiver ausente, para com MISSING_BASE_URL, e qualquer outro campo ausente também para o teste antes de enviar qualquer coisa. Depois, faz uma solicitação real, somente leitura, com as duas credenciais juntas: pede um único pedido de venda ao serviço SalesOrder, enviando a conta de serviço como acesso Basic e a API Key na mesma solicitação. Uma resposta 200 conta como aprovado. O erro diz qual credencial verificar: 401 significa que o usuário ou a senha da conta de serviço foi recusado, enquanto 400 ou 403 significa que a própria API Key foi recusada ou que seu Access Scope não cobre o serviço. O teste desiste após cerca de 12 segundos se a instância não responder.
Mapping / escolher modelo#
Escolha o mapping padrão do Epicor Kinetic. Ele trabalha com os três serviços que o escopo da API Key cobre: os pedidos de venda vêm de Erp.BO.SalesOrderSvc, os clientes de Erp.BO.CustomerSvc e as consultas de estoque leem Erp.BO.PartSvc. Depois que o teste aprovar, execute uma extração e confira um pedido real lado a lado (número do pedido, cliente, linhas e quantidades) e compare a quantidade de uma peça com o que o Epicor mostra, antes de ativar. Se um campo da sua instância diferir, ajuste esse campo no mapping em vez de renomear algo no Epicor.
Ativar#
Após ativar, a conexão traz pedidos de venda e clientes do Epicor Kinetic para este sistema na frequência definida, e as consultas de estoque leem as quantidades atuais do Epicor. Acompanhe as primeiras extrações em Runs / Logs e compare com o Epicor antes de deixar a conexão sem supervisão.
O que esta conexão não faz: não devolve alterações de estoque ao Epicor Kinetic. As quantidades no Epicor continuam sob o controle do Epicor: esta conexão apenas as lê. Continue mantendo o estoque no próprio Epicor.
Perguntas frequentes#
O teste falha com 401
O Epicor recusou o acesso Basic: o usuário ou a senha da conta de serviço não corresponde, ou essa conta não consegue acessar a empresa do campo company. Este erro é sobre a conta de serviço, não sobre a API Key.
Confira username e password com a conta no User Account Security Maintenance, confirme que essa conta tem acesso à empresa que você preencheu e teste novamente. Não altere a API Key por causa de um 401.
O teste falha com 400 ou 403
A própria API Key foi recusada, ou seu Access Scope não cobre o serviço que o teste chamou. A conta de serviço pode estar perfeitamente bem: este erro é sobre a chave e seu escopo, a segunda metade das credenciais.
No API Key Maintenance, revise a chave que você colou e seu Access Scope: deve cobrir Erp.BO.SalesOrderSvc, Erp.BO.CustomerSvc e Erp.BO.PartSvc. Se a chave foi copiada incompleta ou o escopo está curto, corrija o escopo ou crie uma nova chave, cole-a inteira em api_key e teste novamente.
O teste para com MISSING_BASE_URL ou outra mensagem de campo ausente
Um dos cinco campos obrigatórios está vazio, então o teste parou antes de enviar qualquer coisa. Os cinco (base_url, company, username, password e api_key) são obrigatórios, porque cada solicitação precisa das duas credenciais e do endereço da empresa.
Preencha os cinco campos conforme a etapa de preencher no Integration, salve e teste novamente. Para base_url, use o endereço completo da instância, sem faltar nada no início.
Todos os valores parecem certos, mas o teste continua falhando
Uma causa comum é o endereço: se base_url termina com um sufixo /api, o sistema acrescenta suas próprias partes de endereço depois e a solicitação vai para um endereço errado. O valor de company causa o mesmo tipo de falha: faz parte do endereço, então um Company ID errado aponta o teste para uma empresa que não responde para estas credenciais.
Remova qualquer sufixo /api de base_url para que seja exatamente o endereço da instância, por exemplo https://mycompany.epicorsaas.com/MyInstance, e confira company com o Company ID da empresa à qual a conta de serviço consegue acessar. Salve e teste novamente antes de alterar qualquer credencial.
Os pedidos chegam, mas os clientes ou o estoque não
A conexão em si está funcionando: o teste aprovou no serviço SalesOrder. O tipo de dado que falta aponta para o escopo da API Key: cada serviço precisa de sua própria cobertura, e um escopo que cobre SalesOrderSvc mas omite CustomerSvc ou PartSvc lê pedidos enquanto os outros dois ficam vazios.
No API Key Maintenance, amplie o Access Scope da chave para cobrir os três: Erp.BO.SalesOrderSvc, Erp.BO.CustomerSvc e Erp.BO.PartSvc. Se o escopo não puder ser alterado na chave existente, crie uma nova chave com o escopo completo, cole-a em api_key, teste novamente e execute uma extração.
Conectado, mas nenhum pedido de venda chega
A conexão está funcionando (o teste leu de verdade o serviço SalesOrder), mas não há nada novo para trazer: a empresa no Epicor não tem pedidos de venda novos no intervalo de extração, ou os pedidos existentes pertencem a outra empresa, diferente da do campo company.
Crie ou confirme um pedido de venda no Epicor sob o mesmo Company ID que a conexão usa, execute uma extração manual e confirme que o pedido aparece na prévia ou em Runs / Logs.