Pular para o conteúdo principal

API Keys (API pública)

🛂 Permissão: api_key.manage 🔒 Plano: requer api_enabled no plano contratado. Limite de RPM por api_rate_limit_rpm. 📍 Caminho: Configurações → API Keys

A 365 Vendas expõe uma API REST pública para integração com ERPs, sistemas legados, BI e automações. O acesso é autenticado por API Keys, geradas no painel.

O que dá para fazer pela API​

Endpoints típicos disponíveis:

  • Produtos — listar, criar, atualizar, alterar estoque.
  • Categorias — CRUD.
  • Clientes — CRUD, busca por CPF/CNPJ.
  • Pedidos — listar, criar, atualizar status.
  • Tabelas de preço — CRUD.
  • Promoções e cupons — CRUD.
  • Estoque — consultar saldos.

A API segue padrões REST + JSON e retorna códigos HTTP convencionais.

Escopos (scopes)​

Cada API Key tem um conjunto de escopos que determinam o que ela pode fazer:

  • orders.read orders.write
  • products.read products.write
  • customers.read customers.write
  • categories.read categories.write
  • coupons.read coupons.write
  • promotions.read promotions.write
  • price_tables.read price_tables.write

Atribua somente os escopos necessários (princípio do menor privilégio).

Como criar uma chave​

  1. Em Configurações → API Keys, clique em Nova API Key.
  2. Preencha:
    • Nome — identificação interna (ex.: "Integração ERP X", "BI Power BI").
    • Escopos — checkboxes.
    • Validade (opcional) — data de expiração.
  3. Salve.
  4. Copie a chave imediatamente — ela é exibida uma única vez. Depois disso, só o prefix fica visível.
  5. Guarde a chave em um cofre / variável de ambiente do consumidor.

O backend armazena apenas o hash SHA-256 da chave. Se o consumidor perdeu a chave, gere uma nova e revogue a antiga.

Como usar​

Inclua a chave no header Authorization:

GET /api/v1/products HTTP/1.1
Host: api.365vendas.com.br
Authorization: Bearer sk_live_abc1234...
Content-Type: application/json

A 365 Vendas identifica o tenant pela chave — não é necessário enviar tenant_id.

Rate limit​

Cada plano tem um limite de requests por minuto (api_rate_limit_rpm). Quando atingido, a API responde 429 Too Many Requests com Retry-After.

  • Plano básico: tipicamente 60 RPM.
  • Planos superiores: 300+ RPM.

Implemente retry com backoff no consumidor.

Monitorando o uso​

A listagem de API Keys mostra:

  • Last used at — última requisição.
  • Status — ativa / expirada / inativa.

Para detalhes de uso, consulte os logs de auditoria (peça ao suporte) ou conecte um Webhook (Webhooks).

Revogando uma chave​

Em Configurações → API Keys, clique em Desativar ou Excluir. Após desativar, próximas requisições retornam 401 Unauthorized.

Boas práticas​

  • Uma chave por integração — facilita revogar uma sem afetar as outras.
  • Defina expiração (90 dias) e gere periodicamente — reduz dano em vazamento.
  • Use escopo read apenas para integrações de leitura (BI, dashboards).
  • Não exponha chaves no front-end (browser) — APIs públicas devem ser chamadas via servidor backend.
  • Em caso de suspeita de vazamento, revogue imediatamente e gere nova.

Referência da API​

A especificação OpenAPI completa está disponível em:

https://api.365vendas.com.br/docs       # Swagger UI
https://api.365vendas.com.br/openapi.json

Use a especificação para gerar SDKs em qualquer linguagem (openapi-generator, swagger-codegen).