Primeros pasos

Lo que necesitás

• Una tienda en el plan Business (el acceso a la API está incluido ahí).
• Una clave de API, que crea el dueño de la tienda desde el panel: Ajustes → API e integraciones → Crear clave. La clave se muestra una sola vez; guardala en un lugar seguro.
• Elegí los permisos mínimos que tu sistema necesita (por ejemplo "Leer stock" y "Escribir stock" para una integración de inventario).

Entornos

Hay dos entornos independientes, cada uno con su propio prefijo de clave. Una clave de un entorno no sirve en el otro (401 API_KEY_WRONG_ENVIRONMENT).

El entorno de pruebas es una copia aislada para integrar sin tocar datos reales. No se autogestiona desde el panel: escribinos y te damos una clave de prueba.

Tu primera llamada

La clave viaja en el header Authorization como bearer. Empezá por GET /me, que te devuelve la tienda sobre la que actúa la clave, sus permisos y los límites:

curl https://api.mandaditoapp.com/partner/v1/me \
  -H "Authorization: Bearer mdt_live_..."

Respuesta:

{
  "store": { "id": "66b0...", "handle": "supermercado-la-central", "title": "Supermercado La Central" },
  "scopes": ["inventory:read", "inventory:write", "prices:write"],
  "environment": "live",
  "plan": "business",
  "rateLimit": { "burst": 40, "perSecond": 2, "maxConcurrent": 4 },
  "apiVersion": "2026-10"
}

Paginación

Las listas se paginan por cursor. Pedí una página con ?limit= (1 a 100, por defecto 50) y seguí con el nextCursor que devuelve, hasta que sea null:

curl "https://api.mandaditoapp.com/partner/v1/products?limit=100" \
  -H "Authorization: Bearer mdt_live_..."

{
  "data": [ { "id": "...", "title": "...", "variants": [ ... ] } ],
  "nextCursor": "eyJfaWQiOiI2NmIw..."
}

Para sincronizar solo lo que cambió, los feeds aceptan ?updatedSince= con una fecha ISO 8601. Guardá la hora de cada corrida y volvé a pedir desde ahí.

Límites de uso

El uso se controla por clave. Cada respuesta trae los headers RateLimit y RateLimit-Policy; cuando te frenan, viene también Retry-After (en segundos).

• Ráfaga de 40 y luego 2 por segundo sostenido (token bucket). Pasarte es 429 RATE_LIMITED.
• 4 pedidos en vuelo por clave a la vez. El quinto en paralelo es 429 CONCURRENCY_LIMITED con Retry-After: 1: esperá a que terminen los tuyos.
• Si la API está muy cargada puede responder 503 PARTNER_API_BUSY con Retry-After: reintentá después de esos segundos.
• Las escrituras en lote toman hasta 50 ítems por llamada. Una sincronización de 5000 SKU son 100 llamadas.

La forma recomendada de integrar es un cliente "educado": mantené pocas llamadas en vuelo, respetá los headers de límite y dormí lo que pide Retry-After. Así nunca te frenan.

Seguí con Autenticación para los permisos y la tabla de errores, o con Sincronizar tu ERP para el mapeo y las escrituras.