Leads e agendamentos

Visão geral

Os recursos de captação expõem dois contratos GET independentes. Leads retorna contatos capturados em formulários e landing pages; Agendamentos retorna solicitações de agenda por unidade. Ambos são read-only — não há criação, atualização ou exclusão por esta API — e compartilham as mesmas regras de paginação, ordenação e datas.

Regras gerais

Convenções comuns aos dois recursos de captação. Base URL nos exemplos: /api2. Toda consulta exige Authorization: Bearer {{token}}.

• Filtros aceitam query string ou JSON body no GET. Quando o mesmo campo existir nos dois lugares, o valor da query string prevalece.
• Filtros de texto (email, phone, name) são por igualdade exata, sem diferenciar maiúsculas/minúsculas. Não há busca parcial.
• Paginação padrão: page=1, limit=20. Limite máximo: 200. Use include_pagination=1 para receber total, last_page e has_next no corpo.
• Datas usam YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS. Formatos inválidos retornam 400.
• Ordenação: use sort e direction (asc ou desc). Padrão: sort=created_at, direction=desc.
• Consulta por id retorna um único registro; quando não houver correspondência, a resposta é 404.

Leads

Consulta dos contatos capturados em formulários, landing pages e campanhas, com dados de atribuição (UTMs), origem e cupom vinculado.

GET /api2/leads?page=1&limit=50&include_pagination=1&created_from=2026-06-01&created_to=2026-06-30&sort=created_at&direction=desc
Authorization: Bearer {{token}}

{
  "success": true,
  "page": 1,
  "limit": 50,
  "total": 1,
  "last_page": 1,
  "has_next": false,
  "leads": [
    {
      "id": 123,
      "store_id": 10,
      "name": "Maria Silva",
      "email": "[email protected]",
      "phone": "11999999999",
      "created_at": "2026-06-20 14:30:00",
      "utm_source": "google",
      "utm_medium": "cpc",
      "utm_campaign": "avaliacao",
      "utm_term": null,
      "utm_content": null,
      "origin": "landing_page",
      "coupon_id": 5,
      "coupon_used": "CAMPANHA_123",
      "promoters_name": "Promotor A"
    }
  ]
}

GET /api2/leads?id=123
Authorization: Bearer {{token}}

Agendamentos

Consulta das solicitações de agenda por unidade, com data e horário, tratamento solicitado, atribuição (UTMs) e status de sincronização com sistemas externos. Disponível em /api2/schedules e no alias em português /api2/agendamentos — ambos com o mesmo contrato.

GET /api2/schedules?page=1&limit=50&include_pagination=1&date_from=2026-06-01&date_to=2026-06-30&status_gester=1,3
Authorization: Bearer {{token}}

{
  "success": true,
  "page": 1,
  "limit": 50,
  "total": 1,
  "last_page": 1,
  "has_next": false,
  "schedules": [
    {
      "id": 456,
      "name": "Ana Costa",
      "email": "[email protected]",
      "phone": "11988888888",
      "date": "2026-06-25",
      "time": "15:00",
      "unity_id": 10,
      "treatment": "Avaliação gratuita",
      "created_at": "2026-06-20 16:10:00",
      "utm_source": "instagram",
      "utm_medium": "social",
      "utm_campaign": "agenda",
      "utm_term": null,
      "utm_content": null,
      "origin": "C",
      "campanha_interna": "https://example.com/lp",
      "campanha_interna_id": null,
      "codigo_gester": "ABC123",
      "status_gester": 2,
      "status_gester_label": "Sincronizado",
      "mensagem_erro_gester": null
    }
  ]
}

GET /api2/schedules?id=456
Authorization: Bearer {{token}}

Status de sincronização do agendamento

O campo status_gester reflete a etapa de sincronização do agendamento com o sistema externo. O campo status_gester_label traz a descrição legível e mensagem_erro_gester detalha a falha quando houver.

Formas de uso suportadas

Combinações testadas e homologadas para leads e agendamentos.

Recomendações para integração

Boas práticas consolidadas para fluxos n8n, CRM e BI que sincronizam captações com a Plataforma Yep.

Recomendado

• Use include_pagination=1 quando o fluxo precisar iterar páginas até has_next=false.
• Para cargas incrementais, prefira janelas por created_from/created_to e guarde o último horário processado no próprio fluxo para evitar duplicidade.
• Combine limit=100 + include_pagination=1 + sort=created_at&direction=asc para paginar com critério de parada e ordem previsíveis.
• Use store_id (leads) ou unity_id (agendamentos) para resultados determinísticos em operações multiunidade.

Evitar

• Esperar busca parcial por nome, e-mail ou telefone — os filtros de texto são por igualdade exata.
• Tentar criar, atualizar ou excluir captações por esta API — os endpoints são somente leitura.
• Depender de ordenação implícita entre páginas — sempre informe sort e direction.

Erros comuns