API pública

Autenticación y claves

Un Propietario o Administrador de la organización emite, rota y revoca las claves en Configuración → API. Cada clave nueva se muestra una sola vez. Envíala en la cabecera Authorization.

Authorization: Bearer adc_<id>.<secret>

La clave pertenece a una tienda y solo da acceso a los datos de esa tienda. Un identificador de otra tienda responde 404, igual que uno inexistente; si el producto que exige el endpoint (PIM o DAM) no está disponible para la tienda, la respuesta es 403 not_contracted. El contrato OpenAPI y la colección de Postman son públicos y no necesitan clave.

Las claves son válidas durante 90 días. La rotación crea una clave nueva y mantiene la anterior funcionando hasta 7 días, sin ampliar su vencimiento original. Cambia la clave en tu integración durante ese solapamiento; mientras dure, se rechaza una nueva rotación. La revocación tiene efecto inmediato.

Límites, paginación y búsqueda por SKU

Cada clave permite 120 solicitudes cada 60 segundos. La IP de origen permite 600 solicitudes en la misma ventana, contadas antes de la autenticación. Una página contiene hasta 100 elementos.

Usa limit y offset para productos. El orden sigue el updatedAt del registro del producto, no cada cambio de atributo o variante. Los eventos usan un cursor; guarda el nextCursor de la respuesta para la siguiente solicitud.

Busca por el código SKU del catálogo con el parámetro sku, repitiéndolo para consultar hasta 100 códigos. No se distingue entre mayúsculas y minúsculas, salvo que un código guardado con ß puede no encontrarse si se pide con SS; envíalos sin espacios al principio o al final, o la respuesta será 400. Los resultados incluyen requestedSku; un código puede coincidir con varias variantes. Los códigos ausentes aparecen en notFound, y un código SKU repetido en la misma consulta se procesa una sola vez. Los productos con una sola variante siguen la regla de código SKU de la tienda cuando está configurada.

/api/v1/variants?sku=SKU-1001&sku=SKU-1002

Endpoints

Cómo tratar rechazos

400

Faltan parámetros, hay parámetros repetidos o no válidos, o la respuesta solicitada supera el límite de tamaño. Revisa los parámetros y los límites en el contrato OpenAPI y ajusta la solicitud.

401

Falta la clave, no es válida, venció o fue revocada, o la tienda está inactiva. La respuesta es unauthorized con WWW-Authenticate: Bearer y no revela el motivo interno. Revisa la clave. Si necesitas otra, pide a un Propietario o Administrador de la organización que emita una clave, si no queda ninguna activa, o que rote la activa. Si la tienda está inactiva, no se puede emitir ni rotar hasta que vuelva a estar activa.

403

La clave es válida, pero no puede ejecutar esta operación. insufficient_scope: los endpoints de esta página son de lectura, así que usa la clave de lectura, no la de escritura. not_contracted: el producto que exige el endpoint (PIM o DAM) no está disponible para la tienda. datalake_disabled: Data Lake no está habilitado para la tienda. Repetir con la misma clave no resuelve estos rechazos.

404

El recurso o snapshot solicitado no está disponible para esta tienda. Revisa el identificador y, para los snapshots, el formato y la fecha. El código export_not_ready indica que no hay un snapshot completo disponible para esa selección.

429

Se alcanzó el límite de la clave o de la IP. Espera los segundos que indica Retry-After antes de reintentar. Las cabeceras X-RateLimit-* vienen en toda respuesta 200 de los endpoints que exigen clave y, en una respuesta 429, solo cuando se agotó el límite de la clave.

500

No se pudo completar la solicitud por un error interno. Vuelve a intentarlo más tarde. Si el error persiste, ponte en contacto con soporte.

Eventos

Consulta GET /api/v1/events con un cursor y elimina duplicados por el id estable del evento. Cada evento está disponible 120 segundos después de registrarse. La consulta trae solo los tipos de evento disponibles para la tienda. La consulta y los webhooks usan los mismos ids.

• product.published
• asset.changed

La consulta no es un historial completo de cambios. Los eventos de activos cubren cambios completados y registrados en la auditoría del DAM; no los emiten la vinculación automática durante una importación, la copia entre variantes hermanas, la reversión de una importación ni las tareas de medios. product.published solo se emite cuando se completa una publicación en VTEX y su historial se registra. Vuelve a leer productos y activos para conciliar los datos.

Webhooks

El destino HTTPS lo registra el equipo responsable del servicio o, si la pantalla está habilitada, un Propietario o Administrador de la organización en Configuración → Webhooks. La entrega empieza después de que ese equipo la habilite para tu tienda. Desde entonces, la entrega a un destino recién registrado empieza en un plazo de hasta una hora y solo incluye eventos posteriores al registro. Si la entrega se detiene por una falla del servicio, reanudarla le corresponde al mismo equipo. La consulta de eventos sigue disponible antes de que empiece la entrega y durante una interrupción.

Verifica la firma HMAC y la marca de tiempo usando el secreto del webhook antes de aceptar una entrega. Después de generar un secreto nuevo, acepta también el anterior durante unos minutos: un lote en curso puede terminar firmado con él. La sección webhooks de OpenAPI define las cabeceras de firma, el contenido, los reintentos y la confirmación de recepción. Usa el id estable del evento para manejar entregas repetidas de forma segura.