Quick start

O PEPINO ZAP é uma API REST que integra o WhatsApp ao seu sistema. Este guia apresenta o caminho mínimo ponta a ponta para colocar uma integração no ar:

1. Obter a API key
2. Criar uma instância
3. Parear via QR Code
4. Enviar a primeira mensagem
5. Receber mensagens e status

Cada passo traz o curl (ou o snippet equivalente), a resposta JSON real e os erros que você pode encontrar. Os exemplos usam o ambiente de teste (sandbox); para produção, basta trocar a base URL e a API key (veja abaixo). Não é preciso ler nada antes — mas, se quiser o contexto de autenticação e modos, ele está em Autenticação.

Conceitos em 30 segundos

Três palavras se repetem ao longo do guia:

• Projeto — a unidade que sua API key representa. Instâncias, conversas, webhooks e a assinatura/créditos pertencem todos a um Projeto. Tudo que você cria com uma key vive dentro do Projeto dela.
• Instância — uma conexão de WhatsApp dentro do Projeto (um número pareado). Você pode ter mais de uma, conforme a cota do plano.
• Modo (teste/produção) — uma única conta, dois ambientes isolados, decididos pelo host. O sandbox é grátis (com teto); a produção exige plano ativo. Dados de um modo nunca aparecem no outro.

Base URL e variáveis

Defina a base URL e a API key uma única vez no shell — os exemplos abaixo reaproveitam essas variáveis.

export BASE_URL="https://sandbox.pepinozap.com.br"
export API_KEY="pzk_test_xxxxxxxxxxxxxxxx"

Todas as chamadas REST levam o header Authorization: Bearer <API_KEY>. A única exceção é o stream de QR via SSE, que autentica por ?token= (explicado no passo 3) porque o EventSource do navegador não envia headers customizados.

Envelope de erro

Sempre que algo dá errado, a resposta segue o mesmo formato — guarde este shape, ele se repete em todos os passos:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key ausente ou inválida"
  }
}

Use o code (estável, para switch no seu código) e exiba a message (legível, em PT-BR) para o usuário/log.

1. Obtenha a API key

A geração de keys é self-service — você não depende de ninguém para começar:

1. Cadastre-se (empresa, CNPJ, e-mail e senha) em app.pepinozap.com.br. O cadastro exige confirmação de e-mail.
2. Confirme o e-mail pelo link enviado. O login só libera depois disso.
3. No painel, vá em Integrações → API Keys. No topo há um toggle Teste / Produção — escolha Teste para seguir este guia e gere a key.

A key crua aparece uma única vez, no momento da criação — copie e guarde em variável de ambiente (não há como recuperá-la depois; se perder, revogue e crie outra). O modo da key é o do toggle no instante em que ela foi gerada: Teste → pzk_test_, Produção → pzk_live_.

O passo a passo completo está em Autenticação.

Confira que a key funciona

Antes de seguir, faça uma chamada de leitura (não exige plano, não consome nada). Listar instâncias de um Projeto novo devolve um array vazio:

curl "$BASE_URL/v1/instances" \
  -H "Authorization: Bearer $API_KEY"

Resposta 200:

[]

Se você receber 401, a key está ausente/inválida ou não casa com o host (veja o Callout acima). Se receber qualquer JSON sem error, a autenticação está ok.

2. Crie uma instância

Uma instância representa uma conexão de WhatsApp dentro do seu Projeto. Criá-la é só registrar o slot — ela nasce desconectada; o pareamento com o número vem no passo 3.

curl -X POST "$BASE_URL/v1/instances" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "minha-instancia" }'

Resposta 201 Created:

{
  "id": "cm5x8a9k20001abc123def456",
  "projectId": "cm5x8a9k20000abc123def000",
  "name": "minha-instancia",
  "status": "DISCONNECTED",
  "phoneNumber": null,
  "jid": null,
  "settings": {
    "rejectCalls": false,
    "rejectCallMessage": "",
    "ignoreGroups": false,
    "alwaysOnline": false,
    "readReceipts": false
  },
  "createdAt": "2026-05-29T22:15:00Z",
  "updatedAt": "2026-05-29T22:15:00Z"
}

Campos da resposta:

