Endpoints

Base: https://api.motochaski.com/v1. Autenticación por X-API-Key salvo donde se indique. Fuente: api/internal/handlers/public_v1.go.

Pedidos

Método	Ruta	Scope	Qué hace
POST	/orders	write:orders	Crear pedido. Campos
GET	/orders	read:orders	Listar. Filtros: status, from_date, to_date, page, limit (default 50)
GET	/orders/:id	read:orders	Detalle
PATCH	/orders/:id/cancel	write:orders	Cancelar. Body { reason, note }. Solo en registered

Con llave atada a una tienda, todo queda acotado a esa tienda: un pedido de otra responde 404, no 403.

Seguimiento

Método	Ruta	Auth	Qué hace
GET	/track/:guide_code	ninguna	{ guide_code, status, status_label, product, events[], tenant_name, tenant_logo_url }

Es lo mismo que ve el cliente final en la página de seguimiento: la línea de tiempo (events) y la marca del delivery. No devuelve al motorizado ni la dirección: cualquiera que vea el sticker tiene el código. Para el detalle completo usa GET /orders/:id con llave.

Tiendas

Método	Ruta	Scope	Qué hace
GET	/stores	read:stores	Tiendas activas asociadas al delivery

Webhooks

Método	Ruta	Scope	Qué hace
GET	/webhooks	manage:webhooks	Activos
POST	/webhooks	manage:webhooks	Registrar. Body { url, events[], store_id? }. Devuelve secret una sola vez
DELETE	/webhooks/:id	manage:webhooks	Desactivar

Catálogo (sin autenticación, fuera de /v1)

Ruta	Qué devuelve
GET /public/countries	Países
GET /public/cities?country_code=PE	Ciudades operativas
GET /public/locations/tree?country_code=PE&city=Lima	Distritos de la ciudad con sus zonas
GET /public/locations/ubigeo?country_code=PE&codes=150122,150131	location_id a partir de ubigeo INEI
GET /public/locations?country_code=PE&q=texto	Búsqueda
GET /public/locations/:id/children	Zonas de un distrito

Cabeceras

Cabecera	Dirección	Uso
X-API-Key	request	La llave
Content-Type: application/json	request	En POST/PATCH
Idempotency-Key	request	En POST /orders: reintentar sin duplicar
Idempotent-Replayed: true	response	La respuesta salió del registro de idempotencia, no se creó nada
X-Motochaski-Event	webhook	Nombre del evento
X-Motochaski-Timestamp	webhook	Unix seconds
X-Motochaski-Signature	webhook	sha256=<hex>

Versionado

Dentro de /v1 solo se agregan campos. Tu parser tiene que tolerar campos nuevos que no conoce. Quitar o cambiar de tipo un campo sería /v2.