Guía
Conceptos
Las ideas que atraviesan toda la API. Cada endpoint asume estos conceptos; aquí viven explicados una sola vez, con ancla propia para enlazar desde cualquier lado.
Publicar no es síncrono. Cuando llama a POST /v1/products la API no espera a que Mercado Libre responda: crea un job, devuelve un job_id con 202 Accepted y procesa en segundo plano. Cada job pasa por estados queued → processing → completed (o failed/cancelled). Usted sigue su avance con GET del job.
El environment lo decide la API Key, no el body. Una key automeli_test_* publica en una cuenta de prueba y no consume créditos; una automeli_live_* publica en su cuenta real y sí los consume. El flujo recomendado es publicar primero en test, revisar y promover a live — ver flujo test → live y API Keys y scopes.
Cada item publicado en live consume 1 crédito. Los reintentos consumen por item reintentado. Consulte su saldo con GET /v1/account (credits.available se calcula según el environment de la key). Antes de un batch grande, verifíquelo — ver catálogo de 1000.
gold_pro (premium, con cuotas) y gold_special (clásica) son los vigentes; gold_premium / gold / silver / bronze se aceptan por compatibilidad. Si no envía ninguno, se usa el configurado por el seller.
Cada key tiene permisos acotados. Lectura de recursos pide products:read / account:read; escritura (publicar, promover, reintentar, cancelar) pide products:write. Si a su key le falta el scope recibe 403 E_AUTH_FORBIDDEN_SCOPE. Gestiona scopes al crear la key — ver API Keys y scopes.
Como los jobs son asíncronos, consulta su estado haciendo poll: pida GET del job cada 5–10 segundos hasta que el status sea terminal (completed, failed o cancelled). No hace falta poll más agresivo; el procesamiento toma segundos por lote. El patrón completo está en catálogo de 1000.
Hay dos límites distintos: el rate limit de requests (responda al header Retry-After en un 429 E_RATE_LIMITED) y el tope de 6 jobs activos a la vez (429 E_PRODUCT_MAX_CONCURRENT_JOBS). Detalle y headers en rate limit.