API de Kargo

API REST y servidor MCP para integrar sistemas externos y agentes de IA con el taller: clientes, equipos, solicitudes de servicio, órdenes de trabajo, agenda, inspecciones, cotizaciones, mantenimiento preventivo y búsqueda de refacciones.

• URL base: https://api.kargo.mx/v1
• MCP (agentes de IA): https://api.kargo.mx/mcp
• OpenAPI 3.1: https://api.kargo.mx/v1/openapi.json (impórtalo en Postman, Insomnia o un generador de clientes)
• Versión: v1. Agregar campos u operaciones es compatible y no cambia la versión; renombrar o quitar algo es /v2.

Empezar en tres pasos

1. Crea una credencial. En la app: Configuración → Integraciones → Nueva integración. Elige un nombre y los alcances. La llave (kgo_live_…) se muestra una sola vez: guárdala en el gestor de secretos de tu sistema.
2. Comprueba que funciona.

curl https://api.kargo.mx/v1/me \
  -H "Authorization: Bearer $KARGO_API_KEY"

3. Haz tu primera consulta.

curl "https://api.kargo.mx/v1/equipment?q=hyster&limit=10" \
  -H "Authorization: Bearer $KARGO_API_KEY"

Autenticación

Manda la llave en Authorization: Bearer kgo_live_…. Para clientes que no pueden poner esa cabecera, X-API-Key hace lo mismo. Nunca la mandes en la URL: terminaría en los registros de cada servidor por el que pase.

Cada llave pertenece a un taller y sólo ve sus datos. Revocarla en la app surte efecto en la siguiente petición. Para rotarla sin cortar el servicio: crea una llave nueva, actualiza tu sistema y revoca la anterior.

Existen dos tipos de credencial:

• integration — la usa otro sistema (ERP, CRM, un script). Puede ejecutar todo lo que sus alcances permitan.
• agent — la opera un agente de IA. Las operaciones marcadas como sensibles (las que comprometen al taller con el cliente: abrir y programar órdenes, posponer un aviso de servicio) están bloqueadas y responden 403 human_confirmation_required. Una persona las hace desde la app.

Alcances

No existe ningún alcance de administración: una integración no crea llaves, no cambia roles ni mueve precios.

Respuestas y errores

Toda respuesta correcta es un objeto con data y, en las listas, meta:

{ "data": { "id": "…", "number": "OT-20261107-0001" } }

Todo error tiene la misma forma. Programa contra error.code, que es estable; el mensaje es para una persona y puede mejorarse sin aviso:

{ "error": { "code": "order_closed", "message": "La orden ya está cerrada o cancelada.", "request_id": "req_8f3a…" } }

Cada respuesta trae X-Request-Id. Cítalo si reportas un problema: con él se encuentra la petición en la bitácora.

Un parámetro desconocido es un error, no se ignora: ?statuss=open (con la errata) responde 422 en vez de devolver todo sin filtrar.

Paginación y sincronización

Las listas devuelven hasta limit registros (1–200, por omisión 50) y meta.next_cursor. Pásalo tal cual como cursor para la página siguiente; null significa que no hay más. El cursor es opaco: no intentes construirlo.

Para sincronizar cambios no repases todo: guarda el mayor updated_at que viste y pídelo con updated_since. Con ese filtro el orden es por modificación ascendente, justo el que necesita quien procesa en el orden en que ocurrieron las cosas. Más allá de 10,000 registros con cursor se rechaza; updated_since no tiene ese tope.

Idempotencia

Toda operación que escribe acepta la cabecera Idempotency-Key con cualquier cadena única por operación (un UUID sirve). Si tu petición se cae a medias y la repites con la misma clave, recibes la respuesta original (Idempotent-Replayed: true) en vez de abrir una segunda orden. Usar la misma clave con una petición distinta responde 422 idempotency_key_reused. Las claves se recuerdan 48 horas.

Límites

Cada credencial tiene un tope de peticiones por minuto (se ve en GET /me; 120 por omisión) y algunas operaciones que consultan servicios de terceros tienen uno propio más bajo. Al pasarte, la respuesta es 429 con Retry-After.

Servidor MCP

El mismo conjunto de operaciones está disponible como herramientas MCP para agentes de IA (Claude, ChatGPT, Cursor y cualquier cliente compatible), con la misma credencial, los mismos alcances y las mismas reglas: lo que la API REST niega, el agente tampoco puede hacerlo.

• Transporte: HTTP transmitible (Streamable HTTP), sin estado. URL: https://api.kargo.mx/mcp
• Autenticación: la misma llave, Authorization: Bearer kgo_live_….

