API REST para Nóminas en México | Integración MCS Payroll

Capacidades de la API

👥

Gestión de Empleados

Crea, actualiza y consulta información completa de empleados, departamentos y puestos

GET /v1/employees
POST /v1/employees
PUT /v1/employees/:id
DELETE /v1/employees/:id

⏰

Control de Asistencia

Registra checadas de entrada/salida con geolocalización y consulta historial de asistencia

POST /v1/checkin
POST /v1/checkout
GET /v1/attendance
GET /v1/attendance/report

💰

Cálculo de Nómina

Procesa nóminas, consulta recibos y obtén cálculos de percepciones y deducciones

POST /v1/payroll/calculate
GET /v1/payroll/receipts
GET /v1/payroll/periods
POST /v1/payroll/process

📅

Permisos y Vacaciones

Gestiona solicitudes de permisos, vacaciones e incapacidades de forma programática

POST /v1/leaves
GET /v1/leaves
PUT /v1/leaves/:id/approve
GET /v1/leaves/balance

📊

Reportes y Analytics

Genera reportes personalizados y obtén métricas de nómina y asistencia en tiempo real

GET /v1/reports/payroll
GET /v1/reports/attendance
GET /v1/analytics/costs
GET /v1/analytics/metrics

🔔

Webhooks

Recibe notificaciones en tiempo real de eventos importantes en tu sistema

POST /v1/webhooks
GET /v1/webhooks
DELETE /v1/webhooks/:id
GET /v1/webhooks/events

Ejemplos de Código

Registrar Checada de Entrada

Registra la entrada de un empleado con geolocalización. El sistema valida automáticamente que la ubicación esté dentro de las zonas permitidas.

POST Autenticación requerida Geolocalización

JavaScript

// Registrar checada de entrada con geolocalización
const response = await fetch('https://api.mcspayroll.com/v1/checkin', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    employee_id: '12345',
    timestamp: new Date().toISOString(),
    location: {
      latitude: 21.1619,
      longitude: -86.8515
    },
    device_info: {
      type: 'mobile',
      os: 'iOS 17.2'
    }
  })
});

const data = await response.json();
console.log(data);
// {
//   "success": true,
//   "checkin_id": "chk_abc123",
//   "employee": "Juan Pérez",
//   "timestamp": "2025-01-15T08:00:00Z",
//   "status": "on_time"
// }

Consultar Lista de Empleados

Obtén la lista completa de empleados con filtros avanzados por departamento, estatus, puesto y más. Incluye paginación automática.

GET Paginación Filtros

cURL

curl -X GET "https://api.mcspayroll.com/v1/employees?department=ventas&status=active&page=1&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Response
{
  "success": true,
  "data": [
    {
      "id": "emp_12345",
      "name": "María González",
      "email": "maria.gonzalez@empresa.com",
      "department": "Ventas",
      "position": "Ejecutivo de Ventas",
      "status": "active",
      "hire_date": "2023-06-15"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150,
    "pages": 3
  }
}

Calcular Nómina

Calcula la nómina de un empleado o grupo de empleados para un periodo específico. Incluye todas las percepciones, deducciones e impuestos.

POST Cálculo automático IMSS/ISR

Python

import requests

url = "https://api.mcspayroll.com/v1/payroll/calculate"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "period_id": "per_2025_01",
    "employee_ids": ["emp_12345", "emp_67890"],
    "include_bonuses": True,
    "include_overtime": True
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

print(f"Nómina calculada: ${data['total_amount']}")
# Nómina calculada: $125,450.00

Configurar Webhook

Recibe notificaciones en tiempo real cuando ocurran eventos importantes como checadas, aprobaciones de permisos o procesamiento de nómina.

POST Tiempo real Eventos

Node.js

// Crear webhook para recibir notificaciones
const webhook = await fetch('https://api.mcspayroll.com/v1/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://tu-servidor.com/webhook',
    events: [
      'checkin.created',
      'checkout.created',
      'leave.approved',
      'payroll.processed'
    ],
    active: true
  })
});

// Tu servidor recibirá:
// POST https://tu-servidor.com/webhook
// {
//   "event": "checkin.created",
//   "data": {
//     "employee_id": "emp_12345",
//     "timestamp": "2025-01-15T08:00:00Z"
//   }
// }

¿Por qué usar nuestra API?

🚀 Fácil de Integrar

Documentación completa con ejemplos en múltiples lenguajes. Comienza a integrar en minutos.

🔒 Segura y Confiable

Autenticación OAuth 2.0, encriptación SSL/TLS y cumplimiento con estándares de seguridad.

⚡ Alto Rendimiento

Infraestructura escalable con tiempos de respuesta menores a 100ms y 99.9% de uptime.

📚 Documentación Completa

Guías detalladas, referencias de API, ejemplos de código y casos de uso reales.

🔄 Webhooks en Tiempo Real

Recibe notificaciones instantáneas de eventos importantes en tu sistema.

💬 Soporte Técnico

Equipo de desarrolladores disponible para ayudarte con tu integración.

Integra MCS Payroll con tus sistemas

99.9%

<100ms

RESTful

JSON