Introducción

La API de Leader CRM permite gestionar todo el ciclo de ventas programaticamente: contactos, empresas, deals, cotizaciónes, facturas, contratos y pagos. Disenada para integraciones con agentes de IA, aplicaciones externas y automatizaciones.

Base URL

https://tu-dominio.com/api/v1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
Autenticación
Laravel Sanctum bearer tokens. Incluye el token en cada solicitud autenticada.
POST /api/v1/auth/login
Publica
Obtener token de autenticación.

Body

Campo Tipo Requerido Descripcion
email string Si Email del usuario
password string Si Contrasena del usuario 
curl -X POST https://tu-dominio.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "jorge@leadercrm.mx",
    "password": "secreto123"
  }'
Ver respuesta de ejemplo 
{
  "token": "1|abc123def456ghi789jkl012mno345pqr678stu901",
  "user": {
    "id": 1,
    "name": "Jorge Zamarron",
    "email": "jorge@leadercrm.mx",
    "role": "admin",
    "avatar_url": "https://tu-dominio.com/storage/avatars/1.jpg"
  },
  "tenant": {
    "id": 1,
    "name": "Zamarron Consulting"
  }
}
POST /api/v1/auth/register
Publica
Registrar nuevo usuario y tenant.

Body

Campo Tipo Requerido Descripcion
name string Si Nombre completo (max 255)
email string Si Email unico
password string Si Min 8 caracteres
password_confirmation string Si Debe coincidir con password
tenant_name string Si Nombre de la empresa (max 255) 
curl -X POST https://tu-dominio.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "J. Garcia Lopez",
    "email": "jgarcia@empresa.mx",
    "password": "MiPassword2024!",
    "password_confirmation": "MiPassword2024!",
    "tenant_name": "Garcia & Asociados"
  }'
Ver respuesta de ejemplo 
{
  "token": "2|xyz789abc123def456ghi789jkl012mno345pqr678",
  "user": {
    "id": 2,
    "name": "J. Garcia Lopez",
    "email": "jgarcia@empresa.mx",
    "role": "admin",
    "avatar_url": null
  },
  "tenant": {
    "id": 2,
    "name": "Garcia & Asociados"
  }
}
POST /api/v1/auth/logout
Auth
Cerrar sesion e invalidar el token. 
curl -X POST https://tu-dominio.com/api/v1/auth/logout \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Ver respuesta de ejemplo 
{ "message": "Logged out successfully." }
GET /api/v1/auth/me
Auth
Obtener usuario y tenant actual. 
curl https://tu-dominio.com/api/v1/auth/me \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Ver respuesta de ejemplo 
{
  "data": {
    "id": 1,
    "name": "Jorge Zamarron",
    "email": "jorge@leadercrm.mx",
    "role": "admin",
    "avatar_url": "https://tu-dominio.com/storage/avatars/1.jpg"
  },
  "tenant": {
    "id": 1,
    "name": "Zamarron Consulting"
  }
}
Formato de Respuesta
Todas las respuestas usan formato JSON estandar de Laravel.

Recurso individual

{
  "data": {
    "id": 1,
    "first_name": "Jorge",
    "last_name": "Zamarron"
  }
}

Lista paginada

{
  "data": [ ... ],
  "links": { "first": "...", "next": "..." },
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 112
  }
}

Codigos de Error

Codigo Significado
200 Exito
201 Recurso creado
401 No autenticado -- token invalido o faltante
403 Prohibido -- permisos insuficientes
404 Recurso no encontrado
422 Error de validacion -- revisar objeto errors
429 Rate limit -- revisar header Retry-After
500 Error interno del servidor
Contactos
Gestiona los contactos del CRM.
GET /api/v1/contacts
Auth
Listar todos los contactos con paginación y filtros.

Parametros

Campo Tipo Requerido Descripcion
search string No Buscar por nombre, email o telefono
lifecycle_stage string No Filtrar por etapa: lead, prospect, customer
owner_id integer No Filtrar por propietario asignado
company_id integer No Filtrar por empresa
per_page integer No Resultados por pagina (default 25, max 100) 
curl "https://tu-dominio.com/api/v1/contacts?search=garcia&lifecycle_stage=lead&per_page=10" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Ver respuesta de ejemplo 
{
  "data": [
    {
      "id": 1,
      "full_name": "Maria Garcia Lopez",
      "primary_email": "mgarcia@ejemplo.mx",
      "primary_phone": "+52 55 1234 5678",
      "lifecycle_stage": "lead",
      "lead_score": 45
    }
  ],
  "meta": { "current_page": 1, "per_page": 10, "total": 3 }
}
GET /api/v1/contacts/{id}
Auth
Obtener un contacto con todos sus datos. 
curl https://tu-dominio.com/api/v1/contacts/1 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Ver respuesta de ejemplo 
{
  "data": {
    "id": 1,
    "first_name": "Maria",
    "last_name": "Garcia Lopez",
    "full_name": "Maria Garcia Lopez",
    "emails": [{ "email": "mgarcia@ejemplo.mx" }],
    "phones": [{ "phone": "+52 55 1234 5678", "type": "mobile" }],
    "job_title": "Directora Comercial",
    "company_id": 3,
    "company_name": "Soluciones Integrales SA de CV",
    "lifecycle_stage": "lead",
    "lead_score": 45,
    "owner_id": 1,
    "owner_name": "Jorge Zamarron",
    "source": "referral",
    "city": "Monterrey",
    "country": "Mexico",
    "custom_fields": { "rfc": "GALM850101ABC" },
    "created_at": "2025-03-15T10:30:00.000000Z"
  }
}
POST /api/v1/contacts
Auth
Crear un nuevo contacto.

