> ## 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 oportunidades > Cria uma oportunidade (deal) usando a chave de integração, aplicando as mesmas validações internas: estágio/responsável padrão quando omitidos, conflito proibido entre `organization_id` e `organization`, origem manual aceita apenas por `crm_lead_source_id` (`lead_source` não é suportado), deduplicação de pessoa quando `avoid_duplicate` e `duplicate_check_types` forem enviados, rastreio de marketing com prioridade para `wegly_code`, fallback de origem por `wegly_source`/`utm_source` e extração automática de parâmetros da `url_conversion`, criação de ferramenta de conversão quando necessário e registro opcional de nota inicial/seguidores. ## OpenAPI ````yaml /openapi.json post /integrations/external/deals 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/deals: post: tags: - Oportunidades summary: Criação de oportunidades description: > Cria uma oportunidade (deal) usando a chave de integração, aplicando as mesmas validações internas: estágio/responsável padrão quando omitidos, conflito proibido entre `organization_id` e `organization`, origem manual aceita apenas por `crm_lead_source_id` (`lead_source` não é suportado), deduplicação de pessoa quando `avoid_duplicate` e `duplicate_check_types` forem enviados, rastreio de marketing com prioridade para `wegly_code`, fallback de origem por `wegly_source`/`utm_source` e extração automática de parâmetros da `url_conversion`, criação de ferramenta de conversão quando necessário e registro opcional de nota inicial/seguidores. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateExternalOpportunity' examples: criacaoOportunidade: summary: Cadastro de oportunidade com rastreio e deduplicação de pessoa value: title: Implementação completa CRM value: 75000.5 expected_close_date: '2024-03-15T00:00:00.000Z' quality_rating: 4 quality_reason: Cliente com budget aprovado visibility: 0 temperature: 3 crm_lead_source_id: a6e77b5f-4d66-4e78-b15f-c0e8a16db962 marketing: url_conversion: >- https://landing.wegly.com.br/obrigado?wegly_code=OPP123&utm_campaign=crm-enterprise&gclid=XYZ tags: - 9d2e4fe8-36f6-4fb2-b1f5-1ccda0e8a101 - 6a31c54f-5b32-4bb5-b9d2-7d9e928f2d55 person: name: Roberto Martins contacts: - type: 0 value: '11999887766' primary: true avoid_duplicate: true duplicate_check_types: - 0 organization: name: Tech Innovators S.A. followers: - user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 role_id: b2c3d4e5-f6a7-8901-bcde-f23456789012 note: content: Oportunidade originada da campanha enterprise. is_pinned: true responses: '201': description: Oportunidade criada com sucesso. content: application/json: schema: $ref: '#/components/schemas/OpportunityCreateResult' '400': description: >- Validação de dados falhou (IDs inexistentes, `lead_source` não suportado, conflitos de parâmetros, etc). '401': description: Token de integração ausente ou inválido. '403': description: >- Permissão `crm/deal.create` ausente ou domínio de origem não autorizado na chave. components: schemas: CreateExternalOpportunity: type: object required: - title additionalProperties: false properties: stage_id: type: string format: uuid description: >- Etapa do funil de oportunidades. Caso omitido, usa a primeira etapa do funil primário. responsible_id: type: string format: uuid description: 'Responsável pela oportunidade. 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 value: type: number description: Valor monetário com até 2 casas decimais. expected_close_date: type: string format: date-time description: Data prevista de fechamento. visibility: $ref: '#/components/schemas/OpportunityVisibility' temperature: $ref: '#/components/schemas/OpportunityTemperature' 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/OpportunityPerson' primary_person_id: type: string format: uuid description: >- Define o participante principal quando múltiplas pessoas são associadas. organization_id: type: string format: uuid description: Organização existente. Conflita com `organization`. organization: $ref: '#/components/schemas/OpportunityOrganization' custom_fields: type: array items: $ref: '#/components/schemas/OpportunityCustomFieldValue' 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/OpportunityFollowerInput' description: >- Seguidores adicionados após a criação da oportunidade. Usuários duplicados na lista são ignorados. note: $ref: '#/components/schemas/OpportunityNoteInput' OpportunityCreateResult: type: object description: Retorno da criação de oportunidade. properties: id: type: string format: uuid code: type: integer description: Código sequencial interno da oportunidade. title: type: string OpportunityVisibility: type: integer enum: - 0 - 1 - 2 description: > 0 = privado (responsável e supervisores), 1 = equipe/responsável, 2 = público. OpportunityTemperature: type: integer enum: - 1 - 2 - 3 description: 1 = frio, 2 = morno, 3 = quente. OpportunityPerson: type: object description: >- Pessoa associada à oportunidade. Envie telefone, e-mail e redes sociais em `contacts`; `phone` e `email` no topo da oportunidade não fazem parte do contrato. 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/OpportunityPersonContact' 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. OpportunityOrganization: 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 OpportunityCustomFieldValue: 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 OpportunityFollowerInput: 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 OpportunityNoteInput: type: object properties: content: type: string is_pinned: type: boolean OpportunityPersonContact: 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. ````