Chaves de API e escopos

A API REST da Ringhum permite que seus próprios sistemas trabalhem com seu workspace: listar chamadas e transcrições, criar assistentes, agendar compromissos, gerenciar contatos, fazer chamadas ativas e muito mais. Cada requisição é autenticada com uma chave de API que pertence a um workspace. Este artigo aborda a criação de chaves e as convenções compartilhadas por todos os endpoints. A referência completa dos endpoints está em /docs.

Quem pode gerenciar chaves

A API está disponível em todos os planos. O que uma chave pode fazer ainda é limitado pelo seu plano: por exemplo, criar um assistente além do limite do seu plano retorna um erro.

Criar uma chave de API

1. Abra Desenvolvedores na barra lateral.
2. No card Chaves de API, clique em Criar chave.
3. Digite um Nome da chave que indique onde a chave é usada, por exemplo "Servidor de produção".
4. Em Escopos, marque leitura, gravação ou ambos.
5. Clique em Criar chave.
6. Copie a chave da caixa verde e guarde-a em um local seguro, como o cofre de segredos do seu servidor. Clique em Concluído.

Importante: A chave é exibida apenas uma vez. A Ringhum armazena apenas uma impressão digital dela, portanto não pode ser mostrada novamente. Se você a perder, crie uma nova chave e revogue a antiga.

As chaves começam com ck_live_. A tabela Chaves de API mostra o nome de cada chave, os primeiros caracteres dela, seus escopos, quando foi usada pela última vez e se está Ativa ou Revogada.

Escopos

Toda chave pode chamar os endpoints que apenas leem dados. Endpoints que criam, alteram ou excluem algo precisam do escopo de gravação. Exemplos são fazer uma chamada, enviar uma mensagem, agendar um compromisso ou atualizar um assistente. A referência em /docs marca esses endpoints. Uma chave sem gravação recebe um erro 403 neles.

Dê a cada sistema o menor acesso necessário. Um painel de relatórios precisa apenas de leitura.

Revogar uma chave

1. Em Desenvolvedores, encontre a chave na tabela Chaves de API.
2. Clique em Revogar e confirme.

Requisições que usam a chave falham imediatamente com 401. Chaves revogadas permanecem na lista, marcadas como Revogada, para que você possa ver o histórico. Uma chave não pode ser editada: para alterar seus escopos, crie uma nova chave e revogue a antiga.

Fazendo requisições

• URL base: https://ringhum.com/api/v1
• Autenticação: envie a chave como um Bearer token: Authorization: Bearer ck_live_…
• Formato: JSON na entrada e na saída. Envie Content-Type: application/json com um corpo.
• Horários são ISO 8601 em UTC. Números de telefone são E.164, por exemplo +14155550132. Ids são inteiros.
• Atualizações usam PATCH apenas com os campos que você quer alterar.
• Toda resposta carrega um cabeçalho X-Request-Id. Inclua-o ao contatar o suporte.

curl "https://ringhum.com/api/v1/calls?per_page=10" \
  -H "Authorization: Bearer ck_live_…"

Para verificar a qual workspace uma chave pertence, chame GET /me.

Respostas e paginação

Um único objeto retorna como {"data": {…}}. Listas paginadas retornam com um objeto meta:

{
  "data": [ … ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 87,
    "next_page_url": "https://ringhum.com/api/v1/calls?page=2",
    "prev_page_url": null
  }
}

Use page e per_page para navegar pelos resultados. per_page tem padrão 25 e pode ser no máximo 100.

Erros

Toda falha tem o mesmo formato, com um type estável que você pode verificar no seu código:

{
  "error": {
    "type": "validation_error",
    "message": "The to field format is invalid.",
    "errors": { "to": ["Use E.164 format, e.g. +15551234567."] }
  }
}

Limites de taxa

Você pode fazer 120 requisições por minuto. As respostas incluem os cabeçalhos X-RateLimit-Limit e X-RateLimit-Remaining. Quando você ultrapassa o limite, recebe 429 com um cabeçalho Retry-After indicando os segundos a esperar.

Dica: Não faça polling dos resultados de chamadas. Adicione um webhook para call.ended e a Ringhum envia o resumo e a transcrição para você quando a chamada terminar. Veja Webhooks.

Perguntas comuns

Existe uma especificação legível por máquina? Sim. A descrição OpenAPI 3.1 está em /api/v1/openapi.json e não precisa de chave. Você pode gerar um cliente a partir dela.

Uma chave para de funcionar se a pessoa que a criou sair? Não. As chaves pertencem ao workspace e continuam funcionando até serem revogadas. Revogue chaves em que você não confia mais, especialmente quando alguém que tinha acesso sai.

Posso usar a API a partir de uma página web? Não. Qualquer pessoa que abrir a página poderia ler a chave. Chame a API a partir do seu servidor.