Body

Campo Tipo Requerido Descripcion
first_name string Si Nombre (max 255)
last_name string No Apellido (max 255)
emails array No [{"email": "a@b.com"}]
phones array No Array de telefonos
job_title string No Puesto (max 255)
company_id integer No ID de empresa existente
lifecycle_stage string No lead, prospect, customer, etc.
source string No Fuente del lead
city string No Ciudad
custom_fields object No Pares clave-valor personalizados 
curl -X POST https://tu-dominio.com/api/v1/contacts \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "first_name": "Roberto",
    "last_name": "Hernandez Ruiz",
    "emails": [{"email": "rhernandez@technogroup.mx"}],
    "phones": [{"phone": "+52 81 8765 4321", "type": "office"}],
    "job_title": "Gerente de Compras",
    "company_id": 3,
    "lifecycle_stage": "lead",
    "source": "website",
    "city": "Guadalajara"
  }'
Ver respuesta de ejemplo 
{ "data": { "id": 5, "first_name": "Roberto", "last_name": "Hernandez Ruiz", "..." } }
PUT /api/v1/contacts/{id}
Auth
Actualizar un contacto. Mismos campos que crear, todos opcionales. 
curl -X PUT https://tu-dominio.com/api/v1/contacts/1 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "lifecycle_stage": "customer", "job_title": "Directora General" }'
DELETE /api/v1/contacts/{id}
Auth
Eliminar un contacto. 
curl -X DELETE https://tu-dominio.com/api/v1/contacts/1 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
GET /api/v1/contacts/{contact_id}/notes
Auth
Listar notas de un contacto. 
curl https://tu-dominio.com/api/v1/contacts/1/notes \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Ver respuesta de ejemplo 
{
  "data": [
    {
      "id": 10,
      "body": "Llamada de seguimiento: interesado en plan empresarial.",
      "user_name": "Jorge Zamarron",
      "created_at": "2025-04-01T09:15:00.000000Z"
    }
  ]
}
POST /api/v1/contacts/{contact_id}/notes
Auth
Agregar una nota a un contacto.

Body

Campo Tipo Requerido Descripcion
body string Si Texto de la nota
is_pinned boolean No Fijar al inicio (default: false) 
curl -X POST https://tu-dominio.com/api/v1/contacts/1/notes \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "body": "Reunion programada para el viernes 18 a las 10am.", "is_pinned": true }'
Empresas
Gestiona las empresas del CRM.
GET /api/v1/companies
Auth
Listar empresas con busqueda y paginación.

Parametros

Campo Tipo Descripcion
search string Buscar por nombre de empresa
per_page integer Resultados por pagina (default 25, max 100) 
curl "https://tu-dominio.com/api/v1/companies?search=soluciones" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Ver respuesta de ejemplo 
{
  "data": [
    {
      "id": 3,
      "name": "Soluciones Integrales SA de CV",
      "industry": "Tecnologia",
      "contacts_count": 12
    }
  ]
}
GET /api/v1/companies/{id}
Auth
Obtener detalle de una empresa. 
curl https://tu-dominio.com/api/v1/companies/3 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Ver respuesta de ejemplo 
{
  "data": {
    "id": 3,
    "name": "Soluciones Integrales SA de CV",
    "domain": "soluciones-integrales.mx",
    "industry": "Tecnologia",
    "employee_range": "51-200",
    "annual_revenue": 15000000,
    "phone": "+52 55 5555 1234",
    "email": "contacto@soluciones-integrales.mx",
    "tax_id": "SIN850101ABC",
    "contacts_count": 12,
    "owner_id": 1
  }
}
POST /api/v1/companies
Auth
Crear una nueva empresa.

Body

Campo Tipo Requerido Descripcion
name string Si Nombre de la empresa (max 255)
domain string No Dominio web
industry string No Industria
employee_range string No Ej. "1-10", "51-200"
annual_revenue numeric No Ingreso anual
tax_id string No RFC (max 100) 
curl -X POST https://tu-dominio.com/api/v1/companies \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Distribuidora del Norte SA de CV",
    "domain": "distnorte.mx",
    "industry": "Distribucion",
    "employee_range": "11-50",
    "annual_revenue": 8500000,
    "phone": "+52 81 8888 9999",
    "email": "info@distnorte.mx",
    "tax_id": "DNO900515XYZ"
  }'
