IA2S

Autenticação

Cada requisição leva o token no cabeçalho Authorization. O token começa com erp_. O token pessoal pertence a uma pessoa e vale para todos os escritórios dela. O token de escritório é gerado por um escritório e age só nele (veja a seção sobre o token de escritório, abaixo).

Authorization: Bearer SEU_TOKEN

O escritório vai no caminho

Os endpoints ficam em https://developer.jur.ia2s.com.br/api/v1/{escritorio}, com o código do escritório, de 5 dígitos, como em /api/v1/10345/clientes. O GET /api/v1/eu mostra em que escritórios o token vale agora, com o código de cada um. Ele e o /api/v1/openapi.json são os únicos sem código; só o openapi.json responde sem token.

Integrações

As rotas da área Integração usam o token do escritório, gerado em Administração → API, com a permissão de cada rota. O token define o escritório, então o caminho não leva o código.

Token de escritório nas operações da API

O token do escritório também usa as rotas /api/v1/{código}/... desta referência, só no escritório dele e nas operações marcadas ao gerá-lo. Nelas, age como quem o gerou: com as permissões dessa pessoa no momento, conferidas a cada requisição, e o log registra a pessoa e o token.

Quando o token é recusado

Tudo é conferido a cada requisição: o que mudou vale na seguinte.

  • Sem token, token desconhecido, revogado ou expirado: 401 TOKEN_INVALIDO, em qualquer escritório.
  • Código de um escritório em que a pessoa não é membro ativo (inclusive se foi desativada nele), ou que não existe: 404 ESCRITORIO_NAO_ENCONTRADO.
  • Pessoa sem a permissão "Usar a API" no escritório: 403 SEM_PERMISSAO.
  • Token bloqueado pela administração do escritório: 403 TOKEN_BLOQUEADO. O bloqueio é só daquele escritório: nos outros, o token continua valendo.
  • Mais de 120 requisições no minuto, somando todos os escritórios: 429 LIMITE_TOKEN.

Token de escritório em operação não marcada: 403 TOKEN_SEM_ESCOPO; com o código de outro escritório: 404 ESCRITORIO_NAO_ENCONTRADO; quem o gerou não está mais ativo no escritório: 403 TOKEN_AUTOR_INATIVO. Revogue o token em Administração → API para cortar o acesso.

Trate o token como uma senha: fora de URLs, de código versionado e de mensagens.