API da Whazu

Contatos, dados do CRM, cadastro do cliente, pedidos feitos e o anúncio de onde o lead veio

Como chamar

Uma chave por empresa, no cabeçalho. A chave já diz de quem são os dados, então nenhum endpoint pede identificador de conta.

A chave é criada no painel, em Configurações e depois API, e aparece inteira uma única vez. Ela começa com whz_live_ e pode ficar presa a endereços de IP e ter data de vencimento.

Toda resposta usa o mesmo envelope: deu certo, vem success: true e o conteúdo em data; deu errado, vem error com código e mensagem. Listagem traz pagination e anda por cursor: mande em cursor o valor da chamada anterior e pare quando hasMore vier falso.

O teto é de 100 chamadas por minuto por chave, e cada resposta traz quanto sobrou nos cabeçalhos X-RateLimit. Datas saem em ISO 8601, no fuso UTC.

Escopos

contacts:readLer contatos, cadastro, pedidos e origem do anúncio

contacts:writeCriar e editar contatos

contacts:deleteArquivar contatos

Endereço base

https://app.whazu.com.br/api/v1

Primeira chamada

curl "https://app.whazu.com.br/api/v1/contacts?limit=5" \
  -H "Authorization: Bearer whz_live_..."

O que vem em um contato

Contato e CRM vêm sempre. Cadastro, pedidos e origem do anúncio você pede em include, para não pagar consulta que não vai usar.

Dados do contato

O básico da pessoa, sempre presente.

idIdentificador do contato na Whazu.

nameNome como está salvo.

phoneNumberTelefone com código do país, só dígitos.

emailE-mail, quando houver.

profilePictureUrlFoto do perfil do WhatsApp.

firstMessageA primeira mensagem que a pessoa mandou.

optInFalso quando a pessoa pediu para não receber mais.

lastMessageAtÚltima mensagem trocada.

createdAt e updatedAtEntrada e última alteração.

Dados do CRM

Onde a pessoa está no funil e de quem ela é.

stageEtapa do funil.

columnColuna do quadro do CRM: id, nome e papel.

tagsEtiquetas aplicadas, com nome e cor.

sellerNameVendedor responsável.

assignedAtQuando o lead caiu para esse vendedor.

productNameProduto ligado ao lead.

sessionNameNúmero da empresa que atendeu.

Cadastro do cliente

include=profile

O que o card Dados do Cliente mostra no perfil. Vem do que o atendente digitou ou do que a venda trouxe.

cpfCPF do cliente.

birthDateData de nascimento, no formato AAAA-MM-DD.

genderM, F ou I.

address.zipCEP.

address.street e numberRua e número.

address.complementComplemento.

address.neighborhoodBairro.

address.city e stateCidade e estado.

Pedidos feitos

include=orders

As compras do contato nas plataformas conectadas: Yampi, Payt, Braip e B4You. Até 20, do mais novo para o mais antigo.

platformyampi, payt, braip ou b4you.

orderIdIdentificador do pedido na plataforma.

orderNumberNúmero do pedido, quando a plataforma manda.

statusSituação informada pela plataforma.

paymentMethodForma de pagamento.

totalValor total, em reais.

productNameProduto comprado.

trackingCodeCódigo de rastreio, quando existe.

createdAtData do pedido.

Origem do anúncio

include=origin

De onde o lead veio: campanha, conjunto e anúncio. Do clique para WhatsApp saem o id do anúncio, o texto, a imagem e o texto do botão.

campaignId e campaignNameCampanha.

adsetId e adsetNameConjunto de anúncios.

adId e adNameAnúncio.

ctwa.adIdId do anúncio clicado, como a Meta mandou no referral.

ctwa.textTexto do anúncio.

ctwa.imageUrlImagem do anúncio, já guardada por nós.

ctwa.headlineTexto do botão do anúncio.

Contato com include=all