PUT /api/v1/companies/{id}
Auth
Actualizar una empresa. Mismos campos, todos opcionales. 
curl -X PUT https://tu-dominio.com/api/v1/companies/3 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "annual_revenue": 18000000 }'
DELETE /api/v1/companies/{id}
Auth
Eliminar una empresa. 
curl -X DELETE https://tu-dominio.com/api/v1/companies/3 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Deals
Gestiona oportunidades de negocio en el pipeline.
GET /api/v1/deals
Auth
Listar deals con filtros por pipeline, etapa y propietario.

Parametros

Campo Tipo Descripcion
pipeline_id integer Filtrar por pipeline
stage_id integer Filtrar por etapa
owner_id integer Filtrar por propietario
search string Buscar por nombre del deal 
curl "https://tu-dominio.com/api/v1/deals?pipeline_id=1&owner_id=1" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Ver respuesta de ejemplo 
{
  "data": [
    {
      "id": 5,
      "name": "Implementacion ERP - Distribuidora del Norte",
      "amount": 450000,
      "stage_name": "Propuesta",
      "probability": 50,
      "owner_name": "Jorge Zamarron"
    }
  ]
}
GET /api/v1/deals/{id}
Auth
Obtener detalle de un deal con contactos asociados. 
curl https://tu-dominio.com/api/v1/deals/5 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Ver respuesta de ejemplo 
{
  "data": {
    "id": 5,
    "name": "Implementacion ERP - Distribuidora del Norte",
    "amount": 450000,
    "currency": "MXN",
    "probability": 50,
    "pipeline_id": 1,
    "stage_id": 3,
    "stage_name": "Propuesta",
    "owner_id": 1,
    "expected_close_date": "2025-06-30",
    "contacts": [
      { "id": 1, "full_name": "Maria Garcia Lopez", "primary_email": "mgarcia@ejemplo.mx" }
    ]
  }
}
POST /api/v1/deals
Auth
Crear un nuevo deal. Requiere pipeline_id y stage_id.

Body

Campo Tipo Requerido Descripcion
name string Si Nombre del deal (max 255)
pipeline_id integer Si ID del pipeline
stage_id integer Si ID de la etapa
amount numeric No Valor del deal
currency string No Ej. "MXN", "USD"
expected_close_date date No Fecha esperada de cierre (YYYY-MM-DD)
contact_ids array No IDs de contactos a asociar 
curl -X POST https://tu-dominio.com/api/v1/deals \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Consultoria Fiscal Q3 - Garcia & Asociados",
    "amount": 180000,
    "currency": "MXN",
    "pipeline_id": 1,
    "stage_id": 2,
    "expected_close_date": "2025-07-15",
    "contact_ids": [1, 4]
  }'
PUT /api/v1/deals/{id}
Auth
Actualizar un deal. Soporta contact_ids para sincronizar contactos. 
curl -X PUT https://tu-dominio.com/api/v1/deals/5 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "amount": 500000, "probability": 75 }'
DELETE /api/v1/deals/{id}
Auth
Eliminar un deal. 
curl -X DELETE https://tu-dominio.com/api/v1/deals/5 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
POST /api/v1/deals/{id}/move-stage
Auth
Mover un deal a otra etapa del pipeline.

Body

Campo Tipo Requerido Descripcion
stage_id integer Si ID de la nueva etapa 
curl -X POST https://tu-dominio.com/api/v1/deals/5/move-stage \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"stage_id": 4}'
Actividades
Tareas, llamadas, reuniones y emails vinculados a contactos o deals.
GET /api/v1/activities
Auth
Listar actividades con filtros por usuario, estado y tipo.

Parametros

Campo Tipo Descripcion
user_id integer Filtrar por usuario asignado
status string pending, completed, cancelled
type string call, email, meeting, task
activitable_type string Ej. App\Models\Contact
activitable_id string ID de la entidad relacionada 
curl "https://tu-dominio.com/api/v1/activities?status=pending&type=call" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Ver respuesta de ejemplo 
{
  "data": [
    {
      "id": 12,
      "subject": "Llamada de seguimiento con Maria Garcia",
      "type": "call",
      "status": "pending",
      "priority": "high",
      "due_at": "2025-04-15T10:00:00.000000Z",
      "completed_at": null,
      "user_id": 1,
      "notes": "Preguntar por la decision sobre la propuesta."
    }
  ]
}
POST /api/v1/activities
Auth
Crear una nueva actividad.

Body

Campo Tipo Requerido Descripcion
subject string Si Asunto de la actividad (max 255)
type string Si call, email, meeting, task
priority string No low, medium, high
due_at date No Fecha de vencimiento
activitable_type string No App\Models\Contact, App\Models\Deal
activitable_id string No ID de la entidad relacionada
notes string No Notas adicionales 
curl -X POST https://tu-dominio.com/api/v1/activities \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "subject": "Enviar propuesta a Roberto Hernandez",
    "type": "task",
    "priority": "high",
    "due_at": "2025-04-16T14:00:00Z",
    "activitable_type": "App\\Models\\Deal",
    "activitable_id": "5",
    "notes": "Incluir descuento del 10% por pronto pago."
  }'
