Chave de API: integrar outro sistema ao seu estúdio

O que é

A chave de API deixa outro sistema (um ERP, uma planilha automática, um site, um aplicativo seu) consultar e gravar dados do seu estúdio sem ninguém digitar nada. Cada chave age como um usuário do estúdio: ela pode exatamente o que esse usuário pode, e nada além.

Quando usar

Um sistema de gestão precisa ler as vendas do dia para a contabilidade.
Um site ou aplicativo próprio precisa cadastrar clientes ou consultar o catálogo.
Uma automação precisa lançar despesas ou consultar contas a receber.

Antes de começar

Só quem administra o estúdio (acesso total, ou permissão para editar Perfis e Usuários) cria, edita e revoga chaves. Se você não conseguir criar uma chave, peça para o dono do studio liberar o seu acesso em Acessos → Perfis.

O recomendado é criar antes um usuário só para a integração, com um perfil que libere apenas as telas que o outro sistema precisa usar. A chave herda as permissões desse usuário.

Passo a passo

Passo 1 — Abrir a aba API Key

Em Configurações → Empresa, abra a aba API Key. Ela lista as chaves já criadas, com o usuário de cada uma, os IPs permitidos, a Validade e o Último uso.

Aba API Key com a lista de chaves

Passo 2 — Criar a chave

Clique em Nova chave, preencha o Nome e escolha o Usuário. Em IPs permitidos, coloque um IP ou uma faixa por linha para aceitar chamadas só desses endereços (vazio aceita qualquer IP). Em Validade, escolha Nunca expira ou Expira em uma data: a chave vale até o fim desse dia. Clique em Criar chave e copie a chave pelo botão de copiar. Ela não é exibida de novo.

O outro sistema envia a chave em toda chamada, no cabeçalho Authorization, assim: Authorization: Bearer hk_... (a chave inteira no lugar de hk_...).

Formulário de nova chave de API preenchido

Passo 3 — Revogar uma chave

Na lista, clique no ícone de lixeira da chave e confirme em Revogar. O sistema que usava a chave perde o acesso em até 30 segundos. Para mudar o nome, os IPs ou a validade, use o ícone de lápis.

Confirmação para revogar uma chave de API

O que acontece depois

Tudo o que o outro sistema altera com a chave aparece na Auditoria com a origem Chave de API, em nome do usuário da chave.
A chave para de funcionar sozinha quando a validade vence ou quando o usuário dela é desativado no estúdio. Na lista, ela aparece como Expirada ou Usuário inativo.
Uma chave nunca dá acesso a outra empresa, mesmo que o usuário dela também trabalhe em outra.

Erros comuns e dúvidas

P: A chave pode fazer tudo no sistema? R: Não. Ela tem as permissões do usuário dela, só neste estúdio. Algumas áreas nunca aceitam chave, mesmo de um usuário com acesso total: login e troca de empresa, a própria tela de chaves, a gestão de usuários e convites, a Heya, o suporte, os dashboards, as configurações gerais da Empresa (logo, horários, feriados, domínio, e-mail dos relatórios) e as telas da plataforma. Se você tem várias integrações, crie um usuário para cada uma: na Auditoria, a alteração aparece em nome do usuário da chave.

P: Perdi a chave. Consigo ver de novo? R: Não. O sistema guarda só uma impressão da chave, nunca a chave em si. Revogue a antiga e crie outra.

P: O outro sistema recebe “Este IP não está autorizado a usar esta chave de API.” O que faço? R: O IP de onde ele chama não está em IPs permitidos. Edite a chave e acrescente o IP, ou deixe a lista vazia para aceitar qualquer IP.

P: O outro sistema recebe “Esta rota não pode ser usada com chave de API.” Por quê? R: Ele está chamando uma das áreas que não aceitam chave (veja a primeira pergunta). Essas operações precisam ser feitas por uma pessoa, na tela.

P: Posso trocar o usuário de uma chave? R: Não. Revogue a chave e crie outra com o novo usuário.

P: A lista de usuários da nova chave está vazia. Por quê? R: Usuários da equipe da plataforma não podem ter chave de API e não aparecem na lista. Cadastre um usuário do próprio estúdio (de preferência um só para a integração) e crie a chave para ele.