Claude Code:

claude mcp add --transport http kargo https://api.kargo.mx/mcp \
  --header "Authorization: Bearer $KARGO_API_KEY"

Cualquier cliente con archivo de configuración:

{
  "mcpServers": {
    "kargo": {
      "type": "http",
      "url": "https://api.kargo.mx/mcp",
      "headers": { "Authorization": "Bearer kgo_live_…" }
    }
  }
}

Para un agente, crea la credencial como tipo agent: así no puede ejecutar las operaciones sensibles sin una persona. Las herramientas de escritura aceptan además idempotency_key.

Referencia de operaciones

Servicio

GET /health

Estado del servicio · sin credencial · health.get

No pide credencial: es para monitoreo (UptimeRobot, el balanceador, un check de tu integración). Responde 200 con status: ok, o 503 con status: degraded si la base de datos no contesta.

Ejemplo

curl "https://api.kargo.mx/v1/health"

Respuesta — data

GET /me

Quién es esta credencial · cualquier credencial · MCP whoami · me.get

Integración, taller, alcances y límite de peticiones. Sirve para comprobar que la llave funciona y qué puede hacer antes de usarla.

Ejemplo

curl "https://api.kargo.mx/v1/me" \
  -H "Authorization: Bearer $KARGO_API_KEY"

Respuesta — data

Clientes

GET /customers

Listar clientes · alcance customers:read · MCP list_customers · customers.list

Clientes del taller, del más reciente al más antiguo. q busca en razón social, nombre corto, RFC y clave externa.

Parámetros

Ejemplo

curl "https://api.kargo.mx/v1/customers?limit=50" \
  -H "Authorization: Bearer $KARGO_API_KEY"

Respuesta — Cada elemento de data

GET /customers/{id}

Consultar un cliente · alcance customers:read · MCP get_customer · customers.get

Consultar un cliente

Parámetros

Ejemplo

curl "https://api.kargo.mx/v1/customers/<id>" \
  -H "Authorization: Bearer $KARGO_API_KEY"

Respuesta — data

POST /customers

Registrar un cliente · alcance customers:write · MCP create_customer · customers.create

Da de alta un cliente como prospecto en borrador: el taller completa después su expediente fiscal. Si mandas external_customer_code y ya existe un cliente con esa clave, devuelve ése (200) en vez de duplicarlo: es la forma de sincronizar desde otro sistema sin crear repetidos.

Cuerpo (JSON)

Ejemplo

curl -X POST "https://api.kargo.mx/v1/customers" \
  -H "Authorization: Bearer $KARGO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "legal_name": "Molinos del Pacífico SA de CV" }'

Respuesta — data

GET /customers/{id}/locations

Ubicaciones de un cliente · alcance customers:read · MCP list_customer_locations · customers.locations

Sucursales y plantas del cliente, con dirección, coordenadas y cómo entrar. serviceable=false marca domicilios fiscales u oficinas a donde no se manda técnico.

Parámetros

Ejemplo

curl "https://api.kargo.mx/v1/customers/<id>/locations?limit=50" \
  -H "Authorization: Bearer $KARGO_API_KEY"

Respuesta — Cada elemento de data

Equipos

GET /equipment

Listar equipos · alcance equipment:read · MCP list_equipment · equipment.list

Equipos de clientes y del taller. q busca por número económico, serie, marca o modelo.

Parámetros

Ejemplo

curl "https://api.kargo.mx/v1/equipment?limit=50" \
  -H "Authorization: Bearer $KARGO_API_KEY"

Respuesta — Cada elemento de data

GET /equipment/{id}

Consultar un equipo · alcance equipment:read · MCP get_equipment · equipment.get

Ficha del equipo con su cliente y la última lectura del horómetro.

Parámetros

Ejemplo

curl "https://api.kargo.mx/v1/equipment/<id>" \
  -H "Authorization: Bearer $KARGO_API_KEY"

Respuesta — data

GET /equipment/{id}/hour-meter-readings

Historial del horómetro · alcance equipment:read · MCP list_hour_meter_readings · equipment.hour_meter_readings

Lecturas del horómetro, la más reciente primero. No incluye las anuladas.

Parámetros

Ejemplo

curl "https://api.kargo.mx/v1/equipment/<id>/hour-meter-readings?limit=50" \
  -H "Authorization: Bearer $KARGO_API_KEY"

Respuesta — Cada elemento de data

Solicitudes

GET /service-requests