{
  "id": "b1f1c0e4-3a2d-4c19-9f7a-0d5c6e8b21aa",
  "phoneNumber": "5511987654321",
  "name": "Marina Alves",
  "email": "marina@exemplo.com.br",
  "stage": "pago",
  "column": {
    "id": "5d2b9a11-7c34-4e60-a8f2-91b7c3d5e0a4",
    "name": "Pago",
    "kind": "pago"
  },
  "tags": [
    {
      "id": "7c0a1e22-90b4-4d7f-8c11-2f9d3b5a6e01",
      "name": "Quente",
      "color": "#22d3ee"
    }
  ],
  "profilePictureUrl": "https://app.whazu.com.br/uploads/fotos/5511987654321.jpg",
  "sessionName": "comercial",
  "firstMessage": "Vi o anúncio, quero saber o preço",
  "optIn": true,
  "sellerName": "Camila",
  "assignedAt": "2026-09-18T13:56:02.000Z",
  "productName": "Kit Verão",
  "lastMessageAt": "2026-09-18T14:02:11.000Z",
  "createdAt": "2026-09-18T13:55:40.000Z",
  "updatedAt": "2026-09-18T14:02:11.000Z",
  "profile": {
    "cpf": "12345678901",
    "birthDate": "1991-03-24",
    "gender": "F",
    "address": {
      "zip": "01310930",
      "street": "Avenida Paulista",
      "number": "1578",
      "complement": "apto 71",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP"
    }
  },
  "orders": [
    {
      "platform": "payt",
      "orderId": "PT-8841203",
      "orderNumber": null,
      "status": "paid",
      "paymentMethod": "pix",
      "total": 259.9,
      "productName": "Kit Verão",
      "trackingCode": null,
      "createdAt": "2026-09-18T14:10:55.000Z"
    }
  ],
  "origin": {
    "campaignId": "23861234567890123",
    "campaignName": "Verão 2026 · conversas",
    "adsetId": "23861234567890456",
    "adsetName": "Mulheres 25 a 44 · Sudeste",
    "adId": "23861234567890789",
    "adName": "Criativo 07 · depoimento",
    "ctwa": {
      "adId": "23861234567890789",
      "text": "O Kit Verão chegou. Fale com a gente e garanta o seu.",
      "imageUrl": "https://app.whazu.com.br/uploads/anuncios/23861234567890789.jpg",
      "headline": "Enviar mensagem"
    }
  }
}

GET/api/v1/contacts

Listar contatos

Os contatos não arquivados, do mais novo para o mais antigo, com filtro e paginação.

Escopo: contacts:read

Parâmetros de busca

searchstring

Procura em nome, telefone e e-mail ao mesmo tempo.

phonestring

Trecho do telefone.

tagstring

Nome exato da etiqueta.

stagestring

Etapa do funil.

dateFromdata ISO 8601

Criados a partir desta data.

dateTodata ISO 8601

Criados até esta data.

cursorstring

Valor devolvido em pagination.cursor da chamada anterior.

limitinteiro

De 1 a 100. O padrão é 20.

Requisição

curl "https://app.whazu.com.br/api/v1/contacts" \
  -H "Authorization: Bearer whz_live_..."

Resposta 200

{
  "success": true,
  "data": [
    {
      "id": "b1f1c0e4-3a2d-4c19-9f7a-0d5c6e8b21aa",
      "phoneNumber": "5511987654321",
      "name": "Marina Alves",
      "email": "marina@exemplo.com.br",
      "stage": "pago",
      "tags": [
        {
          "id": "7c0a1e22-90b4-4d7f-8c11-2f9d3b5a6e01",
          "name": "Quente",
          "color": "#22d3ee"
        }
      ],
      "profilePictureUrl": "https://app.whazu.com.br/uploads/fotos/5511987654321.jpg",
      "optIn": true,
      "lastMessageAt": "2026-09-18T14:02:11.000Z",
      "createdAt": "2026-09-18T13:55:40.000Z",
      "updatedAt": "2026-09-18T14:02:11.000Z"
    }
  ],
  "pagination": {
    "cursor": "b1f1c0e4-3a2d-4c19-9f7a-0d5c6e8b21aa",
    "hasMore": true
  }
}

GET/api/v1/contacts/{id}

Ver um contato

O contato inteiro. Com include você pede também o cadastro do cliente, os pedidos e a origem do anúncio.

Escopo: contacts:read

Parâmetros do caminho

iduuid

Identificador do contato.obrigatório

Parâmetros de busca

includestring

