Skip to main content
Toda requisição para a API da Salvy precisa de uma chave de API. Ela identifica sua empresa e autoriza o acesso aos recursos da plataforma.

​
Acessando a página

Você pode criar, listar e revogar chaves a qualquer momento na página de API & Webhooks, disponível em Configurações > Funcionalidades, ou diretamente em app.salvy.com.br/settings/api.

​
Criando uma chave

  1. Acesse a página de API & Webhooks.
  2. Clique em Criar chave de API.
  3. Selecione o ambiente da chave (Sandbox ou Produção) no seletor exibido acima do campo de nome. Veja Ambientes para entender a diferença.
  4. Dê um nome (opcional) à chave para identificá-la depois, por exemplo o sistema ou a finalidade em que ela será usada.
  5. Clique em Criar chave.
A chave é exibida apenas uma vez. Copie e guarde-a em um local seguro antes de fechar a janela.
Após copiar a chave, use-a no cabeçalho Authorization das suas requisições:
Consulte a Introdução para mais detalhes sobre autenticação.

​
Revogando uma chave

Para revogar uma chave, clique no ícone de lixeira na coluna Ações e confirme a ação.
A revogação é imediata e não pode ser desfeita. Qualquer sistema que esteja utilizando a chave deixará de acessar a API assim que a revogação for confirmada.
Chaves revogadas continuam visíveis na tabela com o status Revogada, junto com a data e o usuário responsável pela revogação, para fins de auditoria.

​
Boas práticas

  • Crie uma chave separada para cada sistema ou finalidade (como produção, homologação ou integrações diferentes). Isso facilita o rastreamento e a revogação quando necessário.
  • A Salvy tem os ambientes sandbox e produção, definidos pela chave utilizada. Use chaves de sandbox para desenvolvimento e testes. Entenda a diferença em Ambientes.
  • Nunca compartilhe chaves em repositórios públicos, e-mails ou mensagens. Armazene-as em um cofre de segredos.
  • Revogue imediatamente qualquer chave que possa ter sido exposta e crie uma nova em seu lugar.
  • Utilize nomes descritivos ao criar chaves para facilitar a identificação posterior.

​
Chaves de organização

Chaves de organização autenticam como a sua organização inteira, e não como uma única empresa. Com uma chave de organização, uma mesma integração alcança todas as empresas da sua organização, sem precisar manter uma chave por empresa.

​
Limitações atuais

Chaves de organização são somente leitura. Elas atendem apenas requisições de leitura (GET). Operações de escrita (POST, PUT, PATCH, DELETE) são bloqueadas e retornam 403 Forbidden com a mensagem “Organization API keys cannot perform this operation yet”. Para escrever, use uma chave de empresa — o suporte a mutações com chave de organização será adicionado no futuro.
  • Apenas produção. Chaves de organização existem somente no ambiente de produção (prefixo salvy_org_prod_). Ainda não há sandbox para chaves de organização.
  • Apenas na v3. Funcionam apenas na versão 3 da API (/api/v3/). Em versões anteriores, utilize chaves de empresa.

​
Chave de empresa ou de organização?

Os endpoints passam a considerar todas as empresas da organização. Por exemplo, uma listagem retorna os recursos de todas as empresas de uma só vez — você não informa a empresa a cada requisição.

​
Criando uma chave de organização

Apenas administradores da organização têm acesso a esta página.
  1. Acesse Configurações da organização > API.
  2. Clique em Criar chave de API.
  3. Dê um nome (opcional) à chave para identificá-la depois, por exemplo o sistema ou a finalidade em que ela será usada.
  4. Selecione os escopos que a chave poderá utilizar.
  5. Clique em Criar chave.
A chave é exibida apenas uma vez. Copie e guarde-a em um local seguro antes de fechar a janela.
Chaves de organização são criadas no ambiente de produção (prefixo salvy_org_prod_). Use-a no cabeçalho Authorization das suas requisições:

​
Revogando uma chave

Para revogar uma chave, clique no ícone de lixeira na coluna Ações e confirme a ação.
A revogação é imediata e não pode ser desfeita. Qualquer sistema que esteja utilizando a chave deixará de acessar a API assim que a revogação for confirmada.
Chaves revogadas continuam visíveis na tabela com o status Revogada, junto com a data e o usuário responsável pela revogação, para fins de auditoria.