{"openapi":"3.1.0","info":{"title":"API da Whazu","version":"1.0.0","summary":"Contatos da Whazu, com dados do CRM, cadastro do cliente, pedidos feitos e origem do anúncio.","description":"API REST da Whazu. A autenticação é por chave da empresa, no cabeçalho Authorization, no formato Bearer whz_live_...\n\nA chave é criada no painel, em Configurações e depois API.\n\nEm GET /contacts/{id}, o parâmetro include liga os blocos extras: profile (cadastro do cliente), orders (pedidos feitos) e origin (campanha, conjunto, anúncio e o criativo do clique para WhatsApp). O valor all liga os três.\n\nListagens andam por cursor: mande em cursor o valor devolvido em pagination.cursor e pare quando hasMore vier falso.\n\nDocumentação: https://app.whazu.com.br/documentacao","contact":{"name":"Suporte Whazu","url":"https://app.whazu.com.br/suporte"}},"servers":[{"url":"https://app.whazu.com.br/api/v1","description":"Produção"}],"tags":[{"name":"Contatos","description":"Contatos, CRM, cadastro do cliente, pedidos e origem do anúncio."}],"security":[{"bearerAuth":[]}],"paths":{"/contacts":{"get":{"tags":["Contatos"],"operationId":"listarContatos","summary":"Listar contatos","description":"Os contatos não arquivados, do mais novo para o mais antigo, com filtro e paginação.\n\nEscopo exigido: contacts:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"search","in":"query","required":false,"description":"Procura em nome, telefone e e-mail ao mesmo tempo.","schema":{"type":"string"}},{"name":"phone","in":"query","required":false,"description":"Trecho do telefone.","schema":{"type":"string"}},{"name":"tag","in":"query","required":false,"description":"Nome exato da etiqueta.","schema":{"type":"string"}},{"name":"stage","in":"query","required":false,"description":"Etapa do funil.","schema":{"type":"string"}},{"name":"dateFrom","in":"query","required":false,"description":"Criados a partir desta data.","schema":{"type":"string","format":"date-time"}},{"name":"dateTo","in":"query","required":false,"description":"Criados até esta data.","schema":{"type":"string","format":"date-time"}},{"name":"cursor","in":"query","required":false,"description":"Valor devolvido em pagination.cursor da chamada anterior.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"De 1 a 100. O padrão é 20.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Deu certo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sucesso"},"example":{"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}}}}},"401":{"description":"Chave ausente, com formato errado, inativa, revogada ou vencida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"A chave não tem o escopo exigido, ou o IP está fora da lista.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"O contato não existe nessa empresa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Passou das 100 chamadas por minuto da chave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}},"post":{"tags":["Contatos"],"operationId":"criarContato","summary":"Criar contato","description":"Cadastra a pessoa e já coloca na coluna de entrada do funil, igual ao contato criado pela tela.\n\nEscopo exigido: contacts:write","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Nome, de 1 a 255 caracteres."},"phone":{"type":"string","description":"Telefone com código do país."},"email":{"type":"string","description":"E-mail válido."},"tags":{"type":"array","items":{"type":"string"},"description":"Etiquetas."},"notes":{"type":"string","description":"Anotação livre."},"stage":{"type":"string","description":"Etapa do funil. O padrão é new."}},"required":["name","phone"]},"example":{"name":"Marina Alves","phone":"5511987654321","email":"marina@exemplo.com.br","tags":["vip"]}}}},"responses":{"201":{"description":"Deu certo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sucesso"},"example":{"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"}}}}},"401":{"description":"Chave ausente, com formato errado, inativa, revogada ou vencida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"A chave não tem o escopo exigido, ou o IP está fora da lista.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"O contato não existe nessa empresa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"409":{"description":"Já existe contato com esse telefone.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Passou das 100 chamadas por minuto da chave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/contacts/{id}":{"get":{"tags":["Contatos"],"operationId":"verContato","summary":"Ver um contato","description":"O contato inteiro. Com include você pede também o cadastro do cliente, os pedidos e a origem do anúncio.\n\nEscopo exigido: contacts:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador do contato.","schema":{"type":"string","format":"uuid"}},{"name":"include","in":"query","required":false,"description":"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.","schema":{"type":"string"}}],"responses":{"200":{"description":"Deu certo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sucesso"},"example":{"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"}}}}}}},"401":{"description":"Chave ausente, com formato errado, inativa, revogada ou vencida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"A chave não tem o escopo exigido, ou o IP está fora da lista.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"O contato não existe nessa empresa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Passou das 100 chamadas por minuto da chave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}},"patch":{"tags":["Contatos"],"operationId":"editarContato","summary":"Editar contato","description":"Altera só o que for enviado. O telefone não muda por aqui.\n\nEscopo exigido: contacts:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador do contato.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Novo nome."},"email":{"type":"string","description":"Novo e-mail."},"tags":{"type":"array","items":{"type":"string"},"description":"Substitui as etiquetas."},"notes":{"type":"string","description":"Anotação."},"stage":{"type":"string","description":"Nova etapa do funil."}}},"example":{"stage":"negociacao","notes":"Pediu proposta por e-mail"}}}},"responses":{"200":{"description":"Deu certo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sucesso"},"example":{"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"}}}}},"401":{"description":"Chave ausente, com formato errado, inativa, revogada ou vencida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"A chave não tem o escopo exigido, ou o IP está fora da lista.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"O contato não existe nessa empresa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Passou das 100 chamadas por minuto da chave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}},"delete":{"tags":["Contatos"],"operationId":"arquivarContato","summary":"Arquivar contato","description":"O contato sai das listagens e o histórico continua guardado. Não é exclusão definitiva.\n\nEscopo exigido: contacts:delete","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Identificador do contato.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deu certo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sucesso"},"example":{"success":true,"data":{"id":"b1f1c0e4-3a2d-4c19-9f7a-0d5c6e8b21aa","deleted":true}}}}},"401":{"description":"Chave ausente, com formato errado, inativa, revogada ou vencida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"A chave não tem o escopo exigido, ou o IP está fora da lista.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"O contato não existe nessa empresa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Passou das 100 chamadas por minuto da chave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/contacts/search":{"get":{"tags":["Contatos"],"operationId":"buscarContatos","summary":"Buscar contatos","description":"Busca por texto, telefone ou etiqueta. Pelo menos um dos três é obrigatório.\n\nEscopo exigido: contacts:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","required":false,"description":"Texto procurado em nome, telefone e e-mail.","schema":{"type":"string"}},{"name":"phone","in":"query","required":false,"description":"Trecho do telefone.","schema":{"type":"string"}},{"name":"tag","in":"query","required":false,"description":"Nome exato da etiqueta.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Valor devolvido em pagination.cursor.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"De 1 a 100. O padrão é 20.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Deu certo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sucesso"},"example":{"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}}}}},"400":{"description":"Nenhum dos parâmetros q, phone ou tag foi enviado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, com formato errado, inativa, revogada ou vencida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"A chave não tem o escopo exigido, ou o IP está fora da lista.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"O contato não existe nessa empresa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Passou das 100 chamadas por minuto da chave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Chave da empresa, começando com whz_live_. Escopos: contacts:read, contacts:write, contacts:delete."}},"schemas":{"Sucesso":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"description":"Conteúdo da resposta"},"pagination":{"$ref":"#/components/schemas/Paginacao"}},"required":["success","data"]},"Erro":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string","examples":["VALIDATION_ERROR","UNAUTHORIZED","FORBIDDEN","FORBIDDEN","NOT_FOUND","CONFLICT","RATE_LIMITED","INTERNAL_ERROR"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["success","error"]},"Paginacao":{"type":"object","properties":{"cursor":{"type":["string","null"],"description":"Valor a mandar em cursor para a próxima página."},"hasMore":{"type":"boolean","description":"Falso quando acabou."}}}}}}