Blocos extras, separados por vírgula: profile, orders, origin. O valor all liga os três. Sem o parâmetro vêm só contato e CRM.

Requisição

curl "https://app.whazu.com.br/api/v1/contacts/b1f1c0e4-3a2d-4c19-9f7a-0d5c6e8b21aa?include=all" \
  -H "Authorization: Bearer whz_live_..."

Resposta 200

{
  "success": true,
  "data": {
    "id": "b1f1c0e4-3a2d-4c19-9f7a-0d5c6e8b21aa",
    "phoneNumber": "5511987654321",
    "name": "Marina Alves",
    "email": "marina@exemplo.com.br",
    "stage": "pago",
    "column": {
      "id": "5d2b9a11-7c34-4e60-a8f2-91b7c3d5e0a4",
      "name": "Pago",
      "kind": "pago"
    },
    "tags": [
      {
        "id": "7c0a1e22-90b4-4d7f-8c11-2f9d3b5a6e01",
        "name": "Quente",
        "color": "#22d3ee"
      }
    ],
    "profilePictureUrl": "https://app.whazu.com.br/uploads/fotos/5511987654321.jpg",
    "sessionName": "comercial",
    "firstMessage": "Vi o anúncio, quero saber o preço",
    "optIn": true,
    "sellerName": "Camila",
    "assignedAt": "2026-09-18T13:56:02.000Z",
    "productName": "Kit Verão",
    "lastMessageAt": "2026-09-18T14:02:11.000Z",
    "createdAt": "2026-09-18T13:55:40.000Z",
    "updatedAt": "2026-09-18T14:02:11.000Z",
    "profile": {
      "cpf": "12345678901",
      "birthDate": "1991-03-24",
      "gender": "F",
      "address": {
        "zip": "01310930",
        "street": "Avenida Paulista",
        "number": "1578",
        "complement": "apto 71",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP"
      }
    },
    "orders": [
      {
        "platform": "payt",
        "orderId": "PT-8841203",
        "orderNumber": null,
        "status": "paid",
        "paymentMethod": "pix",
        "total": 259.9,
        "productName": "Kit Verão",
        "trackingCode": null,
        "createdAt": "2026-09-18T14:10:55.000Z"
      }
    ],
    "origin": {
      "campaignId": "23861234567890123",
      "campaignName": "Verão 2026 · conversas",
      "adsetId": "23861234567890456",
      "adsetName": "Mulheres 25 a 44 · Sudeste",
      "adId": "23861234567890789",
      "adName": "Criativo 07 · depoimento",
      "ctwa": {
        "adId": "23861234567890789",
        "text": "O Kit Verão chegou. Fale com a gente e garanta o seu.",
        "imageUrl": "https://app.whazu.com.br/uploads/anuncios/23861234567890789.jpg",
        "headline": "Enviar mensagem"
      }
    }
  }
}

GET/api/v1/contacts/search

Buscar contatos

Busca por texto, telefone ou etiqueta. Pelo menos um dos três é obrigatório.

Escopo: contacts:read

Parâmetros de busca

qstring

Texto procurado em nome, telefone e e-mail.

phonestring

Trecho do telefone.

tagstring

Nome exato da etiqueta.

cursorstring

Valor devolvido em pagination.cursor.

limitinteiro

De 1 a 100. O padrão é 20.

Erros específicos

400 VALIDATION_ERROR Nenhum dos parâmetros q, phone ou tag foi enviado.

Requisição

curl "https://app.whazu.com.br/api/v1/contacts/search" \
  -H "Authorization: Bearer whz_live_..."

Resposta 200

