LunaDocs

Carregando a busca...

EnglishEntrar no console
Nesta página

Chaves

Usar com IA

Criar, listar e revogar as credenciais que autenticam as suas chamadas.

Listar chaves

GET/v1/api-keys

As chaves deste cliente, com escopos, perfil, status (active, revoked ou expired), data de criação, último uso, revogação e o que a conta pode fazer com cada uma (allowedActions).

Autenticação
Chave de API
Escopo exigido
keys:read

Parâmetros de consulta

  • kindstringopcional
    Valores: integration session elevation

Respostas

200Sucesso.

Sem campos.

400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Criar uma chave

POST/v1/api-keys

Cunha uma chave nova e devolve o segredo uma única vez. Guarde-o no momento em que recebe, porque não há rota que o devolva depois.

Autenticação
Chave de API
Escopo exigido
keys:write

Corpo da requisição

application/json · obrigatório

  • labelstringopcional
    1 a 120 caracteres
  • scopesarray<string>opcional
    O que a chave pode fazer, escopo por escopo. Mande scopes ou profile, e nunca os dois: a lista de escopos que cada perfil concede está em GET /v1/api-keys/profiles.no mínimo 1 itens
  • profilestringopcional
    Um perfil pronto no lugar de scopes: agent (atendimento), full (integração completa) ou read_only (somente leitura). A chave nasce com os escopos que o perfil concede no momento da criação, e a lista deles está em GET /v1/api-keys/profiles.Valores: agent full read_only
  • expiresAtstring (date-time)opcional
  • modestringopcional
    live (o padrão) é a chave de sempre. test cria uma chave do modo de teste: POST /v1/messages com ela NÃO vai à Meta, não usa número seu e não conta na capacidade do plano; a Luna devolve ao seu webhook eventos simulados, assinados e com test: true. Uma chave de teste só usa POST /v1/messages e POST /v1/test-mode/inbound-messages, e não aceita externalId. Não dá para mudar depois: crie outra.Valores: live test
  • externalIdstringopcional
    O seu identificador para o cliente a que esta chave pertence (1 a 128 caracteres), o mesmo externalId do link de conexão e dos números. Com ele, a chave é de UM cliente seu: só lê e envia pelos números com este externalId (inclusive os conectados depois), só cria link com ele, e não lista nem cria endpoints de webhook nem chaves. Sem ele, a chave é da conta inteira. Não dá para mudar depois: crie outra.1 a 128 caracteres

Respostas

201Criado.
  • idstring (uuid)obrigatório
  • labelstring | nullobrigatório
    O nome que você deu à chave, para reconhecê-la na lista.
  • kindstringobrigatório
    integration para chave sua, session para uma sessão do console. elevation é valor histórico, de credenciais emitidas até 10/08/2026, e nenhuma chave nova nasce com ele.Valores: integration session elevation
  • scopesarray<string>obrigatório
    O que esta chave pode fazer. Uma rota fora deste conjunto responde 403.
  • modestringobrigatório
    live é a chave de sempre. test é a chave do modo de teste: ela envia mensagem simulada, sem ir à Meta, e só usa POST /v1/messages e POST /v1/test-mode/inbound-messages. Não muda depois da criação. O guia Modo de teste explica.Valores: live test
  • externalIdstring | nullobrigatório
    O cliente seu a que a chave se restringe, ou nulo na chave da conta. Com valor, a chave só lê e envia pelos números com este externalId, só cria link de conexão com ele, só vê templates e contas das WABAs desses números, e não lista nem cria endpoints de webhook nem chaves. Não muda depois da criação.
  • createdAtstringobrigatório
  • expiresAtstring | nullobrigatório
    Nulo em chave de integração: ela vale até ser revogada.
  • revokedAtstring | nullobrigatório
  • lastUsedAtstring | nullobrigatório
    O último uso registrado, para identificar chave esquecida.
  • statusstringobrigatório
    active: a chave vale. revoked: foi revogada (revokedAt diz quando). expired: passou de expiresAt sem ser revogada. Revogada vale mais que expirada. É a API quem decide, e o seu código não precisa comparar datas.Valores: active revoked expired
  • profilestring | nullobrigatório
    O perfil escolhido ao criar a chave (profile em POST /v1/api-keys), ou nulo quando os escopos foram escolhidos um a um e nas chaves anteriores a este campo. É só o rótulo: o que a chave pode fazer é scopes.Valores: agent full read_only
  • allowedActionsarray<string>obrigatório
    O que a sua conta pode fazer com a chave agora: revoke (POST /v1/api-keys/{id}/revoke), só em chave de integração que ainda vale. Mostre o botão quando o verbo está na lista. Não leva em conta os escopos da chave que perguntou.
  • secretstringobrigatório
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Teste grátis terminadoJSON
{
  "error": "trial_expired",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}
Conta bloqueada pela HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
Tipo de conteúdo não lidoJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Listar os escopos que uma chave pode ter

GET/v1/api-keys/scopes

Os escopos que uma chave de integração pode receber, cada um com o nome em português, o que ele permite e se dá um poder que exige cuidado.

Autenticação
Chave de API
Escopo exigido
keys:read

Respostas

200Sucesso.
  • dataarray<object>obrigatório
  • data[].scopestringobrigatório
    O nome do escopo, o que vai em scopes ao criar a chave.
  • data[].labelstringobrigatório
    O nome da permissão em português.
  • data[].summarystringobrigatório
    O que a permissão deixa fazer.
  • data[].sensitivebooleanobrigatório
    true quando a permissão dá um poder que exige cuidado (criar chaves, redirecionar o webhook).
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Listar os perfis de chave

GET/v1/api-keys/profiles