PUT /api/v1/activities/{id}
Auth
Actualizar una actividad. Mismos campos, todos opcionales. 
curl -X PUT https://tu-dominio.com/api/v1/activities/12 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "priority": "medium", "due_at": "2025-04-18T10:00:00Z" }'
DELETE /api/v1/activities/{id}
Auth
Eliminar una actividad. 
curl -X DELETE https://tu-dominio.com/api/v1/activities/12 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
POST /api/v1/activities/{id}/complete
Auth
Marcar una actividad como completada. Sin body requerido. 
curl -X POST https://tu-dominio.com/api/v1/activities/12/complete \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Cotizaciones
Crea y gestiona cotizaciónes con lineas de detalle.
GET /api/v1/quotes
Auth
Listar cotizaciónes con filtros por contacto, deal y estado.

Parametros

Campo Tipo Descripcion
contact_id integer Filtrar por contacto
deal_id integer Filtrar por deal
status string draft, sent, approved, rejected 
curl "https://tu-dominio.com/api/v1/quotes?status=sent" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Ver respuesta de ejemplo 
{
  "data": [
    {
      "id": 8,
      "quote_number": "COT-000008",
      "title": "Propuesta Consultoria Fiscal Q3",
      "status": "sent",
      "total": 208800,
      "subtotal": 180000,
      "tax_total": 28800,
      "currency": "MXN",
      "valid_until": "2025-05-15",
      "contact_id": 1,
      "deal_id": 5,
      "items": [
        {
          "description": "Consultoria fiscal especializada",
          "quantity": 120,
          "unit_price": 1500,
          "tax_rate": 16,
          "total": 208800
        }
      ]
    }
  ]
}
GET /api/v1/quotes/{id}
Auth
Obtener detalle de una cotización con items. 
curl https://tu-dominio.com/api/v1/quotes/8 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
POST /api/v1/quotes
Auth
Crear una cotización con lineas de detalle. Los totales se calculan automaticamente.

Body

Campo Tipo Requerido Descripcion
contact_id integer Si ID del contacto
deal_id integer No ID del deal asociado
title string No Titulo de la cotización
currency string No Moneda (ej. MXN)
valid_until date No Fecha de vigencia
items array Si Min 1 item: description, quantity, unit_price, tax_rate, discount_percent 
curl -X POST https://tu-dominio.com/api/v1/quotes \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "contact_id": 1,
    "deal_id": 5,
    "title": "Propuesta de Servicios TI",
    "currency": "MXN",
    "valid_until": "2025-05-30",
    "items": [
      { "description": "Licencia ERP anual", "quantity": 1, "unit_price": 250000, "tax_rate": 16 },
      { "description": "Implementacion y capacitacion", "quantity": 80, "unit_price": 2500, "discount_percent": 5, "tax_rate": 16 }
    ]
  }'
PUT /api/v1/quotes/{id}
Auth
Actualizar una cotización. Si se envian items, reemplazan los existentes. 
curl -X PUT https://tu-dominio.com/api/v1/quotes/8 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "valid_until": "2025-06-15" }'
DELETE /api/v1/quotes/{id}
Auth
Eliminar una cotización. 
curl -X DELETE https://tu-dominio.com/api/v1/quotes/8 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
POST /api/v1/quotes/{id}/send
Auth
Enviar cotización. Cambia estado a "sent". 
curl -X POST https://tu-dominio.com/api/v1/quotes/8/send \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
POST /api/v1/quotes/{id}/approve
Auth
Aprobar cotización. Cambia estado a "approved". 
curl -X POST https://tu-dominio.com/api/v1/quotes/8/approve \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
POST /api/v1/quotes/{id}/reject
Auth
Rechazar cotización. Opcionalmente con razon. 
curl -X POST https://tu-dominio.com/api/v1/quotes/8/reject \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"reason": "Presupuesto excede nuestro limite aprobado."}'
Facturas
Crea y gestiona facturas con lineas de detalle y seguimiento de pagos.
GET /api/v1/invoices
Auth
Listar facturas con filtros por contacto, deal y estado.

Parametros

Campo Tipo Descripcion
contact_id integer Filtrar por contacto
deal_id integer Filtrar por deal
status string draft, sent, paid, overdue 
curl "https://tu-dominio.com/api/v1/invoices?status=sent" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Ver respuesta de ejemplo 
{
  "data": [
    {
      "id": 4,
      "invoice_number": "FAC-000004",
      "status": "sent",
      "total": 208800,
      "amount_paid": 0,
      "amount_due": 208800,
      "currency": "MXN",
      "issued_at": "2025-04-05T00:00:00.000000Z",
      "due_at": "2025-05-05T00:00:00.000000Z",
      "contact_id": 1,
      "deal_id": 5
    }
  ]
}
GET /api/v1/invoices/{id}
Auth
Obtener detalle de una factura con items. 
curl https://tu-dominio.com/api/v1/invoices/4 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
POST /api/v1/invoices
Auth
Crear factura con lineas de detalle. Numero de factura auto-generado (FAC-XXXXXX).

Body

