Integrações e tokens
O parceiro cria uma integração no painel e entrega ao programador só o token dela. A senha dele nunca entra na história.
O que é uma integração
Uma integração representa um sistema ligado à conta do parceiro: “Bling – João Dev”, “n8n do estoque”, “Loja própria”. Cada uma tem:
- um nome, para o parceiro saber qual é qual;
- um conjunto de permissões, escolhido por ele dentro do que a OTL liberou;
- um token de acesso, com validade.
O parceiro tem, por padrão, uma integração ativa. Quem precisa de mais (um ERP e uma automação, por exemplo) solicita à OTL pelo próprio painel. Integrações revogadas não contam nesse limite.
O token
otl_prod_4f9Kx2mQ7vB1nZ8cR3tY6uW0aE5dG2hJ9kL4pS7xV1b
otl_sbx_8Hq1Lz0vN5mC2xB7kJ4gF9dS6aP3oI8uY1tR5eW2qZ0- É exibido uma única vez, na hora em que é criado. A OTL não o guarda em formato legível e não tem como mostrá-lo de novo.
- O prefixo diz o ambiente:
otl_prod_para produção,otl_sbx_para sandbox. - Não é um JWT. É um valor opaco: não há o que decodificar, e ele não carrega informação. Para
saber o que o token pode fazer, chame o
/v1/eu.
Validade
O parceiro escolhe a validade ao criar: 7, 30, 180 dias, 1 ano ou sem expiração.
- A partir de 7 dias do vencimento, toda resposta da API traz o cabeçalho
Aviso-Expiracao-Tokencom a data. Faça o seu sistema avisar alguém quando ele aparecer. - Depois do vencimento, as chamadas respondem
401 TOKEN_EXPIRADO. - Renovar é gerar um novo token na mesma integração: nome e permissões continuam, o token anterior para de funcionar na hora, e o parceiro envia o novo ao programador.
Existe para integrações que não podem parar por data vencida. Em troca, vale até alguém revogar: o parceiro deve revogar a integração assim que o programador ou o sistema deixar de atendê-lo.
O que muda na hora
Estas mudanças valem na chamada seguinte, sem esperar nada:
| O que aconteceu | O que a API passa a responder |
|---|---|
| O parceiro revogou a integração | 401 TOKEN_INVALIDO |
| O parceiro gerou um novo token | O token antigo: 401 TOKEN_INVALIDO |
| O parceiro tirou uma permissão | 403 ESCOPO_INSUFICIENTE nas rotas que a exigem |
| A OTL reduziu o teto do parceiro | Idem, em todas as integrações dele |
| A OTL suspendeu a API do parceiro | 403 API_NAO_LIBERADA |
| A conta do parceiro foi desativada | 401 CONTA_DESATIVADA |
Trocar a senha do painel não afeta as integrações: elas não dependem da senha.