Pular para o conteúdo principal

Autenticação

A autenticação tem dois passos: o seu sistema troca a API Key e o Secret por dois tokens e, depois, envia esses tokens em todas as chamadas.

Gerando a API Key e o Secret​

  1. No Tesselys, abra o menu lateral, seção Sistema, e entre em Integrações > Integração de API. A tela se chama API Externa.
  2. Clique em Gerar API Key e confirme.
  3. Copie os dois valores e marque a confirmação de que os guardou.
CredencialFormatoOnde vai
API Keytesselys_ak_ seguido de 48 caracteres hexadecimais (60 no total)Cabeçalho x-api-key do POST /external/v1/auth
Secret27 caracteres (base64url)Corpo do POST /external/v1/auth

Regras:

  • Só o Proprietário ou um Administrador da empresa gera ou revoga a chave.
  • Gerar e revogar são ações sensíveis: quem usa verificação em duas etapas pode ter de confirmar com o código.
  • A API Key e o Secret aparecem uma vez só. O Tesselys guarda apenas um resumo criptográfico (hash) da chave e não consegue mostrá-la de novo.
  • Cada empresa tem uma chave ativa. Gerar outra revoga a atual na hora e desconecta todas as integrações que a usavam.
Guarde bem

Se perder a API Key ou o Secret, a única saída é gerar uma chave nova (e atualizar todos os sistemas que usavam a antiga).

Conta de serviço​

Ao gerar a chave, o Tesselys cria uma conta de serviço da empresa, com papel de Proprietário. É ela quem aparece como autora do que a integração grava. A API Externa só aceita a sessão dessa conta: o token de login de uma pessoa não funciona nas rotas /external/v1 (resposta 403).

Obtendo os tokens​

POST /external/v1/auth​

CabeçalhoValorObrigatório
Content-Typeapplication/jsonSim
x-api-keySua API KeySim

Corpo:

{ "secret": "SEU_SECRET" }

Resposta (200):

{
"accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"companyToken": "3f2b9c1e-6d4a-4b8e-9f0a-1c2d3e4f5a6b",
"expiresIn": 3600,
"refreshToken": "rt_7c1e9a4b2d...",
"refreshExpiresIn": 86400
}
CampoDescrição
accessTokenToken de acesso (JWT). Vai no cabeçalho Authorization.
companyTokenIdentificador da sessão da empresa (um UUID, não um JWT). Vai no cabeçalho x-company-token.
expiresInValidade do accessToken, em segundos. Use o valor recebido em vez de fixar um número na integração.
refreshTokenToken para renovar a sessão sem reenviar a API Key e o Secret (veja Renovando).
refreshExpiresInValidade do refreshToken, em segundos.

Erros (401):

friendlyMessageCausa
API Key inválida ou expirada.Cabeçalho x-api-key ausente, chave errada ou revogada.
Secret inválido ou credenciais de autenticação incorretas.Secret errado.
A empresa associada a esta API Key está inativa.Empresa inativa no Tesselys.
A conta de serviço está inativa. Gere uma nova API Key.A conta de serviço foi desativada (por exemplo, depois de revogar a chave).

Usando os tokens​

Toda chamada às rotas /external/v1 (exceto auth e health) leva os dois cabeçalhos:

Authorization: Bearer {accessToken}
x-company-token: {companyToken}
curl https://erp-api.ideros.api.br/external/v1/persons \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN"

Cabeçalho opcional: locale (pt-BR, en-US ou es-ES) escolhe o idioma das mensagens de erro.

Renovando​

Há duas validades diferentes:

TokenValidadeQuando vence
accessTokenO que vier em expiresInA chamada responde 401
companyTokenAté 4 horasA chamada responde 403 com "code": "COMPANY_SESSION_EXPIRED"

Para renovar, use o refreshToken:

POST /external/v1/auth/refresh-token​

curl -X POST https://erp-api.ideros.api.br/external/v1/auth/refresh-token \
-H "Content-Type: application/json" \
-d '{ "refreshToken": "rt_7c1e9a4b2d..." }'

A resposta traz um accessToken, um companyToken e um refreshToken novos, no mesmo formato de POST /external/v1/auth. Guarde sempre o refreshToken mais recente: o anterior deixa de valer.

Se o refreshToken estiver inválido ou vencido, a resposta é 401: chame POST /external/v1/auth de novo com a API Key e o Secret. O mais simples é renovar um pouco antes de expiresIn acabar.

observação

A rota POST /external/v1/auth/refresh-company foi removida e responde 404. Use refresh-token.

Revogando a chave​

  1. Na tela API Externa, clique em Revogar API Key.
  2. Digite REVOGAR para confirmar.

A revogação vale na hora: a API Key deixa de autenticar e a conta de serviço é desativada. Para reconectar, gere uma chave nova.

Boas práticas​

  • Nunca coloque a API Key ou o Secret em código que roda no navegador ou em repositórios.
  • Guarde as credenciais em variáveis de ambiente ou num cofre de segredos.
  • Reaproveite os tokens enquanto valem, em vez de autenticar a cada chamada.
  • Se suspeitar de vazamento, gere uma chave nova: a antiga é revogada no mesmo momento.
Ainda com dúvida?

A nossa equipe ajuda você a configurar e usar esse recurso.