{"openapi":"3.1.0","info":{"title":"API do dot.Sales","version":"1.0.0","description":"API REST para integrar seus sistemas ao CRM. Respostas em JSON, nomes em português.\n\n## Primeiros passos\n1. Um **administrador** da conta cria a chave em **Configurações → Integrações → API e Webhooks** e escolhe os escopos. A chave aparece uma vez só: guarde-a num cofre de segredos.\n2. Envie a chave em toda requisição, no cabeçalho `Authorization: Bearer dsk_...`.\n3. Teste:\n\n```bash\ncurl -H \"Authorization: Bearer $CHAVE\" https://sales.dottech.ai/api/v1/conta\n```\n\nA chave enxerga **todos** os dados da conta para os escopos dados. Use-a só no servidor; nunca em aplicativo, navegador ou repositório público. Revogar a chave tem efeito em até 30 segundos.\n\n## Escopos\n| Escopo | O que libera |\n|---|---|\n| `conta:ler` | Empresa, usuários, funis e etapas, campos personalizados e tags. |\n| `funis:escrever` | Cria funis e etapas, renomeia, muda cor e descrição, marca a etapa de entrada e a de qualificação e reordena as etapas. |\n| `leads:ler` | Leads, com tags, campos personalizados e histórico. |\n| `leads:dados_pessoais` | Inclui CPF, data de nascimento e endereço nas respostas de leads. Conceda só se a integração precisar (LGPD). |\n| `leads:escrever` | Cria e edita leads (dados, etapa, responsável, campos, tags), anotações e registra a perda com o motivo. Criar lead e mudar etapa disparam as automações do funil. |\n| `vendas:ler` | Vendas (itens comprados, pedidos) de cada lead. |\n| `vendas:escrever` | Registra venda no lead, como \"Confirmar venda\" na tela: entra no faturamento, metas, ranking e na conversão de compra da Meta. |\n| `tarefas:ler` | Tarefas da empresa e de cada lead. |\n| `tarefas:escrever` | Cria, edita e conclui tarefas. |\n| `produtos:ler` | Itens do catálogo. |\n| `automacoes:ler` | Automações das etapas e workflows, com o fluxo completo (nós e conexões). |\n| `automacoes:escrever` | Cria e duplica automações e workflows (nascem desligados), liga, desliga e renomeia. Ligada, a automação envia mensagens e mexe nos leads. |\n| `webhooks:gerenciar` | Cria, edita e testa webhooks (avisos de eventos para a sua URL) e vê as entregas. |\n| `vitoria:ler` | Consultas da Vitor[IA] (vendas, metas, funil, atendimento, ligações, campanhas…) pelo servidor MCP /api/v1/mcp, para usar no Claude, Cursor e outros assistentes. Exige o add-on Vitor[IA]; traz o primeiro nome dos leads e o nome dos vendedores. |\n\n## Limites\n- **10 requisições por segundo** por chave.\n- **5000 requisições por hora** por conta, somando todas as chaves.\n- Toda resposta traz `RateLimit-Limit`, `RateLimit-Remaining` e `RateLimit-Reset` (segundos).\n- Ao estourar, a resposta é **429** com `Retry-After`. Não bloqueamos IP: espere e tente de novo.\n\n## Paginação\nListas devolvem `{ \"dados\": [...], \"paginacao\": { \"limite\": 50, \"proximo_cursor\": \"...\" } }`, das mais recentes para as mais antigas. Para a próxima página, repita a chamada com `?cursor=<proximo_cursor>` e os mesmos filtros. Quando `proximo_cursor` vier `null`, acabou. Lista vazia é `200` com `dados: []`.\n\n## Sincronização incremental\nPara manter uma cópia dos leads em dia, chame `GET /leads?atualizado_desde=<data>`: vêm só os leads alterados desde então, em ordem de atualização (mais antigos primeiro). Percorra as páginas e guarde o `atualizado_em` do último item para a próxima rodada. Conta como alteração mudar um dado do lead (nome, contato, etapa, responsável, observações...); tags e campos personalizados aparecem no histórico do lead. Vale para mudanças a partir de 20/10/2026.\n\n## Erros\nTodo erro tem o mesmo formato:\n\n```json\n{ \"erro\": { \"codigo\": \"escopo_insuficiente\", \"mensagem\": \"...\", \"requisicao_id\": \"...\" } }\n```\n\nUse o `codigo` no seu código (a `mensagem` pode mudar). Ao falar com o suporte, informe o `requisicao_id`.\n\n## Formatos\n- Datas em ISO 8601 (UTC). Nos filtros `_desde`/`_ate`, uma data sem hora (`2026-10-20`) inclui o dia inteiro.\n- Telefones em E.164 (`+5511999998888`). No filtro `telefone`, qualquer formato é aceito.\n- Ids são UUID. Pegue os ids de funis, etapas, usuários, campos e tags em `GET /conta`.\n\n## Dados pessoais (LGPD)\nCPF, data de nascimento e endereço dos leads só aparecem com o escopo `leads:dados_pessoais`. Conceda-o só às integrações que precisam.\n\n## Versionamento\nTudo fica em `/api/v1`. Novos campos e novas rotas podem entrar a qualquer momento: ignore campos que você não conhece. Mudanças incompatíveis só numa `/api/v2`, com aviso prévio.\n\n## Escrita\n- **Automações:** criar um lead (`fonte` = `api`) dispara as automações de \"novo lead\" do funil, e mudar a etapa dispara as de \"mudou de fase\" — como qualquer outra entrada de lead. Elas não rodam dentro da sua requisição: entram na fila e são processadas em seguida, com espaçamento, para importações grandes não dispararem tudo de uma vez. Adicionar tag dispara as automações de tag.\n- **Duplicados:** `POST /leads` procura um lead da conta com o mesmo telefone (ou, sem telefone, o mesmo e-mail). `se_existir` decide: `atualizar` (padrão — os campos enviados sobrescrevem, menos o nome), `ignorar` ou `erro` (409 com o `lead_id`). A resposta traz `criado`.\n- **Tudo ou nada:** dados do lead, campos e tags são validados antes e gravados numa transação só.\n- **Histórico:** as mudanças aparecem no histórico do lead com o autor \"API: <nome da chave>\".\n- **Retentativas:** mande `Idempotency-Key` nos POST para poder repetir com segurança depois de um erro de rede.\n- Para apagar o valor de um campo, envie `null`. Para tirar o responsável, `responsavel_id: null`.\n\n## Vendas e perdas\n- **Perda:** `POST /leads/{id}/perda` com o motivo (`objecao_id` ou `motivo` pelo nome — a lista está em `/conta → objecoes`). Move para a etapa de perda e grava o motivo, como na tela; é o que o dashboard e o gráfico de motivos contam. Criar ou mover lead direto para uma etapa de perda (`etapa_id` no POST/PATCH) é recusado com 422 `etapa_de_perda`, porque perda sem motivo não aparece nos relatórios. Para reabrir, mude a etapa pelo PATCH.\n- **Venda:** `POST /leads/{id}/vendas` com os itens (`produto_id` do catálogo ou `nome` + `valor`), `vendedor_id` e `vendido_em`. Vira um pedido confirmado, como \"Confirmar venda\" na tela: entra no faturamento, nas metas e no ranking, e manda a conversão de compra para a Meta quando o lead veio de anúncio. Mande sempre `Idempotency-Key` (é obrigatório): repetir uma venda sem ela contaria em dobro.\n- `GET /leads/{id}/vendas` lista o que o lead comprou; o `GET /leads/{id}` traz `perda` (motivo, observação e data) quando ele está perdido.\n\n## Funis e etapas\n- `GET /funis` traz os funis com as etapas (os mesmos de `/conta`). `POST /funis` cria como a tela: as etapas abertas que você mandar (a primeira é a de entrada; sem lista, \"Novo Lead\"), mais **Venda** e **Perda** no fim.\n- Etapa nova entra depois da última aberta; com `posicao`, as etapas são renumeradas como no \"inserir entre\" da tela. Venda e Perda só mudam nome, cor e descrição.\n- Arquivar funil ou etapa continua só pela tela (arquivar etapa move os leads, e mover dispara automações).\n\n## Automações e workflows\n- Automação de etapa e workflow são a mesma coisa: um **gatilho** e um **fluxo** de nós. Com gatilho automático (novo lead, tempo na etapa, mudou de etapa, mensagem recebida, tag, data em campo) ela fica numa etapa (`etapa_id`); a `manual` é executada pelo chat (\"Executar workflow\").\n- **Criar e duplicar dão automação desligada.** Confira e ligue com `PATCH /automacoes/{id}` `{ \"ativa\": true }`: o fluxo é validado de novo e, se algo estiver errado (tag apagada, etapa arquivada...), a resposta é 422 `fluxo_invalido` com a lista.\n- Ligada, ela vale a partir do próximo evento e não roda para trás. A exceção é o gatilho de data em campo, que agenda também os leads que já têm a data preenchida.\n- Ligada, a automação manda mensagens e mexe nos leads: teste numa etapa só sua antes de ligar no funil de verdade.\n- O fluxo usa o formato do editor (veja `POST /automacoes`). As automações do Instagram têm tela própria e não aparecem aqui.\n\n## Webhooks\nAvisos automáticos para a sua URL quando algo acontece no CRM. Crie em **Configurações → Integrações → API e Webhooks → Webhooks** ou pela API (`POST /webhooks`, escopo `webhooks:gerenciar`) e escolha os eventos. Os formatos de cada evento estão na seção **Webhooks** desta referência.\n\n- Cada aviso é um `POST` em JSON: `{ \"id\", \"tipo\", \"ocorrido_em\", \"empresa_id\", \"dados\" }`.\n- **Responda 2xx em até 10 s** e processe depois. Redirecionamento (3xx) também conta como entregue (não é seguido); qualquer outra resposta, ou demora, conta como falha.\n- **Novas tentativas:** 1 min, 5 min, 30 min, 2 h, 6 h, 12 h e 24 h (~45 h no total). Um webhook sem nenhuma entrega com sucesso por 3 dias é desativado e os administradores recebem aviso.\n- **Sem repetição:** o `id` do evento (cabeçalho `X-DotSales-Evento-Id`) é o mesmo em todas as tentativas — guarde e ignore o que já processou. A ordem de chegada não é garantida: use `ocorrido_em`.\n- **Assinatura:** `X-DotSales-Assinatura: t=<unix>,v1=<hex>`, onde `v1 = HMAC-SHA256(segredo, t + \".\" + corpo_bruto)`. Confira com o corpo **bruto** (antes de interpretar o JSON) e recuse `t` com mais de 5 minutos.\n\n```js\n// Node.js (Express: app.post('/webhook', express.raw({ type: 'application/json' }), ...))\nconst crypto = require('crypto')\nfunction assinaturaValida(corpoBruto, cabecalho, segredo) {\n  const partes = Object.fromEntries(cabecalho.split(',').map(p => p.split('=')))\n  if (Math.abs(Date.now() / 1000 - Number(partes.t)) > 300) return false\n  const esperado = crypto.createHmac('sha256', segredo).update(`${partes.t}.${corpoBruto}`).digest('hex')\n  return crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(partes.v1 || ''))\n}\n```\n\n```python\nimport hmac, hashlib, time\ndef assinatura_valida(corpo_bruto: bytes, cabecalho: str, segredo: str) -> bool:\n    partes = dict(p.split(\"=\", 1) for p in cabecalho.split(\",\"))\n    if abs(time.time() - int(partes[\"t\"])) > 300:\n        return False\n    esperado = hmac.new(segredo.encode(), f\"{partes['t']}.\".encode() + corpo_bruto, hashlib.sha256).hexdigest()\n    return hmac.compare_digest(esperado, partes.get(\"v1\", \"\"))\n```\n\n- Teste a sua URL com `POST /webhooks/{id}/teste` (manda um evento `ping`). O log de entregas (`GET /webhooks/{id}/entregas`) mostra o status HTTP e o que a sua URL respondeu; `POST /webhooks/entregas/{id}/reenviar` reenvia.\n- Só HTTPS e endereços públicos (IPs internos são recusados). Redirecionamentos não são seguidos.\n\n### Node \"Webhook\" das automações\nO node **Webhook** do construtor de automações manda o lead que passou por ele para a sua URL (n8n, Make, Zapier, sua API), com o mesmo envio dos webhooks acima: só HTTPS, assinatura no mesmo formato e as mesmas novas tentativas.\n\n- Evento `automacao.executed` (cabeçalhos `X-DotSales-Event` e `X-DotSales-Evento`). O corpo traz `event_id`, `automacao`, `movimentacao` (de qual etapa para qual) e o `lead` completo, com tags, campos personalizados, primeira mensagem, objeção e rastreio do anúncio.\n- `X-DotSales-Event-Id` / `X-DotSales-Evento-Id` e `event_id` são iguais em todas as tentativas; `X-DotSales-Tentativa` diz qual é.\n- A assinatura usa **um segredo por conta**, à parte dos webhooks acima: veja e troque em **API e Webhooks → Webhooks → Node \"Webhook\" das automações** (administradores).\n- O lead vai como está no momento do envio (numa nova tentativa, já com o que mudou).\n\n## Em breve\nEnvio de mensagens e leitura de conversas."},"servers":[{"url":"https://sales.dottech.ai/api/v1"}],"security":[{"chave":[]}],"tags":[{"name":"Conta","description":"Dados de referência: usuários, funis, etapas, campos e tags."},{"name":"Leads","description":"Leads (contato + oportunidade), com tags, campos e histórico."},{"name":"Empresas","description":"Empresas do contato: uma empresa tem vários contatos. Para ligar um lead, grave o empresa_contato dele com o nome da empresa."},{"name":"Tarefas"},{"name":"Vendas e perdas","description":"Registrar venda e perda com motivo, como na tela, e ler as vendas do lead."},{"name":"Produtos","description":"Catálogo de produtos e serviços."},{"name":"Funis e etapas","description":"Criar e editar funis, etapas e a ordem das etapas."},{"name":"Automações","description":"Automações das etapas e workflows: consultar, criar, duplicar, ligar e desligar."},{"name":"Gestão de webhooks","description":"Criar, editar, testar e apagar os avisos de eventos para a sua URL, e ver ou reenviar as entregas."}],"paths":{"/conta":{"get":{"tags":["Conta"],"summary":"Dados da conta","description":"Empresa, usuários, funis com etapas, campos personalizados e tags. Chame uma vez e guarde em cache: os ids daqui são usados nos filtros.\n\n**Escopo:** `conta:ler`","parameters":[],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"$ref":"#/components/schemas/Conta"}},"required":["dados"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"conta:ler"}},"/leads":{"get":{"tags":["Leads"],"summary":"Listar leads","description":"Mais recentes primeiro. Combine filtros à vontade (são somados com E).\n\n**Escopo:** `leads:ler`","parameters":[{"name":"limite","in":"query","required":false,"description":"Itens por página (1–100, padrão 50).","schema":{"description":"Itens por página (1–100, padrão 50).","default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"paginacao.proximo_cursor da página anterior.","schema":{"description":"paginacao.proximo_cursor da página anterior.","type":"string","maxLength":300}},{"name":"funil_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"}},{"name":"etapa_id","in":"query","required":false,"description":"Uma ou mais etapas, separadas por vírgula.","schema":{"description":"Uma ou mais etapas, separadas por vírgula.","type":"string"}},{"name":"responsavel_id","in":"query","required":false,"description":"Id do usuário, ou \"nenhum\" para leads sem responsável.","schema":{"description":"Id do usuário, ou \"nenhum\" para leads sem responsável.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"string","const":"nenhum"}]}},{"name":"tag_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"}},{"name":"telefone","in":"query","required":false,"description":"Qualquer formato; é normalizado para E.164 (DDI 55 se faltar).","schema":{"description":"Qualquer formato; é normalizado para E.164 (DDI 55 se faltar).","type":"string","maxLength":40}},{"name":"email","in":"query","required":false,"description":"E-mail exato (sem diferenciar maiúsculas).","schema":{"description":"E-mail exato (sem diferenciar maiúsculas).","type":"string","maxLength":200}},{"name":"criado_desde","in":"query","required":false,"schema":{"type":"string","maxLength":40}},{"name":"criado_ate","in":"query","required":false,"schema":{"type":"string","maxLength":40}},{"name":"atualizado_desde","in":"query","required":false,"description":"Para sincronizar: só leads alterados a partir desta data, e a lista passa a vir em ordem de atualização (mais antigos primeiro). Guarde o atualizado_em do último item e use na próxima sincronização.","schema":{"description":"Para sincronizar: só leads alterados a partir desta data, e a lista passa a vir em ordem de atualização (mais antigos primeiro). Guarde o atualizado_em do último item e use na próxima sincronização.","type":"string","maxLength":40}},{"name":"incluir","in":"query","required":false,"description":"tags, campos, perda","schema":{"description":"tags, campos, perda","type":"string"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"paginacao":{"$ref":"#/components/schemas/Paginacao"}},"required":["dados","paginacao"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"leads:ler"},"post":{"tags":["Leads"],"summary":"Criar lead","description":"Sem funil_id, entra no funil padrão; sem etapa_id, na etapa de entrada. Se já existir lead com o mesmo telefone (ou e-mail), vale `se_existir`. Dispara as automações de novo lead (pela fila).\n\n**Escopo:** `leads:escrever`","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Valor único por operação (ex.: um UUID). Repetir a mesma requisição com a mesma chave em 24 h devolve a resposta da primeira, sem gravar de novo (cabeçalho Idempotente-Repetida: true)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nome":{"type":"string","minLength":1,"maxLength":200},"telefone":{"description":"Qualquer formato; vira E.164 (DDI 55 se faltar). null apaga.","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"email":{"anyOf":[{"type":"string","maxLength":200,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"empresa_contato":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"funil_id":{"description":"Sem etapa_id, o lead vai para a etapa de entrada deste funil.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"etapa_id":{"description":"Precisa ser de funil_id (se vier); sem funil_id, o funil é o da etapa.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"responsavel_id":{"description":"Usuário com acesso ativo à conta (ver /conta). null tira o responsável.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"fonte_detalhe":{"description":"De onde veio, em texto livre (ex.: \"site\", \"n8n\"). A fonte é sempre \"api\".","anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"probabilidade":{"anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"previsao_fechamento":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"motivo_perda":{"description":"Texto livre antigo, que os relatórios não leem. Para registrar a perda use POST /leads/{id}/perda.","anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"observacoes":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"instagram":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"pais":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"estado":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"cidade":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"profissao":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"cpf":{"description":"Exige o escopo leads:dados_pessoais.","anyOf":[{"type":"string","maxLength":20},{"type":"null"}]},"data_nascimento":{"description":"Exige o escopo leads:dados_pessoais.","anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"endereco":{"description":"Exige o escopo leads:dados_pessoais.","anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"rastreio":{"description":"Origem do lead. Chaves fixas (chave desconhecida é erro): plataforma, anuncio_id, conjunto_id, campanha_id, utm_source, utm_medium, utm_campaign, utm_term, utm_content, fbclid, gclid, gbraid, wbraid, ttclid, msclkid, pagina_url. Valor vazio (\"\" ou null) conta como chave ausente.","type":"object","properties":{"plataforma":{"description":"Onde o anúncio rodou: meta (Facebook/Instagram), google, tiktok ou outro.","type":"string","enum":["meta","google","tiktok","outro"]},"anuncio_id":{"description":"Id do anúncio na plataforma, como texto (Meta: o id numérico do anúncio).","type":"string","pattern":"^\\d{3,30}$"},"conjunto_id":{"description":"Id do conjunto de anúncios, como texto.","type":"string","pattern":"^\\d{3,30}$"},"campanha_id":{"description":"Id da campanha, como texto.","type":"string","pattern":"^\\d{3,30}$"},"utm_source":{"type":"string","minLength":1,"maxLength":300},"utm_medium":{"type":"string","minLength":1,"maxLength":300},"utm_campaign":{"description":"Nome da campanha como UTM (texto livre). O id vai em campanha_id.","type":"string","minLength":1,"maxLength":300},"utm_term":{"type":"string","minLength":1,"maxLength":300},"utm_content":{"type":"string","minLength":1,"maxLength":300},"fbclid":{"type":"string","minLength":1,"maxLength":300},"gclid":{"type":"string","minLength":1,"maxLength":300},"gbraid":{"type":"string","minLength":1,"maxLength":300},"wbraid":{"type":"string","minLength":1,"maxLength":300},"ttclid":{"type":"string","minLength":1,"maxLength":300},"msclkid":{"type":"string","minLength":1,"maxLength":300},"pagina_url":{"description":"Página onde o lead converteu. UTMs e ids de clique da URL entram também, se não vierem nas chaves.","type":"string","maxLength":2000,"format":"uri"}},"additionalProperties":false},"campos":{"description":"Campos personalizados (ids em /conta). valor null apaga. Seleção múltipla: lista de opções.","maxItems":100,"type":"array","items":{"type":"object","properties":{"campo_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"valor":{"anyOf":[{"type":"string","maxLength":10000},{"type":"number"},{"maxItems":100,"type":"array","items":{"type":"string","maxLength":500}},{"type":"null"}]}},"required":["campo_id","valor"]}},"tags_adicionar":{"description":"Ids ou nomes de tag. Nome que não existe é criado.","maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}},"se_existir":{"description":"Se já houver lead com o mesmo telefone (ou o mesmo e-mail, sem telefone): atualizar (padrão; o nome do lead existente não muda), ignorar ou erro (409).","default":"atualizar","type":"string","enum":["atualizar","ignorar","erro"]}},"required":["nome"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"$ref":"#/components/schemas/Lead"},"criado":{"type":"boolean","description":"false quando o lead já existia (se_existir)."}},"required":["dados","criado"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"409":{"description":"Conflito (ver codigo): duplicado, telefone em uso ou requisição com a mesma Idempotency-Key ainda em andamento.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"422":{"description":"Idempotency-Key já usada com outra requisição.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"leads:escrever"}},"/leads/{id}":{"get":{"tags":["Leads"],"summary":"Obter um lead","description":"Sempre com tags, campos personalizados e a perda (motivo, se o lead está perdido). `incluir=tarefas` traz as 50 tarefas mais recentes (exige também `tarefas:ler`).\n\n**Escopo:** `leads:ler`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id do lead."},{"name":"incluir","in":"query","required":false,"description":"tarefas","schema":{"description":"tarefas","type":"string"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"$ref":"#/components/schemas/Lead"}},"required":["dados"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"leads:ler"},"patch":{"tags":["Leads"],"summary":"Editar lead","description":"Só os campos enviados mudam. Mudar etapa dispara as automações de \"mudou de fase\" (pela fila). `tags_adicionar` / `tags_remover` aceitam ids ou nomes.\n\n**Escopo:** `leads:escrever`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id do lead."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nome":{"type":"string","minLength":1,"maxLength":200},"telefone":{"description":"Qualquer formato; vira E.164 (DDI 55 se faltar). null apaga.","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"email":{"anyOf":[{"type":"string","maxLength":200,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"empresa_contato":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"funil_id":{"description":"Sem etapa_id, o lead vai para a etapa de entrada deste funil.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"etapa_id":{"description":"Precisa ser de funil_id (se vier); sem funil_id, o funil é o da etapa.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"responsavel_id":{"description":"Usuário com acesso ativo à conta (ver /conta). null tira o responsável.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"fonte_detalhe":{"description":"De onde veio, em texto livre (ex.: \"site\", \"n8n\"). A fonte é sempre \"api\".","anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"probabilidade":{"anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"previsao_fechamento":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"motivo_perda":{"description":"Texto livre antigo, que os relatórios não leem. Para registrar a perda use POST /leads/{id}/perda.","anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"observacoes":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"instagram":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"pais":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"estado":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"cidade":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"profissao":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"cpf":{"description":"Exige o escopo leads:dados_pessoais.","anyOf":[{"type":"string","maxLength":20},{"type":"null"}]},"data_nascimento":{"description":"Exige o escopo leads:dados_pessoais.","anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"endereco":{"description":"Exige o escopo leads:dados_pessoais.","anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"rastreio":{"description":"Origem do lead. Chaves fixas (chave desconhecida é erro): plataforma, anuncio_id, conjunto_id, campanha_id, utm_source, utm_medium, utm_campaign, utm_term, utm_content, fbclid, gclid, gbraid, wbraid, ttclid, msclkid, pagina_url. Valor vazio (\"\" ou null) conta como chave ausente.","type":"object","properties":{"plataforma":{"description":"Onde o anúncio rodou: meta (Facebook/Instagram), google, tiktok ou outro.","type":"string","enum":["meta","google","tiktok","outro"]},"anuncio_id":{"description":"Id do anúncio na plataforma, como texto (Meta: o id numérico do anúncio).","type":"string","pattern":"^\\d{3,30}$"},"conjunto_id":{"description":"Id do conjunto de anúncios, como texto.","type":"string","pattern":"^\\d{3,30}$"},"campanha_id":{"description":"Id da campanha, como texto.","type":"string","pattern":"^\\d{3,30}$"},"utm_source":{"type":"string","minLength":1,"maxLength":300},"utm_medium":{"type":"string","minLength":1,"maxLength":300},"utm_campaign":{"description":"Nome da campanha como UTM (texto livre). O id vai em campanha_id.","type":"string","minLength":1,"maxLength":300},"utm_term":{"type":"string","minLength":1,"maxLength":300},"utm_content":{"type":"string","minLength":1,"maxLength":300},"fbclid":{"type":"string","minLength":1,"maxLength":300},"gclid":{"type":"string","minLength":1,"maxLength":300},"gbraid":{"type":"string","minLength":1,"maxLength":300},"wbraid":{"type":"string","minLength":1,"maxLength":300},"ttclid":{"type":"string","minLength":1,"maxLength":300},"msclkid":{"type":"string","minLength":1,"maxLength":300},"pagina_url":{"description":"Página onde o lead converteu. UTMs e ids de clique da URL entram também, se não vierem nas chaves.","type":"string","maxLength":2000,"format":"uri"}},"additionalProperties":false},"campos":{"description":"Campos personalizados (ids em /conta). valor null apaga. Seleção múltipla: lista de opções.","maxItems":100,"type":"array","items":{"type":"object","properties":{"campo_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"valor":{"anyOf":[{"type":"string","maxLength":10000},{"type":"number"},{"maxItems":100,"type":"array","items":{"type":"string","maxLength":500}},{"type":"null"}]}},"required":["campo_id","valor"]}},"tags_adicionar":{"description":"Ids ou nomes de tag. Nome que não existe é criado.","maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}},"tags_remover":{"description":"Ids ou nomes de tag.","maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"$ref":"#/components/schemas/Lead"}},"required":["dados"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"409":{"description":"Outro lead da conta já tem este telefone (telefone_em_uso).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"leads:escrever"}},"/leads/{id}/notas":{"post":{"tags":["Leads"],"summary":"Anotar no lead","description":"Anotação no histórico do lead, como as feitas no painel do funil (autor \"API: <nome da chave>\").\n\n**Escopo:** `leads:escrever`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id do lead."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Valor único por operação (ex.: um UUID). Repetir a mesma requisição com a mesma chave em 24 h devolve a resposta da primeira, sem gravar de novo (cabeçalho Idempotente-Repetida: true)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"texto":{"description":"Texto da anotação.","type":"string","minLength":1,"maxLength":5000}},"required":["texto"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"$ref":"#/components/schemas/EventoHistorico"}},"required":["dados"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"409":{"description":"Conflito (ver codigo): duplicado, telefone em uso ou requisição com a mesma Idempotency-Key ainda em andamento.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"422":{"description":"Idempotency-Key já usada com outra requisição.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"leads:escrever"}},"/leads/{id}/historico":{"get":{"tags":["Leads"],"summary":"Histórico do lead","description":"Mudanças de etapa, campos, tags, responsável, anotações e outros eventos, mais recentes primeiro.\n\n**Escopo:** `leads:ler`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id do lead."},{"name":"limite","in":"query","required":false,"description":"Itens por página (1–100, padrão 50).","schema":{"description":"Itens por página (1–100, padrão 50).","default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"paginacao.proximo_cursor da página anterior.","schema":{"description":"paginacao.proximo_cursor da página anterior.","type":"string","maxLength":300}},{"name":"tipo","in":"query","required":false,"description":"Um ou mais tipos, separados por vírgula (ex.: mudanca_etapa,anotacao).","schema":{"description":"Um ou mais tipos, separados por vírgula (ex.: mudanca_etapa,anotacao).","type":"string"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"array","items":{"$ref":"#/components/schemas/EventoHistorico"}},"paginacao":{"$ref":"#/components/schemas/Paginacao"}},"required":["dados","paginacao"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"leads:ler"}},"/leads/{id}/perda":{"post":{"tags":["Vendas e perdas"],"summary":"Dar o lead por perdido","description":"Como na tela: move para a etapa de perda (a primeira do funil do lead, ou `etapa_id`) e grava o motivo, que entra no dashboard e no gráfico de motivos. Lead já perdido: só o motivo muda, sem duplicar. Dispara as automações da etapa de perda (pela fila). Mover para uma etapa de perda pelo PATCH é recusado (422 `etapa_de_perda`): use esta rota.\n\n**Escopo:** `leads:escrever`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id do lead."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Valor único por operação (ex.: um UUID). Repetir a mesma requisição com a mesma chave em 24 h devolve a resposta da primeira, sem gravar de novo (cabeçalho Idempotente-Repetida: true)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"objecao_id":{"description":"Motivo da perda (ver /conta → objecoes).","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"motivo":{"description":"Nome do motivo, se você não guardou o id (sem diferenciar maiúsculas e acentos).","type":"string","minLength":1,"maxLength":200},"observacao":{"description":"Texto livre, como na tela.","anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"etapa_id":{"description":"Etapa de perda de destino. Sem ela: a atual, se o lead já está perdido; senão, a primeira etapa de perda do funil do lead.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"$ref":"#/components/schemas/Lead"},"etapa_alterada":{"type":"boolean","description":"false quando o lead já estava na etapa de perda (só o motivo mudou)."}},"required":["dados","etapa_alterada"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"409":{"description":"Conflito (ver codigo): duplicado, telefone em uso ou requisição com a mesma Idempotency-Key ainda em andamento.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"422":{"description":"O funil do lead não tem etapa de perda ativa (sem_etapa_de_perda), ou Idempotency-Key já usada com outra requisição.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"leads:escrever"}},"/leads/{id}/vendas":{"get":{"tags":["Vendas e perdas"],"summary":"Vendas do lead","description":"Itens vendidos (`comprado`), em aberto e cancelados, mais recentes primeiro, com o pedido.\n\n**Escopo:** `vendas:ler`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id do lead."},{"name":"limite","in":"query","required":false,"description":"Itens por página (1–100, padrão 50).","schema":{"description":"Itens por página (1–100, padrão 50).","default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"paginacao.proximo_cursor da página anterior.","schema":{"description":"paginacao.proximo_cursor da página anterior.","type":"string","maxLength":300}},{"name":"status","in":"query","required":false,"description":"Só itens neste status (comprado = vendas).","schema":{"description":"Só itens neste status (comprado = vendas).","type":"string","enum":["aberto","comprado","cancelado"]}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"array","items":{"$ref":"#/components/schemas/Venda"}},"paginacao":{"$ref":"#/components/schemas/Paginacao"}},"required":["dados","paginacao"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"vendas:ler"},"post":{"tags":["Vendas e perdas"],"summary":"Registrar venda","description":"Como \"Confirmar venda\" na tela: cria um pedido confirmado com os itens comprados, na data e com o vendedor informados. Entra no faturamento, metas, ranking e Pedidos, e dispara a conversão de compra (Purchase) na Meta quando o lead veio de anúncio. Produto marcado como peça única fica esgotado. `marcar_ganho: true` também move o lead para a etapa de ganho. **Idempotency-Key obrigatória.**\n\n**Escopo:** `vendas:escrever`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id do lead."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":200},"description":"Valor único por operação (ex.: um UUID). Repetir a mesma requisição com a mesma chave em 24 h devolve a resposta da primeira, sem gravar de novo (cabeçalho Idempotente-Repetida: true). Obrigatório nesta rota: repetir sem ele duplicaria a venda."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"itens":{"description":"Até 50 itens, que viram um pedido.","minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"produto_id":{"description":"Item do catálogo (ver /produtos).","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"nome":{"description":"Item avulso (fora do catálogo): nome.","type":"string","minLength":1,"maxLength":200},"descricao":{"type":"string","maxLength":500},"valor":{"description":"Valor UNITÁRIO em reais. Obrigatório no item avulso; num produto, substitui o preço do catálogo.","type":"number","minimum":0,"maximum":100000000},"quantidade":{"description":"Padrão 1.","type":"integer","minimum":1,"maximum":999},"cor_id":{"description":"Variante do produto, se ele tiver.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"tamanho_id":{"description":"Variante do produto, se ele tiver.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"}},"additionalProperties":false}},"vendedor_id":{"description":"Quem vendeu (usuário com acesso ativo, ver /conta). Sem ele, o responsável pelo lead.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"vendido_em":{"description":"Data da venda (padrão: agora). Data sem hora vale o dia no fuso de Brasília. Não pode ser futura.","type":"string","maxLength":40},"observacao":{"description":"Observação do pedido.","type":"string","maxLength":1000},"marcar_ganho":{"description":"true também move o lead para a etapa de ganho do funil dele (dispara as automações dessa etapa).","type":"boolean"}},"required":["itens"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"object","properties":{"pedido":{"type":"object","properties":{"id":{"type":"string"},"numero":{"type":"string"},"status":{"type":"string"},"valor_total":{"type":"number"}}},"vendas":{"type":"array","items":{"$ref":"#/components/schemas/Venda"}},"etapa_alterada":{"type":"boolean"}},"required":["pedido","vendas","etapa_alterada"]}},"required":["dados"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"409":{"description":"Conflito (ver codigo): duplicado, telefone em uso ou requisição com a mesma Idempotency-Key ainda em andamento.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"422":{"description":"O funil do lead não tem etapa de ganho ativa (sem_etapa_de_ganho), ou Idempotency-Key já usada com outra requisição.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"vendas:escrever"}},"/empresas":{"get":{"tags":["Empresas"],"summary":"Listar empresas","description":"Mais recentes primeiro. Os contatos de uma empresa: GET /leads e o campo contato_empresa_id de cada lead.\n\n**Escopo:** `leads:ler`","parameters":[{"name":"limite","in":"query","required":false,"description":"Itens por página (1–100, padrão 50).","schema":{"description":"Itens por página (1–100, padrão 50).","default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"paginacao.proximo_cursor da página anterior.","schema":{"description":"paginacao.proximo_cursor da página anterior.","type":"string","maxLength":300}},{"name":"busca","in":"query","required":false,"description":"Parte do nome (sem diferenciar acento ou maiúscula) ou do CNPJ.","schema":{"description":"Parte do nome (sem diferenciar acento ou maiúscula) ou do CNPJ.","type":"string","minLength":1,"maxLength":200}},{"name":"segmento_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"array","items":{"$ref":"#/components/schemas/Empresa"}},"paginacao":{"$ref":"#/components/schemas/Paginacao"}},"required":["dados","paginacao"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"leads:ler"},"post":{"tags":["Empresas"],"summary":"Criar empresa","description":"Nome único na conta (sem diferenciar acento, maiúscula ou espaço): repetido dá 409 empresa_duplicada com o id da que existe; CNPJ repetido dá 409 cnpj_em_uso.\n\n**Escopo:** `leads:escrever`","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Valor único por operação (ex.: um UUID). Repetir a mesma requisição com a mesma chave em 24 h devolve a resposta da primeira, sem gravar de novo (cabeçalho Idempotente-Repetida: true)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nome":{"description":"Único na conta (sem diferenciar acento, maiúscula ou espaço).","type":"string","minLength":1,"maxLength":200},"cnpj":{"description":"Com ou sem pontuação; é gravado só com os números.","anyOf":[{"type":"string"},{"type":"null"}]},"segmento_id":{"description":"Segmento da lista da conta (o painel em Contatos → Empresas → Segmentos).","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"faturamento_faixa":{"anyOf":[{"type":"string","enum":["ate_360mil","360mil_4_8mi","4_8mi_30mi","30mi_300mi","acima_300mi"]},{"type":"null"}]},"site":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"telefone":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"cidade":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"uf":{"anyOf":[{"type":"string","enum":["AC","AL","AM","AP","BA","CE","DF","ES","GO","MA","MG","MS","MT","PA","PB","PE","PI","PR","RJ","RN","RO","RR","RS","SC","SE","SP","TO"]},{"type":"null"}]},"responsavel_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]}},"required":["nome"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"$ref":"#/components/schemas/Empresa"}},"required":["dados"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"409":{"description":"Conflito (ver codigo): duplicado, telefone em uso ou requisição com a mesma Idempotency-Key ainda em andamento.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"422":{"description":"Idempotency-Key já usada com outra requisição.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"leads:escrever"}},"/empresas/{id}":{"get":{"tags":["Empresas"],"summary":"Obter uma empresa","description":"**Escopo:** `leads:ler`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id da empresa do contato."}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"$ref":"#/components/schemas/Empresa"}},"required":["dados"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"leads:ler"},"patch":{"tags":["Empresas"],"summary":"Editar empresa","description":"Renomear muda também o empresa_contato dos contatos dela. Campos personalizados da empresa ainda não são editados pela API.\n\n**Escopo:** `leads:escrever`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id da empresa do contato."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nome":{"description":"Renomear muda também o empresa_contato dos contatos dela.","type":"string","minLength":1,"maxLength":200},"cnpj":{"description":"Com ou sem pontuação; é gravado só com os números.","anyOf":[{"type":"string"},{"type":"null"}]},"segmento_id":{"description":"Segmento da lista da conta (o painel em Contatos → Empresas → Segmentos).","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"faturamento_faixa":{"anyOf":[{"type":"string","enum":["ate_360mil","360mil_4_8mi","4_8mi_30mi","30mi_300mi","acima_300mi"]},{"type":"null"}]},"site":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"telefone":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"cidade":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"uf":{"anyOf":[{"type":"string","enum":["AC","AL","AM","AP","BA","CE","DF","ES","GO","MA","MG","MS","MT","PA","PB","PE","PI","PR","RJ","RN","RO","RR","RS","SC","SE","SP","TO"]},{"type":"null"}]},"responsavel_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"$ref":"#/components/schemas/Empresa"}},"required":["dados"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"leads:escrever"}},"/tarefas":{"get":{"tags":["Tarefas"],"summary":"Listar tarefas","description":"Mais recentes primeiro (pela data de criação).\n\n**Escopo:** `tarefas:ler`","parameters":[{"name":"limite","in":"query","required":false,"description":"Itens por página (1–100, padrão 50).","schema":{"description":"Itens por página (1–100, padrão 50).","default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"paginacao.proximo_cursor da página anterior.","schema":{"description":"paginacao.proximo_cursor da página anterior.","type":"string","maxLength":300}},{"name":"status","in":"query","required":false,"description":"pendente, em_andamento, concluida, cancelada (vários separados por vírgula).","schema":{"description":"pendente, em_andamento, concluida, cancelada (vários separados por vírgula).","type":"string"}},{"name":"responsavel_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"}},{"name":"lead_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"}},{"name":"vence_desde","in":"query","required":false,"schema":{"type":"string","maxLength":40}},{"name":"vence_ate","in":"query","required":false,"schema":{"type":"string","maxLength":40}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"array","items":{"$ref":"#/components/schemas/Tarefa"}},"paginacao":{"$ref":"#/components/schemas/Paginacao"}},"required":["dados","paginacao"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"tarefas:ler"},"post":{"tags":["Tarefas"],"summary":"Criar tarefa","description":"Com ou sem lead. O responsável recebe a notificação de tarefa atribuída.\n\n**Escopo:** `tarefas:escrever`","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Valor único por operação (ex.: um UUID). Repetir a mesma requisição com a mesma chave em 24 h devolve a resposta da primeira, sem gravar de novo (cabeçalho Idempotente-Repetida: true)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"titulo":{"type":"string","minLength":1,"maxLength":300},"descricao":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"tipo":{"default":"tarefa","type":"string","enum":["tarefa","ligacao","reuniao","email","whatsapp","visita","outro"]},"prioridade":{"default":"normal","type":"string","enum":["baixa","normal","alta","urgente"]},"vence_em":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]},"inicia_em":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]},"lead_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"responsavel_id":{"description":"Recebe a notificação de tarefa atribuída.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]}},"required":["titulo"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"$ref":"#/components/schemas/Tarefa"}},"required":["dados"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"409":{"description":"Conflito (ver codigo): duplicado, telefone em uso ou requisição com a mesma Idempotency-Key ainda em andamento.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"422":{"description":"Idempotency-Key já usada com outra requisição.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"tarefas:escrever"}},"/tarefas/{id}":{"get":{"tags":["Tarefas"],"summary":"Obter uma tarefa","description":"**Escopo:** `tarefas:ler`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id da tarefa."}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"$ref":"#/components/schemas/Tarefa"}},"required":["dados"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"tarefas:ler"},"patch":{"tags":["Tarefas"],"summary":"Editar ou concluir tarefa","description":"`status: \"concluida\"` grava a conclusão e registra no histórico do lead. Voltar de concluída limpa a data de conclusão.\n\n**Escopo:** `tarefas:escrever`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id da tarefa."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"titulo":{"type":"string","minLength":1,"maxLength":300},"descricao":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"tipo":{"type":"string","enum":["tarefa","ligacao","reuniao","email","whatsapp","visita","outro"]},"prioridade":{"type":"string","enum":["baixa","normal","alta","urgente"]},"status":{"description":"concluida grava a conclusão (e o histórico do lead); voltar de concluida limpa a data.","type":"string","enum":["pendente","em_andamento","concluida","cancelada"]},"observacao_conclusao":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"vence_em":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]},"inicia_em":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]},"lead_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"responsavel_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"$ref":"#/components/schemas/Tarefa"}},"required":["dados"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"tarefas:escrever"}},"/produtos":{"get":{"tags":["Produtos"],"summary":"Listar produtos e serviços","description":"**Escopo:** `produtos:ler`","parameters":[{"name":"limite","in":"query","required":false,"description":"Itens por página (1–100, padrão 50).","schema":{"description":"Itens por página (1–100, padrão 50).","default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"paginacao.proximo_cursor da página anterior.","schema":{"description":"paginacao.proximo_cursor da página anterior.","type":"string","maxLength":300}},{"name":"tipo","in":"query","required":false,"schema":{"type":"string","enum":["servico","produto"]}},{"name":"incluir_inativos","in":"query","required":false,"description":"true para incluir itens desativados (padrão: só ativos).","schema":{"description":"true para incluir itens desativados (padrão: só ativos).","type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"array","items":{"$ref":"#/components/schemas/Produto"}},"paginacao":{"$ref":"#/components/schemas/Paginacao"}},"required":["dados","paginacao"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"produtos:ler"}},"/funis":{"get":{"tags":["Funis e etapas"],"summary":"Listar funis","description":"Todos os funis com as etapas, na ordem do menu da tela (`ordem`), inclusive os excluídos (`ativo: false`) e os arquivados (`arquivado: true`).\n\n**Escopo:** `conta:ler`","parameters":[],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"array","items":{"$ref":"#/components/schemas/Funil"}}},"required":["dados"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"conta:ler"},"post":{"tags":["Funis e etapas"],"summary":"Criar funil","description":"Cria com as etapas abertas do corpo (a primeira é a de entrada; sem lista, \"Novo Lead\"), mais Venda e Perda no fim.\n\n**Escopo:** `funis:escrever`","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Valor único por operação (ex.: um UUID). Repetir a mesma requisição com a mesma chave em 24 h devolve a resposta da primeira, sem gravar de novo (cabeçalho Idempotente-Repetida: true)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nome":{"type":"string","minLength":1,"maxLength":100},"descricao":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"etapas":{"description":"Etapas abertas, em ordem; a primeira é a de entrada. Sem a lista, o funil nasce com \"Novo Lead\". Venda e Perda entram sempre, no fim.","minItems":1,"maxItems":30,"type":"array","items":{"type":"object","properties":{"nome":{"type":"string","minLength":1,"maxLength":100},"cor":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"descricao":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}},"required":["nome"],"additionalProperties":false}}},"required":["nome"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"$ref":"#/components/schemas/Funil"}},"required":["dados"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"409":{"description":"Conflito (ver codigo): duplicado, telefone em uso ou requisição com a mesma Idempotency-Key ainda em andamento.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"422":{"description":"Idempotency-Key já usada com outra requisição.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"funis:escrever"}},"/funis/{id}":{"get":{"tags":["Funis e etapas"],"summary":"Obter um funil","description":"**Escopo:** `conta:ler`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id do funil."}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"$ref":"#/components/schemas/Funil"}},"required":["dados"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"conta:ler"},"patch":{"tags":["Funis e etapas"],"summary":"Editar funil","description":"Nome e descrição.\n\n**Escopo:** `funis:escrever`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id do funil."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nome":{"type":"string","minLength":1,"maxLength":100},"descricao":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"$ref":"#/components/schemas/Funil"}},"required":["dados"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"funis:escrever"}},"/funis/{id}/etapas":{"post":{"tags":["Funis e etapas"],"summary":"Criar etapa","description":"Etapa aberta (Venda e Perda são fixas). Funil arquivado: 409 `funil_arquivado`.\n\n**Escopo:** `funis:escrever`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id do funil."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Valor único por operação (ex.: um UUID). Repetir a mesma requisição com a mesma chave em 24 h devolve a resposta da primeira, sem gravar de novo (cabeçalho Idempotente-Repetida: true)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nome":{"type":"string","minLength":1,"maxLength":100},"cor":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"descricao":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"posicao":{"description":"1 = primeira etapa aberta. Sem posicao, entra depois da última aberta. Com posicao, as etapas são renumeradas como na tela: abertas 1..N, Venda 998 e Perda 999.","type":"integer","minimum":1,"maximum":9007199254740991}},"required":["nome"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"$ref":"#/components/schemas/Etapa"}},"required":["dados"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"409":{"description":"Conflito (ver codigo): duplicado, telefone em uso ou requisição com a mesma Idempotency-Key ainda em andamento.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"422":{"description":"Idempotency-Key já usada com outra requisição.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"funis:escrever"}},"/funis/{id}/etapas/ordem":{"put":{"tags":["Funis e etapas"],"summary":"Reordenar etapas","description":"Mande os ids de todas as etapas abertas ativas na ordem nova. Venda e Perda ficam no fim.\n\n**Escopo:** `funis:escrever`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id do funil."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"etapas":{"description":"Ids de todas as etapas abertas ativas (entrada e normais), na ordem nova. Venda e Perda ficam no fim.","minItems":1,"maxItems":100,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"}}},"required":["etapas"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"$ref":"#/components/schemas/Funil"}},"required":["dados"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"funis:escrever"}},"/etapas/{id}":{"patch":{"tags":["Funis e etapas"],"summary":"Editar etapa","description":"Nome, cor, descrição; marcar como etapa de entrada ou de qualificação (uma de cada por funil). Venda e Perda só mudam nome, cor e descrição (422 `etapa_fixa`).\n\n**Escopo:** `funis:escrever`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id da etapa."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nome":{"type":"string","minLength":1,"maxLength":100},"cor":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"descricao":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"entrada":{"description":"Torna esta a etapa de entrada do funil (a anterior deixa de ser).","type":"boolean","const":true},"qualificada":{"description":"Etapa de qualificação (uma por funil: marcar esta desmarca a outra). Não vale para a etapa de entrada.","type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"$ref":"#/components/schemas/Etapa"}},"required":["dados"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"409":{"description":"Etapa ou funil arquivado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"422":{"description":"Regra da etapa (etapa_fixa, etapa_de_entrada).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"funis:escrever"}},"/automacoes":{"get":{"tags":["Automações"],"summary":"Listar automações","description":"Automações de etapa e workflows, sem o fluxo (use GET /automacoes/{id}). Filtre por `etapa_id` para ver as de uma coluna do funil.\n\n**Escopo:** `automacoes:ler`","parameters":[{"name":"limite","in":"query","required":false,"description":"Itens por página (1–100, padrão 50).","schema":{"description":"Itens por página (1–100, padrão 50).","default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"paginacao.proximo_cursor da página anterior.","schema":{"description":"paginacao.proximo_cursor da página anterior.","type":"string","maxLength":300}},{"name":"funil_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"}},{"name":"etapa_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"}},{"name":"gatilho","in":"query","required":false,"description":"novo_lead, tempo_na_fase, mudou_de_fase, recebeu_mensagem, tag_adicionada, gatilho_data_campo, agendamento, manual (vários separados por vírgula).","schema":{"description":"novo_lead, tempo_na_fase, mudou_de_fase, recebeu_mensagem, tag_adicionada, gatilho_data_campo, agendamento, manual (vários separados por vírgula).","type":"string"}},{"name":"ativa","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"array","items":{"$ref":"#/components/schemas/AutomacaoResumo"}},"paginacao":{"$ref":"#/components/schemas/Paginacao"}},"required":["dados","paginacao"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"automacoes:ler"},"post":{"tags":["Automações"],"summary":"Criar automação ou workflow","description":"Nasce **desligada** (ligue com PATCH). Gatilhos: novo_lead, tempo_na_fase, mudou_de_fase, recebeu_mensagem, tag_adicionada, gatilho_data_campo, agendamento, manual. Os automáticos exigem `etapa_id`; `manual` aceita só `funil_id` (ou nada).\n\nMonte o fluxo na tela uma vez e leia com `GET /automacoes/{id}`: é o mesmo formato. Cada nó é `{ \"id\", \"type\", \"label\", \"config\", \"position\" }` e cada conexão `{ \"sourceId\", \"targetId\", \"sourceHandle\" }`. Um nó `start` (config `{}`) e pelo menos uma ação; `label` e `position` são opcionais.\n\n| type | config (principais) |\n|---|---|\n| `send_message` | `message`; `instanceId` (número; sem ele, o do lead); `messageButtons` |\n| `send_media` | `mediaUrl` (http/https), `mediaType` (image, video, audio, document), `mediaCaption` |\n| `send_template` | `instanceId` (API Oficial), `templateName`, `templateLanguage`, `templateVariables` |\n| `send_catalog` | `instanceId`, `catalogCaption` |\n| `capture_input` | `message` e `customFieldId` ou `nativeField`; saídas `answered` e `timeout` |\n| `wait` | `waitValue`, `waitUnit` (seconds, minutes, hours, days), `waitForMessage` |\n| `condition` | `conditions` [{ `type`, `value`, `tagId`, `instanceId`, `field`, `operator`, `userId` }]. Em `field_equals`, `operator` greater, less, greater_or_equal e less_or_equal comparam como número (`value` \"1500\" ou \"1.500,00\"). `responsible_is` compara o responsável do lead: `operator` equals ou not_equals com `userId`, ou is_empty / is_not_empty (sem / com responsável). Saídas `condition_N` (a primeira condição verdadeira) e `else` |\n| `round_robin` | `roundRobinPaths`; saídas `path_N` |\n| `random` | `variations` [{ `id`, `weight` }]; saídas `variation-<id>` |\n| `assign_user` | `userId` |\n| `add_tag` / `remove_tag` | `tagId` ou `tags` [{ `tagId` }] para várias no mesmo bloco (a primeira também fica em `tagId`) |\n| `move_stage` | `stageId` (`funnelId` é preenchido pela etapa); `objecaoId` na etapa de perda |\n| `set_custom_field` | `customFieldId`, `customFieldValue` (ou `customFieldValues` em seleção múltipla) |\n| `create_task` | `taskTitle`, `taskType`, `taskPriority` (low, medium, high, urgent), `taskDueDays`, `taskAssignTo` (owner, specific), `taskUserId` |\n| `notify` | `notifyMessage`, `notifyDestinatarios` [{ `tipo`: numero ou usuario, `valor` }], `notifyCanais` (whatsapp, sistema), `notifyInstanceId` |\n| `notify_group` | `notifyInstanceId`, `notifyMessage`, `notifyDestinatarios` [{ `tipo`: \"grupo\", `valor` }] |\n| `webhook` | `webhookUrl`, `webhookMethod`, `webhookHeaders` |\n| `create_order` | `orderItems` [{ `servicoId`, `nome`, `qtd`, `corId`, `tamanhoId` }], `orderStatus` (pendente, confirmado) |\n| `gerar_followup_ia` | `aiAgentId`, `followupIntensidade` (leve, moderado, persuasivo) |\n| `send_meta_conversion` | `metaEventType` (Lead, Purchase… ou custom + `metaEventName`) |\n| `end` | `{}` |\n\nTodo id dentro do config (tag, etapa, número, usuário, campo, agente, template, produto, motivo de perda) tem de ser desta conta. O nome que acompanha o id (`tagName`, `stageName`, `userName`...) é preenchido quando vier vazio. Erros apontam o nó: `nos[3].config.tagId`.\n\n**Escopo:** `automacoes:escrever`","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Valor único por operação (ex.: um UUID). Repetir a mesma requisição com a mesma chave em 24 h devolve a resposta da primeira, sem gravar de novo (cabeçalho Idempotente-Repetida: true)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nome":{"type":"string","minLength":1,"maxLength":200},"descricao":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"funil_id":{"description":"Sem etapa_id, só para workflow manual (null = sem funil). Com etapa_id, pode ser omitido.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"etapa_id":{"description":"Etapa onde a automação fica. Obrigatório nos gatilhos automáticos; não vale para manual.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"gatilho":{"type":"object","properties":{"tipo":{"type":"string","enum":["novo_lead","tempo_na_fase","mudou_de_fase","recebeu_mensagem","tag_adicionada","gatilho_data_campo","agendamento","manual"]},"tempo_minutos":{"description":"Espera depois do evento; em tempo_na_fase, o tempo na etapa. 0 = na hora.","type":"integer","minimum":0,"maximum":525600},"fase_origem_id":{"description":"mudou_de_fase: só quando o lead vier desta etapa do mesmo funil (null = de qualquer uma).","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"fase_destino_id":{"description":"Ignorado: em mudou_de_fase o destino é sempre etapa_id.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"tag_id":{"description":"tag_adicionada: só esta tag (null = qualquer tag).","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"evento":{"description":"agendamento: o que aconteceu com o compromisso da agenda nativa (padrão: criado). lembrete = antes do início ou depois do fim, pelo deslocamento (padrão: 24 horas antes).","type":"string","enum":["criado","remarcado","cancelado","lembrete"]},"agenda_id":{"description":"agendamento: só esta agenda (null = qualquer agenda).","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"campo_id":{"description":"gatilho_data_campo: campo personalizado de data ou data e hora.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"minutos_antes":{"type":"integer","minimum":0,"maximum":525600},"minutos_depois":{"type":"integer","minimum":0,"maximum":525600},"horas_antes":{"type":"integer","minimum":0,"maximum":8760},"horas_depois":{"type":"integer","minimum":0,"maximum":8760},"dias_antes":{"type":"integer","minimum":0,"maximum":365},"dias_depois":{"type":"integer","minimum":0,"maximum":365},"horario_ativacao":{"description":"Janela de horário: fora dela, a execução espera a próxima abertura.","type":"object","properties":{"ativo":{"type":"boolean"},"modo":{"type":"string","enum":["simples","avancado"]},"hora_inicio":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"hora_fim":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"dias_semana":{"description":"0 = domingo.","maxItems":7,"type":"array","items":{"type":"integer","minimum":0,"maximum":6}},"por_dia":{"description":"modo avancado: uma janela por dia (\"0\" = domingo).","type":"object","propertyNames":{"anyOf":[{"type":"string","enum":["0","1","2","3","4","5","6"]},{"not":{}}]},"additionalProperties":{"type":"object","properties":{"ativo":{"type":"boolean"},"hora_inicio":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"hora_fim":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}},"required":["ativo","hora_inicio","hora_fim"],"additionalProperties":false}}},"required":["ativo"],"additionalProperties":false}},"required":["tipo"],"additionalProperties":false},"nos":{"description":"Nós do fluxo no formato do editor. Um nó \"start\" e pelo menos uma ação.","minItems":2,"maxItems":150,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":100},"type":{"type":"string","enum":["start","end","send_message","send_media","send_template","send_catalog","capture_input","wait","condition","round_robin","random","assign_user","add_tag","remove_tag","move_stage","set_custom_field","create_task","notify","notify_group","webhook","create_order","gerar_followup_ia","send_meta_conversion"]},"label":{"type":"string","maxLength":200},"config":{"default":{},"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"position":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"]}},"required":["id","type"]}},"conexoes":{"description":"Ligações entre os nós (sourceId → targetId).","maxItems":400,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":100},"sourceId":{"type":"string","minLength":1,"maxLength":100},"targetId":{"type":"string","minLength":1,"maxLength":100},"sourceHandle":{"description":"Saída do nó: default, yes/no, path_N, condition_N, else, answered, timeout, button-*, variation-*.","type":"string","minLength":1,"maxLength":200},"label":{"type":"string","maxLength":200}},"required":["sourceId","targetId"]}},"pasta":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"marcar_conversa_nao_lida":{"description":"Padrão true: o envio da automação deixa a conversa como não lida.","type":"boolean"}},"required":["nome","gatilho","nos","conexoes"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"$ref":"#/components/schemas/Automacao"}},"required":["dados"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"409":{"description":"Conflito (ver codigo): duplicado, telefone em uso ou requisição com a mesma Idempotency-Key ainda em andamento.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"422":{"description":"Idempotency-Key já usada com outra requisição.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"automacoes:escrever"}},"/automacoes/{id}":{"get":{"tags":["Automações"],"summary":"Obter uma automação","description":"Com o fluxo completo (nós e conexões), no formato aceito por POST /automacoes.\n\n**Escopo:** `automacoes:ler`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id da automação."}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"$ref":"#/components/schemas/Automacao"}},"required":["dados"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"automacoes:ler"},"patch":{"tags":["Automações"],"summary":"Ligar, desligar ou renomear","description":"Ligar (`ativa: true`) valida o fluxo de novo: tag apagada, etapa arquivada, número de outra conta etc. dão 422 `fluxo_invalido` com a lista. Desligar cancela as execuções agendadas.\n\n**Escopo:** `automacoes:escrever`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id da automação."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ativa":{"description":"true liga (o fluxo é validado de novo; falha = 422 fluxo_invalido); false desliga e cancela as execuções agendadas.","type":"boolean"},"nome":{"type":"string","minLength":1,"maxLength":200},"descricao":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"pasta":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"$ref":"#/components/schemas/Automacao"}},"required":["dados"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"422":{"description":"O fluxo não passa na validação (fluxo_invalido).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"automacoes:escrever"}},"/automacoes/{id}/duplicar":{"post":{"tags":["Automações"],"summary":"Duplicar automação","description":"Cópia **desligada**, no mesmo lugar ou em outra etapa (`etapa_id`; o funil vem dela). Workflow manual muda de funil com `funil_id`.\n\n**Escopo:** `automacoes:escrever`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id da automação."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Valor único por operação (ex.: um UUID). Repetir a mesma requisição com a mesma chave em 24 h devolve a resposta da primeira, sem gravar de novo (cabeçalho Idempotente-Repetida: true)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nome":{"description":"Padrão: \"<nome> (cópia)\".","type":"string","minLength":1,"maxLength":200},"funil_id":{"description":"Outro funil (com etapa_id). Em workflow manual, null tira do funil.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"etapa_id":{"description":"Outra etapa (o funil vem dela).","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"pasta":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]}},"additionalProperties":false}}}},"responses":{"201":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"$ref":"#/components/schemas/Automacao"}},"required":["dados"]}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"409":{"description":"Conflito (ver codigo): duplicado, telefone em uso ou requisição com a mesma Idempotency-Key ainda em andamento.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"422":{"description":"Idempotency-Key já usada com outra requisição.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"automacoes:escrever"}},"/webhooks":{"get":{"tags":["Gestão de webhooks"],"summary":"Listar webhooks","description":"**Escopo:** `webhooks:gerenciar`","parameters":[],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"descricao":{"type":["string","null"]},"eventos":{"type":"array","items":{"type":"string","enum":["lead.criado","lead.atualizado","lead.etapa_alterada","lead.excluido","lead.tag_adicionada","lead.tag_removida","tarefa.criada","tarefa.concluida","mensagem.recebida"]}},"ativo":{"type":"boolean"},"desativado_em":{"type":["string","null"]},"desativado_motivo":{"type":["string","null"]},"criado_em":{"type":"string"},"ultimo_sucesso_em":{"type":["string","null"]},"ultima_falha_em":{"type":["string","null"]},"segredo":{"type":"string","description":"Só ao criar, em GET /webhooks/{id} e ao gerar um novo. Usado para conferir a assinatura."}}}}}}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"webhooks:gerenciar"},"post":{"tags":["Gestão de webhooks"],"summary":"Criar webhook","description":"Devolve o `segredo` usado na assinatura. Até 10 webhooks por conta.\n\n**Escopo:** `webhooks:gerenciar`","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Valor único por operação (ex.: um UUID). Repetir a mesma requisição com a mesma chave em 24 h devolve a resposta da primeira, sem gravar de novo (cabeçalho Idempotente-Repetida: true)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"description":"https://... que recebe os avisos (POST).","type":"string","maxLength":2000},"eventos":{"description":"Eventos que este webhook recebe.","minItems":1,"maxItems":9,"type":"array","items":{"type":"string","enum":["lead.criado","lead.atualizado","lead.etapa_alterada","lead.excluido","lead.tag_adicionada","lead.tag_removida","tarefa.criada","tarefa.concluida","mensagem.recebida"]}},"descricao":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}},"required":["url","eventos"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"descricao":{"type":["string","null"]},"eventos":{"type":"array","items":{"type":"string","enum":["lead.criado","lead.atualizado","lead.etapa_alterada","lead.excluido","lead.tag_adicionada","lead.tag_removida","tarefa.criada","tarefa.concluida","mensagem.recebida"]}},"ativo":{"type":"boolean"},"desativado_em":{"type":["string","null"]},"desativado_motivo":{"type":["string","null"]},"criado_em":{"type":"string"},"ultimo_sucesso_em":{"type":["string","null"]},"ultima_falha_em":{"type":["string","null"]},"segredo":{"type":"string","description":"Só ao criar, em GET /webhooks/{id} e ao gerar um novo. Usado para conferir a assinatura."}}}}}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"409":{"description":"Conflito (ver codigo): duplicado, telefone em uso ou requisição com a mesma Idempotency-Key ainda em andamento.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"422":{"description":"Idempotency-Key já usada com outra requisição.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"webhooks:gerenciar"}},"/webhooks/{id}":{"get":{"tags":["Gestão de webhooks"],"summary":"Obter webhook (com o segredo)","description":"**Escopo:** `webhooks:gerenciar`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id do webhook."}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"descricao":{"type":["string","null"]},"eventos":{"type":"array","items":{"type":"string","enum":["lead.criado","lead.atualizado","lead.etapa_alterada","lead.excluido","lead.tag_adicionada","lead.tag_removida","tarefa.criada","tarefa.concluida","mensagem.recebida"]}},"ativo":{"type":"boolean"},"desativado_em":{"type":["string","null"]},"desativado_motivo":{"type":["string","null"]},"criado_em":{"type":"string"},"ultimo_sucesso_em":{"type":["string","null"]},"ultima_falha_em":{"type":["string","null"]},"segredo":{"type":"string","description":"Só ao criar, em GET /webhooks/{id} e ao gerar um novo. Usado para conferir a assinatura."}}}}}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"webhooks:gerenciar"},"patch":{"tags":["Gestão de webhooks"],"summary":"Editar webhook","description":"`ativo: true` reativa um webhook desativado. `novo_segredo: true` troca o segredo na hora.\n\n**Escopo:** `webhooks:gerenciar`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id do webhook."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2000},"eventos":{"minItems":1,"maxItems":9,"type":"array","items":{"type":"string","enum":["lead.criado","lead.atualizado","lead.etapa_alterada","lead.excluido","lead.tag_adicionada","lead.tag_removida","tarefa.criada","tarefa.concluida","mensagem.recebida"]}},"descricao":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"ativo":{"description":"true reativa um webhook desativado.","type":"boolean"},"novo_segredo":{"description":"Gera um segredo novo (o antigo para de valer na hora).","type":"boolean","const":true}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"descricao":{"type":["string","null"]},"eventos":{"type":"array","items":{"type":"string","enum":["lead.criado","lead.atualizado","lead.etapa_alterada","lead.excluido","lead.tag_adicionada","lead.tag_removida","tarefa.criada","tarefa.concluida","mensagem.recebida"]}},"ativo":{"type":"boolean"},"desativado_em":{"type":["string","null"]},"desativado_motivo":{"type":["string","null"]},"criado_em":{"type":"string"},"ultimo_sucesso_em":{"type":["string","null"]},"ultima_falha_em":{"type":["string","null"]},"segredo":{"type":"string","description":"Só ao criar, em GET /webhooks/{id} e ao gerar um novo. Usado para conferir a assinatura."}}}}}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"webhooks:gerenciar"},"delete":{"tags":["Gestão de webhooks"],"summary":"Apagar webhook","description":"**Escopo:** `webhooks:gerenciar`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id do webhook."}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"object","properties":{"id":{"type":"string"},"apagado":{"type":"boolean"}}}}}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"webhooks:gerenciar"}},"/webhooks/{id}/entregas":{"get":{"tags":["Gestão de webhooks"],"summary":"Log de entregas","description":"Mais recentes primeiro. Guardado por 30 dias.\n\n**Escopo:** `webhooks:gerenciar`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id do webhook."},{"name":"limite","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":300}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pendente","enviando","entregue","falhou","cancelada"]}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"evento_id":{"type":"string","format":"uuid"},"evento":{"type":["string","null"]},"status":{"type":"string","enum":["pendente","enviando","entregue","falhou","cancelada"]},"tentativas":{"type":"integer"},"status_http":{"type":["integer","null"]},"erro":{"type":["string","null"]},"resposta":{"type":["string","null"],"description":"Até 2 KB do que a sua URL respondeu."},"latencia_ms":{"type":["integer","null"]},"criado_em":{"type":"string"},"entregue_em":{"type":["string","null"]},"proxima_tentativa_em":{"type":["string","null"]}}}},"paginacao":{"$ref":"#/components/schemas/Paginacao"}}}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"webhooks:gerenciar"}},"/webhooks/{id}/teste":{"post":{"tags":["Gestão de webhooks"],"summary":"Testar webhook","description":"Manda um evento `ping` agora (mesmo com o webhook desativado) e devolve o resultado.\n\n**Escopo:** `webhooks:gerenciar`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id do webhook."}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"object","properties":{"ok":{"type":"boolean"},"status_http":{"type":["integer","null"]},"erro":{"type":["string","null"]},"latencia_ms":{"type":"integer"},"entrega_id":{"type":"string","format":"uuid"}}}}}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"webhooks:gerenciar"}},"/webhooks/entregas/{id}/reenviar":{"post":{"tags":["Gestão de webhooks"],"summary":"Reenviar entrega","description":"**Escopo:** `webhooks:gerenciar`","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id da entrega."}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requisições por hora da conta (5000)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Quantas ainda restam nesta hora."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Segundos até a contagem zerar."},"X-Requisicao-Id":{"schema":{"type":"string"},"description":"Id desta requisição (informe ao suporte)."}},"content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"object","properties":{"ok":{"type":"boolean"},"status_http":{"type":["integer","null"]},"erro":{"type":["string","null"]},"latencia_ms":{"type":"integer"},"entrega_id":{"type":"string","format":"uuid"}}}}}}}},"400":{"description":"Parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Escopo insuficiente ou conta suspensa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de requisições atingido. Aguarde o tempo de Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos até poder tentar de novo."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"x-escopo":"webhooks:gerenciar"}}},"webhooks":{"lead.criado":{"post":{"summary":"Lead criado","description":"Lead novo, de qualquer origem.\n\nCabeçalhos: `X-DotSales-Evento: lead.criado`, `X-DotSales-Evento-Id`, `X-DotSales-Tentativa`, `X-DotSales-Assinatura`. O objeto do lead vem no estado do momento da entrega.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Id do evento — o mesmo em todas as tentativas."},"tipo":{"type":"string","const":"lead.criado"},"ocorrido_em":{"type":"string"},"empresa_id":{"type":"string","format":"uuid"},"dados":{"type":"object","properties":{"lead":{"$ref":"#/components/schemas/Lead"}}}}}}}},"responses":{"2XX":{"description":"Recebido. Responda em até 10 s; processe depois."}}}},"lead.atualizado":{"post":{"summary":"Lead atualizado","description":"Mudou um dado do lead; traz o antes e o depois de cada campo.\n\nCabeçalhos: `X-DotSales-Evento: lead.atualizado`, `X-DotSales-Evento-Id`, `X-DotSales-Tentativa`, `X-DotSales-Assinatura`. O objeto do lead vem no estado do momento da entrega.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Id do evento — o mesmo em todas as tentativas."},"tipo":{"type":"string","const":"lead.atualizado"},"ocorrido_em":{"type":"string"},"empresa_id":{"type":"string","format":"uuid"},"dados":{"type":"object","properties":{"lead":{"$ref":"#/components/schemas/Lead"},"mudancas":{"type":"object","description":"Campo → { antes, depois }. Dados pessoais vêm só como { alterado: true }.","additionalProperties":{"type":"object","properties":{"antes":{},"depois":{},"alterado":{"type":"boolean"}}}}}}}}}}},"responses":{"2XX":{"description":"Recebido. Responda em até 10 s; processe depois."}}}},"lead.etapa_alterada":{"post":{"summary":"Lead mudou de etapa","description":"Mudou de etapa ou de funil; traz de onde saiu e para onde foi.\n\nCabeçalhos: `X-DotSales-Evento: lead.etapa_alterada`, `X-DotSales-Evento-Id`, `X-DotSales-Tentativa`, `X-DotSales-Assinatura`. O objeto do lead vem no estado do momento da entrega.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Id do evento — o mesmo em todas as tentativas."},"tipo":{"type":"string","const":"lead.etapa_alterada"},"ocorrido_em":{"type":"string"},"empresa_id":{"type":"string","format":"uuid"},"dados":{"type":"object","properties":{"lead":{"$ref":"#/components/schemas/Lead"},"de_funil_id":{"type":["string","null"]},"para_funil_id":{"type":["string","null"]},"de_etapa_id":{"type":["string","null"]},"para_etapa_id":{"type":["string","null"]}}}}}}}},"responses":{"2XX":{"description":"Recebido. Responda em até 10 s; processe depois."}}}},"lead.excluido":{"post":{"summary":"Lead excluído","description":"Lead apagado.\n\nCabeçalhos: `X-DotSales-Evento: lead.excluido`, `X-DotSales-Evento-Id`, `X-DotSales-Tentativa`, `X-DotSales-Assinatura`. O objeto do lead vem no estado do momento da entrega.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Id do evento — o mesmo em todas as tentativas."},"tipo":{"type":"string","const":"lead.excluido"},"ocorrido_em":{"type":"string"},"empresa_id":{"type":"string","format":"uuid"},"dados":{"type":"object","properties":{"lead_id":{"type":"string"},"nome":{"type":["string","null"]}}}}}}}},"responses":{"2XX":{"description":"Recebido. Responda em até 10 s; processe depois."}}}},"lead.tag_adicionada":{"post":{"summary":"Tag adicionada","description":"Uma tag entrou no lead.\n\nCabeçalhos: `X-DotSales-Evento: lead.tag_adicionada`, `X-DotSales-Evento-Id`, `X-DotSales-Tentativa`, `X-DotSales-Assinatura`. O objeto do lead vem no estado do momento da entrega.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Id do evento — o mesmo em todas as tentativas."},"tipo":{"type":"string","const":"lead.tag_adicionada"},"ocorrido_em":{"type":"string"},"empresa_id":{"type":"string","format":"uuid"},"dados":{"type":"object","properties":{"lead":{"$ref":"#/components/schemas/Lead"},"tag":{"$ref":"#/components/schemas/Tag"}}}}}}}},"responses":{"2XX":{"description":"Recebido. Responda em até 10 s; processe depois."}}}},"lead.tag_removida":{"post":{"summary":"Tag removida","description":"Uma tag saiu do lead.\n\nCabeçalhos: `X-DotSales-Evento: lead.tag_removida`, `X-DotSales-Evento-Id`, `X-DotSales-Tentativa`, `X-DotSales-Assinatura`. O objeto do lead vem no estado do momento da entrega.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Id do evento — o mesmo em todas as tentativas."},"tipo":{"type":"string","const":"lead.tag_removida"},"ocorrido_em":{"type":"string"},"empresa_id":{"type":"string","format":"uuid"},"dados":{"type":"object","properties":{"lead":{"$ref":"#/components/schemas/Lead"},"tag":{"$ref":"#/components/schemas/Tag"}}}}}}}},"responses":{"2XX":{"description":"Recebido. Responda em até 10 s; processe depois."}}}},"tarefa.criada":{"post":{"summary":"Tarefa criada","description":"Tarefa nova.\n\nCabeçalhos: `X-DotSales-Evento: tarefa.criada`, `X-DotSales-Evento-Id`, `X-DotSales-Tentativa`, `X-DotSales-Assinatura`. O objeto do lead vem no estado do momento da entrega.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Id do evento — o mesmo em todas as tentativas."},"tipo":{"type":"string","const":"tarefa.criada"},"ocorrido_em":{"type":"string"},"empresa_id":{"type":"string","format":"uuid"},"dados":{"type":"object","properties":{"tarefa":{"$ref":"#/components/schemas/Tarefa"},"lead_id":{"type":["string","null"]}}}}}}}},"responses":{"2XX":{"description":"Recebido. Responda em até 10 s; processe depois."}}}},"tarefa.concluida":{"post":{"summary":"Tarefa concluída","description":"Tarefa marcada como concluída.\n\nCabeçalhos: `X-DotSales-Evento: tarefa.concluida`, `X-DotSales-Evento-Id`, `X-DotSales-Tentativa`, `X-DotSales-Assinatura`. O objeto do lead vem no estado do momento da entrega.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Id do evento — o mesmo em todas as tentativas."},"tipo":{"type":"string","const":"tarefa.concluida"},"ocorrido_em":{"type":"string"},"empresa_id":{"type":"string","format":"uuid"},"dados":{"type":"object","properties":{"tarefa":{"$ref":"#/components/schemas/Tarefa"},"lead_id":{"type":["string","null"]}}}}}}}},"responses":{"2XX":{"description":"Recebido. Responda em até 10 s; processe depois."}}}},"mensagem.recebida":{"post":{"summary":"Mensagem recebida","description":"Mensagem do lead chegou (WhatsApp, Instagram...).\n\nCabeçalhos: `X-DotSales-Evento: mensagem.recebida`, `X-DotSales-Evento-Id`, `X-DotSales-Tentativa`, `X-DotSales-Assinatura`. O objeto do lead vem no estado do momento da entrega.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Id do evento — o mesmo em todas as tentativas."},"tipo":{"type":"string","const":"mensagem.recebida"},"ocorrido_em":{"type":"string"},"empresa_id":{"type":"string","format":"uuid"},"dados":{"type":"object","properties":{"mensagem":{"type":"object","properties":{"id":{"type":"string"},"conversa_id":{"type":"string"},"canal":{"type":["string","null"],"description":"whatsapp, instagram_dm, instagram_comment..."},"tipo":{"type":["string","null"],"description":"texto, imagem, audio, video, documento..."},"texto":{"type":["string","null"]},"arquivo":{"type":["object","null"],"properties":{"url":{"type":"string"},"nome":{"type":["string","null"]},"tipo":{"type":["string","null"]}}},"criado_em":{"type":"string"}}},"lead":{"$ref":"#/components/schemas/Lead"}}}}}}}},"responses":{"2XX":{"description":"Recebido. Responda em até 10 s; processe depois."}}}}},"components":{"schemas":{"Tag":{"description":"Tag de lead.","type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"nome":{"type":"string"},"cor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","nome","cor"],"additionalProperties":false},"Arquivo":{"description":"Arquivo anexado a um campo do tipo \"arquivo\".","type":"object","properties":{"nome":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"mime":{"anyOf":[{"type":"string"},{"type":"null"}]},"tamanho":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["nome","url","mime","tamanho"],"additionalProperties":false},"CampoValor":{"description":"Valor de um campo personalizado do lead.","type":"object","properties":{"campo_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"nome":{"type":"string"},"tipo":{"description":"texto, texto_longo, moeda, data, data_hora, selecao_simples, selecao_multipla ou arquivo.","type":"string"},"valor":{"description":"Texto; lista de opções em selecao_multipla; lista de arquivos em arquivo.","anyOf":[{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"$ref":"#/components/schemas/Arquivo"}}]},{"type":"null"}]}},"required":["campo_id","nome","tipo","valor"],"additionalProperties":false},"Tarefa":{"description":"Tarefa.","type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"titulo":{"type":"string"},"descricao":{"anyOf":[{"type":"string"},{"type":"null"}]},"tipo":{"description":"tarefa, ligacao, reuniao, email, whatsapp, visita ou outro.","anyOf":[{"type":"string"},{"type":"null"}]},"prioridade":{"description":"baixa, normal, alta ou urgente.","anyOf":[{"type":"string"},{"type":"null"}]},"status":{"description":"pendente, em_andamento, concluida ou cancelada.","anyOf":[{"type":"string"},{"type":"null"}]},"vence_em":{"anyOf":[{"description":"Data e hora em ISO 8601 (UTC).","type":"string"},{"type":"null"}]},"iniciada_em":{"anyOf":[{"description":"Data e hora em ISO 8601 (UTC).","type":"string"},{"type":"null"}]},"concluida_em":{"anyOf":[{"description":"Data e hora em ISO 8601 (UTC).","type":"string"},{"type":"null"}]},"observacao_conclusao":{"anyOf":[{"type":"string"},{"type":"null"}]},"lead_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"responsavel_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"criado_por_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"criado_em":{"description":"Data e hora em ISO 8601 (UTC).","type":"string"}},"required":["id","titulo","descricao","tipo","prioridade","status","vence_em","iniciada_em","concluida_em","observacao_conclusao","lead_id","responsavel_id","criado_por_id","criado_em"],"additionalProperties":false},"Empresa":{"description":"Empresa do contato. Uma empresa tem vários contatos (o lead aponta por contato_empresa_id).","type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"nome":{"type":"string"},"cnpj":{"description":"Só os 14 números.","anyOf":[{"type":"string"},{"type":"null"}]},"segmento_id":{"description":"Segmento, da lista da conta.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"segmento":{"description":"Nome do segmento.","anyOf":[{"type":"string"},{"type":"null"}]},"faturamento_faixa":{"description":"ate_360mil, 360mil_4_8mi, 4_8mi_30mi, 30mi_300mi ou acima_300mi.","anyOf":[{"type":"string"},{"type":"null"}]},"site":{"anyOf":[{"type":"string"},{"type":"null"}]},"telefone":{"anyOf":[{"type":"string"},{"type":"null"}]},"cidade":{"anyOf":[{"type":"string"},{"type":"null"}]},"uf":{"anyOf":[{"type":"string"},{"type":"null"}]},"responsavel_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"campos":{"description":"Campos personalizados da empresa: nome do campo → valor (número e moeda como \"1234.5\", data AAAA-MM-DD, sim/não \"sim\" ou \"nao\").","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"criado_em":{"description":"Data e hora em ISO 8601 (UTC).","type":"string"},"atualizado_em":{"description":"Data e hora em ISO 8601 (UTC).","type":"string"}},"required":["id","nome","cnpj","segmento_id","segmento","faturamento_faixa","site","telefone","cidade","uf","responsavel_id","campos","criado_em","atualizado_em"],"additionalProperties":false},"Perda":{"description":"Perda registrada: o motivo marcado ao dar o lead por perdido.","type":"object","properties":{"objecao_id":{"description":"Motivo (ver /conta → objecoes).","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"objecao":{"description":"Nome do motivo.","anyOf":[{"type":"string"},{"type":"null"}]},"observacao":{"anyOf":[{"type":"string"},{"type":"null"}]},"em":{"description":"Quando foi registrada.","type":"string"}},"required":["objecao_id","objecao","observacao","em"],"additionalProperties":false},"Lead":{"description":"Lead (contato + oportunidade).","type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"nome":{"type":"string"},"telefone":{"description":"E.164 (ex.: +5511999998888) quando o número é válido; senão, como foi cadastrado.","anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"empresa_contato":{"description":"Nome da empresa do contato. Ao gravar, o lead é ligado à empresa com esse nome (sem diferenciar acento ou maiúscula), ou ela é criada; CPF e textos como \"Autônomo\" ficam só como texto.","anyOf":[{"type":"string"},{"type":"null"}]},"contato_empresa_id":{"description":"Empresa do contato (GET /empresas/{id}). Uma empresa tem vários contatos.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"funil_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"etapa_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"responsavel_id":{"description":"Usuário responsável (ver /conta → usuarios).","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"fonte":{"description":"De onde o lead veio: whatsapp, instagram, importacao, manual, webhook, api...","anyOf":[{"type":"string"},{"type":"null"}]},"fonte_detalhe":{"anyOf":[{"type":"string"},{"type":"null"}]},"probabilidade":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"previsao_fechamento":{"description":"Data prevista de fechamento (AAAA-MM-DD).","anyOf":[{"type":"string"},{"type":"null"}]},"fechado_em":{"description":"Campo antigo, normalmente vazio: a venda fica em GET /leads/{id}/vendas.","anyOf":[{"description":"Data e hora em ISO 8601 (UTC).","type":"string"},{"type":"null"}]},"motivo_perda":{"description":"Texto livre antigo, normalmente vazio: o motivo registrado está em `perda`.","anyOf":[{"type":"string"},{"type":"null"}]},"observacoes":{"anyOf":[{"type":"string"},{"type":"null"}]},"instagram":{"description":"Usuário do Instagram.","anyOf":[{"type":"string"},{"type":"null"}]},"pais":{"anyOf":[{"type":"string"},{"type":"null"}]},"estado":{"anyOf":[{"type":"string"},{"type":"null"}]},"cidade":{"anyOf":[{"type":"string"},{"type":"null"}]},"profissao":{"anyOf":[{"type":"string"},{"type":"null"}]},"rastreio":{"description":"Primeiro toque de origem, com os nomes do contrato de entrada: plataforma, anuncio_id, conjunto_id, campanha_id, utm_*, gclid, fbclid, pagina_url, ctwa_clid, ponto_de_entrada...","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},{"type":"null"}]},"criado_em":{"description":"Data e hora em ISO 8601 (UTC).","type":"string"},"atualizado_em":{"description":"Muda quando muda um dado do lead (nome, contato, etapa, responsável, observações...). Tags e campos personalizados não contam: veja o histórico. Confiável a partir de 20/10/2026.","anyOf":[{"description":"Data e hora em ISO 8601 (UTC).","type":"string"},{"type":"null"}]},"ultima_interacao_em":{"anyOf":[{"description":"Data e hora em ISO 8601 (UTC).","type":"string"},{"type":"null"}]},"cpf":{"description":"Só com o escopo leads:dados_pessoais.","anyOf":[{"type":"string"},{"type":"null"}]},"data_nascimento":{"description":"AAAA-MM-DD. Só com o escopo leads:dados_pessoais.","anyOf":[{"type":"string"},{"type":"null"}]},"endereco":{"description":"Só com o escopo leads:dados_pessoais.","anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"description":"Com incluir=tags (sempre presente em GET /leads/{id}).","type":"array","items":{"$ref":"#/components/schemas/Tag"}},"campos":{"description":"Com incluir=campos (sempre presente em GET /leads/{id}).","type":"array","items":{"$ref":"#/components/schemas/CampoValor"}},"tarefas":{"description":"Em GET /leads/{id}?incluir=tarefas: as 50 mais recentes.","type":"array","items":{"$ref":"#/components/schemas/Tarefa"}},"perda":{"description":"Com incluir=perda (sempre presente em GET /leads/{id}). null se o lead não está numa etapa de perda ou não tem motivo registrado.","anyOf":[{"$ref":"#/components/schemas/Perda"},{"type":"null"}]}},"required":["id","nome","telefone","email","empresa_contato","contato_empresa_id","funil_id","etapa_id","responsavel_id","fonte","fonte_detalhe","probabilidade","previsao_fechamento","fechado_em","motivo_perda","observacoes","instagram","pais","estado","cidade","profissao","rastreio","criado_em","atualizado_em","ultima_interacao_em"],"additionalProperties":false},"EventoHistorico":{"description":"Evento do histórico de um lead.","type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"tipo":{"description":"mudanca_etapa, campo_alterado, tag_adicionada, tag_removida, responsavel_alterado, anotacao, tarefa_concluida...","type":"string"},"etapa_anterior_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"etapa_nova_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"campo_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"campo_nome":{"anyOf":[{"type":"string"},{"type":"null"}]},"valor_anterior":{"anyOf":[{"type":"string"},{"type":"null"}]},"valor_novo":{"anyOf":[{"type":"string"},{"type":"null"}]},"usuario_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"usuario_nome":{"anyOf":[{"type":"string"},{"type":"null"}]},"observacao":{"anyOf":[{"type":"string"},{"type":"null"}]},"anexos":{"anyOf":[{},{"type":"null"}]},"criado_em":{"description":"Data e hora em ISO 8601 (UTC).","type":"string"}},"required":["id","tipo","etapa_anterior_id","etapa_nova_id","campo_id","campo_nome","valor_anterior","valor_novo","usuario_id","usuario_nome","observacao","anexos","criado_em"],"additionalProperties":false},"Produto":{"description":"Item do catálogo (produto ou serviço).","type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"nome":{"type":"string"},"descricao":{"anyOf":[{"type":"string"},{"type":"null"}]},"tipo":{"description":"servico ou produto.","anyOf":[{"type":"string"},{"type":"null"}]},"codigo":{"anyOf":[{"type":"string"},{"type":"null"}]},"valor":{"anyOf":[{"type":"number"},{"type":"null"}]},"valor_promocional":{"anyOf":[{"type":"number"},{"type":"null"}]},"moeda":{"anyOf":[{"type":"string"},{"type":"null"}]},"categoria":{"anyOf":[{"type":"string"},{"type":"null"}]},"duracao_minutos":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"fotos":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"disponivel":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"ativo":{"type":"boolean"},"criado_em":{"description":"Data e hora em ISO 8601 (UTC).","type":"string"}},"required":["id","nome","descricao","tipo","codigo","valor","valor_promocional","moeda","categoria","duracao_minutos","fotos","tags","disponivel","ativo","criado_em"],"additionalProperties":false},"Venda":{"description":"Item vendido (ou em aberto) de um lead.","type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"nome":{"description":"Item vendido (com variante e quantidade, ex.: \"Camiseta (Azul · M) (×2)\").","type":"string"},"descricao":{"anyOf":[{"type":"string"},{"type":"null"}]},"valor":{"description":"Valor total do item (unitário × quantidade).","type":"number"},"status":{"description":"comprado = venda; aberto = pedido ainda não confirmado.","type":"string","enum":["aberto","comprado","cancelado"]},"vendido_em":{"description":"Data da venda (data_compra).","anyOf":[{"description":"Data e hora em ISO 8601 (UTC).","type":"string"},{"type":"null"}]},"vendedor_id":{"description":"Quem vendeu (ver /conta → usuarios).","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"produto_id":{"description":"Item do catálogo (null = item avulso).","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"pedido":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"numero":{"type":"string"},"status":{"type":"string"},"valor_total":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["id","numero","status","valor_total"],"additionalProperties":false},{"type":"null"}]},"observacao":{"anyOf":[{"type":"string"},{"type":"null"}]},"criado_em":{"description":"Data e hora em ISO 8601 (UTC).","type":"string"}},"required":["id","nome","descricao","valor","status","vendido_em","vendedor_id","produto_id","pedido","observacao","criado_em"],"additionalProperties":false},"Etapa":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"nome":{"type":"string"},"cor":{"anyOf":[{"type":"string"},{"type":"null"}]},"descricao":{"anyOf":[{"type":"string"},{"type":"null"}]},"posicao":{"description":"Ordem no funil (crescente). Venda e Perda ficam no fim (998 e 999 nos funis criados pela tela e pela API).","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"tipo":{"description":"entrada = onde o lead novo cai; ganho = Venda; perda = Perda.","type":"string","enum":["entrada","normal","ganho","perda"]},"qualificada":{"description":"Etapa de qualificação: lead de anúncio que chega nela (ou depois) vira QualifiedLead na Meta. Uma por funil.","type":"boolean"},"soma_valor":{"description":"O que o topo da coluna soma. null = padrão da tela.","anyOf":[{"type":"string","enum":["aberto","ganhos","ambos","nenhum"]},{"type":"null"}]},"ativo":{"description":"false = etapa arquivada (não recebe leads).","type":"boolean"}},"required":["id","nome","cor","descricao","posicao","tipo","qualificada","soma_valor","ativo"],"additionalProperties":false},"Funil":{"description":"Funil com as etapas.","type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"nome":{"type":"string"},"descricao":{"anyOf":[{"type":"string"},{"type":"null"}]},"padrao":{"description":"Funil onde entra o lead sem funil_id.","type":"boolean"},"ativo":{"description":"false = funil excluído na tela (os erros 409 seguem com o código `funil_arquivado`).","type":"boolean"},"arquivado":{"description":"true = arquivado na tela: fora do menu e das listas de seleção, mas mantém os leads, segue recebendo leads e contando nas métricas.","type":"boolean"},"ordem":{"description":"Posição do funil no menu da tela (0 = primeiro); null = no fim.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"criado_em":{"description":"Data e hora em ISO 8601 (UTC).","type":"string"},"etapas":{"description":"Em ordem de posição, incluindo as arquivadas (ativo: false).","type":"array","items":{"$ref":"#/components/schemas/Etapa"}}},"required":["id","nome","descricao","padrao","ativo","arquivado","ordem","criado_em","etapas"],"additionalProperties":false},"AutomacaoResumo":{"description":"Automação de etapa ou workflow, sem o fluxo.","type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"nome":{"type":"string"},"descricao":{"anyOf":[{"type":"string"},{"type":"null"}]},"ativa":{"description":"Ligada: dispara sozinha nos eventos do gatilho (as manuais, quando executadas pelo chat).","type":"boolean"},"funil_id":{"description":"null só em workflow manual sem funil.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"etapa_id":{"description":"Etapa onde a automação fica (a coluna do funil). null em workflow manual.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"gatilho":{"description":"Gatilho no formato gravado pela tela: { \"tipo\", \"tempo_minutos\", \"fase_origem_id\", \"tag_id\", \"campo_id\", \"horario_ativacao\", ... }.","type":"object","properties":{"tipo":{"description":"novo_lead, tempo_na_fase (tempo na etapa), mudou_de_fase (lead chegou na etapa), recebeu_mensagem, tag_adicionada, gatilho_data_campo (data em campo personalizado) ou manual (workflow executado pelo chat).","type":"string"}},"required":["tipo"],"additionalProperties":{}},"pasta":{"anyOf":[{"type":"string"},{"type":"null"}]},"marcar_conversa_nao_lida":{"type":"boolean"},"total_nos":{"description":"Nós do workflow, contando Início e Fim.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"criada_em":{"description":"Data e hora em ISO 8601 (UTC).","type":"string"},"atualizada_em":{"anyOf":[{"description":"Data e hora em ISO 8601 (UTC).","type":"string"},{"type":"null"}]}},"required":["id","nome","descricao","ativa","funil_id","etapa_id","gatilho","pasta","marcar_conversa_nao_lida","total_nos","criada_em","atualizada_em"],"additionalProperties":false},"Automacao":{"description":"Automação de etapa ou workflow, com o fluxo completo.","type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"nome":{"type":"string"},"descricao":{"anyOf":[{"type":"string"},{"type":"null"}]},"ativa":{"description":"Ligada: dispara sozinha nos eventos do gatilho (as manuais, quando executadas pelo chat).","type":"boolean"},"funil_id":{"description":"null só em workflow manual sem funil.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"etapa_id":{"description":"Etapa onde a automação fica (a coluna do funil). null em workflow manual.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}]},"gatilho":{"description":"Gatilho no formato gravado pela tela: { \"tipo\", \"tempo_minutos\", \"fase_origem_id\", \"tag_id\", \"campo_id\", \"horario_ativacao\", ... }.","type":"object","properties":{"tipo":{"description":"novo_lead, tempo_na_fase (tempo na etapa), mudou_de_fase (lead chegou na etapa), recebeu_mensagem, tag_adicionada, gatilho_data_campo (data em campo personalizado) ou manual (workflow executado pelo chat).","type":"string"}},"required":["tipo"],"additionalProperties":{}},"pasta":{"anyOf":[{"type":"string"},{"type":"null"}]},"marcar_conversa_nao_lida":{"type":"boolean"},"total_nos":{"description":"Nós do workflow, contando Início e Fim.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"criada_em":{"description":"Data e hora em ISO 8601 (UTC).","type":"string"},"atualizada_em":{"anyOf":[{"description":"Data e hora em ISO 8601 (UTC).","type":"string"},{"type":"null"}]},"nos":{"description":"Nós no formato do editor (ver POST /automacoes).","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"type":"string"},"config":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"position":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"],"additionalProperties":false}},"required":["id","type","config"],"additionalProperties":{}}},"conexoes":{"description":"Ligações entre os nós no formato do editor.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"sourceId":{"type":"string"},"targetId":{"type":"string"},"sourceHandle":{"type":"string"}},"required":["id","sourceId","targetId"],"additionalProperties":{}}}},"required":["id","nome","descricao","ativa","funil_id","etapa_id","gatilho","pasta","marcar_conversa_nao_lida","total_nos","criada_em","atualizada_em","nos","conexoes"],"additionalProperties":false},"Conta":{"description":"Dados de referência da conta: use os ids daqui nos filtros.","type":"object","properties":{"empresa":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"nome":{"type":"string"}},"required":["id","nome"],"additionalProperties":false},"usuarios":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"nome":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"papel":{"description":"admin, gerente ou membro.","type":"string"},"ativo":{"type":"boolean"}},"required":["id","nome","email","papel","ativo"],"additionalProperties":false}},"funis":{"type":"array","items":{"$ref":"#/components/schemas/Funil"}},"campos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"nome":{"type":"string"},"tipo":{"type":"string"},"opcoes":{"type":"array","items":{"type":"string"}},"aba":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"nome":{"type":"string"}},"required":["id","nome"],"additionalProperties":false},{"type":"null"}]},"ordem":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"ativo":{"type":"boolean"}},"required":["id","nome","tipo","opcoes","aba","ordem","ativo"],"additionalProperties":false}},"tags":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}},"objecoes":{"description":"Motivos de perda (use em POST /leads/{id}/perda). Só os ativos são aceitos.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"nome":{"type":"string"},"descricao":{"anyOf":[{"type":"string"},{"type":"null"}]},"ordem":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"ativo":{"type":"boolean"}},"required":["id","nome","descricao","ordem","ativo"],"additionalProperties":false}}},"required":["empresa","usuarios","funis","campos","tags","objecoes"],"additionalProperties":false},"Paginacao":{"type":"object","properties":{"limite":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"proximo_cursor":{"description":"Passe em ?cursor= para a próxima página. null = acabou.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["limite","proximo_cursor"],"additionalProperties":false},"Erro":{"description":"Formato único de erro.","type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"description":"nao_autenticado, chave_invalida, chave_expirada, empresa_bloqueada, escopo_insuficiente, parametros_invalidos, cursor_invalido, nao_encontrado, limite_por_segundo, limite_por_hora, erro_interno.","type":"string"},"mensagem":{"type":"string"},"detalhes":{},"requisicao_id":{"description":"Informe ao suporte em caso de problema.","type":"string"}},"required":["codigo","mensagem","requisicao_id"],"additionalProperties":false}},"required":["erro"],"additionalProperties":false}},"securitySchemes":{"chave":{"type":"http","scheme":"bearer","description":"Chave da conta (dsk_...), criada por um administrador."}}}}