# Vindo de outro parceiro oficial (360dialog, Gupshup)

Fonte: https://lunahia.com.br/docs/migrar-de-outro-parceiro

Se você já opera clientes por outro parceiro oficial, o modelo é familiar: o negócio é dono da conta de WhatsApp Business, o número está na Cloud API da Meta e você conecta um cliente por um fluxo da Meta. O que muda são os nomes das coisas, o webhook e a forma de pagar a Meta. Este guia faz o de-para e diz o que fazer com um número que já está no outro parceiro.

A [referência da API](https://lunahia.com.br/docs/referencia) traz o contrato de cada rota. As colunas dos outros parceiros descrevem, com palavras nossas, o que a documentação pública de cada um mostra; se algo mudou por lá, vale a documentação deles.

## O que muda e o que fica igual

- **Fica igual:** o seu cliente continua dono da conta de WhatsApp Business (a WABA) e da forma de pagamento dele na Meta. A Luna não é dona de nada disso.
- **Muda a forma de pagar a Meta.** A Luna é Tech Provider e não tem linha de crédito com a Meta, então não existe carteira, saldo nem recarga. Cada negócio paga a Meta direto, e a Luna só **exibe** o consumo de cada número em `GET /v1/usage`. Você repassa esse valor ao seu cliente como achar melhor, fora da Luna.
- **Não há objeto “cliente” nem “aplicativo”.** O seu cliente é o `externalId`, um rótulo que você põe na chave, no link de conexão, no endpoint e que volta em todo evento. A instância é o número.
- **Muda o webhook.** Um endpoint para a conta inteira (ou um por cliente com `externalIds`), entrega assinada, ordem preservada dentro de cada conversa e `event_id` para deduplicar. Não há cabeçalhos próprios na chamada: a autenticação da entrega é a assinatura. Veja [Receber eventos](https://lunahia.com.br/docs/receber-eventos).

## De-para por parceiro

### Para quem vem da 360dialog

| 360dialog | Luna |
| --- | --- |
| Cabeçalho de chave, uma chave por canal | `Authorization: Bearer hlsn_...`. Uma chave por cliente, com `externalId` e `profile: "agent"`. |
| Enviar mensagem | `POST /v1/messages`: `202` assíncrono e `Idempotency-Key`. |
| Cadastrar a URL do webhook por canal, com cabeçalhos | `POST /v1/webhooks/endpoints` com `url`, `eventTypes` e `externalIds`. Sem cabeçalhos próprios; a assinatura é `X-Luna-Signature`. |
| Listar clientes | Não há objeto “cliente”: o `externalId` é o seu cliente. |
| Listar canais | `GET /v1/numbers`, com os filtros `externalId`, `state` e `canSend`. |
| Criar chave de um canal | `POST /v1/api-keys` com `externalId`. |
| Endereço de integração e retorno com o cliente e os canais | `POST /v1/onboarding/links` com `redirectUrl`, que recebe `status` e `numberId` na query. O link vale 72 horas. Veja [Conectar um número](https://lunahia.com.br/docs/conectar-numero). |
| Evento de canal criado | `onboarding.link.completed` |
| Evento de canal em execução | `number.connected` |
| Evento de qualidade do número | `number.quality_changed` |
| Estado de saúde: disponível, limitado, bloqueado | `connection.status` e `connection.reasons` em `GET /v1/numbers/{id}`, e `GET /v1/numbers/{id}/health`. Veja [Saúde da conta](https://lunahia.com.br/docs/saude-da-conta). |
| Listar, criar e apagar templates | `GET /v1/templates?wabaId=`, `POST /v1/templates` e `DELETE /v1/templates/{id}`. Veja [Templates](https://lunahia.com.br/docs/templates). |
| Replicar um template para outro cliente | Não há. Crie o template em cada WABA com `POST /v1/templates`. `GET /v1/templates/{id}` traz o conteúdo e o `wabaId`, o que ajuda a copiar à mão. |
| Saldo do cliente | `GET /v1/usage?numberId=`, só para exibir. Não há saldo nem recarga. |
| Limite de canais | `GET /v1/subscription`: `capacity` e `capacityLeft`. Veja [Plano e números](https://lunahia.com.br/docs/plano-e-numeros). |
| Pedido de cancelamento do canal | `DELETE /v1/numbers/{id}`, que dispara `number.disconnected`. Não desregistra o número na Meta. |

### Para quem vem da Gupshup

| Gupshup | Luna |
| --- | --- |
| Criar um aplicativo por cliente | Não há aplicativo: a instância é o número. Crie um link de conexão com `POST /v1/onboarding/links`. |
| Link de incorporação assinado | O link de conexão: uma `url` com token, válida por 72 horas. |
| Assinaturas de callback por aplicativo | `POST /v1/webhooks/endpoints`. |
| Templates por aplicativo | `/v1/templates`, por WABA. |
| Carteira e saldo | Não existe, por desenho: cada negócio paga a Meta direto. `GET /v1/usage` só exibe o consumo. |
| Uso diário por aplicativo | `GET /v1/usage`, por número. |
| Perfil comercial e nome de exibição | `GET` e `PATCH /v1/numbers/{id}/profile`, sem o nome de exibição. Esse nome o negócio vê e pede no WhatsApp Manager, da Meta. Veja [Perfil do negócio](https://lunahia.com.br/docs/numero-na-meta#perfil). |

## O que muda no webhook

- **Assinatura.** Cada entrega traz `X-Luna-Signature: t=...,v1=...`, o HMAC-SHA256 de `t` + `.` + corpo bruto. Veja [Verifique a assinatura](https://lunahia.com.br/docs/receber-eventos#assinatura).
- **Ordem e repetição.** A ordem vale dentro de uma conversa, e a entrega pode repetir. Deduplique pelo `event_id`, que é estável.
- **Qual conta e qual cliente.** Os eventos de conexão e de template trazem o `waba_id`, e todo evento traz o objeto `number` com o `external_id` do seu cliente. Você não precisa cruzar listas para saber de quem é o evento.
- **Link abandonado.** Um cliente que fecha a janela da Meta deixa o link `open`, com `lastFailure` e `reason: "abandoned"`. O evento `onboarding.link.failed` chega depois.

## Mover um número que já está no outro parceiro

1. O negócio precisa ser dono da conta de WhatsApp Business e ter o número liberado no parceiro anterior. Os pré-requisitos e o PIN da verificação em duas etapas estão em [Número que vem de outro provedor](https://lunahia.com.br/docs/conectar-numero#outro-provedor).
2. Mande o link de conexão (`POST /v1/onboarding/links`). Se o número ficar em `PIN_REQUIRED`, informe o PIN em `POST /v1/numbers/{id}/pin`. O PIN errado gasta uma das tentativas de registro que a Meta concede.
3. Espere o evento `number.connected` e confira `connection.canSend` em `GET /v1/numbers/{id}`. Só então desligue o número no parceiro anterior, para não ficar sem canal no intervalo.
4. Troque o webhook do seu sistema: os eventos e a assinatura são outros, como na tabela acima.

> **O que não foi confirmado na prática:** os templates pertencem à WABA e não ao parceiro, mas a Helsen ainda não testou conectar uma WABA que já tem templates aprovados. Depois de conectar, liste `GET /v1/templates?wabaId=` e confira o que a Luna conhece. Um template que ela não conhece é aceito no envio e quem decide é a Meta.

## Capacidade e links

O plano da Luna define quantos números você mantém ativos. O link de conexão **não reserva vaga**: se você mandar mais links do que há vagas, os últimos clientes ficam com o número em "conectando" até haver vaga. Antes de entregar cada link, confira as vagas, como explica [Plano e números](https://lunahia.com.br/docs/plano-e-numeros).

> 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. 360dialog e Gupshup são empresas independentes, sem relação com a Helsen; este guia descreve o modelo de cada plataforma para quem migra e não é uma comparação comercial.
