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 /v2/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 consume créditos de prueba; una automeli_live_* publica en su cuenta real y consume créditos reales. 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 /v2/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. Se define a nivel job; si no envía ninguno, se usa gold_special (Clásica).
Cada publicación del catálogo tiene un estado que define qué hace Automeli con ella: enabled (se revisa en Amazon y se actualiza en Mercado Libre) o disabled (no se actualiza); algunas cuentas tienen estados adicionales habilitados. Se lee en el listado del catálogo y se cambia con PATCH /products/sync-status. Siempre como palabra, nunca como número.
Cada key tiene permisos acotados. Lectura de recursos pide products:read / account:read; escritura (publicar, promover, reintentar, cancelar, cambiar sync-status) 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.
Todos los listados de v2 devuelven next_cursor + has_more; se recorren repitiendo la llamada con ?cursor=… hasta que has_more sea false. total viene sólo en la primera página. El detalle vive en paginación por cursor.
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.