# Vindo da Z-API ou da Evolution API

Fonte: https://lunahia.com.br/docs/migrar-de-api-nao-oficial

A Z-API e a Evolution API conectam um número como um aparelho; a Luna fala só com a WhatsApp Cloud API oficial da Meta. Este guia traduz o que você fazia lá para o que se faz aqui: como autenticar, enviar, receber, e o que cada estado e cada evento vira. Termina com a lista do que não existe na API oficial, para você não procurar o que não está aqui.

A [referência da API](https://lunahia.com.br/docs/referencia) traz o contrato de cada rota. Antes das tabelas, leia [a diferença de modelo](https://lunahia.com.br/migrar-da-evolution-api): a janela de 24 horas, o `202` sem `wamid` e a ausência de QR code são o que quebra uma migração no meio. As colunas da Z-API e da Evolution descrevem, com palavras nossas, o que a documentação pública de cada uma mostra.

## O que muda antes de tocar no código

- **Instância vira número.** Em vez de criar uma instância e ler um QR code, você manda ao seu cliente um link de conexão (`POST /v1/onboarding/links`) e o dono do número entra com a conta dele na Meta. O número fica na conta do seu cliente, e é isso que evita o banimento por sessão. Veja [Conectar um número](https://lunahia.com.br/docs/conectar-numero).
- **Texto livre só dentro de 24 horas.** Depois que o contato para de escrever por 24 horas, o caminho é um template aprovado. A Luna recusa o texto fora da janela com `409 window_closed` antes de gastar a chamada. Veja [a janela](https://lunahia.com.br/docs/enviar-mensagens#janela).
- **O envio responde `202`.** A resposta traz o `id` da Luna e `status: "queued"`. O `wamid` e o estado de entrega chegam depois, pelo evento `message.status`. Os estados estão em [Os estados da mensagem](https://lunahia.com.br/docs/enviar-mensagens#estados).
- **Só celulares do Brasil.** `to` é o telefone com DDI e DDD, só dígitos, começando por `55`. Outro formato responde `400` com `campos: [{campo: "to"}]`, salvo para quem já escreveu para o seu número. O nono dígito não é problema: a Luna acha a conversa com e sem ele, e o texto vai para o `wa_id` que a Meta usou. Quem nunca escreveu recebe o telefone como você o escreveu.
- **A fila tem ritmo.** Para o mesmo contato, saem 30 mensagens de uma vez e depois uma a cada 7 segundos. Você não configura isso, e o limite nunca volta como `429`. Não há como cancelar uma mensagem que já está na fila, nem estimar a hora em que ela sai.
- **Template não é recusado em silêncio.** Um template que a Luna conhece e que não está `APPROVED` responde `409 template_not_approved`, e variável faltando ou sobrando responde `400` com `campos`. Um número que não consegue enviar agora (`connection.canSend: false` em `GET /v1/numbers`) ainda aceita o pedido com `202` e a falha chega em `message.status`: leia `canSend` antes de enviar.

## Autenticar e enviar

| O que você fazia | Z-API | Evolution API | Luna |
| --- | --- | --- | --- |
| Autenticar | O identificador da instância e um token, mais um token de segurança da conta. | Uma chave da instalação. | `Authorization: Bearer hlsn_...` com escopos. Uma chave por cliente, com `externalId`. |
| Criar a instância de um cliente | Criar uma instância pelo parceiro. | Criar uma instância. | Link de conexão por cliente: `POST /v1/onboarding/links`. |
| Enviar texto | Uma chamada com o telefone e a mensagem; devolve dois identificadores na hora. | Uma chamada por instância com o número e o texto. | `POST /v1/messages` com `from`, `to` e `text.body`. Devolve `id` e `status: "queued"`; o `wamid` vem depois. |
| Pausa entre mensagens | Um atraso por mensagem, de 1 a 15 segundos. | Um atraso por mensagem. | Fila automática: rajada de 30, depois uma a cada 7 segundos por contato. |
| Mostrar “digitando” | Um atraso de digitação no envio. | Uma chamada de presença. | `POST /v1/messages/{id}/typing`, com o `id` da mensagem **recebida**. Também a marca como lida e some em cerca de 25 segundos. |
| Enviar mídia | A URL ou o arquivo em base64 no próprio envio. | O arquivo no próprio envio. | `POST /v1/numbers/{id}/media` e depois `image.id`, ou `image.link` com uma URL pública. Dois passos, porque a Meta trabalha com identificador de mídia. |
| Botões e lista | Botões de ação e lista de opções. | Enviar botões e enviar lista. | `interactive.type`: `button`, `list` ou `cta_url`. A resposta volta em `message.interactive.id`, no evento `message.received`. |
| Reação | Enviar reação. | Enviar reação. | `type: "reaction"`, com `reaction.message_id` (o `wamid`) e `reaction.emoji`. |
| Responder citando | Responder uma mensagem. | Um campo de citação no envio. | `context.message_id`, com o `id` da Luna ou o `wamid`. |
| Marcar como lida | Ler mensagens. | Marcar mensagem como lida. | `POST /v1/messages/{id}/read`, por mensagem. |
| Apagar a instância | Apagar a instância. | Apagar a instância. | `DELETE /v1/numbers/{id}`. Libera a vaga na Luna e não derruba o número na Meta. |

O telefone vai como o cliente o escreveu, com ou sem o nono dígito. O corpo mínimo de um envio de texto:

```json
{
  "from": "YOUR_PHONE_NUMBER_ID",
  "to": "5531990009991",
  "text": { "body": "Olá! Sua consulta está confirmada." }
}
```

Campos que pertencem ao tipo vão dentro do objeto do tipo, e não no topo do corpo: `image.caption`, `location.latitude`. Um campo desconhecido responde `400` com o nome dele. Mande sempre o `Idempotency-Key`: veja [Idempotência](https://lunahia.com.br/docs/enviar-mensagens#idempotencia).

## Eventos e estados

Na Luna há um endpoint de webhook para a conta inteira, ou um por cliente com `externalIds`. Todo evento traz o objeto `number`, com o `external_id` do cliente dono do número, então um endpoint só atende todos os seus clientes. A entrega é assinada e pode repetir: deduplique pelo `event_id`. Veja [Receber eventos](https://lunahia.com.br/docs/receber-eventos).

### Webhook por número (como a “instância”)

Lá cada instância tinha a sua URL de webhook. Aqui o número é a instância e o endpoint aceita `phoneNumberIds`: ele recebe só os eventos desses números (o UUID da Luna, o `id` de `GET /v1/numbers`, ou o `metaPhoneNumberId`).

```bash
curl -X POST "https://api.lunahia.com.br/v1/webhooks/endpoints" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhooks/numero-1",
  "phoneNumberIds": [
    "YOUR_PHONE_NUMBER_ID"
  ]
}'
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "url": "https://example.com/webhooks/numero-1",
    "phoneNumberIds": [
      "YOUR_PHONE_NUMBER_ID"
    ]
  }),
});
console.log(res.status, await res.json());
```

```python
import os
import requests

res = requests.post(
    "https://api.lunahia.com.br/v1/webhooks/endpoints",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    json={
        "url": "https://example.com/webhooks/numero-1",
        "phoneNumberIds": [
            "YOUR_PHONE_NUMBER_ID",
        ],
    },
    timeout=10,
)
print(res.status_code, res.json())
```

Para trocar a URL só desse número, use `PATCH /v1/webhooks/endpoints/{id}` com o novo `url`. Para números que ainda vão ser conectados, cadastre o endpoint com `externalIds` (o `externalId` que você dá ao cliente): ele recebe de todo número com esse `externalId`, inclusive os conectados depois. Detalhes na seção “Webhook por número” de [Receber eventos](https://lunahia.com.br/docs/receber-eventos).

```bash
curl -X PATCH "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhooks/numero-1-novo"
}'
```

```js
const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "url": "https://example.com/webhooks/numero-1-novo"
  }),
});
console.log(res.status, await res.json());
```

```python
import os
import requests

res = requests.patch(
    "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID",
    headers={
        "Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
    },
    json={
        "url": "https://example.com/webhooks/numero-1-novo",
    },
    timeout=10,
)
print(res.status_code, res.json())
```

| O que você ouvia | Z-API | Evolution API | Luna |
| --- | --- | --- | --- |
| Mensagem recebida | Webhook “ao receber”. | `MESSAGES_UPSERT` | `message.received` |
| Mensagem que o dono mandou pelo celular | “Ao receber”, com as enviadas por mim. | `SEND_MESSAGE` | `message.echo`, só em número em coexistência. |
| Estado da mensagem | Webhook de status, com os estados de envio, recebimento, leitura e reprodução. | `MESSAGES_UPDATE` | `message.status`: `sent`, `delivered`, `read`, `played` e `failed`. A Meta não manda `delivered` quando entrega e leitura coincidem. |
| Conectou | Webhook “ao conectar”. | `QRCODE_UPDATED` e `CONNECTION_UPDATE`. | `onboarding.link.completed` quando o cliente termina o link, e `number.connected` quando o número fica pronto. |
| Desconectou | Webhook “ao desconectar”. | `CONNECTION_UPDATE` | `number.disconnected`, `number.action_required` e `number.credential_expiring`. O estado fica em `connection` de `GET /v1/numbers/{id}`. |
| Aprovação de template | - | - | `template.status` |

> **`number.disconnected` não quer dizer sempre `disconnected`.** Quando o cliente remove o aplicativo, o número fica em `connection.status: "action_required"` com o motivo `credential_invalid`, e se reconecta pelo link. Só o `DELETE /v1/numbers/{id}` deixa `disconnected`. Veja [Número desconectado](https://lunahia.com.br/docs/saude-da-conta#desconectado).

Não existe evento de ligação recebida, e não existe configuração de rejeitar chamada. Se o seu agente depende de uma delas, trate no seu lado. A leitura automática existe: ligue `autoRead` no número, com `PATCH /v1/numbers/{id}`, e a Luna marca como lida cada mensagem que o número recebe, sem indicador de digitando. Para marcar só as que você processa, deixe `autoRead` desligado e use `POST /v1/messages/{id}/read`.

## O que não existe na API oficial

Não são faltas da Luna: são recursos de quem conecta um número como aparelho. Cada linha diz o que fazer no lugar.

| O que existia lá | Aqui |
| --- | --- |
| QR code e código de pareamento | Não há QR code. A conexão é pelo link de conexão, e o dono do número entra com a conta dele na Meta. É isso que impede o banimento. |
| Conferir se um número tem WhatsApp antes de enviar | A API oficial não responde isso. Envie normalmente: se o número não tem WhatsApp, chega `message.status` com `failed` e o código 131026, e repetir o envio não muda o resultado. |
| Agenda de contatos, foto e recado de quem escreve, lista de chats | O número de negócio não tem agenda nem lista de chats. Guarde os contatos no seu banco a partir de `message.received` (`wa_id` e `profile_name`). |
| Mensagens antigas do aparelho | A Luna só tem o que passou por ela depois da conexão. Em número em coexistência, a Meta importa o histórico dentro de um prazo: veja [Conectar um número](https://lunahia.com.br/docs/conectar-numero#coexistencia). |
| Status e stories | A API oficial não publica nem responde status. |
| Enquetes, eventos e fixar mensagem | Use botões ou lista, que o contato responde e volta em `message.received`, em `message.interactive`. |
| Editar, apagar e encaminhar mensagem enviada | A API de mensagens da Meta não oferece essas operações ao negócio. Corrija mandando outra mensagem; `context.message_id` cita a original. |
| Etiquetas e anotações do aplicativo Business | Etiqueta é do aplicativo no celular e não existe na API. Marque a conversa no seu sistema, pelo `conversationId` ou pelo `wa_id`. |
| Presença do contato: online, “digitando”, visto por último | A Meta não entrega a presença do contato. O “digitando” do seu agente sai por `POST /v1/messages/{id}/typing`. |
| Privacidade da conta e bloqueio de contato | Bloquear existe, em `POST /v1/numbers/{id}/blocked-users`. O resto das configurações de privacidade é do aplicativo. |
| Listas de transmissão, canais, comunidades | A API oficial não tem. Para falar com muita gente, use template, e respeite o limite de qualidade e a preferência de marketing do contato (`contact.preferences_changed`). |
| Grupos | Grupo comum de WhatsApp não existe na API oficial. A Meta tem uma API de grupos própria, com limites e requisitos, que a Luna ainda não expõe. |
| Proxy por instância, IP dedicado, desbanimento | Não há sessão para proteger: o número é registrado na Meta, e o risco é de qualidade, não de IP. Veja `GET /v1/numbers/{id}/health` e [Saúde da conta](https://lunahia.com.br/docs/saude-da-conta). |
| Texto livre a qualquer hora | Fora de 24 horas, só template. É a regra da Meta, e a Luna a aplica antes de gastar a chamada (`409 window_closed`). |
| Áudio em MP3 como mensagem de voz | A Meta exige OGG com OPUS e a Luna não converte. Converta antes: `ffmpeg -i entrada.mp3 -c:a libopus -b:a 32k -ar 48000 -ac 1 saida.ogg`. |

## Por onde começar

1. Crie a conta e uma chave por cliente: [Conta e chaves](https://lunahia.com.br/docs/conta-e-chaves).
2. Troque a criação da instância pelo link de conexão: [SaaS com N clientes](https://lunahia.com.br/docs/saas-com-n-clientes).
3. Cadastre o webhook e troque o seu tratamento de eventos pela tabela acima: [Receber eventos](https://lunahia.com.br/docs/receber-eventos).
4. Teste o envio sem ir à Meta, com a chave de teste: [Modo de teste](https://lunahia.com.br/docs/modo-de-teste).

> A Helsen cobra pela capacidade de números ativos do seu plano, e por nada além disso. O uso da plataforma WhatsApp é cobrado pela Meta, do seu cliente final, no método de pagamento dele. Z-API e Evolution API são projetos de terceiros, sem relação com a Helsen; este guia descreve o modelo de cada plataforma para quem migra e não é uma comparação comercial.