• id — guarde este valor: ele identifica a instância em todas as próximas chamadas (substitui o {id} nas URLs).
• projectId — o Projeto ao qual a instância pertence (o da sua key).
• status — começa sempre em DISCONNECTED. O ciclo completo é DISCONNECTED → CONNECTING → QR_PENDING → CONNECTED; veja Ciclo de vida.
• phoneNumber / jid — null até o pareamento; preenchidos quando a instância conecta.
• settings — configurações de comportamento (rejeitar chamadas, ignorar grupos etc.), todas desligadas por padrão. Como ajustar: Configurações da instância.

# Guarde o id para reusar nos próximos passos:
export INSTANCE_ID="cm5x8a9k20001abc123def456"

Erros possíveis na criação

Como desfazer

Para remover a instância (retorna 204 No Content, sem corpo):

curl -X DELETE "$BASE_URL/v1/instances/$INSTANCE_ID" \
  -H "Authorization: Bearer $API_KEY"

3. Pareie via QR Code

A instância nasceu DISCONNECTED. Para conectá-la a um número, você gera um QR Code e o escaneia no app do WhatsApp do aparelho (Aparelhos conectados → Conectar um aparelho). Há duas formas de obter esse QR.

Recomendamos o polling: cada requisição é curta e atravessa antivírus e proxies corporativos sem problemas. O stream SSE é uma alternativa, porém alguns antivírus e proxies bufferizam streams e impedem a entrega do QR Code. O guia completo (com o vocabulário rico de status do SSE) está em Sua primeira instância.

Polling (recomendado)

Faça GET /v1/instances/{id}/qr/poll a cada ~2 segundos. Diferente do SSE, esse endpoint usa o header Authorization normalmente.

curl "$BASE_URL/v1/instances/$INSTANCE_ID/qr/poll" \
  -H "Authorization: Bearer $API_KEY"

Enquanto não conectado, a resposta 200 traz o QR atual:

{
  "connected": false,
  "qr": {
    "code": "2@AbCdEf123...,Xyz==,...",
    "at": "2026-05-29T22:15:10Z"
  }
}

Depois que o número escaneia e pareia:

{
  "connected": true,
  "qr": null
}

Como interpretar:

• connected — true quando o pareamento foi concluído. Pare o polling nesse ponto.
• qr — objeto { code, at } enquanto não conectado, ou null quando já conectado. Renderize o campo code como um QR Code (com uma biblioteca de QR) para leitura no aparelho. O code muda a cada ciclo: sempre desenhe o code mais recente que o poll retornar.

const id = process.env.INSTANCE_ID;
const apiKey = process.env.API_KEY;
const BASE_URL = 'https://sandbox.pepinozap.com.br';

const timer = setInterval(async () => {
  const res = await fetch(`${BASE_URL}/v1/instances/${id}/qr/poll`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  const { connected, qr } = await res.json();

  if (connected) {
    clearInterval(timer); // pareamento concluído — pode enviar
    return;
  }
  if (qr) {
    renderQrCode(qr.code); // desenhe "qr.code" como QR Code
  }
}, 2000);

Alternativa: stream SSE

O endpoint GET /v1/instances/{id}/qr transmite Server-Sent Events (Content-Type: text/event-stream). Como o EventSource do navegador não envia o header Authorization, este endpoint autentica pela query string ?token=<API_KEY>:

curl -N "$BASE_URL/v1/instances/$INSTANCE_ID/qr?token=$API_KEY"

O stream emite estes eventos:

• ready — evento inicial, indicando que o fluxo foi aberto.
• qr — data contém { code, at }; renderize o campo code como QR Code para leitura.
• status — data contém { status, jid?, reason?, at? }, refletindo a transição da instância.
• ping — keepalive emitido periodicamente (a cada ~25s) para manter a conexão viva atrás de proxies.

Para não expor a API key crua na URL, emita um token efêmero com POST /v1/instances/{id}/qr-token (válido ~2 min, escopado a esta instância) e passe-o no ?token= em vez da key:

curl -X POST "$BASE_URL/v1/instances/$INSTANCE_ID/qr-token" \
  -H "Authorization: Bearer $API_KEY"

Resposta 200:

{ "token": "eyJhbGciOi..." }

Confirme a conexão

Após o pareamento, a instância reconecta sozinha depois de quedas, reinícios ou deploys, sem novo QR — exceto nos estados terminais BANNED e ERROR, ou se o número for deslogado no aparelho (volta a DISCONNECTED, exigindo novo pareamento). Você pode conferir o estado a qualquer momento:

curl "$BASE_URL/v1/instances/$INSTANCE_ID" \
  -H "Authorization: Bearer $API_KEY"

Com a instância pareada, a resposta 200 agora traz phoneNumber e jid preenchidos:

{
  "id": "cm5x8a9k20001abc123def456",
  "projectId": "cm5x8a9k20000abc123def000",
  "name": "minha-instancia",
  "status": "CONNECTED",
  "phoneNumber": "5511999999999",
  "jid": "5511999999999@s.whatsapp.net",
  "settings": { "rejectCalls": false, "rejectCallMessage": "", "ignoreGroups": false, "alwaysOnline": false, "readReceipts": false },
  "createdAt": "2026-05-29T22:15:00Z",
  "updatedAt": "2026-05-29T22:16:40Z"
}

4. Envie a primeira mensagem

Com a instância em CONNECTED, envie uma mensagem de texto com POST /v1/instances/{id}/messages.

curl -X POST "$BASE_URL/v1/instances/$INSTANCE_ID/messages" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "body": "Mensagem de teste"
  }'