{
  "success": true,
  "data": [
    {
      "id": "b1f1c0e4-3a2d-4c19-9f7a-0d5c6e8b21aa",
      "phoneNumber": "5511987654321",
      "name": "Marina Alves",
      "email": "marina@exemplo.com.br",
      "stage": "pago",
      "tags": [
        "vip"
      ],
      "optIn": true,
      "lastMessageAt": "2026-09-18T14:02:11.000Z",
      "createdAt": "2026-09-18T13:55:40.000Z"
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false
  }
}

POST/api/v1/contacts

Criar contato

Cadastra a pessoa e já coloca na coluna de entrada do funil, igual ao contato criado pela tela.

Escopo: contacts:write

Corpo da requisição

namestring

Nome, de 1 a 255 caracteres.obrigatório

phonestring

Telefone com código do país.obrigatório

emailstring

E-mail válido.

tagsarray de string

Etiquetas.

notesstring

Anotação livre.

stagestring

Etapa do funil. O padrão é new.

Erros específicos

409 CONFLICT Já existe contato com esse telefone.

Requisição

curl "https://app.whazu.com.br/api/v1/contacts" \
  -X POST \
  -H "Authorization: Bearer whz_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Marina Alves","phone":"5511987654321","email":"marina@exemplo.com.br","tags":["vip"]}'

Resposta 201

{
  "success": true,
  "data": {
    "id": "b1f1c0e4-3a2d-4c19-9f7a-0d5c6e8b21aa",
    "phoneNumber": "5511987654321",
    "name": "Marina Alves",
    "email": "marina@exemplo.com.br",
    "stage": "new",
    "tags": [
      "vip"
    ],
    "createdAt": "2026-09-18T13:55:40.000Z"
  }
}

PATCH/api/v1/contacts/{id}

Editar contato

Altera só o que for enviado. O telefone não muda por aqui.

Escopo: contacts:write

Parâmetros do caminho

iduuid

Identificador do contato.obrigatório

Corpo da requisição

namestring

Novo nome.

emailstring

Novo e-mail.

tagsarray de string

Substitui as etiquetas.

notesstring

Anotação.

stagestring

Nova etapa do funil.

Requisição

curl "https://app.whazu.com.br/api/v1/contacts/b1f1c0e4-3a2d-4c19-9f7a-0d5c6e8b21aa" \
  -X PATCH \
  -H "Authorization: Bearer whz_live_..." \
  -H "Content-Type: application/json" \
  -d '{"stage":"negociacao","notes":"Pediu proposta por e-mail"}'

Resposta 200

{
  "success": true,
  "data": {
    "id": "b1f1c0e4-3a2d-4c19-9f7a-0d5c6e8b21aa",
    "phoneNumber": "5511987654321",
    "name": "Marina Alves",
    "email": "marina@exemplo.com.br",
    "stage": "negociacao",
    "tags": [
      "vip"
    ],
    "createdAt": "2026-09-18T13:55:40.000Z",
    "updatedAt": "2026-09-19T09:12:03.000Z"
  }
}

DELETE/api/v1/contacts/{id}

Arquivar contato

O contato sai das listagens e o histórico continua guardado. Não é exclusão definitiva.

Escopo: contacts:delete

Parâmetros do caminho

iduuid

Identificador do contato.obrigatório

Requisição

curl "https://app.whazu.com.br/api/v1/contacts/b1f1c0e4-3a2d-4c19-9f7a-0d5c6e8b21aa" \
  -X DELETE \
  -H "Authorization: Bearer whz_live_..."

Resposta 200

{
  "success": true,
  "data": {
    "id": "b1f1c0e4-3a2d-4c19-9f7a-0d5c6e8b21aa",
    "deleted": true
  }
}

Erros

O código HTTP diz o tipo do problema e o campo error.code diz o motivo. Trate pelo código, não pela mensagem.

400VALIDATION_ERRORAlgum campo não passou na validação.

401UNAUTHORIZEDChave ausente, com formato errado, inativa, revogada ou vencida.

402FORBIDDENConta bloqueada por falta de pagamento.

403FORBIDDENA chave não tem o escopo exigido, ou o IP está fora da lista.

404NOT_FOUNDO contato não existe nessa empresa.

409CONFLICTJá existe contato com esse telefone.

429RATE_LIMITEDPassou das 100 chamadas por minuto da chave.

500INTERNAL_ERRORFalha do nosso lado. A chamada pode ser repetida.

Levar para outra ferramenta

A mesma referência em arquivo, no padrão OpenAPI 3.1.

Postman, Insomnia, n8n, Make e agentes de inteligência artificial importam esse arquivo e montam as chamadas sozinhos. Ele é gerado da mesma fonte desta página, então não fica desatualizado.

Baixar

curl -O https://app.whazu.com.br/documentacao/openapi.json