# Percurso do integrador: cadastro e webhooks 100 % por API

`GET /v1/onboarding-links/{id}`

Se você cadastra seus clientes a partir do seu sistema, sem entrar no painel, este é o caminho inteiro, em cinco passos.

**1. Um link por cliente.** `POST /v1/onboarding-links` com o seu `externalId` (o seu id para esse cliente) e `webhook: { url }`. Devolvemos a `url` para o seu cliente e o segredo `whsec_…` do webhook **uma única vez**: guarde já, ele assina tudo desse cliente. Um `externalId` que outro número da sua conta já usa dá `409` neste momento, não no fim do cadastro.

**2. O seu cliente conecta.** Abre a `url`, entra com a conta da Meta e escolhe o número. Ao terminar, o número já nasce com o seu webhook (a URL do link) e chega ali **`onboarding.completed`**, com `connection.id` (`conn_…`), o seu `externalId`, `reconnected` e o `webhookId`. Um número novo também traz `connection.created`, como sempre.

**3. Se não terminar, você fica sabendo do mesmo jeito.** Cada tentativa interrompida (falhou, foi cancelada ou abandonada) manda **`onboarding.failed`** para a URL do webhook do link, assinado com o mesmo segredo: `reason` (`meta_error`, `incomplete`, `timeout`, `cancelled`, `abandoned`…), `metaErrorCode` e `metaMessage` se a Meta os deu, e `linkUsable` (se o seu cliente pode tentar de novo com o mesmo link). Se preferir perguntar: `GET /v1/onboarding-links?externalId=…` ou `GET /v1/onboarding-links/{id}` trazem `outcome` (`pending`, `completed` ou `failed`, com o mesmo motivo).

**4. O webhook do número é seu.** Veja e altere com `/v1/webhooks?externalId=…`: URL, eventos, cabeçalho fixo, rotacionar o segredo, testar.

**5. O desligamento.** Quando o número é desconectado (pelo painel, porque o negócio nos tirou o acesso na Meta ou porque a permissão foi revogada), o webhook dele fica desligado (`active: false`, `disabledReason: "connection_disconnected"`) e para de receber. Se o **mesmo** número reconectar, ele volta sozinho; os que você pausou ou os que desligamos por falha, não.

## Exemplos

### cURL

```bash
# 1) one link per end-customer: your id + the webhook its number will have
curl -X POST https://api.waiaconnect.com/v1/onboarding-links \
  -H "Authorization: Bearer wc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalId": "pharmacy-42", "label": "Pharmacy 42", "mode": "coexistence",
       "webhook": {"url": "https://api.yourcompany.com/hooks/connect"}}'
# → 201 { "publicId": "onb_…", "url": "https://…/c#<token>", "expiresAt": "…",
#         "webhook": { "secret": "whsec_…", "createdOnCompletion": true, … } }   ← store the secret NOW

# 2) send "url" to your customer. Then, on https://api.yourcompany.com/hooks/connect:
#    { "type": "onboarding.completed", "connection": { "id": "conn_…", "externalId": "pharmacy-42", … },
#      "data": { "onboardingLinkId": "onb_…", "reconnected": false, "webhookId": "wh_…", … } }
#    { "type": "onboarding.failed", "connection": { "id": null, … },
#      "data": { "externalId": "pharmacy-42", "reason": "meta_error", "metaErrorCode": 2655093,
#                "metaMessage": "The business is already sharing…", "linkUsable": true, … } }

# 3) or ask (polling) by your id
curl "https://api.waiaconnect.com/v1/onboarding-links?externalId=pharmacy-42" -H "Authorization: Bearer wc_live_YOUR_API_KEY"
# → { "links": [ { "id": "onb_…", "status": "used", "connectionId": "conn_…",
#       "outcome": { "state": "completed", "connectionId": "conn_…", "webhookId": "wh_…", … } } ] }
curl https://api.waiaconnect.com/v1/onboarding-links/onb_… -H "Authorization: Bearer wc_live_YOUR_API_KEY"

# 4) the number's webhook, by your id (PATCH to change url/events, rotate-secret, test)
curl "https://api.waiaconnect.com/v1/webhooks?externalId=pharmacy-42" -H "Authorization: Bearer wc_live_YOUR_API_KEY"

# 5) offboarding: disconnecting the number switches its webhook off
#    (active: false, disabledReason: "connection_disconnected"); reconnecting it switches it back on
```

