API REST de Mindy POS

Cómo comenzar

1. Genera tu API Key

   Ve a Ajustes › API en el panel de Mindy y crea una nueva key. Se muestra una sola vez — guárdala. Formato: mk_live_xxxxxxxx.

2. Configura los permisos

   Al crear la key elige los scopes necesarios y el límite de requests por minuto (30 – 300).

3. Haz tu primera petición

   curl -X GET "https://app.mindy.gt/api/v1/products?per_page=1" \
     -H "Authorization: Bearer mk_live_tu_api_key"

4. Verifica la respuesta

   {
     "success": true,
     "data": [ ... ],
     "meta": { "page": 1, "per_page": 1, "total": 150, "total_pages": 150 }
   }

Inicio rápido

Reemplaza mk_live_tu_api_key con tu key real.

curl -X GET "https://app.mindy.gt/api/v1/products?per_page=5" \
  -H "Authorization: Bearer mk_live_tu_api_key"

const res = await fetch(
  "https://app.mindy.gt/api/v1/products?per_page=5",
  { headers: { Authorization: "Bearer mk_live_tu_api_key" } }
);
const data = await res.json();

import requests
r = requests.get(
    "https://app.mindy.gt/api/v1/products",
    params={"per_page": 5},
    headers={"Authorization": "Bearer mk_live_tu_api_key"}
)
print(r.json())

$ch = curl_init("https://app.mindy.gt/api/v1/products?per_page=5");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer mk_live_tu_api_key"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);

{
  "success": true,
  "data": [
    { "id": 42, "name": "Laptop HP 15", "sale_price": 4500.00,
      "category_id": 5, "is_active": true, "has_variants": false }
  ],
  "meta": { "page": 1, "per_page": 5, "total": 150, "total_pages": 30 }
}

Autenticación

Incluye tu API Key en el header Authorization de cada petición:

Authorization: Bearer mk_live_tu_api_key

Scopes disponibles

Errores

Todas las respuestas de error tienen esta estructura:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Producto no encontrado",
    "status": 404
  }
}

Rate Limiting

Límite configurable por API Key: 30, 60, 120 o 300 req/min. Cada respuesta incluye:

Al exceder el límite recibirás un 429. Espera al reinicio antes de reintentar.

Paginación

{
  "success": true,
  "data": [...],
  "meta": { "page": 1, "per_page": 20, "total": 150, "total_pages": 8 }
}

Mi cuenta

Útil para introspección y debugging: muestra los scopes, el límite y el comercio asociado a la key.

{
  "success": true,
  "data": {
    "key_prefix": "mk_live_a1b2",
    "name": "Tienda online",
    "commerce_id": 42,
    "commerce_name": "Mi Negocio GT",
    "scopes": ["catalog:read", "sales:read", "products:write"],
    "rate_limit": 60,
    "is_active": true,
    "last_used_at": "2026-06-03 14:22:11",
    "expires_at": null,
    "created_at": "2026-05-10 09:00:00"
  }
}

Productos

curl "https://app.mindy.gt/api/v1/products?per_page=5&include=stock" \
  -H "Authorization: Bearer mk_live_tu_api_key"

const res = await fetch(
  "https://app.mindy.gt/api/v1/products?per_page=5&include=stock",
  { headers: { Authorization: "Bearer mk_live_tu_api_key" } }
);
const { data, meta } = await res.json();

import requests
r = requests.get(
    "https://app.mindy.gt/api/v1/products",
    params={"per_page": 5, "include": "stock"},
    headers={"Authorization": "Bearer mk_live_tu_api_key"}
)
print(r.json())

$ch = curl_init(
  "https://app.mindy.gt/api/v1/products?per_page=5&include=stock"
);
curl_setopt($ch, CURLOPT_HTTPHEADER,
  ["Authorization: Bearer mk_live_tu_api_key"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);

{
  "id": 5821,
  "type": "-",
  "quantity": 3.0,
  "description": "Por venta API. R#000142",
  "date": "2026-06-01 10:35:00",
  "branch_id": 1,
  "branch_name": "Sucursal Central"
}

curl -X POST "https://app.mindy.gt/api/v1/products" \
  -H "Authorization: Bearer mk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Camiseta Polo",
    "sale_price": 150.00,
    "barcode": "7501234567890",
    "category_id": 3
  }'

const res = await fetch(
  "https://app.mindy.gt/api/v1/products",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer mk_live_tu_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Camiseta Polo",
      sale_price: 150.00,
      barcode: "7501234567890",
      category_id: 3,
    }),
  }
);
const product = await res.json();

import requests
r = requests.post(
    "https://app.mindy.gt/api/v1/products",
    headers={"Authorization": "Bearer mk_live_tu_api_key"},
    json={
        "name": "Camiseta Polo",
        "sale_price": 150.00,
        "barcode": "7501234567890",
        "category_id": 3,
    }
)
print(r.json())  # 201 Created

