Conectar a Acumatica: receber pedidos e clientes, consultar estoque

Entre na sua instância da Acumatica com um usuário de API dedicado, preencha a URL da instância, a empresa e a versão do endpoint no Integration, teste, mapeie e ative.

O conector da Acumatica conecta sua instância do Acumatica Cloud ERP ao Integration: ele traz pedidos de venda e clientes para o sistema e permite consultar o estoque mantido na Acumatica. Uma conexão atende a uma empresa da Acumatica. O estoque pode ser lido da Acumatica, mas alterações de estoque não são enviadas de volta à Acumatica por esta conexão.

Pré-requisitos#

• Uma instância da Acumatica na qual você consegue entrar, e o nome exato da empresa (tenant) usado no acesso.
• Um usuário de acesso para esta conexão — recomenda-se um usuário de API dedicado — que consiga ler pedidos de venda, clientes e itens de estoque nessa empresa.
• Um endpoint publicado em Acumatica → Web Service Endpoints. Se sua instância publica o endpoint padrão, o nome costuma ser Default e a versão corresponde à sua versão da Acumatica.
• Se o acesso da sua empresa exige uma filial, saiba também o nome da filial. Se o acesso não pede filial, esse campo pode ficar vazio depois.

Obter credenciais#

1. Não há uma chave separada para criar neste conector. As credenciais são o próprio usuário de acesso da Acumatica: prepare um usuário de API dedicado na Acumatica, confirme que consegue entrar com ele e anote o nome de usuário e a senha.
2. Anote o nome da empresa (tenant) exatamente como aparece no acesso, e o nome da filial se o seu acesso exigir uma. Esses valores precisam coincidir palavra por palavra com a instância.
3. Anote o endereço da sua instância — o endereço raiz da sua instância da Acumatica, por exemplo https://mycompany.acumatica.com. Não adicione /entity no final.
4. Na Acumatica, abra Web Service Endpoints e verifique o endpoint publicado: anote o nome do endpoint e a versão do endpoint. Você só precisará preenchê-los depois se forem diferentes de Default e 24.200.001.

Preencher no Integration#

1. Abra Integration → Marketplace → Acumatica → Nova conexão.
2. base_url — Instance URL, obrigatório: preencha o endereço raiz da sua instância da Acumatica, por exemplo https://mycompany.acumatica.com. Não adicione /entity no final.
3. company — Company, obrigatório: preencha o nome da empresa (tenant) exatamente como aparece quando você entra na Acumatica.
4. branch — Branch, opcional: preencha apenas se o acesso da sua empresa exigir uma filial. Se o acesso não pede filial, deixe vazio.
5. username — Username, obrigatório: preencha o nome de acesso do usuário de API dedicado que você preparou na Acumatica.
6. password — Password, obrigatório: preencha a senha desse mesmo usuário de acesso. Ela é armazenada criptografada e nunca exibida.
7. endpoint_name — Endpoint name, opcional: deixe vazio se sua instância publica o endpoint padrão — o sistema usará Default. Preencha apenas quando Web Service Endpoints mostrar um nome diferente.
8. endpoint_version — Endpoint version, opcional: deixe vazio se sua instância publica a versão 24.200.001 — o sistema usará 24.200.001. Preencha a versão exata mostrada em Web Service Endpoints quando a sua for diferente; a versão precisa corresponder à sua versão da Acumatica.

Testar a conexão#

Clique em Testar a conexão. O teste faz duas coisas em ordem. Primeiro, entra na sua instância com o nome de usuário, a senha, a empresa e a filial que você preencheu — o acesso só dá certo quando a instância responde e devolve uma sessão, que o teste usa na hora e encerra no final. Depois, com essa sessão, ele lê um único item de estoque usando o nome e a versão do endpoint da conexão. Se passar, o acesso funciona, o endpoint responde e o usuário de acesso consegue ler itens de estoque. O teste aguarda cerca de 12 segundos; se o tempo esgotar, verifique se o endereço da instância está acessível e tente de novo. Se falhar, guarde o código de erro exato exibido — as perguntas frequentes relacionam cada código à sua causa e solução.

