Links de conexão
Um link que o seu cliente abre para conectar o número de WhatsApp dele, sem receber o login do seu console. Um link por cliente seu, amarrado ao externalId que você escolheu.
Listar os links de conexão
GET/v1/onboarding/links
Os links que você criou, do mais recente para o mais antigo, inclusive os revogados. Filtros: externalId (igualdade), q (começo do externalId) e status (open, used, expired ou revoked).
Parâmetros de consulta
qstringopcionalO começo do rótulo do seu cliente: os links cujo externalId começa com este texto, sem diferenciar maiúscula. Use no lugar de externalId quando você só lembra do começo. Combina com os outros filtros.1 a 128 caracteresexternalIdstringopcionalO rótulo que você deu ao seu cliente (externalId): só os links dele. Igualdade exata; um rótulo sem link devolve lista vazia.1 a 128 caracteresstatusstringopcionalSó os links neste estado: open, used, expired ou revoked.Valores:openusedexpiredrevokedlimitintegeropcionalmínimo 1 · máximo 100cursorstringopcionalaté 256 caracteres
Respostas
200Sucesso.
dataarray<object>obrigatóriodata[].idstring (uuid)obrigatóriodata[].externalIdstring | nullobrigatóriodata[].statusstringobrigatórioopen: o cliente ainda pode abrir. used: uma conexão feita por este link já concluiu. expired: passou do prazo sem ser usado. revoked: você revogou, e revokedAt diz quando (vale mais que os outros).Valores:openusedexpiredrevokeddata[].createdAtstringobrigatórioQuando você criou o link.data[].purposestringobrigatórionew: o link conecta um número novo. reconnect: o link renova a autorização de um número que já existe (foi criado com numberId). Links criados antes deste campo existir têm a finalidade deduzida: com número e ainda não usados são reconnect.Valores:newreconnectdata[].revokedAtstring | nullobrigatórioQuando você revogou o link, ou nulo se não foi revogado.data[].lastFailureobject | nullobrigatórioA última tentativa de conexão por este link que não deu certo, ou nulo quando a última tentativa não falhou ou não houve nenhuma. É a mesma regra do evento onboarding.link.failed.data[].lastFailure.stepstring | nullobrigatórioO nome da tela da janela da Meta em que o cliente parou, como o navegador relatou. Nulo quando não foi relatado.data[].lastFailure.reasonstringobrigatórioPor que a última tentativa não deu certo: abandoned, error, failed, country_not_supported ou registration_blocked, os mesmos de onboarding.link.failed. Novos motivos podem aparecer.data[].lastFailure.atstringobrigatórioQuando a tentativa parou.data[].allowedActionsarray<string>obrigatórioO que a sua conta pode fazer com o link agora, só num link aberto: revoke (DELETE /v1/onboarding/links/{id}) e reissue (POST /v1/onboarding/links/{id}/reissue, que gera a url de novo). Não leva em conta os escopos da chave que perguntou.data[].expiresAtstringobrigatóriodata[].usedAtstring | nullobrigatóriodata[].redirectUrlstring | nullobrigatórioPara onde a página do link leva o seu cliente ao terminar, ou nulo se ele fica na página.data[].displayNamestring | nullobrigatórioO nome do seu cliente que a página do link mostra, ou nulo.data[].numberIdstring (uuid) | nullobrigatórioO id do número que resultou da conexão, o mesmo de GET /v1/numbers. Nulo até a Luna registrar o número, e nulo quando a conta foi conectada sem número. Em um link de reconexão (criado com numberId), é o número que o link reconecta, desde a criação.nextCursorstring | nullobrigatórioMande este valor de volta em cursor para pegar a próxima página. Nulo significa fim.
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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"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"
}{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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 um link de conexão para o seu cliente
POST/v1/onboarding/links
Cria um link que o seu cliente abre para conectar o número de WhatsApp dele, sem receber o login do seu console.
Corpo da requisição
externalIdstringopcionalO seu identificador para este cliente, em texto livre de 1 a 128 caracteres. A Luna não o interpreta: ele volta como externalId no link e no número que resultar da conexão.1 a 128 caracteresdisplayNamestringopcionalO nome do seu cliente, em texto livre de 1 a 120 caracteres, que a página do link mostra ("Conectar o WhatsApp de ..."). Serve para o cliente reconhecer de quem é o pedido. É só texto da página: a janela da Meta que abre em seguida mostra o nome da Luna e não pode ser mudada.1 a 120 caracteresredirectUrlstringopcionalPara onde a página do link leva o seu cliente quando a conexão termina (https, até 2048 caracteres). A página acrescenta status (o estado final da conexão) e numberId (o número, quando a Luna já o registrou) na query. Ausente, o cliente fica na página da Luna.até 2048 caracteres · /^https:\/\/[^\s]+$/numberIdstringopcionalO número a reconectar: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Com ele, o link abre a reconexão daquele número em vez de uma conexão nova.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
Respostas
201Criado.
idstring (uuid)obrigatóriourlstringobrigatórioO endereço que você manda ao seu cliente. Ele contém o token, e o token aparece só nesta resposta.expiresAtstringobrigatórioexternalIdstring | nullobrigatórioredirectUrlstring | nullobrigatórioA redirectUrl do pedido, ou nulo.displayNamestring | nullobrigatórioO nome do seu cliente que a página do link mostra, ou nulo.
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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"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"
}{
"error": "connection_not_released",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Esta conta ainda não pode conectar um número: falta confirmar o e-mail do cadastro. Abra o link que enviamos para esse e-mail e tente de novo. A lista faltando mostra o que ainda não foi cumprido.",
"faltando": [
"email_confirmado"
]
}{
"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."
}{
"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."
}{
"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."
}409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
{
"error": "number_capacity_reached",
"message": "Esta conta já tem 20 números ativos, o máximo contratado (20). Para conectar outro, desconecte um número (DELETE /v1/numbers/{id}) ou escreva para contato@lunahia.com.br.",
"capacity": 20,
"activeNumbers": 20
}{
"error": "reconnect_not_applicable",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "A autorização deste número não admite reconexão.",
"credentialStatus": "active"
}415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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 um link de conexão
GET/v1/onboarding/links/{id}
O estado de um link: open, used, expired ou revoked, com a finalidade, a última falha e o que a conta pode fazer com ele.
Parâmetros de caminho
idstring (uuid)obrigatório
Respostas
200Sucesso.
idstring (uuid)obrigatórioexternalIdstring | nullobrigatóriostatusstringobrigatórioopen: o cliente ainda pode abrir. used: uma conexão feita por este link já concluiu. expired: passou do prazo sem ser usado. revoked: você revogou, e revokedAt diz quando (vale mais que os outros).Valores:openusedexpiredrevokedcreatedAtstringobrigatórioQuando você criou o link.purposestringobrigatórionew: o link conecta um número novo. reconnect: o link renova a autorização de um número que já existe (foi criado com numberId). Links criados antes deste campo existir têm a finalidade deduzida: com número e ainda não usados são reconnect.Valores:newreconnectrevokedAtstring | nullobrigatórioQuando você revogou o link, ou nulo se não foi revogado.lastFailureobject | nullobrigatórioA última tentativa de conexão por este link que não deu certo, ou nulo quando a última tentativa não falhou ou não houve nenhuma. É a mesma regra do evento onboarding.link.failed.lastFailure.stepstring | nullobrigatórioO nome da tela da janela da Meta em que o cliente parou, como o navegador relatou. Nulo quando não foi relatado.lastFailure.reasonstringobrigatórioPor que a última tentativa não deu certo: abandoned, error, failed, country_not_supported ou registration_blocked, os mesmos de onboarding.link.failed. Novos motivos podem aparecer.lastFailure.atstringobrigatórioQuando a tentativa parou.allowedActionsarray<string>obrigatórioO que a sua conta pode fazer com o link agora, só num link aberto: revoke (DELETE /v1/onboarding/links/{id}) e reissue (POST /v1/onboarding/links/{id}/reissue, que gera a url de novo). Não leva em conta os escopos da chave que perguntou.expiresAtstringobrigatóriousedAtstring | nullobrigatórioredirectUrlstring | nullobrigatórioPara onde a página do link leva o seu cliente ao terminar, ou nulo se ele fica na página.displayNamestring | nullobrigatórioO nome do seu cliente que a página do link mostra, ou nulo.numberIdstring (uuid) | nullobrigatórioO id do número que resultou da conexão, o mesmo de GET /v1/numbers. Nulo até a Luna registrar o número, e nulo quando a conta foi conectada sem número. Em um link de reconexão (criado com numberId), é o número que o link reconecta, desde a criação.
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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"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"
}{
"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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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 um link de conexão
DELETE/v1/onboarding/links/{id}
Revoga o link. A url deixa de funcionar na hora e passa a responder 404 a quem a abrir, como uma que nunca existiu. Uma conexão que o cliente já tinha começado na janela da Meta não pode mais ser concluída por ela. O link continua na sua lista, com status revoked e revokedAt. Revogar de novo um link já revogado responde 404.
Parâmetros de caminho
idstring (uuid)obrigatório
Respostas
204Sem conteúdo: a operação foi feita e a resposta não tem corpo.
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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"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"
}{
"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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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 vários links de conexão de uma vez
POST/v1/onboarding/links/batch
Cria até 100 links, cada item no mesmo formato de POST /v1/onboarding/links e com as mesmas regras, inclusive a capacidade do plano. Responde 200 com um resultado por item, com a url de cada link criado; um item que falha não derruba os outros.
Corpo da requisição
linksarray<object>obrigatórioDe 1 a 100 links, cada um no mesmo formato do corpo de POST /v1/onboarding/links: externalId, displayName, redirectUrl e numberId, todos opcionais.1 a 100 itenslinks[].externalIdstringopcionalO seu identificador para este cliente, em texto livre de 1 a 128 caracteres. A Luna não o interpreta: ele volta como externalId no link e no número que resultar da conexão.1 a 128 caractereslinks[].displayNamestringopcionalO nome do seu cliente, em texto livre de 1 a 120 caracteres, que a página do link mostra ("Conectar o WhatsApp de ..."). Serve para o cliente reconhecer de quem é o pedido. É só texto da página: a janela da Meta que abre em seguida mostra o nome da Luna e não pode ser mudada.1 a 120 caractereslinks[].redirectUrlstringopcionalPara onde a página do link leva o seu cliente quando a conexão termina (https, até 2048 caracteres). A página acrescenta status (o estado final da conexão) e numberId (o número, quando a Luna já o registrou) na query. Ausente, o cliente fica na página da Luna.até 2048 caracteres · /^https:\/\/[^\s]+$/links[].numberIdstringopcionalO número a reconectar: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Com ele, o link abre a reconexão daquele número em vez de uma conexão nova.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
Respostas
200Sucesso.
resultsarray<object>obrigatórioUm resultado por item de links, na mesma ordem.results[].indexintegerobrigatórioA posição do item em links, a partir de 0.results[].statusintegerobrigatório201 quando o link foi criado; senão o status do erro daquele item.results[].linkobject | nullobrigatórioO link criado, com a url (que aparece só aqui). Nulo quando houve erro.results[].link.idstring (uuid)obrigatórioresults[].link.urlstringobrigatórioO endereço que você manda ao seu cliente. Ele contém o token, e o token aparece só nesta resposta.results[].link.expiresAtstringobrigatórioresults[].link.externalIdstring | nullobrigatórioresults[].link.redirectUrlstring | nullobrigatórioA redirectUrl do pedido, ou nulo.results[].link.displayNamestring | nullobrigatórioO nome do seu cliente que a página do link mostra, ou nulo.results[].errorobject | nullobrigatórioO erro deste item, no mesmo formato de erro da API. Nulo quando o link foi criado.results[].error.errorstringobrigatórioresults[].error.messagestringobrigató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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"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"
}{
"error": "connection_not_released",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Esta conta ainda não pode conectar um número: falta confirmar o e-mail do cadastro. Abra o link que enviamos para esse e-mail e tente de novo. A lista faltando mostra o que ainda não foi cumprido.",
"faltando": [
"email_confirmado"
]
}{
"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."
}{
"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."
}{
"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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Gerar de novo a url de um link de conexão
POST/v1/onboarding/links/{id}/reissue
Gera um token novo para o mesmo link (mesmo id, mesmo rótulo, mesmo prazo): a url antiga deixa de funcionar na hora e a nova aparece só nesta resposta. Só vale para um link aberto; usado, vencido ou revogado responde 409. Use quando o seu cliente perdeu a url, em vez de revogar e criar outro.
Parâmetros de caminho
idstring (uuid)obrigatório
Respostas
200Sucesso.
idstring (uuid)obrigatóriourlstringobrigatórioO endereço que você manda ao seu cliente. Ele contém o token, e o token aparece só nesta resposta.expiresAtstringobrigatórioexternalIdstring | nullobrigatórioredirectUrlstring | nullobrigatórioA redirectUrl do pedido, ou nulo.displayNamestring | nullobrigatórioO nome do seu cliente que a página do link mostra, ou nulo.
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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"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"
}{
"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."
}{
"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."
}{
"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.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
{
"error": "link_not_open",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Só um link aberto pode ser reemitido, e este está usado. Crie um link novo com POST /v1/onboarding/links.",
"status": "used"
}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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}