$ch = curl_init("https://app.mindy.gt/api/v1/products");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer mk_live_tu_api_key",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "name" => "Camiseta Polo",
    "sale_price" => 150.00,
    "barcode" => "7501234567890",
    "category_id" => 3,
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);
$res = json_decode(curl_exec($ch), true);

// 201 Created
{
  "success": true,
  "data": {
    "id": 55, "name": "Camiseta Polo", "sale_price": 150.00,
    "barcode": "7501234567890", "category_id": 3,
    "is_active": true, "has_variants": false,
    "stock": [{ "branch_id": 1, "branch_name": "Central", "quantity": 0 }]
  }
}

Cada item se procesa de forma independiente; un error en uno no cancela los demás. Modos: create (falla por item si el barcode existe) o upsert (actualiza si existe, crea si no).

{
  "mode": "upsert",
  "products": [
    {
      "name": "Agua 500ml",
      "sale_price": 3.50,
      "purchase_price": 1.80,
      "barcode": "7501234567890",
      "sku": "AGU-500",
      "category_id": 5,
      "min_stock": 10
    }
  ]
}

{
  "success": true,
  "data": {
    "mode": "upsert",
    "processed": 3, "succeeded": 3, "failed": 0,
    "results": [
      { "index": 0, "success": true,  "id": 201, "name": "Agua 500ml",   "action": "created" },
      { "index": 1, "success": true,  "id": 88,  "name": "Coca-Cola 1L", "action": "updated" },
      { "index": 2, "success": false, "error": "sale_price es requerido y debe ser > 0" }
    ]
  }
}

{ "success": true, "data": { "id": 88, "deleted": true } }

Stock

{
  "success": true,
  "data": [{
    "product_id": 1,
    "stock": [{ "branch_id": 1, "branch_name": "Central", "quantity": 25 }],
    "total_stock": 25, "low_stock": false, "minimum_stock": 5
  }]
}

Cantidad positiva = entrada, negativa = salida. Valida que no quede stock negativo. Dispara stock.adjusted.

{
  "product_id": 88,
  "branch_id": 1,
  "quantity": -5,
  "reason": "Merma por daño en almacén"
}

{
  "success": true,
  "data": {
    "product_id": 88, "product_name": "Coca-Cola 1L",
    "branch_id": 1, "adjustment": -5,
    "new_stock": 45.0, "adjusted_at": "2026-06-03 11:00:00"
  }
}

Categorías

Paquetes

{
  "id": 10, "name": "Combo Almuerzo", "sale_price": 45.00,
  "components": [
    { "product_id": 20, "product_name": "Hamburguesa", "quantity": 1 },
    { "product_id": 31, "product_name": "Papas fritas", "quantity": 1 }
  ]
}

Sucursales

{
  "id": 1, "name": "Sucursal Central",
  "address": "6ta Avenida 10-20, Zona 1",
  "phone": "22334455", "email": "central@negocio.gt", "is_default": true
}

Proveedores

{
  "id": 7, "name": "Distribuidora XYZ",
  "address": "7a Av. 15-30, Guatemala",
  "email": "ventas@xyz.gt", "phone": "24441234",
  "phone_2": null, "nit": "12345678", "is_active": true
}

Marcas y Unidades

{ "id": 3, "name": "Coca-Cola", "is_active": true }

{ "id": 2, "name": "Litro", "is_active": true }

[
  { "id": 12, "name": "Servicios básicos", "is_active": true },
  { "id": 13, "name": "Transporte", "is_active": true }
]

Clientes

{
  "success": true,
  "data": {
    "client_id": 55,
    "total_credit": 850.00, "total_paid": 500.00, "total_balance": 350.00,
    "credits": [
      { "id": 14, "sale_id": 3021, "amount": 500.00, "paid": 500.00,
        "balance": 0.00, "expires_at": "2026-07-01", "is_paid": true },
      { "id": 18, "sale_id": 3105, "amount": 350.00, "paid": 0.00,
        "balance": 350.00, "expires_at": "2026-08-15", "is_paid": false }
    ]
  }
}

{ "name": "María López", "phone": "55001234", "nit": "123456-7" }

// 201 Created
{
  "success": true,
  "data": {
    "id": 100, "name": "María López", "nit": "123456-7",
    "phone": "55001234", "is_active": true,
    "has_credit": false, "credit_limit": 0
  }
}

Recordatorios

{
  "start_date": "2026-06-10 10:00:00",
  "end_date": "2026-06-10 11:00:00",
  "description": "Cita de seguimiento",
  "branch_id": 1,
  "client_id": 55,
  "category_id": 3
}

Ventas

