Conectar o Xero: receber pedidos, clientes, faturas e produtos, consultar estoque
Conclua o fluxo OAuth2 do seu app em developer.xero.com com os três escopos de leitura, copie o Tenant ID da lista de conexões, cole os dois valores no Integration, teste, mapeie e ative.
O conector do Xero traz pedidos, clientes, faturas e produtos da sua organização do Xero para este sistema, pode devolver clientes, produtos e faturas ao Xero e pode consultar quantidades de estoque pelos Items do Xero. Ele não devolve alterações de estoque ao Xero: nesta conexão o estoque é somente leitura. Uma conexão é para uma organização do Xero, identificada pelo seu Tenant ID.
Pré-requisitos#
- Uma organização do Xero à qual você consiga entrar e um app registrado para ela em developer.xero.com.
- Você consegue concluir o fluxo OAuth2 desse app em developer.xero.com e conceder os três escopos de leitura: accounting.transactions.read, accounting.contacts.read e accounting.settings.read. Um token sem qualquer um deles vai falhar no teste ou nas extrações.
- Você sabe para qual organização é a conexão. O Tenant ID é o ID da organização, não o ID do app: são dois valores diferentes e não são intercambiáveis.
Obter credenciais#
- Acesse developer.xero.com, abra seu app e conclua o fluxo OAuth2. Quando o Xero pedir escopos, inclua pelo menos accounting.transactions.read, accounting.contacts.read e accounting.settings.read.
- Copie o access token que o fluxo OAuth2 retorna. Esse token é o que você cola no Integration: não há uma API key separada para criar nesta conexão.
- Obtenha o Tenant ID da sua organização de uma destas duas formas: chame GET https://api.xero.com/connections com o access token e copie o tenantId da sua organização da resposta; ou abra developer.xero.com → seu app → connections e leia o tenantId exibido ali.
Preencher no Integration#
- Abra Integration → Marketplace → Xero → Nova conexão.
- tenant_id, obrigatório, Tenant ID (Organisation): cole o tenantId da sua organização, no formato xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. É o ID da organização da lista de conexões, não o ID do app.
- access_token, obrigatório, Access token: cole completo o access token retornado pelo fluxo OAuth2. É um campo do tipo senha e é guardado como segredo. Certifique-se de que o token foi concedido com accounting.transactions.read, accounting.contacts.read e accounting.settings.read.
Testar a conexão#
Clique em Testar a conexão. O teste envia uma solicitação real para GET https://api.xero.com/api.xro/2.0/Organisation com dois cabeçalhos: Authorization: Bearer seguido do seu access token, e xero-tenant-id com seu tenant_id. Uma resposta 200 conta como aprovado, e o resultado mostra o nome da organização que o Xero retornou, para você confirmar que é a organização desejada. Um 401 significa que o token é inválido ou expirou; um 403 significa que o token não tem escopo suficiente. Se tenant_id ou access_token estiver ausente, o teste para antes de enviar qualquer coisa, porque os dois valores são necessários para esta sondagem. A sondagem expira após 12 segundos.
Mapping / escolher modelo#
Escolha o mapping padrão do Xero. Pedidos, clientes e faturas seguem os registros padrão do Xero Accounting, e produtos e consultas de estoque seguem os Items do Xero. Depois que o teste aprovar, execute uma extração e confira um pedido real lado a lado (número, cliente, linhas e valores), confira uma fatura e um produto da mesma forma e compare a quantidade de um item com o que o Xero mostra, antes de ativar.
Ativar#
Após ativar, a conexão traz pedidos, clientes, faturas e produtos da organização do Xero indicada pelo seu tenant_id na frequência definida, devolve clientes, produtos e faturas ao Xero quando esses fluxos rodam, e lê as quantidades de estoque dos Items do Xero ao consultar o estoque. Acompanhe as primeiras execuções em Runs / Logs e compare com o Xero 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 Xero. As quantidades dos Items do Xero são lidas apenas para consulta, então os ajustes de estoque continuam precisando ser feitos no próprio Xero ou no sistema onde o ajuste realmente acontece.
Perguntas frequentes#
O teste falha com 401: token inválido ou expirado
O Xero recusou o próprio access token: está errado, incompleto ou não é mais válido. Nesse caso, a sondagem da organização nem passa da autenticação, então o tenant_id não é a primeira coisa a verificar.
Volte a developer.xero.com → seu app, conclua o fluxo OAuth2 novamente, copie o novo access token completo no campo access_token e teste novamente.
O teste falha com 403: o escopo não basta
O token foi aceito, mas não recebeu os escopos de leitura de que esta conexão precisa. Os três obrigatórios são accounting.transactions.read, accounting.contacts.read e accounting.settings.read: faltar qualquer um deles pode gerar este resultado.
Refaça o fluxo OAuth2 em developer.xero.com para seu app e conceda os três escopos desta vez, cole o novo access token no Integration e teste novamente. Não cole apenas o token antigo de novo: os escopos dele não mudam.
O token está certo, mas o teste continua falhando: organização errada
O tenant_id não pertence à organização para a qual o token foi autorizado. A sondagem envia seu tenant_id no cabeçalho xero-tenant-id e o Xero responde apenas por aquela organização: um token válido combinado com o ID de outra organização falha aqui, e o nome da organização num resultado bem-sucedido é a conferência de que você escolheu a certa.
Copie novamente o tenantId da organização desejada: chame GET https://api.xero.com/connections com o access token e escolha o tenantId daquela organização na resposta, ou leia em developer.xero.com → seu app → connections. Substitua tenant_id, salve e teste novamente; depois confirme que o nome da organização exibido coincide.
O teste para antes de enviar: falta um valor obrigatório
tenant_id ou access_token está vazio. A sondagem da organização precisa dos dois: o token para o cabeçalho Authorization e o tenant_id para o cabeçalho xero-tenant-id, então o teste para em vez de enviar uma solicitação que não pode ter sucesso.
Preencha os dois campos conforme a etapa de preencher no Integration (tenant_id da lista de conexões e access_token colado completo), salve e teste novamente.
Conectado, mas as quantidades de estoque nunca mudam no Xero
Esse é o limite desta conexão, não uma falha: o estoque é lido dos Items do Xero para consulta e as alterações de estoque não são devolvidas ao Xero. Pedidos, clientes, faturas e produtos fluem como descrito acima; os níveis de estoque no Xero continuam sob controle do Xero.
Faça os ajustes de estoque no próprio Xero, ou no sistema onde o ajuste realmente acontece, e use a consulta de estoque desta conexão para verificar as quantidades depois.
O teste expira após 12 segundos
A sondagem da organização não recebeu resposta do Xero a tempo. É um problema de acesso ou de resposta no caminho até api.xero.com, não um veredito sobre seu token ou tenant_id: nenhum dos dois valores chegou a ser julgado.
Aguarde um momento e execute Testar a conexão novamente com os mesmos dois valores. Se os tempos esgotados se repetirem enquanto outras conexões testam bem, anote o horário e a mensagem exata de Runs / Logs antes de mudar qualquer valor.