Clientes

El recurso de clientes representa a las personas y empresas a las que tu cuenta factura y vende. Es el recurso central al que se vinculan la cuenta corriente, las tareas de CRM y los puntos de beneficios.

Endpoint base: /api/v1/customers

Scopes: customers:read, customers:write

Campos

Endpoints

Ejemplo — Petición

Crear un cliente con POST /api/v1/customers/:

{
  "name": "Distribuidora del Sur S.A.",
  "email": "[email protected]",
  "phone": "+54 11 4567-8900",
  "document_type": "cuit",
  "document_number": "30712345678",
  "address": "Av. Siempre Viva 742, CABA",
  "status": "active",
  "tags": ["mayorista", "preferencial"]
}

Ejemplo — Respuesta

{
  "success": true,
  "data": {
    "_id": "66f1a2b3c4d5e6f7a8b9c0d1",
    "name": "Distribuidora del Sur S.A.",
    "email": "[email protected]",
    "phone": "+54 11 4567-8900",
    "document_type": "cuit",
    "document_number": "30712345678",
    "address": "Av. Siempre Viva 742, CABA",
    "status": "active",
    "tags": ["mayorista", "preferencial"],
    "creation_date": "2026-05-21T14:30:00Z"
  }
}

La cuenta corriente lleva el saldo de un cliente o proveedor: registra los comprobantes como débitos y los pagos como créditos, y permite definir un límite de crédito y un plazo de pago. Cada cuenta está asociada a una entidad (cliente o proveedor).

Endpoint base: /api/v1/current-accounts

Scopes: current_accounts:read, current_accounts:write

Campos del body de creación de una cuenta corriente (POST /api/v1/current-accounts/):

Campos

Endpoints

La cuenta corriente usa un controller propio, no el factory CRUD: no expone endpoints /bulk/*. Estos son sus endpoints principales:

Ejemplo — Petición

Crear una cuenta corriente para un cliente con POST /api/v1/current-accounts/:

{
  "entity_type": "customer",
  "entity_id": "66f1a2b3c4d5e6f7a8b9c0d1",
  "entity_name": "Distribuidora del Sur S.A.",
  "credit_limit": 200000,
  "payment_terms_days": 30
}

Ejemplo — Respuesta

{
  "success": true,
  "data": {
    "_id": "67a0b1c2d3e4f5a6b7c8d9e0",
    "entity_type": "customer",
    "entity_id": "66f1a2b3c4d5e6f7a8b9c0d1",
    "entity_name": "Distribuidora del Sur S.A.",
    "credit_limit": 200000,
    "payment_terms_days": 30,
    "balance": 0,
    "creation_date": "2026-05-21T14:35:00Z"
  }
}

Para registrar un pago sobre una cuenta usá POST /api/v1/current-accounts/{id}/payments/:

{
  "amount": 50000,
  "payment_method": "credit_card",
  "reference": "TRANS-123",
  "payment_date": "2026-05-21T10:00:00",
  "auto_apply": false
}

Las tareas de CRM son acciones de seguimiento comercial (llamadas, reuniones, recordatorios) que pueden vincularse a un cliente y asignarse a un usuario.

Campos — Tareas

Endpoints adicionales: POST /api/v1/crm-tasks/{id}/complete/ (marcar completada), GET /api/v1/crm-tasks/by-customer/{customer_id}/ (tareas de un cliente).

Ejemplo — Petición POST /api/v1/crm-tasks/:

{
  "title": "Llamar para renovar contrato",
  "description": "Contacto anual de seguimiento comercial",
  "customer_id": "66f1a2b3c4d5e6f7a8b9c0d1",
  "due_date": "2026-06-01T09:00:00Z",
  "status": "pending",
  "priority": "high",
  "tags": ["seguimiento"]
}

Ejemplo — Respuesta

{
  "success": true,
  "data": {
    "_id": "67b1c2d3e4f5a6b7c8d9e0f1",
    "title": "Llamar para renovar contrato",
    "customer_id": "66f1a2b3c4d5e6f7a8b9c0d1",
    "due_date": "2026-06-01T09:00:00Z",
    "status": "pending",
    "priority": "high",
    "creation_date": "2026-05-21T14:40:00Z"
  }
}

Un pipeline define el embudo de ventas: un conjunto ordenado de etapas por las que avanzan las oportunidades. Cada cuenta puede tener uno o varios pipelines.

Campos — Pipelines

Una oportunidad representa una venta potencial dentro de un pipeline. Avanza por las etapas del pipeline y puede vincularse a un cliente, con un monto y una probabilidad de cierre.

Campos — Oportunidades

Endpoints adicionales: GET /api/v1/crm-opportunities/board/{pipeline_id}/ (vista tablero), POST /api/v1/crm-opportunities/{id}/move/ (mover de etapa), GET /api/v1/crm-opportunities/by-customer/{customer_id}/.

Un segmento agrupa clientes según reglas de filtrado. Puede ser dinámico (se recalcula a partir de las reglas) o estático (lista fija de clientes).

Campos — Segmentos

Endpoints adicionales: GET /api/v1/crm-segments/metadata/ (campos y operadores disponibles para las reglas), GET /api/v1/crm-segments/{id}/customers/ (clientes del segmento).

Los recordatorios programan un aviso sobre un cliente para una fecha y hora determinadas, con envío por uno o varios canales.

Campos — Recordatorios

Endpoints adicionales: GET /api/v1/crm-reminders/by-customer/{customer_id}/, POST /api/v1/crm-reminders/{id}/cancel/ (cancelar recordatorio).

Las comunicaciones registran los mensajes intercambiados con un cliente (email, SMS, WhatsApp, etc.), tanto salientes como entrantes, y conforman su historial de contacto.

Campos — Comunicaciones

Endpoints adicionales: GET /api/v1/crm-communications/by-customer/{customer_id}/, POST /api/v1/crm-communications/send-template/ (enviar una comunicación a partir de una plantilla).

Las plantillas son mensajes reutilizables con variables del tipo {{nombre}} que se completan al enviar una comunicación a un cliente.

Campos — Plantillas

Endpoint adicional: POST /api/v1/crm-templates/{id}/render/ (renderizar la plantilla reemplazando las variables).

El recurso de recompensas gestiona el catálogo de beneficios del programa de fidelización: descuentos, productos gratis, cashback y vouchers que los clientes pueden canjear con los puntos acumulados.

Endpoint base: /api/v1/rewards

Scopes: benefits:read, benefits:write

Campos

Endpoints

Endpoints adicionales: GET /api/v1/rewards/redemptions/ (historial de canjes), POST /api/v1/rewards/redeem/ (canjear una recompensa).

Ejemplo — Petición

Crear una recompensa con POST /api/v1/rewards/:

{
  "name": "10% de descuento en tu próxima compra",
  "reward_type": "discount_percentage",
  "points_cost": 500,
  "value_percentage": 10,
  "stock": 100,
  "active": true,
  "featured": true
}

Ejemplo — Respuesta

{
  "success": true,
  "data": {
    "_id": "67c2d3e4f5a6b7c8d9e0f1a2",
    "name": "10% de descuento en tu próxima compra",
    "reward_type": "discount_percentage",
    "points_cost": 500,
    "value_percentage": 10,
    "stock": 100,
    "active": true,
    "featured": true,
    "creation_date": "2026-05-21T14:45:00Z"
  }
}