Conectar seu próprio software com chaves de API

A API pública permite que seu software, ou o do seu desenvolvedor, leia e grave seus registros do Kluvan: produtos, clientes, estoque, relatórios, documentos da Contabilidade, pessoas do RH, CRM, assinaturas e os aplicativos que você tem. Você controla cada chave: o que pode fazer, por quanto tempo e para qual filial.

Antes de começar

• Somente o proprietário pode criar e revogar chaves.
• Uma chave nunca libera um aplicativo que sua organização não tem, e todas as regras do plano, dos aplicativos e das filiais continuam valendo.

Passos

1. Abra Configurações → Acesso de desenvolvedor.
2. Em Nova chave, digite um Nome que você reconheça, por exemplo "Leitor do depósito".
3. Defina Validade em dias (1–365). O padrão é 90.
4. Em Filial, mantenha Todas as filiais ou escolha uma.
5. Em Pode ver, marque cada escopo necessário. Cada um indica Leitura ou Gravação, por exemplo Produtos · Leitura.
6. Marque a frase que confirma sua autorização para o acesso selecionado.
7. Pressione Criar a chave.
8. Copie a chave agora. Ela só aparece esta vez.
9. Forneça a chave ao seu software. Ele a envia no cabeçalho Authorization: Bearer.

Chamar a API

• O endereço é https://api.kluvan.com/v1/public-api. O Guia do desenvolvedor (/developers) mostra exemplos e cada operação com o escopo necessário. OpenAPI 3.1 baixa o contrato completo, com campos das requisições.
• Toda gravação precisa de um Idempotency-Key: um novo UUID por alteração. Se a resposta se perder, envie a mesma requisição com a mesma chave novamente por até 7 dias; ela não será aplicada duas vezes. A mesma chave com uma requisição alterada é recusada.
• Uma alteração em um registro existente também envia a versão atual do registro (v), para que uma cópia antiga nunca sobrescreva uma mais recente.
• Valores são informados na menor unidade da moeda (150.00 é 15000).
• Listas de registros de aplicativos retornam até 50 registros e um valor next; passe-o como after para obter a próxima página.
• Até 120 requisições por minuto por chave. Acima disso, a resposta é 429 com Retry-After. Todo erro contém um código (veja o guia de erros).

Bom saber

• Escopos de gravação alteram registros reais e podem executar ações de aplicativos, com seus efeitos no estoque e na contabilidade. Conceda à chave apenas os escopos necessários.
• Chaves de filial leem apenas os registros da filial. Operações de catálogo, clientes, CRM, RH e assinaturas precisam de uma chave para todas as filiais.
• O Kluvan guarda apenas uma impressão digital (hash) de cada chave. Perdeu uma chave? Revogue-a e crie outra.
• Revogar interrompe uma chave imediatamente. A chave também deixa de funcionar no último dia de validade. Você pode manter até 20 chaves.
• Atividade da API lista cada chamada: horário, operação, chave e status. Corpos de requisições e chaves nunca são registrados.
• A API não oferece faturamento do plano, login, recebimento de pagamentos nem webhooks: não há notificações de saída, então seu software lê as listas necessárias.
• Uma sessão de navegador autenticada não pode chamar esta API, e as chaves para aplicativos assistentes são separadas: veja conectar um aplicativo assistente.