PT FR EN
Acessar
API REST v1

Documentação da API

Catálogo dos endpoints REST disponíveis. Autenticação via Bearer JWT no header Authorization.

Base URL: https://crm.xpevolution.fr/api/v1

Auth: Authorization: Bearer <jwt-access-token> (obter em /auth/login)

Content-Type: application/json em todos os POSTs/PATCHs

Módulos:

🔐 Auth

POST /auth/register — Cria tenant + admin Público (sem auth)
POST /auth/login — Login com slug + email + senha Público (sem auth)
POST /auth/refresh — Renova access token Público (sem auth)
POST /auth/logout — Logout (auditado) Requer auth
GET /me — Usuário autenticado atual Requer auth

👥 Users

GET /users — Lista paginada (filtros: q, role, is_active, sort, order, page, per_page) Requer auth
POST /users — Criar usuário Role mínima: tenant_admin
GET /users/{id:uuid} — Detalhe Requer auth
PATCH /users/{id:uuid} — Atualizar (admin: tudo / self: campos limitados) Requer auth
DELETE /users/{id:uuid} — Soft delete Role mínima: tenant_admin
POST /users/{id:uuid}/restore — Restaurar Role mínima: tenant_admin
POST /users/{id:uuid}/password — Trocar senha (self exige current_password) Requer auth

🏛️ Accounts (empresas)

GET /accounts — Lista (filtros: q, lifecycle_stage, tier, industry, owner_id, country) Requer auth
POST /accounts — Criar Role mínima: sales+
GET /accounts/{id:uuid} — Detalhe Requer auth
PATCH /accounts/{id:uuid} — Atualizar Role mínima: sales+
DELETE /accounts/{id:uuid} — Soft delete Role mínima: manager+
POST /accounts/{id:uuid}/restore — Restaurar Role mínima: manager+

👤 Contacts (pessoas)

GET /contacts — Lista (filtros: q, lifecycle_stage, lead_status, temperature, account_id, owner_id, do_not_contact) Requer auth
POST /contacts — Criar (full_name e dedupe_hash auto-gerados) Role mínima: sales+
GET /contacts/{id:uuid} — Detalhe Requer auth
PATCH /contacts/{id:uuid} — Atualizar Role mínima: sales+
DELETE /contacts/{id:uuid} — Soft delete Role mínima: manager+
POST /contacts/{id:uuid}/restore — Restaurar Role mínima: manager+

🔄 Pipelines & Stages

GET /pipelines — Listar pipelines Requer auth
POST /pipelines — Criar (?seed=true cria 6 stages padrão) Role mínima: manager+
GET /pipelines/{id:uuid} — Detalhe c/ stages Requer auth
PATCH /pipelines/{id:uuid} — Atualizar Role mínima: manager+
DELETE /pipelines/{id:uuid} — Soft delete Role mínima: tenant_admin
POST /pipelines/{id:uuid}/restore — Restaurar Role mínima: tenant_admin
GET /pipelines/{id:uuid}/stages — Listar stages Requer auth
POST /pipelines/{id:uuid}/stages — Criar stage Role mínima: manager+
PATCH /pipelines/{id:uuid}/stages/{stageId:uuid} — Atualizar stage Role mínima: manager+
DELETE /pipelines/{id:uuid}/stages/{stageId:uuid} — Deletar stage (bloqueia se tem opps) Role mínima: manager+

💼 Opportunities (deals)

GET /opportunities — Lista (15+ filtros: status, priority, owner, account, pipeline, stage, faixa de valor, datas) Requer auth
POST /opportunities — Criar (FK validation completa) Role mínima: sales+
GET /opportunities/{id:uuid} — Detalhe Requer auth
PATCH /opportunities/{id:uuid} — Atualizar (stage_id BANIDO — usar /move) Role mínima: sales+
DELETE /opportunities/{id:uuid} — Soft delete Role mínima: manager+
POST /opportunities/{id:uuid}/restore — Restaurar Role mínima: manager+
POST /opportunities/{id:uuid}/move — Mover de stage (auto-detecta won/lost, registra histórico) Role mínima: sales+
GET /opportunities/{id:uuid}/history — Timeline de movimentações Requer auth

📅 Activities

GET /activities — Lista (filtros: type, status, owner_id=me, opportunity_id, overdue, due_from/to) Requer auth
POST /activities — Criar (link polimórfico obrigatório) Role mínima: sales+
GET /activities/{id:uuid} — Detalhe Requer auth
PATCH /activities/{id:uuid} — Atualizar Role mínima: sales+
DELETE /activities/{id:uuid} — Soft delete Role mínima: sales+
POST /activities/{id:uuid}/restore — Restaurar Role mínima: manager+
POST /activities/{id:uuid}/complete — Atalho: marcar como concluída Role mínima: sales+

📊 Dashboard

GET /dashboard/summary — 12 KPIs (contatos, accounts, pipeline aberto, won_this_month, conversion_rate, avg_cycle, activities) Requer auth
GET /dashboard/pipeline — Kanban-ready (?pipeline_id=...). Stages com counts e values Requer auth
GET /dashboard/activity-feed — Timeline (?limit=20). Joina nomes de owner, contact, account, opp Requer auth

Health & Diagnóstico

GET /api/v1/ping — Liveness Público (sem auth)
GET /api/v1/health — Readiness (DB + Redis + Meili) Público (sem auth)