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
- No Tesselys, abra o menu lateral, seção Sistema, e entre em Integrações > Integração de API. A tela se chama API Externa.
- Clique em Gerar API Key e confirme.
- Copie os dois valores e marque a confirmação de que os guardou.
| Credencial | Formato | Onde vai |
|---|---|---|
| API Key | tesselys_ak_ seguido de 48 caracteres hexadecimais (60 no total) | Cabeçalho x-api-key do POST /external/v1/auth |
| Secret | 27 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.
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çalho | Valor | Obrigatório |
|---|---|---|
Content-Type | application/json | Sim |
x-api-key | Sua API Key | Sim |
Corpo:
{ "secret": "SEU_SECRET" }
Resposta (200):
{
"accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"companyToken": "3f2b9c1e-6d4a-4b8e-9f0a-1c2d3e4f5a6b",
"expiresIn": 3600,
"refreshToken": "rt_7c1e9a4b2d...",
"refreshExpiresIn": 86400
}
| Campo | Descrição |
|---|---|
accessToken | Token de acesso (JWT). Vai no cabeçalho Authorization. |
companyToken | Identificador da sessão da empresa (um UUID, não um JWT). Vai no cabeçalho x-company-token. |
expiresIn | Validade do accessToken, em segundos. Use o valor recebido em vez de fixar um número na integração. |
refreshToken | Token para renovar a sessão sem reenviar a API Key e o Secret (veja Renovando). |
refreshExpiresIn | Validade do refreshToken, em segundos. |
Erros (401):
friendlyMessage | Causa |
|---|---|
| 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:
| Token | Validade | Quando vence |
|---|---|---|
accessToken | O que vier em expiresIn | A chamada responde 401 |
companyToken | Até 4 horas | A 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.
A rota POST /external/v1/auth/refresh-company foi removida e responde 404. Use refresh-token.
Revogando a chave
- Na tela API Externa, clique em Revogar API Key.
- Digite
REVOGARpara 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.
A nossa equipe ajuda você a configurar e usar esse recurso.