Guia Rápido - Fluxo Completo

Guia Rápido - Fluxo Completo#

1. Registrar empresa e obter token#

bash
# Registrar
curl -X POST https://api.catcher.one/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Minha Empresa",
    "owner_email": "eu@empresa.com",
    "owner_name": "Joao",
    "password": "MinhaSenh@123"
  }'
# Salve o token retornado (ctc_xxxx...)

2. Criar e conectar instância#

bash
TOKEN="ctc_xxxx..."

# Criar instancia
curl -X POST https://api.catcher.one/v1/instances \
  -H "X-API-Key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Principal"}'
# Salve o ID retornado

INSTANCE="84c2e480-..."

# Conectar (gera QR code)
curl -X POST https://api.catcher.one/v1/instances/$INSTANCE/connect \
  -H "X-API-Key: $TOKEN"
# Escaneie o QR code no WhatsApp

# Ou use pairing code
curl -X POST https://api.catcher.one/v1/instances/$INSTANCE/pairing-code \
  -H "X-API-Key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone": "554137984905"}'

3. Enviar mensagem#

bash
# Todo envio assíncrono exige Idempotency-Key (sem ele: 400 IDEMPOTENCY_KEY_REQUIRED).
# Use um valor único por mensagem lógica; reenviar a MESMA chave devolve o mesmo
# message_id em vez de duplicar o envio.
curl -X POST https://api.catcher.one/v1/instances/$INSTANCE/messages/text \
  -H "X-API-Key: $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "to": "554137984905",
    "text": "Ola! Teste do Catcher"
  }'
# 202 { "status": "queued", "message_id": "<uuid>", "task_id": "...", "idempotency_key": "..." }

4. Configurar webhook para receber eventos#

bash
curl -X POST https://api.catcher.one/v1/webhooks \
  -H "X-API-Key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meuservidor.com/webhook",
    "events": "message.received,message.sent,message.delivered,message.read,message.played,message.delivery_failed,connection.update"
  }'
# Guarde o "secret" da resposta (só aparece aqui) para validar X-Catcher-Signature.
# O status de cada envio chega por estes eventos: não consulte a mensagem em loop.
# Veja "Boas Práticas de Integração" (assinatura, dedupe por event_id, estados finais).

5. Ouvir eventos em tempo real#

bash
# SSE
curl -N \
  -H "X-API-Key: $TOKEN" \
  "https://api.catcher.one/v1/instances/$INSTANCE/events"

# Ou via WebSocket com wscat
wscat -H "X-API-Key: $TOKEN" -c "wss://api.catcher.one/v1/instances/$INSTANCE/ws"

6. Buscar mensagem e baixar mídia recebida#

bash
# Consulta pontual (ex.: abrir uma mensagem). Para acompanhar status, use os eventos;
# para reconciliar depois de uma queda, use /events/history?after=<event_id>.
# Buscar mensagem pelo UUID do Catcher (elemento de message_ids do evento) ou pelo ID do WhatsApp (hex)
curl -H "X-API-Key: $TOKEN" \
  "https://api.catcher.one/v1/instances/$INSTANCE/message/3EB0ABC123DEF456"
# Resposta inclui media_id se a mensagem tiver midia

# Baixar midia (imagem, audio, video, documento, sticker)
MEDIA_ID="b2c3d4e5-f6a7-8901-bcde-f12345678901"
curl -o arquivo_recebido.ogg \
  -H "X-API-Key: $TOKEN" \
  "https://api.catcher.one/v1/instances/$INSTANCE/media/$MEDIA_ID"