Endpoints

URL base: https://api.zelta.dev/crm/v1

Todos los endpoints requieren autenticacion mediante token Bearer. Consulta la para obtener tu token.

Contactos

Listar contactos

http

GET /contacts

Parametros de consulta:

Parametro	Tipo	Descripcion
`page`	integer	Numero de pagina (default: 1)
`per_page`	integer	Resultados por pagina (default: 25, max: 100)
`search`	string	Buscar por nombre, email o telefono
`tag`	string	Filtrar por etiqueta
`segment_id`	string	Filtrar por segmento
`vertical`	string	Filtrar por vertical: `automotive`, `real_estate`, `education`, `services`
`sort_by`	string	Campo de ordenamiento: `created_at`, `name`, `updated_at`
`sort_dir`	string	Direccion: `asc` o `desc`

Ejemplo:

bash

curl -X GET "https://api.zelta.dev/crm/v1/contacts?page=1&per_page=10&tag=VIP&vertical=automotive" \
  -H "Authorization: Bearer {token}"

Respuesta:

json

{
  "data": [
    {
      "id": "cont_abc123",
      "name": "Maria Garcia",
      "email": "maria@empresa.com",
      "phone": "+52 55 1234 5678",
      "company": "Acme Corp",
      "vertical": "automotive",
      "tags": ["VIP", "Financiamiento aprobado"],
      "custom_fields": {
        "vehiculo_interes": "SUV Premium 2026",
        "tipo_compra": "financiamiento",
        "presupuesto": 850000
      },
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-03-01T14:22:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 48
  }
}

Scope requerido: crm:read

Crear contacto

http

POST /contacts

Cuerpo de la peticion:

json

{
  "name": "Carlos Lopez",
  "email": "carlos@ejemplo.com",
  "phone": "+52 55 9876 5432",
  "company": "Tech Solutions",
  "position": "Director Comercial",
  "tags": ["Lead caliente"],
  "vertical": "services",
  "custom_fields": {
    "industria": "Tecnologia",
    "presupuesto_anual": 500000,
    "tipo_servicio": "Consultoria IT"
  }
}

Scope requerido: crm:write

Obtener contacto

http

GET /contacts/{contact_id}

Actualizar contacto

http

PATCH /contacts/{contact_id}

Eliminar contacto

http

DELETE /contacts/{contact_id}

Scope requerido: crm:delete

Atencion

Eliminar un contacto tambien elimina todas sus actividades, notas y negocios asociados. Esta accion no se puede deshacer.

Importar contactos

http

POST /contacts/import

Cuerpo (multipart/form-data):

Campo	Tipo	Requerido	Descripcion
`file`	file	Si	Archivo CSV, XLSX o JSON
`duplicate_strategy`	string	No	`skip`, `update` o `create` (default: `skip`)
`vertical`	string	No	Vertical para mapeo automatico de campos

Scope requerido: crm:write

Negocios (Deals)

Listar negocios

http

GET /deals

Parametros de consulta:

Parametro	Tipo	Descripcion
`page`	integer	Numero de pagina (default: 1)
`per_page`	integer	Resultados por pagina (default: 25, max: 100)
`pipeline_id`	string	Filtrar por pipeline
`stage_id`	string	Filtrar por etapa
`owner_id`	string	Filtrar por propietario
`status`	string	`open`, `won`, `lost`
`min_value`	number	Valor minimo del negocio
`max_value`	number	Valor maximo del negocio
`vertical`	string	Filtrar por vertical

Crear negocio

http

POST /deals

Cuerpo de la peticion:

json

{
  "name": "Venta SUV Premium - Maria Garcia",
  "contact_id": "cont_abc123",
  "pipeline_id": "pipe_auto01",
  "stage_id": "stage_001",
  "value": 850000,
  "currency": "MXN",
  "expected_close_date": "2026-04-30",
  "owner_id": "user_vendedor01",
  "custom_fields": {
    "vehiculo": "SUV Premium 2026",
    "color": "Negro",
    "tipo_compra": "financiamiento",
    "enganche": 170000
  }
}

Scope requerido: crm:write

Obtener negocio

http

GET /deals/{deal_id}

Respuesta:

json

{
  "id": "deal_def456",
  "name": "Venta SUV Premium - Maria Garcia",
  "contact": {
    "id": "cont_abc123",
    "name": "Maria Garcia",
    "email": "maria@empresa.com"
  },
  "pipeline": {
    "id": "pipe_auto01",
    "name": "Ventas de vehiculos"
  },
  "stage": {
    "id": "stage_004",
    "name": "Prueba completada",
    "probability": 60
  },
  "value": 850000,
  "weighted_value": 510000,
  "currency": "MXN",
  "status": "open",
  "expected_close_date": "2026-04-30",
  "days_in_stage": 3,
  "total_days": 21,
  "owner": {
    "id": "user_vendedor01",
    "name": "Roberto Martinez"
  },
  "custom_fields": {
    "vehiculo": "SUV Premium 2026",
    "color": "Negro",
    "tipo_compra": "financiamiento",
    "enganche": 170000
  },
  "activities_count": 8,
  "created_at": "2026-02-18T09:00:00Z",
  "updated_at": "2026-03-11T11:45:00Z"
}

Actualizar negocio

http

PATCH /deals/{deal_id}

Mover de etapa

http

POST /deals/{deal_id}/move

json

{
  "stage_id": "stage_005",
  "reason": "Cliente acepto la cotizacion, procede a financiamiento"
}

Marcar como ganado

http

POST /deals/{deal_id}/won

json

{
  "final_value": 835000,
  "reason": "Cierre con descuento del 2%",
  "notes": "Entrega programada para el 15 de abril"
}

Marcar como perdido

http

POST /deals/{deal_id}/lost

json

{
  "reason": "Precio fuera de presupuesto",
  "competitor": "Agencia XYZ",
  "notes": "Cliente encontro mejor precio en la competencia"
}

Scope requerido: crm:write

Pipelines

Listar pipelines

http

GET /pipelines

Obtener pipeline con etapas

http

GET /pipelines/{pipeline_id}

Respuesta:

json

{
  "id": "pipe_auto01",
  "name": "Ventas de vehiculos",
  "vertical": "automotive",
  "stages": [
    {
      "id": "stage_001",
      "name": "Prospecto nuevo",
      "probability": 10,
      "position": 1,
      "deals_count": 12,
      "total_value": 9600000
    },
    {
      "id": "stage_002",
      "name": "Contacto realizado",
      "probability": 20,
      "position": 2,
      "deals_count": 8,
      "total_value": 6400000
    }
  ],
  "total_deals": 45,
  "total_value": 38000000,
  "weighted_value": 15200000
}

Crear pipeline

http

POST /pipelines

Cuerpo de la peticion:

json

{
  "name": "Ventas seminuevos",
  "vertical": "automotive",
  "stages": [
    { "name": "Lead nuevo", "probability": 10 },
    { "name": "Vehiculo seleccionado", "probability": 30 },
    { "name": "Prueba completada", "probability": 60 },
    { "name": "Oferta aceptada", "probability": 85 },
    { "name": "Cierre ganado", "probability": 100 },
    { "name": "Cierre perdido", "probability": 0 }
  ]
}

Scope requerido: crm:admin

Actualizar pipeline

http

PATCH /pipelines/{pipeline_id}

Eliminar pipeline

http

DELETE /pipelines/{pipeline_id}

Scope requerido: crm:admin

Automatizaciones

Listar automatizaciones

http

GET /automations

Parametros de consulta:

Parametro	Tipo	Descripcion
`active`	boolean	Solo automatizaciones activas
`type`	string	`workflow`, `sequence`

Obtener automatizacion

http

GET /automations/{automation_id}

Crear automatizacion

http

POST /automations

Cuerpo de la peticion:

json

{
  "name": "Asignar leads automotrices de alto valor",
  "active": true,
  "trigger": {
    "event": "deal.created",
    "conditions": [
      { "field": "value", "operator": "greater_than", "value": 500000 },
      { "field": "vertical", "operator": "equals", "value": "automotive" }
    ]
  },
  "actions": [
    {
      "type": "assign_owner",
      "config": {
        "strategy": "round_robin",
        "team_id": "team_senior"
      }
    },
    {
      "type": "send_email",
      "config": {
        "template_id": "tpl_bienvenida_vip",
        "to": "{{contact.email}}"
      }
    },
    {
      "type": "create_task",
      "config": {
        "title": "Llamar al prospecto VIP",
        "due_in_hours": 2,
        "assign_to": "{{deal.owner}}"
      }
    }
  ]
}

Scope requerido: crm:automations

Activar/desactivar automatizacion

http

PATCH /automations/{automation_id}

json

{
  "active": false
}

Historial de ejecuciones

http

GET /automations/{automation_id}/executions

Respuesta:

json

{
  "data": [
    {
      "id": "exec_001",
      "automation_id": "auto_abc123",
      "status": "success",
      "trigger_event": "deal.created",
      "trigger_data": {
        "deal_id": "deal_def456",
        "deal_name": "Venta SUV Premium"
      },
      "actions_executed": 3,
      "duration_ms": 245,
      "executed_at": "2026-03-11T14:30:00Z"
    }
  ]
}

Eliminar automatizacion

http

DELETE /automations/{automation_id}

Actividades

Listar actividades

http

GET /activities

Parametros de consulta:

Parametro	Tipo	Descripcion
`contact_id`	string	Filtrar por contacto
`deal_id`	string	Filtrar por negocio
`type`	string	`email`, `call`, `meeting`, `task`, `note`
`from`	date	Fecha de inicio (ISO 8601)
`to`	date	Fecha de fin (ISO 8601)

Crear actividad

http

POST /activities

json

{
  "type": "call",
  "contact_id": "cont_abc123",
  "deal_id": "deal_def456",
  "subject": "Llamada de seguimiento post-prueba de manejo",
  "description": "Cliente interesado en financiamiento a 48 meses. Enviar opciones de credito.",
  "duration_minutes": 15,
  "completed": true
}

Scope requerido: crm:write

Obtener actividad

http

GET /activities/{activity_id}

Actualizar actividad

http

PATCH /activities/{activity_id}

Reportes

Resumen del pipeline

http

GET /reports/pipeline

Parametros de consulta:

Parametro	Tipo	Descripcion
`pipeline_id`	string	ID del pipeline (requerido)
`from`	date	Fecha de inicio del periodo
`to`	date	Fecha de fin del periodo
`group_by`	string	`stage`, `owner`, `vertical`, `month`

Ejemplo:

bash

curl -X GET "https://api.zelta.dev/crm/v1/reports/pipeline?pipeline_id=pipe_auto01&from=2026-01-01&to=2026-03-11&group_by=stage" \
  -H "Authorization: Bearer {token}"

Respuesta:

json

{
  "pipeline": {
    "id": "pipe_auto01",
    "name": "Ventas de vehiculos"
  },
  "period": {
    "from": "2026-01-01",
    "to": "2026-03-11"
  },
  "summary": {
    "total_deals": 120,
    "total_value": 96000000,
    "won_deals": 35,
    "won_value": 28000000,
    "lost_deals": 22,
    "conversion_rate": 29.2,
    "average_deal_value": 800000,
    "average_days_to_close": 28
  },
  "by_stage": [
    {
      "stage": "Prospecto nuevo",
      "deals_count": 25,
      "total_value": 20000000,
      "avg_days": 4
    }
  ]
}

Scope requerido: crm:reports

Rendimiento del equipo

http

GET /reports/team

Parametros de consulta:

Parametro	Tipo	Descripcion
`from`	date	Fecha de inicio
`to`	date	Fecha de fin
`pipeline_id`	string	Filtrar por pipeline

Pronostico de ingresos

http

GET /reports/forecast

Parametros de consulta:

Parametro	Tipo	Descripcion
`pipeline_id`	string	ID del pipeline
`period`	string	`monthly`, `quarterly`, `yearly`
`type`	string	`weighted`, `best_case`, `committed`

Webhooks

Listar webhooks

http

GET /webhooks

Crear webhook

http

POST /webhooks

json

{
  "url": "https://mi-sistema.com/webhook/zelta-crm",
  "events": ["deal.won", "deal.lost", "contact.created"],
  "secret": "mi_secreto_seguro",
  "active": true
}

Scope requerido: crm:admin

Eliminar webhook

http

DELETE /webhooks/{webhook_id}

Codigos de respuesta

Codigo	Descripcion
`200`	Solicitud exitosa
`201`	Recurso creado exitosamente
`204`	Recurso eliminado exitosamente
`400`	Solicitud mal formada
`401`	No autenticado
`403`	Sin permisos suficientes
`404`	Recurso no encontrado
`409`	Conflicto (ej: duplicado detectado)
`422`	Error de validacion
`429`	Limite de tasa excedido
`500`	Error interno del servidor

Paginacion

Todos los endpoints de listado soportan paginacion. Usa los campos meta.current_page y meta.total_pages de la respuesta para navegar entre paginas. El maximo de resultados por pagina es 100.

Endpoints ​

Contactos ​

Listar contactos ​

Crear contacto ​

Obtener contacto ​

Actualizar contacto ​

Eliminar contacto ​

Importar contactos ​

Negocios (Deals) ​

Listar negocios ​

Crear negocio ​

Obtener negocio ​

Actualizar negocio ​

Mover de etapa ​

Marcar como ganado ​

Marcar como perdido ​

Pipelines ​

Listar pipelines ​

Obtener pipeline con etapas ​

Crear pipeline ​

Actualizar pipeline ​

Eliminar pipeline ​

Automatizaciones ​

Listar automatizaciones ​

Obtener automatizacion ​

Crear automatizacion ​

Activar/desactivar automatizacion ​

Historial de ejecuciones ​

Eliminar automatizacion ​

Actividades ​

Listar actividades ​

Crear actividad ​

Obtener actividad ​

Actualizar actividad ​

Reportes ​

Resumen del pipeline ​

Rendimiento del equipo ​

Pronostico de ingresos ​

Webhooks ​

Listar webhooks ​

Crear webhook ​

Eliminar webhook ​

Codigos de respuesta ​

Endpoints

Contactos

Listar contactos

Crear contacto

Obtener contacto

Actualizar contacto

Eliminar contacto

Importar contactos

Negocios (Deals)

Listar negocios

Crear negocio

Obtener negocio

Actualizar negocio

Mover de etapa

Marcar como ganado

Marcar como perdido

Pipelines

Listar pipelines

Obtener pipeline con etapas

Crear pipeline

Actualizar pipeline

Eliminar pipeline

Automatizaciones

Listar automatizaciones

Obtener automatizacion

Crear automatizacion

Activar/desactivar automatizacion

Historial de ejecuciones

Eliminar automatizacion

Actividades

Listar actividades

Crear actividad

Obtener actividad

Actualizar actividad

Reportes

Resumen del pipeline

Rendimiento del equipo

Pronostico de ingresos

Webhooks

Listar webhooks

Crear webhook

Eliminar webhook

Codigos de respuesta