Campo Tipo Requerido Descripcion
contact_id integer Si ID del contacto
deal_id integer No ID del deal asociado
currency string No Moneda (max 10)
due_at date No Fecha de vencimiento
items array Si Min 1 item: description, quantity, unit_price, tax_rate 
curl -X POST https://tu-dominio.com/api/v1/invoices \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "contact_id": 1,
    "deal_id": 5,
    "currency": "MXN",
    "due_at": "2025-05-05",
    "notes": "Favor de realizar pago por transferencia bancaria.",
    "items": [
      { "description": "Consultoria fiscal especializada - 120 hrs", "quantity": 120, "unit_price": 1500, "tax_rate": 16 }
    ]
  }'
PUT /api/v1/invoices/{id}
Auth
Actualizar factura. Si se envian items, reemplazan los existentes. 
curl -X PUT https://tu-dominio.com/api/v1/invoices/4 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "due_at": "2025-05-20" }'
DELETE /api/v1/invoices/{id}
Auth
Eliminar una factura. 
curl -X DELETE https://tu-dominio.com/api/v1/invoices/4 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
POST /api/v1/invoices/{id}/send
Auth
Enviar factura. Cambia estado a "sent". 
curl -X POST https://tu-dominio.com/api/v1/invoices/4/send \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Contratos
Gestiona contratos con flujo de firma.
GET /api/v1/contracts
Auth
Listar contratos. Filtros: contact_id, deal_id, status (draft, sent, signed, expired). 
curl "https://tu-dominio.com/api/v1/contracts?status=draft" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Ver respuesta de ejemplo 
{
  "data": [
    {
      "id": 2,
      "contract_number": "CTR-000002",
      "title": "Contrato de Servicios de Consultoria",
      "type": "service",
      "status": "draft",
      "value": 450000,
      "currency": "MXN",
      "start_date": "2025-05-01",
      "end_date": "2025-12-31",
      "contact_id": 1,
      "deal_id": 5
    }
  ]
}
GET /api/v1/contracts/{id}
Auth
Obtener detalle de un contrato. 
curl https://tu-dominio.com/api/v1/contracts/2 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
POST /api/v1/contracts
Auth
Crear un contrato. Numero auto-generado (CTR-XXXXXX), estado inicial "draft".

Body

Campo Tipo Requerido Descripcion
contact_id integer Si ID del contacto
title string Si Titulo del contrato (max 255)
deal_id integer No ID del deal asociado
type string No Tipo de contrato (max 50)
value numeric No Valor del contrato
start_date date No Fecha de inicio
end_date date No Fecha de fin (>= start_date) 
curl -X POST https://tu-dominio.com/api/v1/contracts \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "contact_id": 1,
    "deal_id": 5,
    "title": "Contrato de Servicios de Consultoria Fiscal",
    "type": "service",
    "value": 450000,
    "currency": "MXN",
    "start_date": "2025-05-01",
    "end_date": "2025-12-31"
  }'
PUT /api/v1/contracts/{id}
Auth
Actualizar un contrato. 
curl -X PUT https://tu-dominio.com/api/v1/contracts/2 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "end_date": "2026-03-31" }'
DELETE /api/v1/contracts/{id}
Auth
Eliminar un contrato. 
curl -X DELETE https://tu-dominio.com/api/v1/contracts/2 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
POST /api/v1/contracts/{id}/sign
Auth
Firmar contrato. Cambia estado a "signed" y registra signed_at.

Body (opcional)

Campo Tipo Descripcion
client_name string Nombre del firmante
company_name string Empresa del firmante 
curl -X POST https://tu-dominio.com/api/v1/contracts/2/sign \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "client_name": "Maria Garcia Lopez",
    "company_name": "Soluciones Integrales SA de CV"
  }'
Pagos
Registra pagos contra facturas. Los saldos se recalculan automaticamente.
GET /api/v1/payments
Auth
Listar pagos. Filtros: invoice_id, contact_id, status (completed, pending, refunded). 
curl "https://tu-dominio.com/api/v1/payments?invoice_id=4" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Ver respuesta de ejemplo 
{
  "data": [
    {
      "id": 3,
      "amount": 104400,
      "currency": "MXN",
      "method": "transfer",
      "reference": "SPEI-20250410-001",
      "status": "completed",
      "paid_at": "2025-04-10T12:00:00.000000Z",
      "invoice_id": 4,
      "contact_id": 1
    }
  ]
}
GET /api/v1/payments/{id}
Auth
Obtener detalle de un pago. 
curl https://tu-dominio.com/api/v1/payments/3 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
POST /api/v1/payments
Auth
Registrar un pago. El saldo de la factura se recalcula automaticamente.

Body

Campo Tipo Requerido Descripcion
invoice_id integer Si ID de la factura
amount numeric Si Monto del pago (min 0.01)
method string No transfer, card, cash, check
reference string No Referencia de pago (ej. SPEI) 
curl -X POST https://tu-dominio.com/api/v1/payments \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "invoice_id": 4,
    "contact_id": 1,
    "amount": 104400,
    "currency": "MXN",
    "method": "transfer",
    "reference": "SPEI-20250410-001"
  }'
