{"openapi":"3.1.0","info":{"title":"API de Atendimento WhatsApp","version":"1.0.0","description":"Documentação completa em /desenvolvedores"},"servers":[{"url":"https://wa.aembi.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Chave de API no formato wak_..."}},"responses":{"Erro":{"description":"Erro","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","tenant_suspended","ip_not_allowed","insufficient_scope","not_found","validation_error","no_connection","connection_offline","contact_opted_out","contact_exists","conversation_closed","ticket_in_progress","erp_unavailable","media_not_found","media_expired","rate_limited","internal_error"]},"message":{"type":"string"},"requestId":{"type":"string"}}}}}}}}}},"paths":{"/api/v1/me":{"get":{"operationId":"me","tags":["Conta"],"summary":"Verificar chave","description":"Retorna a empresa (tenant) e as permissões da chave usada. Ideal para validar a integração na primeira configuração.","parameters":[],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"example":{"data":{"tenant":{"id":"cm1a2b3c4d5e6f7g8h9i0j","slug":"sua-empresa","name":"Sua Empresa"},"key":{"name":"Integração ERP","scopes":["messages:send","contacts:read"],"rateLimitPerMinute":120},"ip":"203.0.113.10"}}}}},"default":{"$ref":"#/components/responses/Erro"}}}},"/api/v1/messages":{"post":{"operationId":"enviar-mensagem","tags":["Mensagens"],"summary":"Enviar mensagem","description":"Coloca a mensagem na fila de envio e responde na hora com status queued; acompanhe a entrega pelo endpoint de consulta. Envie o cabeçalho Idempotency-Key (até 100 caracteres, ex.: o número da fatura) para poder repetir a requisição com segurança: a mesma chave devolve a mesma mensagem, sem reenviar. Por padrão, o envio sai pela conexão de atendimento. Mídias podem ser enviadas por URL https ou em base64, com até 25 MB.\n\nEscopo exigido: `messages:send`","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Opcional. Identificador único do envio (até 100 caracteres), ex.: o número da fatura. Repetir a requisição com a mesma chave devolve a mesma mensagem, sem reenviar.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to"],"properties":{"to":{"type":"string","description":"Número com DDI e DDD, só dígitos. Números brasileiros sem 55 são completados. Ex.: 5518999999999"},"type":{"type":"string","description":"text (padrão), image, video, audio ou document."},"text":{"type":"string","description":"Texto da mensagem, obrigatório para text. Até 4096 caracteres, com formatação do WhatsApp (*negrito*, _itálico_)."},"mediaUrl":{"type":"string","description":"URL https da mídia. Informe mediaUrl ou mediaBase64."},"mediaBase64":{"type":"string","description":"Conteúdo da mídia em base64, com ou sem o prefixo data:."},"mimeType":{"type":"string","description":"Tipo do arquivo, ex.: application/pdf. Obrigatório com mediaBase64."},"fileName":{"type":"string","description":"Nome exibido para documentos, ex.: fatura-2026-09.pdf."},"caption":{"type":"string","description":"Legenda de imagem, vídeo ou documento (até 1024 caracteres)."},"connection":{"type":"string","description":"Nome da conexão de envio. Padrão: a conexão de atendimento."},"name":{"type":"string","description":"Nome do contato, usado quando ele ainda não existe."},"transactional":{"type":"boolean","description":"true para mensagens transacionais (fatura, aviso técnico), que são entregues mesmo a contatos descadastrados de campanhas. Padrão: false."}}},"example":{"to":"5518999999999","type":"document","mediaUrl":"https://exemplo.com.br/faturas/2026-09.pdf","fileName":"fatura-2026-09.pdf","caption":"Sua fatura de setembro","transactional":true}}}},"responses":{"202":{"description":"Aceito para envio","content":{"application/json":{"example":{"data":{"id":"cmv1a2b3c4d5e6f7g8h9i0j1","status":"queued","type":"document","to":"5518999999999","connection":"principal","conversationId":null,"protocol":null,"error":null,"createdAt":"2026-09-29T13:20:00.000Z","sentAt":null}}}}},"default":{"$ref":"#/components/responses/Erro"}}}},"/api/v1/messages/{id}":{"get":{"operationId":"consultar-mensagem","tags":["Mensagens"],"summary":"Consultar mensagem","description":"Retorna o status atual de uma mensagem enviada pela API: queued (na fila), sent (enviada), delivered (entregue), read (lida) ou failed (falhou; o motivo vem em error).\n\nEscopo exigido: `messages:read`","parameters":[{"name":"id","in":"path","required":true,"description":"ID retornado no envio.","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"example":{"data":{"id":"cmv1a2b3c4d5e6f7g8h9i0j1","status":"delivered","type":"document","to":"5518999999999","connection":"principal","conversationId":"cmv1k2l3m4n5o6p7q8r9s0t1","protocol":"202609290012","error":null,"createdAt":"2026-09-29T13:20:00.000Z","sentAt":"2026-09-29T13:20:03.000Z"}}}}},"default":{"$ref":"#/components/responses/Erro"}}}},"/api/v1/messages/{id}/media":{"get":{"operationId":"baixar-midia","tags":["Mensagens"],"summary":"Baixar mídia","description":"Retorna o arquivo de uma mensagem com mídia (imagem, áudio, vídeo ou documento), recebida ou enviada. Aceita o id que vem no webhook message.received (o link pronto está em mediaUrl) ou o id retornado no envio pela API. Os erros continuam em JSON.\n\nEscopo exigido: `messages:read`","parameters":[{"name":"id","in":"path","required":true,"description":"ID da mensagem (webhook) ou ID do envio pela API.","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"default":{"$ref":"#/components/responses/Erro"}}}},"/api/v1/contacts":{"get":{"operationId":"listar-contatos","tags":["Contatos"],"summary":"Listar contatos","description":"Lista os contatos da empresa, dos mais recentes para os mais antigos. Quando houver mais resultados, nextCursor vem preenchido: envie esse valor em cursor para buscar a próxima página.\n\nEscopo exigido: `contacts:read`","parameters":[{"name":"q","in":"query","required":false,"description":"Busca por nome ou por parte do número.","schema":{"type":"string"}},{"name":"waId","in":"query","required":false,"description":"Número exato, ex.: 5518999999999.","schema":{"type":"string"}},{"name":"tag","in":"query","required":false,"description":"Somente contatos com esta tag.","schema":{"type":"string"}},{"name":"erpClienteId","in":"query","required":false,"description":"Somente contatos vinculados a este cliente do ERP.","schema":{"type":"string"}},{"name":"optOut","in":"query","required":false,"description":"true para descadastrados de campanhas; false para os demais.","schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"description":"Itens por página, de 1 a 100. Padrão: 50.","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Valor de nextCursor da página anterior.","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"example":{"data":{"items":[{"id":"cmu1a2b3c4d5e6f7g8h9i0j1","waId":"5518999999999","name":"Maria Souza","pushName":"Maria","tags":["cliente","fibra"],"notes":null,"erpClienteId":"10452","erpContatoId":null,"birthday":"1990-05-14","optOut":false,"optOutAt":null,"verified":true,"createdAt":"2026-08-02T14:10:00.000Z","updatedAt":"2026-09-29T16:00:00.000Z"}],"nextCursor":"cmu9z8y7x6w5v4u3t2s1r0q9"}}}}},"default":{"$ref":"#/components/responses/Erro"}}},"post":{"operationId":"criar-contato","tags":["Contatos"],"summary":"Cadastrar contato","description":"Cadastra um contato. Se o número já existir, retorna 409 contact_exists com o id do contato existente; nesse caso, use o PATCH.\n\nEscopo exigido: `contacts:write`","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["waId"],"properties":{"waId":{"type":"string","description":"Número com DDI e DDD. Números brasileiros sem 55 são completados."},"name":{"type":"string","description":"Nome do contato (até 120 caracteres)."},"tags":{"type":"array","items":{"type":"string"},"description":"Lista de tags (até 30, com até 40 caracteres cada)."},"notes":{"type":"string","description":"Observações internas (até 2000 caracteres)."},"erpClienteId":{"type":"string","description":"ID do cliente no ERP."},"erpContatoId":{"type":"string","description":"ID do contato no ERP."},"birthday":{"type":"string","description":"Data de nascimento no formato AAAA-MM-DD."},"optOut":{"type":"boolean","description":"true se o contato não quer receber campanhas."}}},"example":{"waId":"5518999999999","name":"Maria Souza","tags":["cliente","fibra"],"erpClienteId":"10452"}}}},"responses":{"201":{"description":"Sucesso","content":{"application/json":{"example":{"data":{"id":"cmu1a2b3c4d5e6f7g8h9i0j1","waId":"5518999999999","name":"Maria Souza","pushName":"Maria","tags":["cliente","fibra"],"notes":null,"erpClienteId":"10452","erpContatoId":null,"birthday":"1990-05-14","optOut":false,"optOutAt":null,"verified":false,"createdAt":"2026-08-02T14:10:00.000Z","updatedAt":"2026-09-29T16:00:00.000Z"}}}}},"default":{"$ref":"#/components/responses/Erro"}}}},"/api/v1/contacts/{id}":{"get":{"operationId":"detalhar-contato","tags":["Contatos"],"summary":"Consultar contato","description":"Retorna o contato e as suas 5 conversas mais recentes.\n\nEscopo exigido: `contacts:read`","parameters":[{"name":"id","in":"path","required":true,"description":"ID do contato ou o número, ex.: 5518999999999.","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"example":{"data":{"id":"cmu1a2b3c4d5e6f7g8h9i0j1","waId":"5518999999999","name":"Maria Souza","pushName":"Maria","tags":["cliente","fibra"],"notes":null,"erpClienteId":"10452","erpContatoId":null,"birthday":"1990-05-14","optOut":false,"optOutAt":null,"verified":true,"createdAt":"2026-08-02T14:10:00.000Z","updatedAt":"2026-09-29T16:00:00.000Z","recentConversations":[{"id":"cmv1k2l3m4n5o6p7q8r9s0t1","protocol":"202609290012","status":"closed","contact":{"id":"cmu1a2b3c4d5e6f7g8h9i0j1","waId":"5518999999999","name":"Maria Souza"},"connection":"principal","department":"Financeiro","agent":"João Lima","tickets":[{"id":"8812","number":"61234"}],"rating":{"score":5,"comment":"Atendimento rápido"},"openedAt":"2026-09-29T15:40:00.000Z","lastMessageAt":"2026-09-29T16:09:00.000Z","closedAt":"2026-09-29T16:10:00.000Z","discarded":false}]}}}}},"default":{"$ref":"#/components/responses/Erro"}}},"patch":{"operationId":"atualizar-contato","tags":["Contatos"],"summary":"Atualizar contato","description":"Altera somente os campos enviados; null limpa o campo. Use addTags e removeTags para mexer nas tags sem reenviar a lista. Ao trocar o erpClienteId, a verificação de identidade é desfeita (verified volta a false): o cliente precisa confirmar a identidade de novo no WhatsApp antes de receber faturas.\n\nEscopo exigido: `contacts:write`","parameters":[{"name":"id","in":"path","required":true,"description":"ID do contato ou o número.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"name":{"type":"string","description":"Nome do contato (até 120 caracteres)."},"tags":{"type":"array","items":{"type":"string"},"description":"Lista de tags (até 30, com até 40 caracteres cada)."},"notes":{"type":"string","description":"Observações internas (até 2000 caracteres)."},"erpClienteId":{"type":"string","description":"ID do cliente no ERP."},"erpContatoId":{"type":"string","description":"ID do contato no ERP."},"birthday":{"type":"string","description":"Data de nascimento no formato AAAA-MM-DD."},"optOut":{"type":"boolean","description":"true se o contato não quer receber campanhas."},"addTags":{"type":"array","items":{"type":"string"},"description":"Tags a acrescentar."},"removeTags":{"type":"array","items":{"type":"string"},"description":"Tags a remover."}}},"example":{"addTags":["inadimplente"],"notes":"Prefere contato à tarde"}}}},"responses":{"200":{"description":"Sucesso","content":{"application/json":{"example":{"data":{"id":"cmu1a2b3c4d5e6f7g8h9i0j1","waId":"5518999999999","name":"Maria Souza","pushName":"Maria","tags":["cliente","fibra","inadimplente"],"notes":"Prefere contato à tarde","erpClienteId":"10452","erpContatoId":null,"birthday":"1990-05-14","optOut":false,"optOutAt":null,"verified":true,"createdAt":"2026-08-02T14:10:00.000Z","updatedAt":"2026-09-29T16:00:00.000Z"}}}}},"default":{"$ref":"#/components/responses/Erro"}}}},"/api/v1/conversations":{"get":{"operationId":"listar-conversas","tags":["Conversas"],"summary":"Listar conversas","description":"Lista as conversas da empresa, da última mensagem mais recente para a mais antiga, com filtros e paginação por cursor.\n\nEscopo exigido: `messages:read`","parameters":[{"name":"contactId","in":"query","required":false,"description":"Somente conversas deste contato.","schema":{"type":"string"}},{"name":"waId","in":"query","required":false,"description":"Somente conversas deste número.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"bot, queued (na fila), open (com atendente) ou closed.","schema":{"type":"string"}},{"name":"since","in":"query","required":false,"description":"Somente conversas com mensagens a partir desta data, ex.: 2026-09-01.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Itens por página, de 1 a 100. Padrão: 50.","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Valor de nextCursor da página anterior.","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"example":{"data":{"items":[{"id":"cmv1k2l3m4n5o6p7q8r9s0t1","protocol":"202609290012","status":"closed","contact":{"id":"cmu1a2b3c4d5e6f7g8h9i0j1","waId":"5518999999999","name":"Maria Souza"},"connection":"principal","department":"Financeiro","agent":"João Lima","tickets":[{"id":"8812","number":"61234"}],"rating":{"score":5,"comment":"Atendimento rápido"},"openedAt":"2026-09-29T15:40:00.000Z","lastMessageAt":"2026-09-29T16:09:00.000Z","closedAt":"2026-09-29T16:10:00.000Z","discarded":false}],"nextCursor":null}}}}},"default":{"$ref":"#/components/responses/Erro"}}}},"/api/v1/conversations/{id}":{"get":{"operationId":"detalhar-conversa","tags":["Conversas"],"summary":"Consultar conversa","description":"Retorna a conversa com departamento, atendente, tickets, avaliação e as últimas mensagens em ordem cronológica. Mensagens com mídia trazem mediaUrl para download.\n\nEscopo exigido: `messages:read`","parameters":[{"name":"id","in":"path","required":true,"description":"ID da conversa ou o protocolo, ex.: 202609290012.","schema":{"type":"string"}},{"name":"messages","in":"query","required":false,"description":"Quantas das últimas mensagens retornar, de 0 a 200. Padrão: 50.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"example":{"data":{"id":"cmv1k2l3m4n5o6p7q8r9s0t1","protocol":"202609290012","status":"closed","contact":{"id":"cmu1a2b3c4d5e6f7g8h9i0j1","waId":"5518999999999","name":"Maria Souza"},"connection":"principal","department":"Financeiro","agent":"João Lima","tickets":[{"id":"8812","number":"61234"}],"rating":{"score":5,"comment":"Atendimento rápido"},"openedAt":"2026-09-29T15:40:00.000Z","lastMessageAt":"2026-09-29T16:09:00.000Z","closedAt":"2026-09-29T16:10:00.000Z","discarded":false,"messages":[{"id":"cmw1a2b3c4d5e6f7g8h9i0j1","direction":"in","senderType":"contact","agent":null,"type":"text","text":"Oi, preciso da segunda via da fatura","fileName":null,"mimeType":null,"mediaUrl":null,"status":null,"createdAt":"2026-09-29T15:40:00.000Z"}],"hasMoreMessages":false}}}}},"default":{"$ref":"#/components/responses/Erro"}}}},"/api/v1/departments":{"get":{"operationId":"listar-departamentos","tags":["Conversas"],"summary":"Listar departamentos","description":"Lista os departamentos ativos da empresa, usados na transferência de conversas e na abertura de tickets.","parameters":[],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"example":{"data":[{"id":"cmd1a2b3c4d5e6f7g8h9i0j1","name":"Financeiro","slug":"financeiro"},{"id":"cmd2a2b3c4d5e6f7g8h9i0j2","name":"Suporte","slug":"suporte"}]}}}},"default":{"$ref":"#/components/responses/Erro"}}}},"/api/v1/conversations/{id}/transfer":{"post":{"operationId":"transferir-conversa","tags":["Conversas"],"summary":"Transferir conversa","description":"Transfere a conversa para outro departamento e a coloca na fila, como no painel. O cliente recebe o aviso \"Estou transferindo você para <departamento>...\" e, se a conversa tiver ticket, a transferência é registrada nele como comentário interno.\n\nEscopo exigido: `conversations:write`","parameters":[{"name":"id","in":"path","required":true,"description":"ID ou protocolo da conversa.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["department"],"properties":{"department":{"type":"string","description":"Nome, slug ou id do departamento de destino."},"agent":{"type":"string","description":"E-mail de um atendente, para direcionar a conversa a ele."},"note":{"type":"string","description":"Observação registrada no ticket (até 1000 caracteres)."}}},"example":{"department":"Financeiro","note":"Cliente pediu renegociação"}}}},"responses":{"200":{"description":"Sucesso","content":{"application/json":{"example":{"data":{"id":"cmv1k2l3m4n5o6p7q8r9s0t1","protocol":"202609290012","status":"queued","contact":{"id":"cmu1a2b3c4d5e6f7g8h9i0j1","waId":"5518999999999","name":"Maria Souza"},"connection":"principal","department":"Financeiro","agent":null,"tickets":[{"id":"8812","number":"61234"}],"rating":{"score":5,"comment":"Atendimento rápido"},"openedAt":"2026-09-29T15:40:00.000Z","lastMessageAt":"2026-09-29T16:09:00.000Z","closedAt":null,"discarded":false}}}}},"default":{"$ref":"#/components/responses/Erro"}}}},"/api/v1/conversations/{id}/close":{"post":{"operationId":"encerrar-conversa","tags":["Conversas"],"summary":"Encerrar conversa","description":"Encerra a conversa pelo mesmo fluxo do painel, com o histórico enviado ao ticket. Se ela passou por atendimento humano ou tem ticket, e ainda não foi avaliada, o cliente recebe a pesquisa de satisfação e a conversa fecha após a resposta (ou em 2 horas); nos demais casos, fecha na hora com a mensagem de encerramento. Envie survey: false para fechar na hora, sem pesquisa. A resposta é 202; a conclusão chega pelo webhook conversation.closed.\n\nEscopo exigido: `conversations:write`","parameters":[{"name":"id","in":"path","required":true,"description":"ID ou protocolo da conversa.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"survey":{"type":"boolean","description":"false para encerrar sem a pesquisa de satisfação. Padrão: true."}}},"example":{"survey":false}}}},"responses":{"202":{"description":"Aceito para envio","content":{"application/json":{"example":{"data":{"id":"cmv1k2l3m4n5o6p7q8r9s0t1","protocol":"202609290012","status":"closing","survey":false}}}}},"default":{"$ref":"#/components/responses/Erro"}}}},"/api/v1/tickets":{"get":{"operationId":"listar-tickets","tags":["Tickets"],"summary":"Listar tickets","description":"Lista os tickets abertos no ERP a partir de conversas do WhatsApp, do mais recente para o mais antigo.\n\nEscopo exigido: `tickets:read`","parameters":[{"name":"contactId","in":"query","required":false,"description":"Somente tickets deste contato.","schema":{"type":"string"}},{"name":"waId","in":"query","required":false,"description":"Somente tickets deste número.","schema":{"type":"string"}},{"name":"conversationId","in":"query","required":false,"description":"ID ou protocolo da conversa.","schema":{"type":"string"}},{"name":"number","in":"query","required":false,"description":"Número do chamado no ERP.","schema":{"type":"string"}},{"name":"since","in":"query","required":false,"description":"Somente tickets abertos a partir desta data, ex.: 2026-09-01.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Itens por página, de 1 a 100. Padrão: 50.","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Valor de nextCursor da página anterior.","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"example":{"data":{"items":[{"id":"cmt1a2b3c4d5e6f7g8h9i0j1","ticketId":"8812","number":"61234","conversationId":"cmv1k2l3m4n5o6p7q8r9s0t1","protocol":"202609290012","contact":{"id":"cmu1a2b3c4d5e6f7g8h9i0j1","waId":"5518999999999","name":"Maria Souza"},"createdAt":"2026-09-29T15:55:00.000Z"}],"nextCursor":null}}}}},"default":{"$ref":"#/components/responses/Erro"}}},"post":{"operationId":"abrir-ticket","tags":["Tickets"],"summary":"Abrir ticket","description":"Abre um ticket no ERP para uma conversa, pelo mesmo fluxo do bot: o histórico da conversa entra como comentário interno e as mídias como anexos. Cada conversa tem no máximo um ticket; se já existir, ele é retornado com created: false. Se o ERP demorar mais de 20 segundos, a resposta é 202 com status processing; consulte depois em GET /api/v1/tickets?conversationId=... ou aguarde o webhook ticket.created.\n\nEscopo exigido: `tickets:write`","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversationId"],"properties":{"conversationId":{"type":"string","description":"ID ou protocolo da conversa."},"department":{"type":"string","description":"Nome do departamento, ex.: Suporte. Padrão: o departamento da conversa."},"description":{"type":"string","description":"Descrição do problema (até 4000 caracteres)."}}},"example":{"conversationId":"202609290012","department":"Suporte","description":"Cliente relata lentidão desde ontem à noite"}}}},"responses":{"201":{"description":"Sucesso","content":{"application/json":{"example":{"data":{"id":"cmt1a2b3c4d5e6f7g8h9i0j1","ticketId":"8812","number":"61234","conversationId":"cmv1k2l3m4n5o6p7q8r9s0t1","protocol":"202609290012","contact":{"id":"cmu1a2b3c4d5e6f7g8h9i0j1","waId":"5518999999999","name":"Maria Souza"},"createdAt":"2026-09-29T15:55:00.000Z","created":true}}}}},"default":{"$ref":"#/components/responses/Erro"}}}},"/api/v1/webhooks":{"get":{"operationId":"listar-webhooks","tags":["Webhooks"],"summary":"Listar webhooks","description":"Lista os webhooks cadastrados para a sua empresa. O segredo não é retornado.\n\nEscopo exigido: `webhooks:manage`","parameters":[],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"example":{"data":[{"id":"cmx1a2b3c4d5e6f7g8h9i0j1","name":"ERP","url":"https://erp.exemplo.com.br/webhooks/wa","events":["message.received","ticket.created"],"active":true,"failCount":0,"disabledReason":null,"createdBy":"Maria Souza","createdAt":"2026-09-29T16:00:00.000Z"}]}}}},"default":{"$ref":"#/components/responses/Erro"}}},"post":{"operationId":"criar-webhook","tags":["Webhooks"],"summary":"Cadastrar webhook","description":"Cadastra uma URL https para receber eventos. O secret retornado serve para verificar a assinatura e aparece somente nesta resposta. Limite de 10 webhooks por empresa.\n\nEscopo exigido: `webhooks:manage`","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","url","events"],"properties":{"name":{"type":"string","description":"Nome de identificação, ex.: ERP."},"url":{"type":"string","description":"URL https que vai receber os eventos."},"events":{"type":"array","items":{"type":"string"},"description":"Eventos desejados. Veja a lista na seção Webhooks."}}},"example":{"name":"ERP","url":"https://erp.exemplo.com.br/webhooks/wa","events":["message.received","message.status"]}}}},"responses":{"201":{"description":"Sucesso","content":{"application/json":{"example":{"data":{"id":"cmx1a2b3c4d5e6f7g8h9i0j1","name":"ERP","url":"https://erp.exemplo.com.br/webhooks/wa","events":["message.received","message.status"],"active":true,"failCount":0,"disabledReason":null,"createdBy":"API: Integração ERP","createdAt":"2026-09-29T16:00:00.000Z","secret":"whsec_6y0Qe9cR2vN4mT8bW1kZ3pL5sA7dF0gH"}}}}},"default":{"$ref":"#/components/responses/Erro"}}}},"/api/v1/webhooks/{id}":{"delete":{"operationId":"excluir-webhook","tags":["Webhooks"],"summary":"Excluir webhook","description":"Remove o webhook e o seu histórico de entregas.\n\nEscopo exigido: `webhooks:manage`","parameters":[{"name":"id","in":"path","required":true,"description":"ID do webhook.","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"example":{"data":{"id":"cmx1a2b3c4d5e6f7g8h9i0j1","deleted":true}}}}},"default":{"$ref":"#/components/responses/Erro"}}}}}}