Guias
Autenticação
Como obter e usar o token de acesso da API Consultiva, e como identificar a empresa.
A API Consultiva usa duas informações distintas:
| O quê | Para quê | Onde vai |
|---|---|---|
| Token de acesso (chave da API) | autenticar o chamador | header Authorization: Bearer {token} |
Empresa (empresa ou cnpj) | dizer de qual loja vêm os dados | query string da requisição |
Token de acesso (Bearer)
A autenticação é feita por Bearer Token no cabeçalho da requisição GET:
Authorization: Bearer XXXyyyXXXyXXXXXXXXXXyXXXyXXXyXXXComo obter o token
O token é gerado dentro do sistema ssOtica:
- O administrador acessa Cadastro › Usuários.
- No perfil do usuário é exibido o código de acesso (chave da API).
- Esse código é o token a ser usado no header
Authorization: Bearer.
Requisitos do token
O código de acesso só aparece para usuários com perfil de administrador e que tenham acesso à empresa contratante da API. A empresa precisa ter o acesso via API contratado — caso contrário as consultas retornam erro de acesso.
Identificação da empresa (empresa / cnpj)
Cada consulta precisa indicar a empresa-alvo, por um destes parâmetros de query:
empresa— o Código da Licença (chave de contrato). Ele é enviado por e-mail após a contratação e também aparece no painel de informações do sistema ssOtica, como "Código da Licença".cnpj— o CNPJ da empresa (com ou sem máscara).
A busca é sempre restrita à rede do usuário do token. Informe ao menos um dos dois.
curl -G https://ssotica-dev.ipe.digital/api/v1/integracoes/clientes \
-H "Authorization: Bearer {seu_token}" \
--data-urlencode "empresa=XXXX-XXXX"
# ou
curl -G https://ssotica-dev.ipe.digital/api/v1/integracoes/clientes \
-H "Authorization: Bearer {seu_token}" \
--data-urlencode "cnpj=12345678000199"Erros de autenticação
- Token ausente/ inválido →
401com corpo{ "error": "Unauthenticated." }. (No playground "Try it" desta documentação, o ssOtica redireciona para o login quando o token não é aceito; o proxy converte isso em um401— gere um token novo e tente de novo.) - Empresa não encontrada →
EMPRESA_NAO_ENCONTRADA. Sem acesso via API contratado →ERRO_INTERNO("Acesso via API não contratado..."). Veja Conceitos.
Contratação
Para contratar a API, fale com o time de Atendimento pelo chat do sistema ssOtica.