CRM Educacional

Funil de prospecção de novos alunos (leads) e oportunidades de upsell/renovação em clientes já matriculados (oportunidades). Leads têm leitura e criação — o caso de uso típico é um site da escola ou uma plataforma de anúncios empurrando um novo lead. O restante do ciclo de vida (mover de fase, ganhar, perder) continua no board da escola. Oportunidades são somente leitura.

Plano Gestão Escolar (ERP): os endpoints desta página respondem somente para clientes do plano Gestão Escolar (ERP), como no sistema web. Para clientes do plano simplificado, a resposta é 403 com "code": "ERP_REQUIRED".

O modelo fase do funil

Cada escola configura suas próprias fases. Um lead novo sempre entra na fase de menor order.

id uuid

Identificador único da fase.

pipeline string

enrollment (funil de leads) ou opportunity (funil de oportunidades).

key string|null

Chave interna estável, quando a fase é uma das padrão da plataforma.

name string

Nome da fase.

order integer

Posição no funil.

is_won boolean

Se esta fase representa conversão (matriculado/venda fechada).

is_lost boolean

Se esta fase representa perda.

Modelo fase

{
  "id": "...",
  "pipeline": "enrollment",
  "name": "Novo Lead",
  "order": 1,
  "is_won": false,
  "is_lost": false
}

O modelo lead

id uuid

Identificador único do lead.

stage object

A fase atual, no formato do modelo acima.

student_name string

Nome da criança de interesse.

guardian_name string

Nome do responsável.

guardian_email string|null

E-mail do responsável.

guardian_phone string|null

Telefone do responsável.

source string

website, walk_in, phone, whatsapp, referral, social_media, public_form, rematricula ou other.

status string

open, won ou lost.

pending_action_label string|null

Sinaliza quando a fase avançou (ex.: para "Matriculado") sem que a matrícula real tenha sido criada ainda.

estimated_value decimal|null

Valor estimado do negócio.

created_at datetime

Data de criação.

Modelo lead

{
  "id": "...",
  "student_name": "Futuro Aluno",
  "guardian_name": "Responsável Interessado",
  "source": "website",
  "status": "open",
  "pending_action_label": null
}

GET /v1/partners/school/{cnpj}/crm/stages/all

Listar fases do funil

Fases do funil de leads (pipeline enrollment), em ordem.

Códigos de resposta

200

Sucesso.

404

Não encontrado.

Requisição GET

GET /api/v1/partners/school/{cnpj}/crm/stages/all

GET /v1/partners/school/{cnpj}/crm/leads

Listar leads

Leads da escola, paginados. Filtro opcional status (query string).

Códigos de resposta

200

Sucesso.

404

Não encontrado.

Requisição GET

GET /api/v1/partners/school/{cnpj}/crm/leads

POST /v1/partners/school/{cnpj}/crm/leads

Criar lead

Corpo: student_name, guardian_name (obrigatórios); student_birthdate, guardian_cpf, guardian_email, guardian_phone, source, interest_grade_id, interest_shift_id, estimated_value, notes (opcionais). Entra automaticamente na primeira fase do funil.

Códigos de resposta

201

Sucesso.

409

Escola sem funil de prospecção configurado.

404

Não encontrado.

Requisição POST

POST /api/v1/partners/school/{cnpj}/crm/leads

{ "student_name": "Novo Interessado", "guardian_name": "Mãe do Interessado" }

GET /v1/partners/school/{cnpj}/crm/opportunities

Listar oportunidades

Oportunidades de upsell/renovação, paginadas — somente leitura.

Códigos de resposta

200

Sucesso.

404

Não encontrado.

Requisição GET

GET /api/v1/partners/school/{cnpj}/crm/opportunities

GET /v1/partners/school/{cnpj}/crm/opportunity/{id}

Obter uma oportunidade

Retorna uma oportunidade com atividades e tarefas — somente leitura.

Códigos de resposta

200

Sucesso.

404

Não encontrado.

Requisição GET

GET /api/v1/partners/school/{cnpj}/crm/opportunity/{id}