Integrações via API
Crie usuários de API, autentique via OAuth2 e consuma os endpoints externos com cobertura para vendas, produtos, serviços, clientes, fornecedores e estoque.
Visão geral
O recurso de API está disponível no plano Premium. A gestão fica em Administração → Usuários de API, onde você cria credenciais exclusivas para ERPs, automações, hubs de integração e parceiros externos.
- Os usuários de API autenticam pelo endpoint /connect/token.
- Esses usuários nascem como administradores técnicos do cliente, com acesso aos endpoints externos autorizados pela API.
- A autenticação não exige TOTP para usuários de API, mas a senha continua seguindo a política de segurança da plataforma.
- Você pode inativar, excluir ou redefinir a senha a qualquer momento pela tela de gestão.
- As integrações externas usam o client_id dedicado stoxis-external-api, separado do aplicativo web.
Recurso Premium: a funcionalidade Acesso via API é liberada somente para clientes com o recurso API_ACCESS ativo.
Fluxo recomendado
1
Crie um usuário de API por integração
Em Administração → Usuários de API, clique em Novo Usuário de API, defina um nome de usuário único, e-mail técnico e uma senha forte.
2
Gere o access token via OAuth2 Password Grant
Envie um POST para https://api.stoxis.com.br/connect/token com Content-Type: application/x-www-form-urlencoded e os parâmetros descritos abaixo.
3
Consuma os endpoints externos
Use o token retornado no header Authorization: Bearer <access_token> ao chamar a base https://api.stoxis.com.br/api/v1/external.
4
Renove a sessão quando necessário
Se solicitar offline_access, a API também retornará um refresh_token para renovação sem reenviar usuário e senha.
Parâmetros do token
| Campo | Obrigatório | Descrição |
|---|---|---|
| grant_type | Sim | Use sempre password para o primeiro token e refresh_token na renovação. |
| client_id | Sim | Valor fixo: stoxis-external-api. |
| username | Sim | Nome de usuário definido na criação do usuário de API. |
| password | Sim | Senha atual do usuário de API. |
| scope | Recomendado | Use openid profile email roles offline_access para habilitar identity token e refresh token. |
| refresh_token | Na renovação | Token retornado anteriormente quando o escopo inclui offline_access. |
Exemplo de autenticação
Exemplo com curl para obter o primeiro access token:
curl --request POST 'https://api.stoxis.com.br/connect/token' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=password' --data-urlencode 'client_id=stoxis-external-api' --data-urlencode 'username=erp-parceiro' --data-urlencode 'password=SuaSenha@123' --data-urlencode 'scope=openid profile email roles offline_access'Exemplo de consumo de um endpoint externo com o token retornado:
curl --request GET 'https://api.stoxis.com.br/api/v1/external/products' --header 'Authorization: Bearer SEU_ACCESS_TOKEN'Multi-loja: se a integração precisar operar em uma loja específica, envie também o header X-Store-Id com o identificador da filial desejada.
Renovando com refresh token
Quando o access token expirar, renove a sessão com o refresh token retornado na autenticação inicial:
curl --request POST 'https://api.stoxis.com.br/connect/token' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=refresh_token' --data-urlencode 'client_id=stoxis-external-api' --data-urlencode 'refresh_token=SEU_REFRESH_TOKEN'Importante: se a senha do usuário de API for redefinida ou o usuário for inativado/excluído, o integrador deve gerar novas credenciais e interromper o uso dos tokens antigos.
Collection completa de endpoints
Em produção, utilize o manual e a collection oficial para testar e integrar. A collection abaixo já inclui autenticação OAuth2, variáveis de ambiente e exemplos prontos para todos os endpoints externos.
Baixar collection
Compatível com Postman e importável no Insomnia.
Inclui exemplos para
- OAuth2 password grant e refresh token.
- Produtos, serviços, clientes e fornecedores.
- Estoque, contas financeiras e vendas.
- Headers opcionais como X-Store-Id para operação por filial.
| Grupo | Base | Operações incluídas |
|---|---|---|
| OAuth2 | /connect/token | Geração de access token e renovação com refresh token. |
| Produtos | /api/v1/external/products | CRUD completo com filtros de paginação. |
| Serviços | /api/v1/external/services | CRUD completo com filtros de paginação. |
| Clientes | /api/v1/external/clients | CRUD completo com payload de pessoa, contatos e endereço. |
| Fornecedores | /api/v1/external/suppliers | CRUD completo com dados comerciais e pessoa vinculada. |
| Estoque | /api/v1/external/inventory | Movimentações, ajustes manuais e alertas de estoque mínimo. |
| Financeiro | /api/v1/external/financial-accounts | Listagem, criação, edição, pagamento e exclusão. |
| Vendas | /api/v1/external/sales | Listagem, consulta, criação de venda e cancelamento. |
Boas práticas
- Crie um usuário por parceiro para facilitar rotação de senha e rastreabilidade.
- Não reutilize credenciais de pessoas da equipe em integrações automáticas.
- Armazene o refresh token em um cofre seguro e aplique rotação periódica da senha técnica.
- Se uma integração sair de operação, inative ou exclua o usuário imediatamente.