Resposta 202 Accepted:

{ "queued": true, "to": "5511999999999" }

O mesmo fluxo em JavaScript com fetch:

const res = await fetch(`${BASE_URL}/v1/instances/${INSTANCE_ID}/messages`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ to: '5511999999999', body: 'Mensagem de teste' }),
});

const data = await res.json(); // { queued: true, to: '5511999999999' }

Erros possíveis no envio

5. Receba mensagens e status

Mensagens recebidas (message.received) e confirmações de entrega/leitura (message.status), além das mudanças de conexão da instância (instance.status), chegam por eventos — não por polling da API. Há dois transportes, que entregam os mesmos eventos, com o mesmo envelope:

Os dois podem ser usados ao mesmo tempo. Ambos são self-service via API key.

Caminho mais rápido para testar: WebSocket

Não precisa de URL pública nem cadastro. Conecte com a sua key na query (o handshake do WebSocket não permite header Authorization) e receba os eventos de todas as instâncias do Projeto:

const ws = new WebSocket(`wss://sandbox.pepinozap.com.br/v1/ws?token=${API_KEY}`);

ws.onmessage = (e) => {
  const evt = JSON.parse(e.data);
  if (evt.event === 'connected') return; // frame de confirmação inicial
  console.log(evt.event, evt.instanceId, evt.data);
};

Logo após conectar, o servidor envia { "event": "connected", "projectId": "..." }. Depois, cada evento chega como um frame de texto com o envelope:

{
  "event": "message.received",
  "instanceId": "cm5x8a9k20001abc123def456",
  "timestamp": "2026-05-29T22:16:30Z",
  "data": { }
}

Detalhes (reconexão com backoff, ciclo de vida) em WebSocket.

Entrega garantida: Webhook

Para backend, cadastre um endpoint via API e receba o secret (whsec_) na criação — guarde-o para validar a assinatura de cada entrega:

curl -X POST "$BASE_URL/v1/webhooks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "meu-endpoint",
    "url": "https://meusistema.com/webhook/pepinozap",
    "events": []
  }'

A plataforma passa a fazer POST no seu url a cada evento, com os headers X-Pepino-Event, X-Pepino-Webhook-Id e X-Pepino-Signature: sha256=<hmac-hex>. Trate as entregas de forma idempotente (o mesmo evento pode chegar mais de uma vez; deduplique pelo X-Pepino-Webhook-Id) e responda 2xx. Veja Webhooks, Eventos e Assinatura.

Erros esperados (resumo)

Os erros seguem o envelope { "error": { "code", "message" } }.

Próximos passos

• Autenticação — API keys, modos teste/produção e o 402 de plano em detalhe.
• Sua primeira instância — ciclo de vida, pareamento por QR e configurações de comportamento da instância.
• API Reference: Mensagens — envio de texto, mídia, localização, contato, figurinha, reação e enquete.
• Webhooks: Eventos — o payload de cada evento recebido.