Domínio customizado na API WhatsApp: marca própria para revendedores

Cliente final que vê "zap-api.tech" na URL da API durante a integração tem dois pensamentos: primeiro, "ah, então não é deles, é da ZAP-API". Segundo, "se eles cobram R$299 e a ZAP-API cobra R$49, posso ir direto na fonte". Ambos os pensamentos custam dinheiro para o reseller.

Domínio customizado resolve isso. Seu cliente vê api.suaempresa.com.br, recebe documentação branded e fica preso à sua marca. Este artigo é o passo a passo técnico completo, do CNAME ao SSL.

Por que domínio próprio importa

• Confiança: domínio próprio é sinal de empresa estabelecida, não revenda.
• Branding: em apresentações comerciais, "API da Sua Empresa em api.suaempresa.com.br" soa muito melhor que "vamos usar a ZAP-API".
• Preço premium: permite cobrar 4-6x mais do que o custo, justificado pelo "produto próprio".
• Sem dependência aparente: se um dia você migrar de provedor, cliente nem percebe (mantém a mesma URL).
• Documentação branded: sua doc em docs.suaempresa.com.br em vez de doc compartilhada.

Pré-requisitos

• Conta reseller ativa na ZAP-API
• Domínio próprio (qualquer registrador: Registro.br, GoDaddy, Cloudflare, etc.)
• Acesso ao painel DNS do seu domínio
• 15 minutos para fazer toda configuração

Passo 1: Registrar o domínio na ZAP-API

Diferente do que a intuição sugere, o primeiro passo não é o DNS — é registrar o domínio, porque é a resposta desse endpoint que te diz exatamente quais registros criar. Logado como reseller:

POST https://api.zap-api.tech/v1/reseller/me/custom-domain
Authorization: Bearer <seu JWT de login>

{
  "domain": "api.suaempresa.com.br"
}

Response em sucesso

{
  "customDomain": "api.suaempresa.com.br",
  "status": "pending",
  "verification": {
    "type": "TXT",
    "name": "_cf-custom-hostname.api.suaempresa.com.br",
    "value": "a1b2c3d4-...",
    "instructions": "Adicione o registro TXT abaixo no DNS do seu domínio..."
  }
}

O bloco verification é o que importa: sem esse TXT, a validação de posse não fecha e o certificado nunca é emitido.

Passo 2: Criar os registros no DNS

São dois registros. O TXT prova que o domínio é seu; o CNAME manda o tráfego para o seu painel.

Tipo:    TXT
Nome:    _cf-custom-hostname.api    (o "name" devolvido no passo 1)
Valor:   a1b2c3d4-...               (o "value" devolvido no passo 1)
TTL:     300

Tipo:    CNAME
Nome:    api                         (ou seja, api.suaempresa.com.br)
Valor:   seu-slug.zap-api.tech       (o slug do seu painel reseller)
TTL:     300 (5 minutos)

Em alguns registradores brasileiros (Registro.br), o campo "Nome" se chama "Subdomínio" e o "Valor" se chama "Apontamento". É a mesma coisa. Seu slug aparece no GET /v1/reseller/me.

Passo 3: Verificar propagação DNS

Propagação DNS leva de 5 minutos a algumas horas. Para checar:

# Linux/Mac
dig api.suaempresa.com.br CNAME

# Windows
nslookup -type=CNAME api.suaempresa.com.br

# Cross-platform (se tiver Node)
node -e "require('dns').resolveCname('api.suaempresa.com.br', console.log)"

Se a resposta inclui seu-slug.zap-api.tech, está propagado.

Passo 4: Disparar a verificação e acompanhar o status

Com o DNS no ar, peça a verificação. O certificado é emitido automaticamente depois que a posse é confirmada:

POST https://api.zap-api.tech/v1/reseller/me/custom-domain/verify
Authorization: Bearer <seu JWT de login>

{
  "customDomain": "api.suaempresa.com.br",
  "status": "active"
}

O status tem três valores: pending (aguardando DNS/certificado), active (no ar com SSL) e failed (posse não confirmada — revise o TXT). Chame de novo até virar active.

Código: script de verificação automatizada

Útil para automatizar onboarding de revenda — registra, espera o DNS e só então dispara a verificação:

// verificar-dominio.js
import { resolveCname } from "dns/promises";
import axios from "axios";

const API = axios.create({
  baseURL: "https://api.zap-api.tech/v1",
  headers: { Authorization: `Bearer ${process.env.ZAP_JWT}` },
});

async function aguardarPropagacao(dominio, alvo, tentativasMax = 30) {
  for (let i = 0; i < tentativasMax; i++) {
    try {
      const cnames = await resolveCname(dominio);
      if (cnames.some((c) => c.includes(alvo))) {
        console.log(`✅ DNS propagado para ${dominio}`);
        return true;
      }
    } catch (err) {
      // ENOTFOUND ainda — continua tentando
    }
    console.log(`⏳ Tentativa ${i + 1}/${tentativasMax}: DNS ainda não propagou`);
    await new Promise((r) => setTimeout(r, 30_000)); // espera 30s
  }
  return false;
}