Os perfis prontos de chave (agent, full e read_only) e os escopos que cada um concede. Em POST /v1/api-keys, profile vale no lugar de scopes.

Autenticação
Chave de API
Escopo exigido
keys:read

Respostas

200Sucesso.
  • dataarray<object>obrigatório
  • data[].idstringobrigatório
    O que vai em profile ao criar a chave.Valores: agent full read_only
  • data[].labelstringobrigatório
  • data[].summarystringobrigatório
    O que a chave deste perfil permite, em uma frase.
  • data[].scopesarray<string>obrigatório
    Os escopos que o perfil concede hoje.
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Consultar uma chave

GET/v1/api-keys/{id}

Os metadados de uma chave. O segredo não volta, pelo mesmo motivo descrito na listagem.

Autenticação
Chave de API
Escopo exigido
keys:read

Parâmetros de caminho

  • idstring (uuid)obrigatório

Respostas

200Sucesso.
  • idstring (uuid)obrigatório
  • labelstring | nullobrigatório
    O nome que você deu à chave, para reconhecê-la na lista.
  • kindstringobrigatório
    integration para chave sua, session para uma sessão do console. elevation é valor histórico, de credenciais emitidas até 10/08/2026, e nenhuma chave nova nasce com ele.Valores: integration session elevation
  • scopesarray<string>obrigatório
    O que esta chave pode fazer. Uma rota fora deste conjunto responde 403.
  • modestringobrigatório
    live é a chave de sempre. test é a chave do modo de teste: ela envia mensagem simulada, sem ir à Meta, e só usa POST /v1/messages e POST /v1/test-mode/inbound-messages. Não muda depois da criação. O guia Modo de teste explica.Valores: live test
  • externalIdstring | nullobrigatório
    O cliente seu a que a chave se restringe, ou nulo na chave da conta. Com valor, a chave só lê e envia pelos números com este externalId, só cria link de conexão com ele, só vê templates e contas das WABAs desses números, e não lista nem cria endpoints de webhook nem chaves. Não muda depois da criação.
  • createdAtstringobrigatório
  • expiresAtstring | nullobrigatório
    Nulo em chave de integração: ela vale até ser revogada.
  • revokedAtstring | nullobrigatório
  • lastUsedAtstring | nullobrigatório
    O último uso registrado, para identificar chave esquecida.
  • statusstringobrigatório
    active: a chave vale. revoked: foi revogada (revokedAt diz quando). expired: passou de expiresAt sem ser revogada. Revogada vale mais que expirada. É a API quem decide, e o seu código não precisa comparar datas.Valores: active revoked expired
  • profilestring | nullobrigatório
    O perfil escolhido ao criar a chave (profile em POST /v1/api-keys), ou nulo quando os escopos foram escolhidos um a um e nas chaves anteriores a este campo. É só o rótulo: o que a chave pode fazer é scopes.Valores: agent full read_only
  • allowedActionsarray<string>obrigatório
    O que a sua conta pode fazer com a chave agora: revoke (POST /v1/api-keys/{id}/revoke), só em chave de integração que ainda vale. Mostre o botão quando o verbo está na lista. Não leva em conta os escopos da chave que perguntou.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Revogar uma chave

POST/v1/api-keys/{id}/revoke

Invalida a chave imediatamente. A operação é idempotente, então revogar de novo devolve o mesmo resultado, sem erro.

Autenticação
Chave de API
Escopo exigido
keys:write

Parâmetros de caminho

  • idstring (uuid)obrigatório

Respostas

200Sucesso.
  • idstring (uuid)obrigatório
  • labelstring | nullobrigatório
    O nome que você deu à chave, para reconhecê-la na lista.
  • kindstringobrigatório
    integration para chave sua, session para uma sessão do console. elevation é valor histórico, de credenciais emitidas até 10/08/2026, e nenhuma chave nova nasce com ele.Valores: integration session elevation
  • scopesarray<string>obrigatório
    O que esta chave pode fazer. Uma rota fora deste conjunto responde 403.
  • modestringobrigatório
    live é a chave de sempre. test é a chave do modo de teste: ela envia mensagem simulada, sem ir à Meta, e só usa POST /v1/messages e POST /v1/test-mode/inbound-messages. Não muda depois da criação. O guia Modo de teste explica.Valores: live test
  • externalIdstring | nullobrigatório
    O cliente seu a que a chave se restringe, ou nulo na chave da conta. Com valor, a chave só lê e envia pelos números com este externalId, só cria link de conexão com ele, só vê templates e contas das WABAs desses números, e não lista nem cria endpoints de webhook nem chaves. Não muda depois da criação.
  • createdAtstringobrigatório
  • expiresAtstring | nullobrigatório
    Nulo em chave de integração: ela vale até ser revogada.
  • revokedAtstring | nullobrigatório
  • lastUsedAtstring | nullobrigatório
    O último uso registrado, para identificar chave esquecida.
  • statusstringobrigatório
    active: a chave vale. revoked: foi revogada (revokedAt diz quando). expired: passou de expiresAt sem ser revogada. Revogada vale mais que expirada. É a API quem decide, e o seu código não precisa comparar datas.Valores: active revoked expired
  • profilestring | nullobrigatório
    O perfil escolhido ao criar a chave (profile em POST /v1/api-keys), ou nulo quando os escopos foram escolhidos um a um e nas chaves anteriores a este campo. É só o rótulo: o que a chave pode fazer é scopes.Valores: agent full read_only
  • allowedActionsarray<string>obrigatório
    O que a sua conta pode fazer com a chave agora: revoke (POST /v1/api-keys/{id}/revoke), só em chave de integração que ainda vale. Mostre o botão quando o verbo está na lista. Não leva em conta os escopos da chave que perguntou.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}