Skip to content

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:

bash
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:

ScopePermite
read:orderslistar y ver pedidos
write:orderscrear y cancelar pedidos
read:storeslistar las tiendas asociadas al delivery
manage:webhooksregistrar 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 deliveryLímite
Pro100 requests por minuto
Business1000 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:

json
{ "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 ​

bash
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:

json
{
  "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.

API pública de Motochaski · v1