> ## Documentation Index > Fetch the complete documentation index at: https://docs.wegly.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Criação de lead > Cria um lead na empresa vinculada à chave de integração usando o usuário que criou a chave como ator padrão. - O estágio padrão é a primeira etapa do funil primário se `stage_id` não for informado. - Se `responsible_id` não for enviado, o responsável será o criador da chave. - A única forma de informar uma origem manual é por `crm_lead_source_id`. O campo `lead_source` não é aceito nesta API. - A visibilidade padrão é privada (`visibility = 0`). - Quando `marketing.wegly_code` corresponder a um tracker ativo da empresa, a fonte do lead será forçada para a origem atrelada ao tracker, mesmo que `crm_lead_source_id` seja enviado (a origem manual continua sendo registrada no histórico de marketing). - Quando não houver tracker nem `crm_lead_source_id`, `marketing.wegly_source` ou `marketing.utm_source` busca/cria a origem automaticamente (`wegly_source` tem prioridade). - `marketing.url_conversion` é parseada automaticamente para preencher parâmetros `wegly_*`, `utm_*`, `gclid`, `fbclid` e `wegly_conversion_tool` faltantes; valores enviados manualmente prevalecem sobre os extraídos da URL. - Deduplicação de pessoa: quando `person.avoid_duplicate = true` e `duplicate_check_types` estiver preenchido, o serviço busca contatos existentes (pelos tipos informados) e reaproveita a pessoa encontrada, adicionando contatos faltantes. Nesse caso, a pessoa é incluída automaticamente em `persons_id`. ## OpenAPI ````yaml /openapi.json post /integrations/external/leads openapi: 3.0.3 info: title: >- Integração Externa - Leads, Oportunidades, Tarefas, Arquivos, Propostas, Chats, Satisfação e Campos Personalizados version: 1.0.0 description: > Documentação oficial da API externa da Wegly para campos personalizados, leads, oportunidades, tarefas, arquivos, propostas, chats e satisfação (`/integrations/external/custom-fields`, `/integrations/external/files`, `/integrations/external/leads`, `/integrations/external/deals`, `/integrations/external/tasks`, `/integrations/external/proposals`, `/integrations/external/chats` e `/integrations/external/satisfaction`). Todas as descrições estão em português e refletem as regras aplicadas pelo serviço. servers: - url: https://api.wegly.com.br description: Ambiente de produção Wegly security: - bearerAuth: [] tags: - name: Campos Personalizados description: >- Consulta dos campos personalizados disponíveis para uso nas integrações externas. - name: Arquivos description: >- Upload de arquivos públicos de integração vinculados diretamente a leads ou oportunidades. - name: Leads description: >- Operações de listagem, criação, consulta e atualização de leads via integração externa. - name: Oportunidades description: Operações de criação de oportunidades (deals) via integração externa. - name: Tarefas description: >- Operações de listagem, criação, consulta, atualização e remoção de tarefas vinculadas a leads, oportunidades, entregas, pessoas ou organizações. - name: Satisfação description: >- Geração de links públicos para formulários de satisfação via integração externa. - name: Propostas description: >- Operações de listagem, criação, consulta, atualização e remoção de propostas via integração externa. - name: Chats description: >- Operações principais de listagem, criação, consulta e resumo de não lidas de chats via integração externa. paths: /integrations/external/leads: post: tags: - Leads summary: Criação de lead description: > Cria um lead na empresa vinculada à chave de integração usando o usuário que criou a chave como ator padrão. - O estágio padrão é a primeira etapa do funil primário se `stage_id` não for informado. - Se `responsible_id` não for enviado, o responsável será o criador da chave. - A única forma de informar uma origem manual é por `crm_lead_source_id`. O campo `lead_source` não é aceito nesta API. - A visibilidade padrão é privada (`visibility = 0`). - Quando `marketing.wegly_code` corresponder a um tracker ativo da empresa, a fonte do lead será forçada para a origem atrelada ao tracker, mesmo que `crm_lead_source_id` seja enviado (a origem manual continua sendo registrada no histórico de marketing). - Quando não houver tracker nem `crm_lead_source_id`, `marketing.wegly_source` ou `marketing.utm_source` busca/cria a origem automaticamente (`wegly_source` tem prioridade). - `marketing.url_conversion` é parseada automaticamente para preencher parâmetros `wegly_*`, `utm_*`, `gclid`, `fbclid` e `wegly_conversion_tool` faltantes; valores enviados manualmente prevalecem sobre os extraídos da URL. - Deduplicação de pessoa: quando `person.avoid_duplicate = true` e `duplicate_check_types` estiver preenchido, o serviço busca contatos existentes (pelos tipos informados) e reaproveita a pessoa encontrada, adicionando contatos faltantes. Nesse caso, a pessoa é incluída automaticamente em `persons_id`. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateExternalLead' examples: criacaoBasica: summary: Cadastro mínimo com rastreio de marketing value: title: Lead vindo do site visibility: 0 crm_lead_source_id: 6d5b7dd0-3e0a-48bd-a99d-f8df1fd74d33 marketing: url_conversion: >- https://meusite.com/obrigado?wegly_code=ABC123&utm_campaign=lancamento person: name: Maria Souza contacts: - type: 0 value: '11988887777' primary: true avoid_duplicate: true duplicate_check_types: - 0 responses: '201': description: Lead criado com sucesso. content: application/json: schema: type: object properties: id: type: string format: uuid code: type: integer description: Código sequencial interno do lead. title: type: string '400': description: >- Validação de dados falhou (ex. `lead_source` não suportado, conflito de organização ou IDs inexistentes). '401': description: Token de integração ausente ou inválido. '403': description: >- Permissão `crm/lead.create` ausente ou domínio de origem não autorizado na chave. components: schemas: CreateExternalLead: type: object required: - title additionalProperties: false properties: stage_id: type: string format: uuid description: Estágio alvo. Caso omitido, usa a primeira etapa do funil primário. responsible_id: type: string format: uuid description: 'Responsável pelo lead. Padrão: criador da chave.' quality_rating: type: integer enum: - 1 - 2 - 3 - 4 - 5 quality_reason: type: string description: Motivo da qualificação; obrigatório se o funil exigir. title: type: string maxLength: 150 visibility: $ref: '#/components/schemas/LeadVisibility' tags: type: array items: type: string description: Lista de IDs de tags existentes. IDs inexistentes resultam em erro. persons_id: type: array items: type: object properties: person_id: type: string format: uuid description: IDs de pessoas já cadastradas que serão associadas. person: $ref: '#/components/schemas/LeadPerson' organization_id: type: string format: uuid description: Organização existente. Conflita com `organization`. organization: $ref: '#/components/schemas/LeadOrganization' custom_fields: type: array items: $ref: '#/components/schemas/LeadCustomFieldValue' marketing: $ref: '#/components/schemas/MarketingTracking' crm_lead_source_id: type: string format: uuid description: >- Origem existente. Única forma aceita para informar origem manual nesta API. followers: type: array items: $ref: '#/components/schemas/LeadFollowerInput' description: >- Seguidores adicionados após a criação do lead. Usuários duplicados na lista são ignorados. note: $ref: '#/components/schemas/LeadNoteInput' LeadVisibility: type: integer enum: - 0 - 1 description: > 0 = privado (responsável, membros dos times do responsável e supervisores), 1 = restrito ao responsável e times relacionados. LeadPerson: type: object description: >- Pessoa associada ao lead. Envie telefone, e-mail e redes sociais em `contacts`; `phone` e `email` no topo do lead não são aceitos. required: - name properties: name: type: string birth_date: type: string format: date gender: type: integer notes: type: string contacts: type: array items: $ref: '#/components/schemas/LeadPersonContact' documents: type: array items: $ref: '#/components/schemas/PersonDocumentInput' address: $ref: '#/components/schemas/AddressInput' addresses: type: array items: $ref: '#/components/schemas/AddressInput' avoid_duplicate: type: boolean description: > Quando true, ativa deduplicação usando os tipos informados em `duplicate_check_types`. Se encontrar pessoa compatível, os contatos faltantes são adicionados e a pessoa é reaproveitada. duplicate_check_types: type: array items: $ref: '#/components/schemas/PersonContactType' description: Tipos de contato que devem ser usados para busca de duplicados. LeadOrganization: type: object required: - name properties: name: type: string legal_name: type: string document: type: string industry: type: string description: type: string phone: type: string email: type: string site: type: string status: type: integer enum: - 0 - 1 addresses: type: array items: $ref: '#/components/schemas/AddressInput' address_name: type: string address_street: type: string address_number: type: string address_complement: type: string address_district: type: string address_city: type: string address_state: type: string address_postal_code: type: string address_status: type: integer address_type: type: integer LeadCustomFieldValue: type: object required: - id properties: id: type: string description: ID do campo customizado. value: type: string option_id: type: string option_ids: type: array items: type: string MarketingTracking: type: object description: > Rastreio de marketing. Todos os valores são sanitizados (trim) e campos vazios são ignorados. `utm_*` são normalizados para `wegly_*` equivalentes quando estes não forem enviados. `utm_term` vira `utm_search_term` se o campo específico não for enviado. `url_conversion` tem seus parâmetros extraídos automaticamente (wegly_*, utm_*, gclid, fbclid, conversion_tool_name). Quando `wegly_code` referencia um tracker válido, a origem do lead é extraída do tracker. Quando não há tracker nem origem explícita, `wegly_source` ou `utm_source` busca/cria a origem automaticamente. properties: wegly_code: type: string description: >- Código de rastreio Wegly. Se existir, define a origem principal do lead. wegly_source: type: string description: >- Origem textual Wegly. Tem prioridade sobre `utm_source` quando for necessário buscar/criar origem automaticamente. wegly_campaign: type: string wegly_ad_set: type: string wegly_content: type: string wegly_displayed_on: type: string wegly_conversion_tool: type: string description: > ID, código ou nome da ferramenta de conversão. Se não existir, é criada automaticamente com código gerado. wegly_creative: type: string gclid: type: string description: Prioritário sobre fbclid quando ambos enviados. fbclid: type: string fbc: type: string fbp: type: string url_conversion: type: string description: > URL completa da conversão. Se não contiver protocolo, será normalizada para https://. É armazenada a base e a URL completa. utm_search_term: type: string utm_source: type: string description: >- Fonte textual de marketing. Busca/cria origem automaticamente quando não houver `wegly_code`, `wegly_source` nem `crm_lead_source_id`. utm_campaign: type: string utm_ad_set: type: string utm_content: type: string utm_term: type: string utm_display_on: type: string client_ip_address: type: string client_user_agent: type: string ga_client_id: type: string LeadFollowerInput: type: object properties: user_id: type: string format: uuid description: >- Usuário existente na empresa. Duplicatas são ignoradas na mesma requisição. role_id: type: string format: uuid description: Função de seguidor (deve existir e estar ativa). notes: type: string maxLength: 1000 required: - user_id - role_id additionalProperties: false LeadNoteInput: type: object properties: content: type: string is_pinned: type: boolean LeadPersonContact: type: object required: - type - value properties: type: $ref: '#/components/schemas/PersonContactType' value: type: string description: > Valor do contato. Telefones (tipos 0,2,3) têm caracteres não numéricos removidos automaticamente. primary: type: boolean description: Marca o contato como principal para a pessoa. PersonDocumentInput: type: object required: - type - value properties: type: type: integer description: Tipo do documento conforme cadastro interno de pessoas. value: type: string label: type: string description: Obrigatório quando o tipo do documento for personalizado. AddressInput: type: object properties: status: type: integer type: type: integer name: type: string street: type: string number: type: string complement: type: string district: type: string city: type: string state: type: string postal_code: type: string PersonContactType: type: integer enum: - 0 - 1 - 2 - 3 - 4 - 5 - 6 - 7 description: > 0=WhatsApp, 1=Email, 2=Celular, 3=Telefone, 4=Instagram, 5=Facebook, 6=LinkedIn, 7=Outros. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Utilize o token de integração no header `Authorization: Bearer {token}`. O domínio de origem (Origin/Referer) deve respeitar `allowed_domain`, quando configurado na chave. ````