{
  "id": 3105, "sale_number": "3105",
  "date": "2026-06-03 10:12:00",
  "payment_method": "Efectivo", "document_type": "VEN",
  "invoice_number": null,
  "total": 125.50, "total_discount": 0.00,
  "total_profit": 45.20, "total_cost": 80.30,
  "status": 1,
  "client_id": 55, "client_name": "Juan Pérez",
  "branch_id": 1, "branch_name": "Sucursal Central",
  "credit_amount": 0.00, "paid_amount": 0.00
}

{
  "...campos de la venta...",
  "items": [
    {
      "id": 9021, "product_id": 88, "product_name": "Coca-Cola 1L",
      "quantity": 2.0, "unit_price": 12.00, "cost_price": 7.50,
      "discount": 0.00, "line_total": 24.00
    }
  ]
}

Descuenta stock automáticamente. payment_method: efectivo, tarjeta o transferencia.

curl -X POST "https://app.mindy.gt/api/v1/sales" \
  -H "Authorization: Bearer mk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "branch_id": 1,
    "payment_method": "efectivo",
    "client_id": 55,
    "items": [
      { "product_id": 88, "quantity": 2, "unit_price": 12.00 }
    ]
  }'

const res = await fetch(
  "https://app.mindy.gt/api/v1/sales",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer mk_live_tu_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      branch_id: 1,
      payment_method: "efectivo",
      client_id: 55,
      items: [{ product_id: 88, quantity: 2, unit_price: 12.00 }],
    }),
  }
);
const sale = await res.json();  // 201 Created

import requests
r = requests.post(
    "https://app.mindy.gt/api/v1/sales",
    headers={"Authorization": "Bearer mk_live_tu_api_key"},
    json={
        "branch_id": 1,
        "payment_method": "efectivo",
        "client_id": 55,
        "items": [{"product_id": 88, "quantity": 2, "unit_price": 12.00}],
    }
)
print(r.status_code, r.json())

$ch = curl_init("https://app.mindy.gt/api/v1/sales");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer mk_live_tu_api_key",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "branch_id" => 1,
    "payment_method" => "efectivo",
    "items" => [
      ["product_id" => 88, "quantity" => 2, "unit_price" => 12.00],
    ],
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);
$res = json_decode(curl_exec($ch), true);

Sin body. Dispara sale.canceled. Devuelve 409 si ya está anulada.

{
  "success": true,
  "data": {
    "id": 3105, "sale_number": "3105",
    "status": "canceled", "canceled_at": "2026-06-03 15:00:00"
  }
}

Egresos

Filtros: date_from, date_to, branch_id, type.

{
  "id": 210, "description": "Pago de energía eléctrica",
  "date": "2026-06-01 09:00:00", "type": "Gasto",
  "amount": 350.00, "reference": "Factura #4521", "notes": "",
  "category_id": 12, "branch_id": 1, "branch_name": "Sucursal Central"
}

date, type, reference, notes y category_id son opcionales.

{
  "description": "Pago de energía eléctrica",
  "amount": 350.00,
  "branch_id": 1,
  "type": "Gasto",
  "reference": "Factura #4521",
  "category_id": 12
}

Reportes

Ventas, costos, utilidad, egresos, resultado neto y desglose por día y método de pago. Filtros: date_from, date_to, branch_id (default: hoy).

{
  "success": true,
  "data": {
    "period": { "from": "2026-06-01", "to": "2026-06-03" },
    "sales": {
      "count": 87, "revenue": 12450.00, "cost": 7200.00,
      "profit": 5250.00, "discounts": 125.00
    },
    "expenses": { "count": 5, "total": 1800.00 },
    "net_result": 10650.00,
    "by_payment_method": [
      { "payment_method": "Efectivo", "count": 60, "total": 8200.00 },
      { "payment_method": "Tarjeta de crédito / débito", "count": 27, "total": 4250.00 }
    ],
    "by_day": [
      { "date": "2026-06-01", "count": 30, "total": 4100.00 },
      { "date": "2026-06-02", "count": 28, "total": 3900.00 }
    ]
  }
}

Cierres de Caja

Filtros: branch_id, date_from, date_to.

{
  "id": 88,
  "opened_at": "2026-06-03 08:00:00",
  "closed_at": "2026-06-03 20:00:00",
  "opening_amount": 500.00, "cash_withdrawal": 200.00,
  "cash_counted": 4350.00, "cash_calculated": 4350.00,
  "cash_difference": 0.00, "is_closed": true,
  "notes": "Cierre sin novedad",
  "opened_by_id": 4, "opened_by_name": "María García",
  "closed_by_id": 4, "closed_by_name": "María García",
  "branch_id": 1, "branch_name": "Sucursal Central",
  "cash_register_id": 2
}

{
  "...campos del cierre...",
  "sales_summary": { "count": 47, "total": 5800.00 }
}

Webhooks