async function ativarDominio(dominio) {
  // 1. Registra e pega o TXT de posse + o slug do painel
  const { data: registro } = await API.post("/reseller/me/custom-domain", {
    domain: dominio,
  });
  const { data: { reseller } } = await API.get("/reseller/me");
  const alvoCname = `${reseller.slug}.zap-api.tech`;

  console.log("Crie estes registros no DNS:");
  console.log(`  TXT   ${registro.verification?.name} = ${registro.verification?.value}`);
  console.log(`  CNAME ${dominio} -> ${alvoCname}`);

  // 2. Espera o CNAME propagar
  const propagou = await aguardarPropagacao(dominio, alvoCname);
  if (!propagou) throw new Error("DNS não propagou em 15 minutos");

  // 3. Dispara a verificação até o certificado ficar pronto
  for (let i = 0; i < 20; i++) {
    const { data: status } = await API.post("/reseller/me/custom-domain/verify");
    if (status.status === "active") {
      console.log(`🎉 ${dominio} ativo com SSL`);
      return status;
    }
    if (status.status === "failed") {
      throw new Error("Verificação de posse falhou — revise o registro TXT");
    }
    console.log(`Status: ${status.status}, tentando novamente...`);
    await new Promise((r) => setTimeout(r, 10_000));
  }
  throw new Error("Domínio não ficou ativo em 200 segundos");
}

ativarDominio("api.suaempresa.com.br");

O que muda para o cliente final

Antes (sem domínio próprio)

// Código do cliente final
const ZAP = axios.create({
  baseURL: "https://api.zap-api.tech/v1",
  headers: { Authorization: "Bearer tk_xxx" },
});

Depois (com domínio próprio)

// Código do cliente final
const SUA_API = axios.create({
  baseURL: "https://api.suaempresa.com.br/v1",
  headers: { Authorization: "Bearer tk_xxx" },
});

Mesmo token, mesma API, URL com sua marca. Para o cliente, é como se você fosse o provedor.

E os webhooks?

Aqui não muda nada do nosso lado — a URL de webhook é a do seu endpoint, para onde a gente entrega os eventos. Se você quiser que o cliente veja sua marca aí também, aponte um subdomínio seu para a sua própria infraestrutura:

https://webhook.suaempresa.com.br/eventos

É um CNAME (ou A) para o seu servidor, não para a ZAP-API. O domínio customizado registrado no passo 1 cobre o painel e a API — um hostname por conta reseller.

Checklist pré-ativação

• ☑ TXT de posse e CNAME criados com os valores do passo 1
• ☑ DNS propagou (verificado com dig/nslookup)
• ☑ POST /v1/reseller/me/custom-domain/verify retornou status "active"
• ☑ Teste curl funcionando: curl https://api.suaempresa.com.br/health
• ☑ Teste navegador funcionando (cadeado verde, sem aviso de SSL)
• ☑ Documentação atualizada com nova URL
• ☑ Cliente piloto testado e validado

FAQ

Quanto tempo leva o DNS propagar?

Em média 5-15 minutos para registradores brasileiros. Pode chegar a 24h em casos extremos. Para acelerar, configure TTL=300 antes de fazer mudanças (avisa servidores DNS para checarem com mais frequência).

O SSL é automático mesmo? Não preciso renovar?

Sim, automático. O certificado é emitido e renovado antes da expiração pela camada de borda, sem ação sua. Se houver falha de renovação, alertamos por email.

Posso ter múltiplos domínios para o mesmo reseller?

Não — é um hostname por conta reseller. Chamar POST /v1/reseller/me/custom-domain com um domínio diferente substitui o anterior (o hostname antigo é removido da borda). Se você atende marcas realmente distintas, o caminho é uma conta reseller por marca. Para remover sem substituir, use DELETE /v1/reseller/me/custom-domain.

E se meu domínio cair (DNS down, registrador instável)?

O domínio é seu — se o seu DNS cair, sua API fica fora. Por isso recomendamos usar provedor DNS robusto (Cloudflare, Route 53, Google Cloud DNS). Para alta disponibilidade extrema, configure DNS em dois provedores diferentes.

Posso usar subdomínio em vez de domínio raiz?

Sim. Subdomínio é justamente o recomendado: api.suaempresa.com.br (subdomínio "api" do domínio raiz). Domínio raiz (suaempresa.com.br direto na API) tecnicamente funciona via ALIAS/ANAME mas requer registrador que suporte (Registro.br não suporta na configuração padrão).

Próximo passo

Ative reseller no painel e configure seu domínio em 15 minutos. Criar conta grátis.