Mapping / escolher modelo#

Escolha o modelo padrão da Acumatica. Ele mapeia os pedidos de venda da Acumatica para pedidos padrão e traz os clientes junto, para que números do pedido, linhas, quantidades e dados do cliente caiam nos campos certos. Os campos que o modelo consegue ler vêm do endpoint publicado na sua instância, então, se sua instância publica um nome ou uma versão de endpoint diferente do padrão, configure primeiro endpoint_name e endpoint_version na conexão e veja a prévia do mapping de novo. Antes de ativar, abra a prévia e confirme num pedido real que as linhas e os nomes dos clientes estão certos; a consulta de estoque lê os itens de estoque diretamente e não precisa de mapping de pedidos.

Ativar#

Após ativar, o Integration entra na sua instância da Acumatica na frequência definida, traz novos pedidos de venda e clientes e responde às consultas de estoque lendo os itens de estoque da Acumatica. Cada sessão de acesso é usada só para aquela execução e é encerrada quando ela termina. O que esta conexão não faz: ela não devolve alterações de estoque à Acumatica, então ajuste as quantidades na própria Acumatica quando o estoque precisar de correção lá. Acompanhe os primeiros pedidos em Runs / Logs antes de deixar sem supervisão.

Perguntas frequentes#

O teste falha com ENDPOINT_VERSION_MISMATCH — a leitura do item de estoque devolve 404

O acesso funcionou, mas o nome ou a versão do endpoint na conexão não corresponde ao endpoint publicado na sua instância. O teste procura o item de estoque pelo nome e pela versão informados, e a instância não tem nada publicado naquele endereço, então a leitura volta com 404. É a causa mais comum quando o acesso em si está certo.

Na Acumatica, abra Web Service Endpoints e copie exatamente o nome e a versão do endpoint publicado. Coloque-os em endpoint_name e endpoint_version na conexão — ou limpe os dois campos se o endpoint publicado for mesmo Default e 24.200.001. Salve e teste de novo.

O teste falha com INVALID_CREDENTIALS — o acesso devolve 401 ou 400

A instância recusou o acesso: o nome de usuário, a senha ou o nome da empresa não corresponde ao que a instância espera. Um nome de empresa digitado de forma um pouco diferente da tela de acesso conta como credencial errada, e uma filial que o acesso exige mas a conexão não informa também.

Entre na Acumatica pelo navegador com o mesmo usuário e confirme que nome de usuário, senha e nome da empresa funcionam lá. Depois preencha de novo username, password e company na conexão exatamente como usados no navegador, adicione branch se aquele acesso pedir um, e teste de novo.

O teste falha com MISSING_SCOPE — a leitura do item de estoque devolve 401 ou 403

O acesso funcionou e o endpoint existe, mas o usuário de acesso não tem permissão para ler itens de estoque nessa empresa. Por isso a instância recusa a leitura do item de estoque mesmo que o usuário consiga entrar.

Na Acumatica, dê ao usuário de API dedicado acesso de leitura aos itens de estoque — e aos pedidos de venda e clientes, que a conexão também lê — nessa empresa, ou troque a conexão para um usuário que já tenha esse acesso. Salve e teste de novo.

O teste falha com MISSING_BASE_URL ou MISSING_CREDENTIALS, ou o acesso não alcança a instância

Um campo obrigatório está vazio, ou o próprio endereço da instância está errado. MISSING_BASE_URL significa que base_url ficou vazio; MISSING_CREDENTIALS significa que falta username, company ou password. Um erro comum de endereço é terminar base_url com /entity — a conexão adiciona os próprios caminhos depois do endereço raiz, então um endereço que já traz esse sufixo aponta o acesso para o lugar errado.

Preencha todos os campos obrigatórios — base_url, company, username e password — e verifique base_url: use apenas o endereço raiz da instância, por exemplo https://mycompany.acumatica.com, sem nada depois. Salve e teste de novo.