Listar solicitudes de servicio · alcance requests:read · MCP list_service_requests · service_requests.list

Lo que han pedido los clientes, lo más reciente primero. Cada solicitud trae el cliente y el equipo en customer y equipment.

Parámetros

Ejemplo

curl "https://api.kargo.mx/v1/service-requests?limit=50" \
  -H "Authorization: Bearer $KARGO_API_KEY"

Respuesta — Cada elemento de data

GET /service-requests/{id}

Consultar una solicitud · alcance requests:read · MCP get_service_request · service_requests.get

Consultar una solicitud

Parámetros

Ejemplo

curl "https://api.kargo.mx/v1/service-requests/<id>" \
  -H "Authorization: Bearer $KARGO_API_KEY"

Respuesta — data

POST /service-requests

Registrar una solicitud de servicio · alcance requests:write · MCP create_service_request · service_requests.create

Registra lo que pide un cliente. Todo servicio empieza aquí: de la solicitud se deriva después la visita, el preventivo o la orden. El folio SOL-… lo asigna la base. Con Idempotency-Key un reintento devuelve la misma solicitud en vez de crear otra. No hace falta conocer el equipo: puede registrarse sólo con la descripción y completarse después.

Cuerpo (JSON)

Ejemplo

curl -X POST "https://api.kargo.mx/v1/service-requests" \
  -H "Authorization: Bearer $KARGO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "description": "Falla en frenos, el montacargas no frena en pendiente" }'

Respuesta — data

Órdenes de trabajo

GET /service-orders

Listar órdenes de trabajo · alcance orders:read · MCP list_service_orders · service_orders.list

Órdenes de trabajo, la más reciente primero. Cada una trae el cliente y el equipo en customer y equipment.

Parámetros

Ejemplo

curl "https://api.kargo.mx/v1/service-orders?limit=50" \
  -H "Authorization: Bearer $KARGO_API_KEY"

Respuesta — Cada elemento de data

GET /service-orders/{id}

Consultar una orden de trabajo · alcance orders:read · MCP get_service_order · service_orders.get

Consultar una orden de trabajo

Parámetros

Ejemplo

curl "https://api.kargo.mx/v1/service-orders/<id>" \
  -H "Authorization: Bearer $KARGO_API_KEY"

Respuesta — data

POST /service-orders

Abrir una orden de trabajo · alcance orders:write · sensible: bloqueada para credenciales agent · MCP open_service_order · service_orders.create

Abre una orden para un equipo. Por omisión es una visita de diagnóstico: la orden de reparación nace después, cuando el cliente autoriza una cotización. El folio OT-… lo asigna la base. Compromete al taller con el cliente, por eso una credencial de tipo agent no puede ejecutarla.

Cuerpo (JSON)

Ejemplo

curl -X POST "https://api.kargo.mx/v1/service-orders" \
  -H "Authorization: Bearer $KARGO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "equipment_id": "<uuid>", "description": "Falla en frenos, el montacargas no frena en pendiente" }'

Respuesta — data

POST /service-orders/{id}/schedule

Programar o reasignar una orden · alcance orders:write · sensible: bloqueada para credenciales agent · MCP schedule_service_order · service_orders.schedule

Mueve la orden en la agenda: día, turno y técnico, en una sola operación. scheduled_date es obligatorio: null la manda al backlog (sin programar). assigned_to ausente deja al técnico como está, null lo quita y un user_id lo asigna (el estado pasa solo de open a assigned). Manda expected_updated_at con el updated_at que leíste para no pisar un cambio de alguien más: si cambió, responde 409 order_changed_elsewhere. Una orden cerrada o cancelada no se reprograma.

Parámetros

Cuerpo (JSON)

Ejemplo

curl -X POST "https://api.kargo.mx/v1/service-orders/<id>/schedule" \
  -H "Authorization: Bearer $KARGO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "scheduled_date": "2026-11-10" }'

Respuesta — data

Disponibilidad

GET /technicians

Listar técnicos asignables · alcance orders:read · MCP list_technicians · technicians.list

Mecánicos y jefes de taller a quienes se les puede asignar una orden. El id es el valor de assigned_to.

Ejemplo

curl "https://api.kargo.mx/v1/technicians" \
  -H "Authorization: Bearer $KARGO_API_KEY"

Respuesta — Cada elemento de data

GET /availability/technicians

Carga de los técnicos en un día · alcance orders:read · MCP technician_availability · availability.technicians

