Cancelar uma sessão de cadastro

POST/v1/onboarding-sessions/{session_id}/cancel

Cancela a sessão: o link deixa de valer. Idempotente (cancelar de novo responde a mesma sessão). Uma sessão já concluída não se cancela (409): o número já foi conectado.

Requer#

Escopo da chave: onboarding onboardingComo os escopos funcionam
Recurso do plano: API e webhooks apiVer os planos que incluem
Formato: Rota do Synergy. Erros no formato da Meta.

Parâmetros#

No caminho#

No caminho
Nome	Tipo	Obrigatório	Descrição
session_id	string	obrigatório	O `id` da sessão de cadastro.

Cabeçalhos#

Cabeçalhos
Nome	Tipo	Obrigatório	Descrição
Authorization	string	obrigatório	Sua chave de API, no formato `Bearer <chave>`. Veja Autenticação.

Respostas#

Respostas
Status	Código	Quando acontece
200	—	Cancelada
401	—	Chave revogada ou desconhecida
401	190	Chave malformada ou forjada
403	—	A chave não tem o escopo `onboarding`
403	—	O plano da organização não inclui a API
404	—	Sessão não encontrada
409	—	Já concluída
429	—	Limite de taxa

Os erros no formato da Meta trazem o código em error.code. Ver todos os erros.

Corpo da resposta 200#

Campos da resposta 200
Nome	Tipo	Obrigatório	Descrição
id	string	obrigatório
status	string	obrigatório	Valores: `pending`, `opened`, `completed`, `expired`, `cancelled`, `blocked`.
url	string \| null	obrigatório	O link para o cliente abrir: só enquanto `pending`. Uso único, preso ao primeiro navegador que o abre.
mode	string	obrigatório	Valores: `cloud`, `coexistence`, `choice`.
return	string	obrigatório	Valores: `redirect`, `popup`.
redirect_url	string	obrigatório
state	string	obrigatório
external_ref	string \| null	obrigatório
display_name	string	obrigatório
created_at	string	obrigatório
expires_at	string	obrigatório
blocked	object \| null	obrigatório
last_error	object \| null	obrigatório
result	object \| null	obrigatório

Limites de taxa#

Organização: 120 requisições a cada 60 s por chave (API_ORG_LIMIT).

Notas#

As rotas da organização respondem no formato da gestão ({ "error": … }, com reason ou feature quando há), não no da Graph API — exceto a chave malformada (401, código 190).
Uma chave recusada (revogada, ou sem o escopo) recebe este 401 pelos 60 s seguintes, por instância do Worker (cache de recusa, como na gestão).

Requisição

curl

curl -X POST 'https://api.synergyconnect.com.br/v1/onboarding-sessions/obs_4Fq9Lm2Xr7Tz1Vb8Nc3Kd6Hs/cancel' \
  -H "Authorization: Bearer $SYNERGY_API_KEY"

JavaScript

const res = await fetch('https://api.synergyconnect.com.br/v1/onboarding-sessions/obs_4Fq9Lm2Xr7Tz1Vb8Nc3Kd6Hs/cancel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNERGY_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os

import requests

res = requests.post(
    "https://api.synergyconnect.com.br/v1/onboarding-sessions/obs_4Fq9Lm2Xr7Tz1Vb8Nc3Kd6Hs/cancel",
    headers={
        "Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}",
    },
)
print(res.status_code, res.json())

Resposta

200

{
  "id": "obs_4Fq9Lm2Xr7Tz1Vb8Nc3Kd6Hs",
  "status": "cancelled",
  "url": null,
  "mode": "choice",
  "return": "redirect",
  "redirect_url": "https://app.minha-plataforma.com/whatsapp/ok",
  "state": "e7f2c0d4-9b1e-4c52-8d0a-3f6a1b2c4d5e",
  "external_ref": "tenant_8841",
  "display_name": "Minha Plataforma",
  "created_at": "2026-01-01T00:00:00.000Z",
  "expires_at": "2026-01-01T00:15:00.000Z",
  "blocked": null,
  "last_error": null,
  "result": null
}

401

{
  "error": "Invalid or revoked key"
}

Há 2 casos com este status; veja a tabela de respostas.

403

{
  "error": "This key lacks the onboarding scope"
}

Há 2 casos com este status; veja a tabela de respostas.

404

{
  "error": "Session not found"
}

409

{
  "error": "The session is already completed"
}

429

{
  "error": "Rate limit hit"
}

Ficou com dúvida? Escreva para suporte@synergyconnect.com.br.