Recibe eventos en tiempo real en tu propia URL. Requiere scope webhooks:manage. Máximo 10 webhooks por comercio.

{
  "id": 3,
  "url": "https://mi-sistema.com/webhook",
  "events": ["sale.created", "client.created"],
  "description": "Sync con ERP",
  "is_active": true, "fail_streak": 0, "disabled_at": null,
  "created_at": "2026-05-01 09:00:00", "updated_at": null
}

{
  "url": "https://mi-sistema.com/webhook",
  "events": ["sale.created", "product.updated"],
  "description": "Sync con ERP",
  "is_active": true
}

// 201 Created — el secret se muestra UNA sola vez
{
  "success": true,
  "data": {
    "id": 3,
    "url": "https://mi-sistema.com/webhook",
    "events": ["sale.created", "product.updated"],
    "secret": "a1b2c3d4e5f6...",
    "is_active": true
  }
}

Eventos disponibles

Verificación de firma

Cada POST a tu URL incluye este header. Calcula HMAC-SHA256(secret, body_raw) y compara con tiempo constante para evitar timing attacks.

X-Mindy-Signature: sha256=<hmac-sha256(secret, body)>

Empleados

Lista de empleados con su rol. No incluye contraseñas ni datos biométricos. Filtros: search, active_only.

{
  "id": 4, "name": "María García",
  "email": "maria@minegocio.gt", "phone": "50001234",
  "photo_url": "https://cdn.mindy.gt/...",
  "role_id": 2, "role_name": "Cajero",
  "is_active": true,
  "created_at": "2025-01-10 08:00:00",
  "last_login_at": "2026-06-03 07:45:00"
}

Suscripciones

Consulta las suscripciones recurrentes de tus clientes, sus cargos generados y los planes disponibles. Solo lectura.

CRM — Leads

Cubre WhatsApp, Messenger, Instagram, Telegram, Email y Mindy Chat. Lectura con crm:read, escritura con crm:write.

{
  "id": 123, "phone": "50212345678", "contact_name": "Juan",
  "channel_label": "WhatsApp Ventas",
  "funnel_id": 1, "pipeline_state": "qualified",
  "archived_status": "none", "assigned_user_id": 45,
  "last_message_at": "2026-05-19 14:32:00",
  "tags": [{ "id": 2, "label": "VIP", "color": "#7c3aed" }],
  "created_at": "2026-05-01 09:00:00"
}

Solo phone es requerido. Devuelve 409 si ya existe un lead con ese teléfono.

{
  "phone": "50212345678",
  "contact_name": "Carlos Mendoza",
  "funnel_id": 1,
  "pipeline_state": "new",
  "notes": "Interesado en plan pro"
}

Dispara webhooks automáticamente: cambiar pipeline_state → crm.lead.stage_changed, archived_status → crm.lead.archived, assigned_user_id → crm.lead.assigned. Usa assigned_user_id: null para desasignar.

{
  "contact_name": "Carlos Mendoza Ruiz",
  "pipeline_state": "qualified",
  "archived_status": "won",
  "assigned_user_id": 4,
  "notes": "Cerrado exitosamente"
}

CRM — Enviar mensaje

Enruta automáticamente por el canal del lead. type: text, image, video, audio o document.

curl -X POST "https://app.mindy.gt/api/v1/crm/leads/123/messages" \
  -H "Authorization: Bearer mk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "type": "text", "content": "Hola, te confirmo tu pedido." }'

const res = await fetch(
  "https://app.mindy.gt/api/v1/crm/leads/123/messages",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer mk_live_tu_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ type: "text", content: "Hola, te confirmo tu pedido." }),
  }
);
const msg = await res.json();

import requests
r = requests.post(
    "https://app.mindy.gt/api/v1/crm/leads/123/messages",
    headers={"Authorization": "Bearer mk_live_tu_api_key"},
    json={"type": "text", "content": "Hola, te confirmo tu pedido."}
)
print(r.json())

$ch = curl_init(
  "https://app.mindy.gt/api/v1/crm/leads/123/messages"
);
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer mk_live_tu_api_key",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "type" => "text",
    "content" => "Hola, te confirmo tu pedido.",
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);
$res = json_decode(curl_exec($ch), true);

// 200 OK
{
  "success": true,
  "data": {
    "message_id": 9999, "channel": "whatsapp",
    "external_id": "EVO_abc123", "sent_at": "2026-05-19 14:32:00"
  }
}

Soporte por canal

CRM — Notas

Dispara crm.note.added.

{ "content": "Llamó para confirmar reunión del martes." }

// 201 Created
{
  "id": 88, "id_lead": 14,
  "content": "Llamó para confirmar reunión del martes.",
  "user_name": null, "created_at": "2026-06-03 11:30:00"
}

CRM — Embudos, Etapas y Tags

Changelog