Introdução

O PEPINO ZAP é uma API REST que permite conectar números de WhatsApp ao seu sistema e enviar e receber mensagens de forma programática. Você cria instâncias, pareia cada uma a um aparelho via QR Code e, a partir daí, envia mensagens de texto e mídia por requisições HTTP e recebe os eventos de entrada e de status por webhook ou WebSocket. Além do transporte, a plataforma é o system of record das suas conversas — ela guarda o histórico (mensagens + mídia hospedada; você lê pela API, sem banco próprio) e expõe uma camada de Inbox/CRM (etiquetas, atribuição a atendentes, funil, relatórios) pela mesma key.

Esta página é o seu mapa mental antes de ir para os guias: o que a API faz, como os recursos se organizam (Organização → Projeto → Instância), a diferença entre os modos teste e produção, como autenticar e quais pré-requisitos liberam o uso real. Se você é novo por aqui, leia até o fim — cada conceito é retomado nos guias com exemplos prontos para copiar.

O que você consegue fazer

Com uma única API key você cobre todo o ciclo de uma conversa de WhatsApp — do envio à gestão do atendimento:

1. Conectar um número — crie uma instância e pareie-a com um aparelho lendo um QR Code (como o "Aparelhos conectados" do WhatsApp).
2. Enviar mensagens — texto, mídia (imagem, vídeo, áudio, documento), localização, contato, sticker, reação e enquete, por chamadas HTTP.
3. Receber mensagens e status — mensagens de entrada e confirmações de entrega/leitura chegam por webhook (entrega garantida, com retry) ou WebSocket (tempo real, sem endpoint público).
4. Ler o histórico — conversas, mensagens e mídia ficam persistidas na nossa infraestrutura; você lista e pagina pela API (GET /v1/inbox/conversations e .../conversations/{id}/messages, com cursor) quando precisar — sem manter banco próprio.
5. Gerir o atendimento (CRM) — além do transporte, a plataforma expõe um Inbox completo pela mesma key: etiquetas, atribuição a atendentes, status e motivos de encerramento, funil de vendas e relatórios de gestão.

Como a plataforma é o system of record das suas conversas, você não precisa manter banco de dados nem storage de mídia próprios só para o WhatsApp — ler do histórico pela API é suficiente para a maioria das integrações. Os metadados de atendimento (etiquetas, atribuição, funil) também vivem aqui. Detalhes em Persistência e histórico e na Referência da API (seções Inbox e Gestão).

Modelo de recursos

Os recursos seguem uma hierarquia de três níveis. Para integrar, na prática você trabalha sempre no nível do Projeto — é a ele que sua API key está amarrada.

A API key é escopada a um único Projeto: toda instância, mensagem ou webhook que você cria, lista ou remove com a key pertence ao Projeto dela. A Organização é o container de conta/cobrança acima dos Projetos — ela existe, mas não aparece nas respostas da API (os objetos retornam projectId, não a organização); você não precisa manipulá-la para integrar.

A geração de keys é self-service: você se cadastra, confirma o e-mail e gera a key no painel. A key crua é exibida uma única vez no momento da criação — guarde-a em local seguro, pois não há como recuperá-la depois (se perder, revogue e gere outra). O passo a passo está em Autenticação.

Glossário rápido

Termos que aparecem em toda a documentação:

Modos: teste e produção

Uma única conta, com dois modos — igual ao test/live do Stripe. O modo é determinado pela base URL (host) da API: hosts que começam com sandbox. operam em teste; api. opera em produção. Os dados são totalmente isolados entre os modos — instâncias, conversas e webhooks de teste nunca aparecem em produção, e vice-versa.

É o host que decide o modo, não a key — mas a key tem que casar com o host. Uma key de produção (pzk_live_) usada no host de teste (sandbox.*), ou o contrário, é rejeitada com 401. Use sempre a key do mesmo modo da base URL.

# pzk_live_ no host de teste → 401 (key do modo errado)
curl https://sandbox.pepinozap.com.br/v1/instances \
  -H "Authorization: Bearer pzk_live_xxxxxxxxxxxxxxxx"

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "chave de API inválida para este ambiente/modo"
  }
}

Autenticação em uma frase

Envie a API key no header Authorization com o esquema Bearer em todas as chamadas REST:

curl https://api.pepinozap.com.br/v1/instances \
  -H "Authorization: Bearer pzk_live_xxxxxxxxxxxxxxxx"

As únicas exceções são os transportes que o navegador abre sem poder definir headers — o stream SSE de QR Code (GET /v1/instances/{id}/qr) e o WebSocket de eventos (/v1/ws). Nesses dois casos, a key vai na query string como ?token=<API_KEY>. Em qualquer outro endpoint, use sempre o header Authorization. O detalhamento (inclusive o token efêmero de 2 minutos para não expor a key na URL do SSE) está em Autenticação.

Pré-requisitos para operar (402 e 429)

Ter uma API key válida não basta para enviar de verdade. As ações de uso real — conectar um número e enviar mensagens — passam por gates de negócio; as ações de leitura e o pareamento por QR Code ficam sempre liberadas.

• 402 PAYMENT_REQUIRED — em produção, o Projeto não tem assinatura ativa, ou um Projeto no modo API ficou sem créditos. Distinga os dois casos pela message. Resolução: assinar ou recarregar em Meu plano, no painel. Em teste, esses gates são liberados (não ocorre 402).
• 429 RATE_LIMITED — apenas em teste: o teto de 100 mensagens/dia por Projeto foi atingido. Em produção não ocorre.

Como começar

Siga os guias nesta ordem — eles formam o caminho mínimo de ponta a ponta:

1. Quick start — o fluxo completo num só lugar: obter a key, criar uma instância, parear via QR Code e enviar a primeira mensagem.
2. Autenticação — gerar e usar a API key no header Authorization: Bearer, os modos teste/produção e o fallback ?token=.
3. Sua primeira instância — o ciclo de status de DISCONNECTED até CONNECTED, o pareamento por QR (polling, recomendado, e SSE) e as configurações da instância.

Referência rápida de erros

Toda resposta de erro segue o mesmo envelope. Use o campo code (estável) no seu tratamento de erros, não a message (apenas legível).

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Body inválido"
  }
}

Próximos passos

• Referência da API — endpoints de instâncias e mensagens (texto, mídia, localização, contato, sticker, reação, enquete), configurações da instância, payloads de requisição e resposta, e erros esperados.
• Inbox e Gestão (CRM) — ler conversas e mensagens persistidas (system of record) com mídia hospedada, e gerir o atendimento: etiquetas, atribuição, status/motivos, funil e relatórios — tudo pela mesma key.
• Persistência e histórico — como a plataforma guarda suas conversas e como ler o histórico pelo Inbox sem manter banco próprio.
• Webhooks — os dez eventos (mensagem, instância, chamada, grupo, contato e etiqueta), envelope de entrega e verificação de assinatura.
• WebSocket — os mesmos eventos em tempo real por conexão persistente, sem endpoint público.