### Node.js

```javascript
const H = { "Authorization": "Bearer wc_live_YOUR_API_KEY", "Content-Type": "application/json" };

// 1) one link per end-customer: your id + the webhook its number will have
const link = await (await fetch("https://api.waiaconnect.com/v1/onboarding-links", {
  method: "POST", headers: H,
  body: JSON.stringify({ externalId: "pharmacy-42", label: "Pharmacy 42", mode: "coexistence",
    webhook: { url: "https://api.yourcompany.com/hooks/connect" } })
})).json();
await saveSecret("pharmacy-42", link.webhook.secret); // shown ONCE — it signs this customer's events
await sendToCustomer(link.url);

// 2) your webhook handler (verify the signature first — see «Verify the signature»)
app.post("/hooks/connect", express.raw({ type: "application/json" }), async (req, res) => {
  const evt = JSON.parse(req.body);
  if (evt.type === "onboarding.completed") await markConnected(evt.data.externalId, evt.connection.id);
  if (evt.type === "onboarding.failed") await tellCustomer(evt.data.externalId, evt.data.reason, evt.data.metaErrorCode, evt.data.linkUsable);
  res.sendStatus(200);
});

// 3) or poll by your id
const { links } = await (await fetch("https://api.waiaconnect.com/v1/onboarding-links?externalId=pharmacy-42", { headers: H })).json();
console.log(links[0]?.outcome); // { state: "pending" | "completed" | "failed", reason, metaErrorCode, … }
```

### PHP

```php
<?php
function connect($method, $url, $body = null) {
  $ch = curl_init($url);
  curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => $method,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer wc_live_YOUR_API_KEY", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => $body ? json_encode($body) : null,
  ]);
  return json_decode(curl_exec($ch), true);
}
// 1) one link per end-customer: your id + the webhook its number will have
$link = connect("POST", "https://api.waiaconnect.com/v1/onboarding-links", [
  "externalId" => "pharmacy-42", "label" => "Pharmacy 42", "mode" => "coexistence",
  "webhook" => ["url" => "https://api.yourcompany.com/hooks/connect"],
]);
save_secret("pharmacy-42", $link["webhook"]["secret"]); // shown ONCE

// 2) in your webhook handler: onboarding.completed / onboarding.failed (data.reason, data.metaErrorCode)
// 3) or poll by your id
$links = connect("GET", "https://api.waiaconnect.com/v1/onboarding-links?externalId=pharmacy-42")["links"];
$outcome = $links[0]["outcome"] ?? null; // state: pending | completed | failed
```

### Python

```python
import requests
H = {"Authorization": "Bearer wc_live_YOUR_API_KEY"}

# 1) one link per end-customer: your id + the webhook its number will have
link = requests.post("https://api.waiaconnect.com/v1/onboarding-links", headers=H, json={
    "externalId": "pharmacy-42", "label": "Pharmacy 42", "mode": "coexistence",
    "webhook": {"url": "https://api.yourcompany.com/hooks/connect"},
}).json()
save_secret("pharmacy-42", link["webhook"]["secret"])  # shown ONCE

# 2) in your webhook handler: onboarding.completed / onboarding.failed (data.reason, data.metaErrorCode)
# 3) or poll by your id
links = requests.get("https://api.waiaconnect.com/v1/onboarding-links", headers=H, params={"externalId": "pharmacy-42"}).json()["links"]
outcome = links[0]["outcome"] if links else None  # state: pending | completed | failed
```

## Notas

- Sem `webhook` no link, `onboarding.completed` e `onboarding.failed` vão para os webhooks da conta (em `onboarding.failed`, `connection.id` vem `null`: o seu `externalId` vai em `data`).
- Um webhook com `events` explícito que não inclui estes tipos não os recebe; um com todos os eventos passa a recebê-los.
- Nos links de cadastro, `connectionId` agora sai como `conn_…`; o id interno fica em `legacyConnectionId`, que vai ser retirado.
- `outcome.state = failed` também quando o link venceu (`link_expired`) ou você o revogou (`link_revoked`) antes de o cliente terminar.