PUT /api/v1/payments/{id}
Auth
Actualizar un pago. 
curl -X PUT https://tu-dominio.com/api/v1/payments/3 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "reference": "SPEI-20250410-002" }'
DELETE /api/v1/payments/{id}
Auth
Eliminar un pago. 
curl -X DELETE https://tu-dominio.com/api/v1/payments/3 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Productos
Catalogo de productos y servicios para cotizaciónes y facturas.
GET /api/v1/products
Auth
Listar productos. Filtros: search, category_id, business_line_id, active_only. 
curl "https://tu-dominio.com/api/v1/products?search=consultoria&active_only=true" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Ver respuesta de ejemplo 
{
  "data": [
    {
      "id": 3,
      "name": "Consultoria Fiscal Especializada",
      "sku": "CONS-FISC-001",
      "description": "Hora de consultoria fiscal con especialista certificado.",
      "unit_price": 1500,
      "tax_rate": 16,
      "currency": "MXN",
      "is_active": true
    }
  ]
}
GET /api/v1/products/{id}
Auth
Obtener detalle de un producto. 
curl https://tu-dominio.com/api/v1/products/3 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
POST /api/v1/products
Auth
Crear un producto o servicio.

Body

Campo Tipo Requerido Descripcion
name string Si Nombre del producto (max 255)
unit_price numeric Si Precio unitario (min 0)
sku string No Codigo SKU (max 100)
tax_rate numeric No Tasa de impuesto (ej. 16 para 16%)
is_active boolean No Default: true 
curl -X POST https://tu-dominio.com/api/v1/products \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Auditoria Financiera Completa",
    "sku": "AUD-FIN-001",
    "description": "Auditoria financiera integral para empresas medianas.",
    "unit_price": 85000,
    "tax_rate": 16,
    "currency": "MXN"
  }'
PUT /api/v1/products/{id}
Auth
Actualizar un producto. 
curl -X PUT https://tu-dominio.com/api/v1/products/3 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "unit_price": 1800 }'
DELETE /api/v1/products/{id}
Auth
Eliminar un producto. 
curl -X DELETE https://tu-dominio.com/api/v1/products/3 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Pipelines
Lectura de pipelines y sus etapas. Necesarios para crear deals.
GET /api/v1/pipelines
Auth
Obtener todos los pipelines activos con sus etapas. Sin paginación. 
curl https://tu-dominio.com/api/v1/pipelines \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Ver respuesta de ejemplo 
{
  "data": [
    {
      "id": 1,
      "name": "Pipeline de Ventas",
      "is_default": true,
      "stages": [
        { "id": 1, "name": "Prospecto", "type": "open", "color": "#6B7280", "default_probability": 10 },
        { "id": 2, "name": "Contactado", "type": "open", "color": "#3B82F6", "default_probability": 25 },
        { "id": 3, "name": "Propuesta", "type": "open", "color": "#F59E0B", "default_probability": 50 },
        { "id": 4, "name": "Negociacion", "type": "open", "color": "#8B5CF6", "default_probability": 75 },
        { "id": 5, "name": "Ganado", "type": "won", "color": "#10B981", "default_probability": 100 },
        { "id": 6, "name": "Perdido", "type": "lost", "color": "#EF4444", "default_probability": 0 }
      ]
    }
  ]
}
GET /api/v1/pipelines/{id}
Auth
Obtener un pipeline con sus etapas. 
curl https://tu-dominio.com/api/v1/pipelines/1 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Eventos
Gestiona eventos, webinars y reuniones con RSVP y check-in.
GET /api/v1/events
Auth
Listar eventos. Filtros: type, upcoming (true/false). 
curl "https://tu-dominio.com/api/v1/events?upcoming=true" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Ver respuesta de ejemplo 
{
  "data": [
    {
      "id": 3,
      "title": "Webinar: Tendencias Fiscales 2025",
      "type": "webinar",
      "start_at": "2025-04-20T17:00:00.000000Z",
      "end_at": "2025-04-20T18:30:00.000000Z",
      "attendees_count": 45
    }
  ]
}
POST /api/v1/events
Auth
Crear un evento.

Body

Campo Tipo Requerido Descripcion
title string Si Titulo del evento (max 255)
type string Si Tipo (meeting, webinar, training, etc.)
start_at date Si Fecha/hora de inicio
end_at date Si Fecha/hora de fin (> start_at)
location string No Ubicacion
max_attendees integer No Maximo de asistentes 
curl -X POST https://tu-dominio.com/api/v1/events \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "title": "Capacitacion Interna: Nuevo Sistema CRM",
    "type": "training",
    "location": "Sala de Juntas B, Piso 3",
    "start_at": "2025-04-25T09:00:00Z",
    "end_at": "2025-04-25T12:00:00Z",
    "is_mandatory": true,
    "max_attendees": 20
  }'
