{"openapi":"3.0.3","info":{"title":"North Clinic CRM — API","version":"1.6.0","description":"API para integração com o North Clinic CRM.\n\n## Autenticação\n\nTodas as requisições exigem o header `X-API-Key`.\n\n```\nX-API-Key: ncrm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n```\n\nAs chaves são geradas em **Configurações → API Keys** no painel do CRM.\n\nCada chave possui **scopes** que determinam quais endpoints podem ser acessados:\n- `scheduling:read` — leitura de profissionais, serviços, disponibilidade e agendamentos\n- `scheduling:write` — criação e cancelamento de agendamentos\n- `leads:read` — leitura de leads e timeline\n- `leads:write` — cadastro geral de leads\n- `medical-records:read` — leitura de medidas e observações dos prontuários (chave específica)\n\nA chave deve declarar quais serviços estão disponíveis via `allowed_service_ids`.\nSem uma lista explícita, o acesso de agendamento falha de forma segura.\n\n## Limites\n\n- **600 requisições/minuto** por IP (teto agregado de segurança)\n- **60 requisições/minuto** por chave (cadastro de leads, grupo integration-write)\n- **60 requisições/minuto** por chave (scheduling)\n- **300 requisições/minuto** por chave (listas de integration)\n- **60 requisições/minuto** por chave (detalhe de lead com timeline)\n- Timeout: 30 segundos por requisição; execução compartilhada de leitura limitada a 25 segundos\n- Por processo: até 24 trabalhos simultâneos, leituras de leads limitadas a 12; até 96 requisições recebidas em processamento/espera, das quais no máximo 72 são leituras de leads\n- Body máximo: 1MB\n\nOs headers `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset` indicam o consumo por chave. Ao exceder, a resposta é `429` com `Retry-After` — **aguarde o tempo indicado antes de repetir** (repetir imediatamente só desperdiça a janela).\n\nOs grupos de cadastro de leads, scheduling, listas de integration e detalhe de lead possuem contadores independentes. Uma chave de acesso completo pode sincronizar listas sem reduzir o teto reservado ao agendamento. O detalhe de lead tem orçamento próprio porque agrega uma timeline de várias fontes.\n\n## Webhooks\n\nEm vez de fazer polling, cadastre um webhook para receber eventos assim que acontecem. Atualmente entregues:\n\n- `lead.created` — novo lead criado (qualquer canal)\n- `appointment.created` — agendamento criado\n- `appointment.cancelled` — agendamento cancelado\n\n**Payload** (POST no seu endpoint):\n\n```json\n{\n  \"event\": \"lead.created\",\n  \"timestamp\": \"2026-07-13T15:30:00.000Z\",\n  \"data\": { \"id\": \"uuid\", \"nome\": \"Maria Santos\", \"telefone\": \"5511999998888\", \"canal\": \"whatsapp\", \"created_at\": \"2026-07-13T15:30:00.000Z\" }\n}\n```\n\n**Assinatura:** cada requisição inclui `X-Webhook-Signature: sha256=<hmac>`, o HMAC-SHA256 do corpo bruto usando o `secret` do webhook. Valide-o antes de confiar no payload. Também enviamos `X-Webhook-Event` e `X-Webhook-Delivery` (id único da entrega, útil para deduplicar).\n\n**Entrega e retry:** responda com `2xx` para confirmar. Falhas são retentadas com back-off (10s, 60s, 300s). Após falhas consecutivas o webhook é desativado e precisa ser reativado no painel. A entrega é *at-least-once* — trate o `X-Webhook-Delivery` como chave de idempotência.\n\n## Paginação\n\nEndpoints com listas usam cursor:\n\n```json\n{\n  \"pagination\": {\n    \"has_more\": true,\n    \"next_cursor\": \"eyJpZCI6Ii4uLiJ9\",\n    \"total_count\": 142\n  }\n}\n```\n\nPasse `cursor` na próxima requisição para obter a página seguinte.\n\n## Meta\n\nToda resposta inclui `meta.request_id` para rastreabilidade.\n"},"servers":[{"url":"https://api.northcliniccrm.com.br/api/v1","description":"Produção"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"LeadResult":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created":{"type":"boolean","description":"true somente quando esta chamada criou o lead"}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Parâmetro obrigatório ausente"},"details":{"description":"Contexto adicional do erro, quando houver"},"docs_url":{"type":"string","format":"uri","description":"Documentação com escopos, limites e formatos esperados","example":"https://www.northcrm.com.br/developers/api/"}},"required":["code","message"]}}},"Pagination":{"type":"object","properties":{"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"total_count":{"type":"integer"}}},"Meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}},"security":[{"ApiKeyAuth":[]}],"paths":{"/integration/clients/{id}/medical-records":{"get":{"tags":["Integração"],"summary":"Consultar prontuários do cliente","description":"Exige medical-records:read. UUID de crm_clientes (não o ID do lead). Retorna medidas e observações de crm_clientes_prontuarios, somente da clínica da chave, sem excluídos. Não inclui anamneses, anexos, receitas ou avaliações de outros módulos. Ordenação por data_registro e id decrescentes. Limite de 60 requisições/minuto. Resposta sem cache.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"date_from","in":"query","schema":{"type":"string","format":"date"},"description":"Data inicial inclusiva"},{"name":"date_to","in":"query","schema":{"type":"string","format":"date"},"description":"Data final inclusiva"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor da página anterior; manter os filtros"}],"responses":{"200":{"description":"Prontuários encontrados (lista vazia se não houver registros)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"crm_cliente_id":{"type":"string","format":"uuid"},"data_registro":{"type":"string","format":"date"},"funcionario_id":{"type":"string","format":"uuid","nullable":true},"avaliacao_inicial":{"type":"boolean","nullable":true},"peso":{"type":"number","nullable":true},"altura":{"type":"number","nullable":true},"cintura":{"type":"number","nullable":true},"abdomen":{"type":"number","nullable":true},"abdomen_superior":{"type":"number","nullable":true},"quadril":{"type":"number","nullable":true},"prega":{"type":"number","nullable":true},"porcentagem_gordura":{"type":"number","nullable":true},"gordura_visceral":{"type":"number","nullable":true},"massa_muscular":{"type":"number","nullable":true},"idade_metabolica":{"type":"number","nullable":true},"pressao_sistolica":{"type":"number","nullable":true},"pressao_diastolica":{"type":"number","nullable":true},"fase":{"type":"number","nullable":true},"nivel_sedentarismo":{"type":"number","nullable":true},"peso_cinco_anos_atras":{"type":"number","nullable":true},"cetose":{"type":"string","nullable":true},"observacoes":{"type":"string","nullable":true},"registrado_em":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","properties":{"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"UUID, datas, limite ou cursor inválidos"},"401":{"description":"Chave ausente ou inválida"},"403":{"description":"Sem escopo medical-records:read"},"404":{"description":"Cliente não encontrado na clínica da chave"},"429":{"description":"Limite de requisições excedido"},"500":{"description":"Erro ao consultar os dados"}}}},"/scheduling/professionals":{"get":{"tags":["Agendamento"],"summary":"Listar profissionais","description":"Profissionais disponíveis para agendamento.","parameters":[{"name":"active","in":"query","schema":{"type":"boolean","default":true},"description":"Filtrar por ativos (default: true)"},{"name":"show_in_schedule","in":"query","schema":{"type":"boolean","default":true},"description":"Filtrar por visíveis na agenda (default: true)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"nome":{"type":"string","example":"Dr. João Silva"},"ativo":{"type":"boolean"},"exibir_na_agenda":{"type":"boolean","description":"Se o profissional aparece na agenda"}}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}}}}},"/scheduling/services":{"get":{"tags":["Agendamento"],"summary":"Listar serviços","description":"Serviços disponíveis para agendamento. Respeita a configuração `allowed_service_ids` da API Key e a configuração da clínica.","parameters":[{"name":"active","in":"query","schema":{"type":"boolean","default":true},"description":"Filtrar por ativos (default: true)"},{"name":"professional_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Filtrar por profissional — retorna apenas serviços que o profissional atende"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"nome":{"type":"string","example":"Consulta Avaliação"},"duracao_minutos":{"type":"integer","example":30},"gera_conversao":{"type":"boolean","description":"Se o agendamento desse serviço marca o lead como convertido automaticamente"}}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}}}}},"/scheduling/availability":{"get":{"tags":["Agendamento"],"summary":"Consultar disponibilidade","description":"Horários livres para um serviço. Máximo 7 dias por consulta. Considera horários de trabalho dos profissionais, agendamentos existentes, bloqueios de agenda e compatibilidade profissional/sala/serviço.","parameters":[{"name":"service_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"},"description":"UUID do serviço retornado por GET /scheduling/services. Não envie o nome."},{"name":"date_from","in":"query","required":true,"schema":{"type":"string","format":"date"},"example":"2026-04-07","description":"Data inicial (YYYY-MM-DD)"},{"name":"date_to","in":"query","required":true,"schema":{"type":"string","format":"date"},"example":"2026-04-13","description":"Data final (YYYY-MM-DD)"},{"name":"professional_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Filtrar por profissional"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"servico_id":{"type":"string","format":"uuid","description":"ID do serviço consultado"},"nome_servico":{"type":"string","description":"Nome do serviço"},"duracao_minutos_servico":{"type":"integer","description":"Duração do serviço em minutos"},"slots":{"type":"array","items":{"type":"object","properties":{"data":{"type":"string","format":"date"},"horario_inicio":{"type":"string","example":"09:00"},"profissional_id":{"type":"string","format":"uuid"},"nome_profissional":{"type":"string"},"sala_id":{"type":"string","format":"uuid"}}}}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"Parâmetros inválidos. service_id e professional_id, quando informado, devem ser UUIDs."},"404":{"description":"Serviço não encontrado"}}}},"/scheduling/appointments":{"post":{"tags":["Agendamento"],"summary":"Criar agendamento","description":"Exige scheduling:write. Envie exatamente um dos campos: lead_id (cadastro prévio) ou lead (busca/cria automaticamente). O lead por ID deve estar ativo na clínica da chave. Mantém restrições de serviços, disponibilidade e créditos.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profissional_id","servico_id","sala_id","data","horario_inicio","horario_fim"],"oneOf":[{"required":["lead"]},{"required":["lead_id"]}],"properties":{"profissional_id":{"type":"string","format":"uuid"},"servico_id":{"type":"string","format":"uuid","description":"UUID retornado por GET /scheduling/services. Não envie o nome do serviço."},"sala_id":{"type":"string","format":"uuid"},"data":{"type":"string","format":"date","example":"2026-04-10","description":"Data do agendamento (YYYY-MM-DD)"},"horario_inicio":{"type":"string","example":"09:00","description":"Horário de início (HH:MM)"},"horario_fim":{"type":"string","example":"09:30","description":"Horário de término (HH:MM)"},"is_avaliacao":{"type":"boolean","default":false,"description":"Se é uma avaliação"},"observacoes":{"type":"string","nullable":true,"description":"Observações sobre o agendamento"},"idempotency_key":{"type":"string","minLength":8,"maxLength":255,"description":"Chave de idempotência transacional para evitar duplicatas (válida por 24h). Reutilizar com outro conteúdo retorna 409."},"lead_id":{"type":"string","format":"uuid","description":"ID retornado por POST /integration/leads. Deve estar ativo na clínica da chave. Envie lead_id OU lead."},"lead":{"type":"object","required":["nome","telefone"],"description":"Reutiliza o lead ativo mais antigo com o mesmo telefone na clínica, sem alterar seus dados.","properties":{"nome":{"type":"string","minLength":1,"maxLength":255,"example":"Maria Santos"},"telefone":{"type":"string","example":"5511999998888","description":"Telefone com DDI+DDD, 10 a 15 dígitos. Aceita pontuação; não adiciona DDI nem nono dígito automaticamente."},"cpf":{"type":"string","nullable":true,"example":"12345678900","description":"Usado apenas em novo cadastro; pontuação é removida."},"data_nascimento":{"type":"string","nullable":true,"format":"date","example":"1990-05-15","description":"Data válida YYYY-MM-DD; somente em novo cadastro."},"origem":{"type":"string","nullable":true,"maxLength":255,"example":"Google Ads","description":"Nome da origem na clínica, sem distinguir maiúsculas/minúsculas. Origem não encontrada fica sem vínculo."}}}}}}}},"responses":{"201":{"description":"Agendamento criado","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lead_id":{"type":"string","format":"uuid"},"profissional_id":{"type":"string","format":"uuid"},"servico_id":{"type":"string","format":"uuid"},"data":{"type":"string","format":"date"},"horario_inicio":{"type":"string","example":"09:00"},"horario_fim":{"type":"string","example":"09:30"},"status":{"type":"string","example":"agendado"},"is_avaliacao":{"type":"boolean"},"observacoes":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"Payload inválido. Informe lead OU lead_id. profissional_id, servico_id, sala_id e lead_id devem ser UUIDs."},"404":{"description":"Serviço ou lead não encontrado na clínica da chave; lead excluído também retorna 404."},"409":{"description":"Horário indisponível (conflito com agendamento existente)"}}},"get":{"tags":["Agendamento"],"summary":"Listar agendamentos","description":"Agendamentos dos serviços permitidos na API Key em um período. Máximo 31 dias.","parameters":[{"name":"date_from","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Data inicial (YYYY-MM-DD)"},{"name":"date_to","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Data final (YYYY-MM-DD)"},{"name":"professional_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Filtrar por profissional"},{"name":"status","in":"query","schema":{"type":"string","enum":["agendado","confirmado","chegou","atendido","faltou","cancelado","excluido","em_atendimento"]},"description":"Filtrar por status"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":100},"description":"Quantidade por página"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor de paginação"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lead_id":{"type":"string","format":"uuid"},"nome_lead":{"type":"string","nullable":true},"profissional_id":{"type":"string","format":"uuid"},"nome_profissional":{"type":"string","nullable":true},"nome_servico":{"type":"string","nullable":true},"data":{"type":"string","format":"date"},"horario_inicio":{"type":"string","example":"09:00","nullable":true},"horario_fim":{"type":"string","example":"09:30","nullable":true},"status":{"type":"string","enum":["agendado","confirmado","chegou","atendido","faltou","cancelado","excluido","em_atendimento","desconhecido"]},"is_avaliacao":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}}},"pagination":{"$ref":"#/components/schemas/Pagination"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}}}}},"/scheduling/appointments/{id}":{"get":{"tags":["Agendamento"],"summary":"Detalhes do agendamento","description":"Retorna informações completas de um agendamento específico quando o serviço está permitido na API Key.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"ID do agendamento"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lead_id":{"type":"string","format":"uuid"},"nome_lead":{"type":"string","nullable":true},"telefone_lead":{"type":"string","nullable":true,"description":"Telefone do lead (visibilidade depende da configuração da API Key)"},"profissional_id":{"type":"string","format":"uuid"},"nome_profissional":{"type":"string","nullable":true},"servico_id":{"type":"string","format":"uuid"},"nome_servico":{"type":"string","nullable":true},"data":{"type":"string","format":"date"},"horario_inicio":{"type":"string","example":"09:00","nullable":true},"horario_fim":{"type":"string","example":"09:30","nullable":true},"status":{"type":"string","enum":["agendado","confirmado","chegou","atendido","faltou","cancelado","excluido","em_atendimento","desconhecido"]},"status_label":{"type":"string","example":"Agendado","description":"Label em português do status"},"is_avaliacao":{"type":"boolean"},"observacoes":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"404":{"description":"Agendamento não encontrado"}}}},"/scheduling/appointments/{id}/cancel":{"post":{"tags":["Agendamento"],"summary":"Cancelar agendamento","description":"Cancela um agendamento de um serviço permitido na API Key. Não é possível cancelar agendamentos já cancelados ou atendidos.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"motivo":{"type":"string","description":"Motivo do cancelamento"}}}}}},"responses":{"200":{"description":"Cancelado","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","example":"cancelado"},"cancelado_em":{"type":"string","format":"date-time"}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"404":{"description":"Agendamento não encontrado"},"409":{"description":"Já cancelado ou atendido"}}}},"/integration/leads":{"post":{"tags":["Integração"],"summary":"Cadastrar ou reutilizar lead","description":"Exige leads:write. Cadastra sem agendamento. Reutiliza o lead ativo mais antigo com o mesmo telefone na clínica da chave, sem alterar seus dados. Telefone deve ser string com DDI e DDD (10 a 15 dígitos); pontuação é removida. Retorna 201 e created=true para novo cadastro ou 200 e created=false para existente. Use data.id como lead_id em POST /scheduling/appointments. Novo cadastro usa o primeiro funil/etapa, canal api, registra touchpoint e emite lead.created. Não exige seleção prévia de serviço nem permissões de agenda. Limite próprio de 60 requisições/minuto por chave.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["nome","telefone"],"description":"Reutiliza o lead ativo mais antigo com o mesmo telefone na clínica, sem alterar seus dados.","properties":{"nome":{"type":"string","minLength":1,"maxLength":255,"example":"Maria Santos"},"telefone":{"type":"string","example":"5511999998888","description":"Telefone com DDI+DDD, 10 a 15 dígitos. Aceita pontuação; não adiciona DDI nem nono dígito automaticamente."},"cpf":{"type":"string","nullable":true,"example":"12345678900","description":"Usado apenas em novo cadastro; pontuação é removida."},"data_nascimento":{"type":"string","nullable":true,"format":"date","example":"1990-05-15","description":"Data válida YYYY-MM-DD; somente em novo cadastro."},"origem":{"type":"string","nullable":true,"maxLength":255,"example":"Google Ads","description":"Nome da origem na clínica, sem distinguir maiúsculas/minúsculas. Origem não encontrada fica sem vínculo."}}}}}},"responses":{"200":{"description":"Lead existente reutilizado; created=false","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadResult"}}}},"201":{"description":"Lead criado; created=true","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadResult"}}}},"400":{"description":"JSON ou dados do lead inválidos"},"401":{"description":"API Key ausente ou inválida"},"403":{"description":"Sem escopo leads:write ou módulo indisponível"},"409":{"description":"Conflito de cadastro não resolvido pelo telefone"},"429":{"description":"Limite de requisições excedido"},"500":{"description":"Funil padrão sem etapa ou falha ao criar lead"},"503":{"description":"Falha temporária ao consultar cadastro, funil ou origem"}}},"get":{"tags":["Integração"],"summary":"Listar leads","description":"Leads criados em um período. Máximo 90 dias. Retorna telefone, canal e flags de agendamento/venda.","parameters":[{"name":"date_from","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Data inicial (YYYY-MM-DD)"},{"name":"date_to","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Data final (YYYY-MM-DD)"},{"name":"source_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Filtrar por origem (origem_id)"},{"name":"channel","in":"query","schema":{"type":"string"},"description":"Filtrar por canal (whatsapp, instagram, api, etc.)"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":100},"description":"Quantidade por página"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor de paginação"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"nome":{"type":"string","example":"Maria Santos"},"telefone":{"type":"string","example":"5511999998888"},"canal":{"type":"string","example":"whatsapp"},"tem_agendamento":{"type":"boolean","description":"Se o lead tem algum agendamento"},"tem_venda":{"type":"boolean","description":"Se o lead tem alguma venda finalizada"},"created_at":{"type":"string","format":"date-time"}}}},"pagination":{"$ref":"#/components/schemas/Pagination"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}}}}},"/integration/leads/{id}":{"get":{"tags":["Integração"],"summary":"Detalhes do lead","description":"Por padrão retorna dados básicos, agendamentos, vendas e timeline. Use include=none para buscar somente dados básicos, ou selecione seções separadas por vírgula. Seções omitidas não aparecem na resposta. Falha de consulta retorna 503, nunca listas vazias apresentadas como resultado completo.","parameters":[{"name":"include","in":"query","required":false,"schema":{"type":"string","example":"agendamentos,vendas"},"description":"Seções: agendamentos, vendas, timeline. none retorna somente dados básicos. Ausente inclui todas. Não muda os escopos exigidos."},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"nome":{"type":"string","example":"Maria Santos"},"telefone":{"type":"string","example":"5511999998888"},"canal":{"type":"string","example":"whatsapp"},"agendamentos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"data":{"type":"string","format":"date"},"horario_inicio":{"type":"string","example":"09:00","nullable":true},"nome_servico":{"type":"string","nullable":true},"status":{"type":"string","enum":["agendado","confirmado","chegou","atendido","faltou","cancelado","excluido","em_atendimento","desconhecido"]}}}},"vendas":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"data_venda":{"type":"string","format":"date"},"valor_venda":{"type":"number","example":1500,"description":"Valor pago da venda"},"itens":{"type":"array","items":{"type":"object","properties":{"tipo":{"type":"string","enum":["servico","pacote","produto"]},"nome":{"type":"string","example":"Limpeza de Pele"}}}}}}},"timeline":{"type":"array","description":"Histórico completo de atividades ordenado por data (mais recente primeiro). Os campos retornados variam de acordo com o `tipo` do evento.","items":{"type":"object","properties":{"tipo":{"type":"string","enum":["interaction","stage_change","automation"],"description":"Tipo do evento"},"data_hora":{"type":"string","format":"date-time","nullable":true},"subtipo":{"type":"string","nullable":true,"description":"(interaction) Tipo da interação: facebook_ctwa_click, venda, avaliacao, atribuicao_responsavel, disparo_campanha, etc."},"plataforma":{"type":"string","nullable":true,"description":"(interaction) Plataforma de origem: facebook, instagram, etc."},"plataforma_detalhe":{"type":"string","nullable":true,"description":"(interaction) Detalhe granular da fonte/plataforma de origem"},"titulo_anuncio":{"type":"string","nullable":true,"description":"(interaction) Título do anúncio que gerou a interação"},"texto_anuncio":{"type":"string","nullable":true,"description":"(interaction) Texto/copy do anúncio"},"midia_anuncio":{"type":"string","nullable":true,"description":"(interaction) URL da mídia (imagem/vídeo) do anúncio"},"source_url":{"type":"string","nullable":true,"description":"(interaction) URL de origem / landing page do anúncio"},"source_id":{"type":"string","format":"uuid","nullable":true,"description":"(interaction) ID da campanha/origem vinculada"},"ctwa_clid":{"type":"string","nullable":true,"description":"(interaction) Click ID do Click-to-WhatsApp (Meta)"},"conversion_source":{"type":"string","nullable":true,"description":"(interaction) Fonte de conversão do evento"},"mensagem":{"type":"string","nullable":true,"description":"(interaction/automation) Mensagem associada ao evento"},"nome_funcionario":{"type":"string","nullable":true,"description":"(interaction) Nome do funcionário envolvido"},"valor_venda":{"type":"number","nullable":true,"description":"(interaction) Valor da venda, quando aplicável"},"nome_servico":{"type":"string","nullable":true,"description":"(interaction) Nome do serviço do agendamento"},"status_agendamento":{"type":"string","nullable":true,"description":"(interaction) Status do agendamento: agendado, confirmado, chegou, atendido, faltou, cancelado"},"referencia_nome":{"type":"string","nullable":true,"description":"(interaction) Nome da referência (lead que indicou)"},"referencia_tipo":{"type":"string","nullable":true,"description":"(interaction) Tipo da referência"},"funil":{"type":"string","nullable":true,"description":"(stage_change) Nome do funil"},"etapa":{"type":"string","nullable":true,"description":"(stage_change) Nome da etapa"},"entrou_em":{"type":"string","format":"date-time","nullable":true,"description":"(stage_change) Quando entrou na etapa"},"saiu_em":{"type":"string","format":"date-time","nullable":true,"description":"(stage_change) Quando saiu da etapa"},"origem_movimentacao":{"type":"string","nullable":true,"description":"(stage_change) Origem da movimentação (manual, automação, etc.)"},"movido_por":{"type":"string","nullable":true,"description":"(stage_change) Nome do usuário que moveu o lead"},"automacao":{"type":"object","nullable":true,"description":"(stage_change) Dados da automação que moveu o lead, quando aplicável","properties":{"tipo_acao":{"type":"string","nullable":true},"mensagem":{"type":"string","nullable":true},"etapa_destino":{"type":"string","nullable":true}}},"tipo_acao":{"type":"string","nullable":true,"description":"(automation) Tipo da ação automática"},"status":{"type":"string","nullable":true,"description":"(automation) Status da automação: agendado, completo, cancelado"},"etapa_destino":{"type":"string","nullable":true,"description":"(automation) Etapa de destino da automação"},"agendado_para":{"type":"string","format":"date-time","nullable":true,"description":"(automation) Data/hora agendada para execução"},"completado_em":{"type":"string","format":"date-time","nullable":true,"description":"(automation) Data/hora em que foi completada"},"motivo_cancelamento":{"type":"string","nullable":true,"description":"(automation) Motivo do cancelamento, quando aplicável"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"Seleção include inválida"},"404":{"description":"Lead não encontrado"},"503":{"description":"Capacidade esgotada ou consulta indisponível; aguarde Retry-After"},"504":{"description":"Prazo excedido; aguarde Retry-After antes de repetir"}}}}},"tags":[{"name":"Agendamento","description":"Profissionais, serviços, disponibilidade e agendamentos."},{"name":"Integração","description":"Leads com histórico completo de atividades."}]}