Conectar o Sage Intacct: sincronizar clientes, faturas e produtos

Obtenha um Client ID e um Client Secret no Sage Developer Portal, autorize um usuário dedicado de Web Services, cole os valores no Integration, teste, mapeie e ative: clientes, faturas e produtos sincronizam nos dois sentidos.

O conector do Sage Intacct sincroniza clientes, faturas e produtos entre o Sage Intacct e o seu sistema nos dois sentidos: você pode trazer cada um e enviá-lo de volta. Pedidos de venda e estoque não fazem parte desta conexão hoje: o que você pode sincronizar agora é clientes, faturas e produtos. Um detalhe importa desde o início: as credenciais estão vinculadas a um usuário de integração de Web Services dedicado, e entrar na interface web com esse usuário invalidará o token (REST-2102).

Pré-requisitos#

• Uma empresa do Sage Intacct, além de um app no Sage Developer Portal para essa empresa.
• Um usuário de integração de Web Services dedicado, autorizado explicitamente na configuração da empresa. Use um usuário criado só para esta conexão, não o login diário de uma pessoa.
• Nunca entre na interface web do Sage Intacct com esse usuário de integração. Isso invalida o token e as sincronizações seguintes falham com REST-2102.
• Se a sua empresa usa várias entidades, tenha o Entity ID em mãos: ele vai no campo company_id. Empresas de entidade única podem deixar esse campo vazio.

Obter credenciais#

1. Vá ao Sage Developer Portal → seu app e copie o Client ID exibido lá.
2. No mesmo lugar, copie o Client Secret. O secret é exibido apenas uma vez: salve-o em local seguro antes de sair da página.
3. Certifique-se de que essas credenciais estejam vinculadas ao usuário de Web Services autorizado explicitamente na configuração da sua empresa do Sage Intacct. Autorize lá o seu usuário de integração dedicado: a etapa do token será rejeitada se o app não estiver autorizado na configuração de Web Services da empresa.

Preencher no Integration#

1. Abra o Integration, crie uma nova conexão e escolha Sage Intacct. O formulário tem os três campos abaixo: preencha-os nesta ordem.
2. client_id (Client ID): obrigatório, campo de texto. Cole o Client ID que você copiou do Sage Developer Portal → seu app.
3. client_secret (Client Secret): obrigatório, campo de senha. Cole o Client Secret da mesma página do app. Ele é guardado como segredo e não é exibido de novo depois de salvar.
4. company_id (Company ID (opcional)): opcional, campo de texto, por exemplo mycompany. Preencha só se você trabalha com várias entidades: insira o Entity ID aqui. Neste formulário, Company ID e Entity ID são o mesmo valor: não há um campo de entidade separado, e empresas de entidade única deixam vazio.
5. Não há campo de endereço do servidor para preencher. A conexão usa sempre o endereço da REST API v1 do Sage Intacct: https://api.intacct.com/ia/api/v1.

Testar a conexão#

Clique em Testar a conexão e o sistema executa duas etapas reais. Etapa um: troca seu Client ID e Client Secret por um token no endereço de token do Sage Intacct (POST https://api.intacct.com/ia/api/v1/oauth2/token). Se qualquer campo obrigatório estiver vazio, o teste para de imediato com MISSING_CLIENT_SECRET e não envia nenhuma solicitação. Se o Sage Intacct responder 401 nesta etapa, o resultado é INVALID_CREDENTIALS: os valores estão errados ou o app não está autorizado na configuração de Web Services da empresa.

Etapa dois: com esse token, o sistema faz uma pequena sondagem pelo serviço de consultas (POST /services/core/query) pedindo um cliente: objeto customer, campos id e name, tamanho 1. Uma resposta 200 significa que a conexão funciona de ponta a ponta. Se a sondagem responder 401, o resultado é INVALID_TOKEN e a mensagem traz o lembrete REST-2102: entrar na interface web com o usuário autorizado invalida o token. O teste espera até 12 segundos antes de declarar tempo esgotado.

Mapping / escolher modelo#

Mapeie os três tipos de objeto desta conexão: clientes, faturas (o objeto arinvoice no Sage Intacct) e produtos. Para cada tipo, associe os campos do Sage Intacct aos campos do seu lado —no mínimo o id e o nome do registro— e confira a prévia com um registro real antes de ativar. Se você preencheu company_id, confirme que os registros da prévia pertencem a essa entidade.

Ativar#

Após ativar, os fluxos que você habilitou sincronizam clientes, faturas e produtos entre o Sage Intacct e o seu sistema: registros novos e alterados são trazidos, e os que você cria ou atualiza no seu lado são enviados de volta ao Sage Intacct. Acompanhe as primeiras execuções em Runs / Logs. Se as sincronizações começarem de repente a falhar com REST-2102, não mude o mapping primeiro: verifique se alguém entrou na interface web com o usuário de integração, emita um token novo e garanta que esse usuário fique fora da interface web.

Perguntas frequentes#

A sincronização falha de repente com REST-2102, ou o teste devolve INVALID_TOKEN

O token foi invalidado. A causa habitual é que alguém entrou na interface web do Sage Intacct com o usuário de integração de Web Services autorizado: esse login invalida o token do qual esta conexão depende.

Emita um token novo para a conexão, teste de novo e mantenha esse usuário de integração fora da interface web de vez: ele deve existir só para esta conexão.

O teste devolve INVALID_CREDENTIALS (401 ao obter o token)

Ou o Client ID ou o Client Secret que você colou está errado, ou o app não está autorizado na configuração de Web Services da sua empresa do Sage Intacct: o Sage Intacct rejeita a solicitação de token nos dois casos.

Copie de novo os dois valores do Sage Developer Portal → seu app (o secret é exibido uma só vez: use a cópia que você salvou), cole de novo sem espaços extras e confirme na configuração da empresa que o app está autorizado para o seu usuário dedicado de Web Services. Depois teste de novo.

O teste devolve MISSING_CLIENT_SECRET

Um dos dois campos obrigatórios —client_id ou client_secret— está vazio no formulário de conexão. O teste verifica isso primeiro e não envia nenhuma solicitação ao Sage Intacct até os dois estarem preenchidos.

Preencha client_id e client_secret com os valores do Sage Developer Portal → seu app, salve e execute o teste de novo.

Pedidos de venda ou estoque não chegam

Não é um erro de mapping. Esta conexão sincroniza apenas clientes, faturas e produtos: pedidos de venda e estoque não são transportados por ela, então nada chega desses dois tipos por mais que o mapping seja ajustado.

Limite os fluxos desta conexão a clientes, faturas e produtos e trate, por enquanto, pedidos de venda e estoque pelo seu outro processo existente.