PUT /api/v1/events/{id}
Auth
Actualizar un evento. 
curl -X PUT https://tu-dominio.com/api/v1/events/3 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "max_attendees": 50 }'
DELETE /api/v1/events/{id}
Auth
Eliminar un evento. 
curl -X DELETE https://tu-dominio.com/api/v1/events/3 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
POST /api/v1/events/{id}/rsvp
Auth
Confirmar asistencia: accepted, declined, tentative. 
curl -X POST https://tu-dominio.com/api/v1/events/3/rsvp \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"status": "accepted"}'
POST /api/v1/events/{id}/check-in/{attendee_id}
Auth
Registrar asistencia de un participante. Sin body requerido. 
curl -X POST https://tu-dominio.com/api/v1/events/3/check-in/15 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Campañas
Campañas de email marketing vinculadas a segmentos.
GET /api/v1/campaigns
Auth
Listar campañas. Filtro: status (draft, sent, scheduled). 
curl "https://tu-dominio.com/api/v1/campaigns?status=draft" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Ver respuesta de ejemplo 
{
  "data": [
    {
      "id": 2,
      "name": "Promocion Servicios Fiscales Q2",
      "status": "draft",
      "segment_name": "Clientes Activos Monterrey",
      "stats": null,
      "sent_at": null
    }
  ]
}
POST /api/v1/campaigns
Auth
Crear una campaña de email.

Body

Campo Tipo Requerido Descripcion
name string Si Nombre de la campaña
subject string No Asunto del email
content string No Contenido HTML del email
segment_id integer No ID del segmento destino
scheduled_at date No Fecha programada de envio 
curl -X POST https://tu-dominio.com/api/v1/campaigns \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Newsletter Abril 2025",
    "subject": "Novedades y promociones de abril",
    "content": "
Hola!
Estas son nuestras novedades...
",
    "segment_id": 1,
    "scheduled_at": "2025-04-20T09:00:00Z"
  }'
PUT /api/v1/campaigns/{id}
Auth
Actualizar una campaña. Mismos campos, todos opcionales. 
curl -X PUT https://tu-dominio.com/api/v1/campaigns/2 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "subject": "Ofertas especiales de abril" }'
DELETE /api/v1/campaigns/{id}
Auth
Eliminar una campaña. 
curl -X DELETE https://tu-dominio.com/api/v1/campaigns/2 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
POST /api/v1/campaigns/{id}/send
Auth
Enviar la campaña. Sin body requerido. 
curl -X POST https://tu-dominio.com/api/v1/campaigns/2/send \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Segmentos
Segmentos estaticos o dinamicos de contactos para campañas.
GET /api/v1/segments
Auth
Listar segmentos. Filtro: type (static, dynamic). 
curl "https://tu-dominio.com/api/v1/segments?type=dynamic" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Ver respuesta de ejemplo 
{
  "data": [
    { "id": 1, "name": "Clientes Activos Monterrey", "type": "dynamic", "member_count": 87 }
  ]
}
POST /api/v1/segments
Auth
Crear un segmento con condiciones de filtro.

Body

Campo Tipo Requerido Descripcion
name string Si Nombre del segmento
type string Si static o dynamic
conditions array No Condiciones de filtro para segmentos dinamicos 
curl -X POST https://tu-dominio.com/api/v1/segments \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Leads de Guadalajara",
    "type": "dynamic",
    "conditions": [
      {"field": "lifecycle_stage", "operator": "=", "value": "lead"},
      {"field": "city", "operator": "=", "value": "Guadalajara"}
    ]
  }'
PUT /api/v1/segments/{id}
Auth
Actualizar un segmento. 
curl -X PUT https://tu-dominio.com/api/v1/segments/1 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "name": "Leads de GDL 2025" }'
DELETE /api/v1/segments/{id}
Auth
Eliminar un segmento. 
curl -X DELETE https://tu-dominio.com/api/v1/segments/1 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
GET /api/v1/segments/{id}/contacts
Auth
Obtener contactos que pertenecen a un segmento. Paginado. 
curl "https://tu-dominio.com/api/v1/segments/1/contacts" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Notificaciones
Notificaciones del usuario autenticado.
GET /api/v1/notifications
Auth
Listar notificaciónes. Filtro: unread_only (true/false). 
curl "https://tu-dominio.com/api/v1/notifications?unread_only=true" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Ver respuesta de ejemplo 
{
  "data": [
    {
      "id": 22,
      "type": "deal_won",
      "title": "Negocio ganado",
      "body": "El negocio 'Implementacion ERP' fue marcado como ganado.",
      "url": "/deals/5",
      "read_at": null,
      "created_at": "2025-04-12T15:30:00.000000Z"
    }
  ]
}
POST /api/v1/notifications/{id}/read
Auth
Marcar una notificación como leida. 
curl -X POST https://tu-dominio.com/api/v1/notifications/22/read \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
POST /api/v1/notifications/read-all
Auth
Marcar todas las notificaciónes como leidas. 
curl -X POST https://tu-dominio.com/api/v1/notifications/read-all \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Usuarios
Usuarios del tenant actual. Solo lectura.
GET /api/v1/users
Auth
Listar usuarios del tenant. Filtro: search (nombre o email). 
curl "https://tu-dominio.com/api/v1/users?search=jorge" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Ver respuesta de ejemplo 
{
  "data": [
    {
      "id": 1,
      "name": "Jorge Zamarron",
      "email": "jorge@leadercrm.mx",
      "role": "admin",
      "avatar_url": "https://tu-dominio.com/storage/avatars/1.jpg"
    }
  ]
}
GET /api/v1/users/{id}
Auth
Obtener detalle de un usuario. 
curl https://tu-dominio.com/api/v1/users/1 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Webhooks
Endpoints publicos para formularios externos.
POST /api/forms/{apiKey}/submit
Publica
Enviar un formulario externo. No requiere autenticación, usa API key en la URL. 
curl -X POST https://tu-dominio.com/api/forms/abc123def456/submit \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Carlos",
    "last_name": "Martinez Diaz",
    "email": "cmartinez@miempresa.mx",
    "phone": "+52 33 1234 5678",
    "message": "Me interesa conocer sus servicios de consultoria."
  }'
