Empezar

La API pública de Motochaski deja que el sistema de una tienda —su ERP, su ecommerce, su hoja de pedidos— cree pedidos en el delivery con el que trabaja y se entere de lo que pasa con ellos.

Qué necesitas

• Una llave de API. Te la da el delivery (el operador) desde su panel, en Configuración → API keys. Tiene esta forma:

  mck_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

  Se muestra una sola vez al crearla. Guárdala en tu servidor, nunca en el navegador ni en una app móvil.

• Que el delivery esté en plan Pro o superior. La API es una funcionalidad del plan del operador; si no la tiene, cada request responde 403.

Llave de tienda

Hoy la llave la crea el delivery. Está previsto que la tienda cree su propia llave (msk_live_…) desde su panel y elija a qué delivery va cada pedido, o lo deje en su bandeja. Ver Pendiente.

La URL base

https://api.motochaski.com/v1

Todos los endpoints van bajo /v1. Un cambio incompatible sería /v2; dentro de /v1 solo se agregan campos, nunca se quitan ni cambian de tipo.

Autenticación

La llave viaja en la cabecera X-API-Key:

curl https://api.motochaski.com/v1/orders \
  -H "X-API-Key: mck_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Sin cabecera o con una llave revocada o vencida: 401.

Permisos (scopes)

Cada llave tiene permisos. Los pide el delivery al crearla:

Scope	Permite
read:orders	listar y ver pedidos
write:orders	crear y cancelar pedidos
read:stores	listar las tiendas asociadas al delivery
manage:webhooks	registrar y desactivar webhooks

Un request sin el scope necesario responde 403 con el nombre del scope que falta.

Llave de tienda o de todo el delivery

Al crear la llave, el delivery puede atarla a una tienda. Si la llave está atada:

• POST /orders crea el pedido para esa tienda aunque mandes otro store_id.
• GET /orders y GET /orders/:id solo ven los pedidos de esa tienda.
• Los webhooks que registres con ella solo reciben eventos de esa tienda.

Es lo normal cuando el que integra es la tienda. Una llave sin tienda ve todo el delivery y es para el propio operador (su contabilidad, su tablero).

Límite de peticiones

Plan del delivery	Límite
Pro	100 requests por minuto
Business	1000 requests por minuto

Al pasarlo, 429. El contador es por llave y por minuto de reloj.

No hagas polling

No consultes GET /orders cada 30 segundos para saber si algo cambió. Registra un webhook: te avisamos nosotros, y no gastas tu límite.

Formato de las respuestas

Todas las respuestas son JSON con esta envoltura:

{ "data": { ... }, "warning": "…", "message": "…", "error": "…" }

• data — el recurso o la lista.
• warning — el request funcionó pero hay algo que mirar (por ejemplo, el destino es zona de riesgo).
• error — solo en respuestas 4xx/5xx, en español, pensado para mostrar.

Tu primer pedido

curl -X POST https://api.motochaski.com/v1/orders \
  -H "X-API-Key: mck_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Idempotency-Key: venta-48213" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_name": "María Quispe",
    "recipient_phone": "+51987654321",
    "delivery_address": "Av. Larco 1234, dpto 502",
    "delivery_reference": "Frente al parque, portón negro",
    "delivery_maps_url": "https://maps.app.goo.gl/AbCdEfGh",
    "location_id": "4f4c5b2e-…",
    "product": "2 polos talla M",
    "amount_to_collect": 89.90
  }'

Respuesta 201:

{
  "data": {
    "id": "b1c2d3…",
    "guide_code": "MC-K7M3P9X",
    "status": "registered",
    "shipping_cost": 12.00,
    "payment_type": "cash_on_delivery",
    ...
  }
}

El guide_code es lo que va impreso en el sticker del paquete y lo que el cliente final usa para hacer seguimiento. Guárdalo junto a tu venta.

La cabecera Idempotency-Key es tu id de venta: si el request se corta y lo reintentas, recibes el mismo pedido en vez de crear otro. Ver reintentar sin duplicar.

Sigue con Crear un pedido para ver todos los campos.