Cuántas órdenes abiertas y cuántas horas estimadas tiene cada técnico ese día. Sirve para decidir a quién asignarle algo sin abrir la agenda. Una orden sin horas estimadas cuenta como 0 h, así que estimated_hours es un piso, no un total garantizado.

Parámetros

Ejemplo

curl "https://api.kargo.mx/v1/availability/technicians" \
  -H "Authorization: Bearer $KARGO_API_KEY"

Respuesta — Cada elemento de data

GET /availability/fleet

Disponibilidad de la flotilla propia · alcance fleet:read · MCP fleet_availability · availability.fleet

Equipos propios del taller con su etapa: disponible, rentado, en revisión, en reparación, en tránsito, de baja o vendido. Sin precios ni datos del cliente. Si está rentado, contract_end dice cuándo regresa.

Parámetros

Ejemplo

curl "https://api.kargo.mx/v1/availability/fleet?limit=50" \
  -H "Authorization: Bearer $KARGO_API_KEY"

Respuesta — Cada elemento de data

Inspecciones

GET /inspections

Listar inspecciones · alcance inspections:read · MCP list_inspections · inspections.list

Revisiones de equipos, la más reciente primero. Cada una trae el cliente y el equipo.

Parámetros

Ejemplo

curl "https://api.kargo.mx/v1/inspections?limit=50" \
  -H "Authorization: Bearer $KARGO_API_KEY"

Respuesta — Cada elemento de data

GET /inspections/{id}

Consultar una inspección con sus hallazgos · alcance inspections:read · MCP get_inspection · inspections.get

La inspección y sus hallazgos, con severidad (urgent / recommended), qué se encontró, qué se recomienda y qué pasa si no se corrige.

Parámetros

Ejemplo

curl "https://api.kargo.mx/v1/inspections/<id>" \
  -H "Authorization: Bearer $KARGO_API_KEY"

Respuesta — data

Cotizaciones

GET /quotes

Listar cotizaciones · alcance quotes:read · MCP list_quotes · quotes.list

Cotizaciones con los totales de su versión vigente en current. Incluye importes: sólo para credenciales que deban verlos.

Parámetros

Ejemplo

curl "https://api.kargo.mx/v1/quotes?limit=50" \
  -H "Authorization: Bearer $KARGO_API_KEY"

Respuesta — Cada elemento de data

GET /quotes/{id}

Consultar una cotización · alcance quotes:read · MCP get_quote · quotes.get

La cotización con los totales de su versión vigente y el historial de versiones.

Parámetros

Ejemplo

curl "https://api.kargo.mx/v1/quotes/<id>" \
  -H "Authorization: Bearer $KARGO_API_KEY"

Respuesta — data

Mantenimiento preventivo

GET /preventive/forecasts

Pronóstico de mantenimiento preventivo · alcance preventive:read · MCP list_preventive_forecasts · preventive.list

Un renglón por equipo en seguimiento: cuándo le toca su siguiente servicio y qué se decidió con el aviso. El sistema detecta; una persona decide. Los más urgentes salen primero.

Parámetros

Ejemplo

curl "https://api.kargo.mx/v1/preventive/forecasts?limit=50" \
  -H "Authorization: Bearer $KARGO_API_KEY"

Respuesta — Cada elemento de data

POST /preventive/alerts/{id}/postpone

Posponer un aviso de preventivo · alcance preventive:write · sensible: bloqueada para credenciales agent · MCP postpone_preventive_alert · preventive.postpone

Pospone el aviso con motivo y fecha: vuelve a la bandeja ese día. El {id} es el alert_id del pronóstico. Decide cuándo se le da servicio a un equipo, así que una credencial de tipo agent no puede ejecutarla.

Parámetros

Cuerpo (JSON)

Ejemplo

curl -X POST "https://api.kargo.mx/v1/preventive/alerts/<id>/postpone" \
  -H "Authorization: Bearer $KARGO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "reason": "Esperando la refacción del cliente", "until": "2026-11-10" }'

Respuesta — data

Refacciones

GET /parts/search

Buscar refacciones · alcance parts:read · MCP search_parts · parts.search

Busca en el catálogo de la tienda por número de parte, equivalencia o nombre. Encuentra por el número grabado en la pieza aunque sea de otra marca, y dice por cuál campo encontró. Deliberadamente sin precio: el precio depende del cliente y del momento, y se cotiza desde una orden.

Parámetros

Ejemplo

curl "https://api.kargo.mx/v1/parts/search?q=montacargas&limit=10" \
  -H "Authorization: Bearer $KARGO_API_KEY"

Respuesta — Cada elemento de data