Ver respuesta de ejemplo 
{
  "success": true,
  "submission_id": 142,
  "contact_id": 89,
  "assigned_to": "Jorge Zamarron"
}
COPOMEX
Consulta de codigos postales de Mexico.
GET /api/copomex/{cp}
Publica
Buscar datos de un codigo postal mexicano (5 digitos). 
curl https://tu-dominio.com/api/copomex/64000
Ver respuesta de ejemplo 
{
  "found": true,
  "municipality": "Monterrey",
  "city": "Monterrey",
  "state": "Nuevo Leon",
  "colonies": ["Centro", "Obispado", "Chepevera"]
}
Guia para AI Agents
Integracion con Claude, GPT, Cursor, Copilot y agentes MCP.

Inicio rapido

  1. Autenticar -- POST a /api/v1/auth/login para obtener un bearer token
  2. Obtener contexto -- GET /api/v1/auth/me para confirmar usuario y tenant
  3. Obtener pipelines -- GET /api/v1/pipelines para conocer las etapas de deals
  4. Comenzar -- Todos los endpoints requieren Authorization: Bearer {token}

MCP Tools disponibles

Tool Descripcion
leader_authenticate Autenticar y obtener bearer token
leader_search_contacts Buscar contactos por nombre, email, etapa
leader_create_contact Crear un nuevo contacto
leader_create_deal Crear un deal/oportunidad
leader_create_quote Crear cotización con items
leader_send_quote Enviar cotización al cliente
leader_create_invoice Crear factura con items
leader_record_payment Registrar pago contra factura
leader_create_activity Crear tarea, llamada, reunion o email
leader_get_pipeline Obtener pipelines y etapas
leader_move_deal_stage Mover deal a otra etapa
leader_get_dashboard_stats Estadisticas del dashboard

Flujos de trabajo comunes

1. Nuevo Lead

Contacto → Deal (con pipeline_id + stage_id) → Actividad de seguimiento

2. Ciclo de Venta Completo

Contacto → Deal → Cotizacion → send → approve → Contrato → sign → Factura → send → Pago

3. Rendimiento del Equipo

Deals ganados + Actividades pendientes + Notificaciones + Distribucion de pipeline

4. Seguimiento Masivo

Listar leads sin actividad → Crear tareas de seguimiento por cada uno

5. Formularios Externos

POST /api/forms/{apiKey}/submit -- sin autenticación, crea contacto automaticamente

Modelo de datos

Tenant (multi-tenant)
  |-- Users (equipo)
  |-- Contacts → Notes, Company, Deals (N:N), Quotes, Invoices, Contracts, Payments
  |-- Companies → Contacts (1:N)
  |-- Pipelines → Stages → Deals
  |-- Deals → Contacts (N:N), Quotes, Invoices, Contracts
  |-- Quotes → Items, Contact, Deal
  |-- Invoices → Items, Payments, Contact, Deal
  |-- Contracts → Contact, Deal, Quote
  |-- Payments → Invoice, Contact
  |-- Products → Images, Category
  |-- Activities (polimorficas: Contact, Deal, Company)
  |-- Events → Attendees
  |-- Campaigns → Segment
  |-- Segments → Contacts (dinamicos/estaticos)
  |-- Notifications (por usuario)

Relaciones clave (que IDs necesitas)

Al crear... Necesitas estos IDs
Contact company_id (opcional), owner_id (opcional)
Deal pipeline_id (requerido), stage_id (requerido), contact_ids (opcional)
Quote / Invoice / Contract contact_id (requerido), deal_id (opcional)
Payment invoice_id (requerido), contact_id (opcional)
Activity activitable_type + activitable_id (opcionales, polimorficos)

Mejores practicas

  • Siempre autenticar primero. Reutilizar el token.
  • Obtener pipelines antes de crear deals (para pipeline_id y stage_id).
  • Buscar antes de crear para evitar duplicados.
  • Usar per_page=100 para operaciónes masivas.
  • Vincular entidades: pasar contact_ids en deals, contact_id en quotes/invoices/contracts.
  • Tipos polimorficos con namespace completo: App\Models\Contact, no solo Contact.
  • Los IDs son integers excepto activitable_id que se envia como string.
  • Fechas en ISO 8601: YYYY-MM-DD o 2025-04-15T10:00:00Z.