Segurança da API — Documentação Complementar

1. Introdução

Esta página descreve como a API do ERP Spalla protege o acesso aos dados: cada integração alcança apenas o que foi liberado para ela, e a documentação detalhada de uma integração só aparece para quem tem o token correspondente. A página também mostra como consultar o manual da sua integração.

O conteúdo aqui é introdutório e não substitui o dicionário oficial. Os objetos liberados, os campos e as permissões de cada integração são os do dicionário oficial da sua instância (seção 2), que é a fonte autoritativa.

2. Onde encontrar o dicionário oficial da sua API

Cada empresa que opera o ERP Spalla publica o seu próprio manual on-line em um endereço próprio. Abra no navegador o endereço no formato abaixo, trocando os campos entre < > pelos valores da sua instância:

https://<host>:<porta>/root/ajuda

O manual abre a documentação pública completa. A documentação detalhada da sua integração é liberada ao informar o seu userToken na própria página (seção 7).

3. Acesso por token

Cada integração se identifica com um userToken próprio, fornecido pela equipe responsável pelo ERP. O token identifica a integração e define o que ela alcança na API.

Como o token é criado. O userToken é gerado pelo próprio ERP e inclui sempre um componente aleatório, de modo que cada token é único e imprevisível. Ele é longo o bastante para tornar inviável, na prática, descobri-lo por tentativa e erro — uma busca por força-bruta não é um caminho viável.

• A comunicação com a API é feita por HTTPS.
• O userToken é um dado de acesso da integração: guarde-o protegido, como qualquer credencial.
• Cada integração tem o seu token, e o acesso de uma não interfere no da outra.

4. O que cada token alcança

O acesso de cada token segue o princípio do menor privilégio: a integração alcança apenas os objetos liberados para ela, com as operações — consulta e, quando liberado, gravação — definidas no cadastro de API do ERP. São as mesmas permissões de acesso que o ERP já aplica aos seus usuários.

• Um objeto só aparece para o token que tem esse objeto liberado.
• Um token não alcança objetos fora do seu escopo.
• A liberação dos objetos e das operações é definida na retaguarda do ERP. Para incluir um objeto, peça a revisão do cadastro de API à equipe responsável.

5. Um servidor, várias integrações

Um mesmo servidor e uma mesma rota atendem várias integrações. Cada uma tem o seu token, o seu conjunto de objetos liberados e a sua documentação exclusiva. Trocar o token muda o escopo, e uma integração não enxerga os objetos da outra.

Convenção visual: azul (Retaguarda do ERP) · verde (Via API).

6. Documentação pública e documentação da sua integração

O manual on-line tem duas camadas:

• Documentação pública — aberta a todos, sem token: introdução, endereço de acesso, autenticação, métodos, o Spalla API Toolkit e os tipos de objeto da API.
• Documentação da sua integração — a lista detalhada dos objetos liberados para o seu token, com exemplo de uso e dicionário de dados. Aparece somente depois que você informa o seu userToken.

A documentação pública não expõe os objetos de nenhuma integração: a lista detalhada só é montada com um token válido.

7. Como consultar o manual da sua integração

Para ver a documentação detalhada da sua integração:

1. Abra o manual on-line no navegador (seção 2).
2. Na seção Dicionário, informe o seu userToken no campo e confirme.
3. A página passa a exibir os objetos liberados para a sua integração, com exemplo de uso e dicionário de dados.

Onde aprofundar

A montagem das requisições — endereço, autenticação, métodos e formato dos valores — está na documentação geral da API. Os objetos liberados, os campos e as permissões da sua integração estão no dicionário oficial da sua instância (seção 2), que é a fonte autoritativa.