Registro de cambios de la API

Notificaciones de actualización de producto - octubre de 2026

Envía por email a los compradores de un producto el aviso de que se ha actualizado — la campaña que un comerciante inicia con Notificar a clientes en la página de un producto — desde tu propio sistema. Aditivo al contrato de la v1. Disponible en todos los planes de pago.

• Nuevo POST /products/{shopify_product_id}/notifications: pone en cola una campaña (202) para todos los compradores de las asignaciones descargables del producto o, con variant_ids, de las asignaciones que sirven a esas variantes. message opcional de texto sin formato de hasta 2.000 caracteres con {customer.first_name}, {shop.name}, {product.title} y {product.metafields.<namespace>.<key>}; sin enlaces. dry_run ejecuta todas las comprobaciones y devuelve los recuentos, el asunto y la nota renderizada sin enviar (200; usa una Idempotency-Key nueva por cada dry run). Cuesta 10 tokens del límite de frecuencia.
• Nuevo GET /notifications/{notificationId}: el estado de la campaña, los recuentos, waiting_for_archive y un vocabulario cerrado de error; completed con partial: true cuando algunos envíos fallaron. Las campañas iniciadas en la app también aparecen.
• Nuevo POST /notifications/{notificationId}/cancel: cancela una campaña en cola (200). Mantiene el límite de 7 días del producto, exactamente igual que cancelar en la app.
• Nuevo objeto opcional notify_customers en POST /mappings y PUT /mappings/{id}: pone en cola una notificación para los compradores de la asignación escrita una vez confirmada la escritura. Una nota que incumple una regla sobre su propio texto (en blanco, demasiado larga, una variable incorrecta, más de cinco metacampos, un enlace en el texto) es 422 invalid_message sin que se escriba nada; un problema con un metacampo y cualquier otro rechazo se informan en el nuevo campo data.notification (created: false, error), nunca como un 4xx. data.notification solo está presente cuando se envió el indicador; las respuestas existentes no cambian.
• Una campaña por producto cada 7 días, contando todas sus variantes y todos los orígenes, y ninguna mientras otra siga en cola o enviándose: 429 notification_cooldown con Retry-After (hasta siete días) y error.details.next_available_at. No es el bucket de tokens — no lo reintentes automáticamente; programa la siguiente llamada en next_available_at.
• Como máximo 5 campañas por tienda en cola o enviándose a la vez, contando todos los productos y todos los orígenes: una sexta es 429 too_many_active_notifications con error.details.limit y error.details.active_notification_ids, y sin Retry-After. Reintenta cuando una de ellas haya terminado. Un dry run se rechaza de la misma manera; en una escritura de asignación se informa en data.notification.
• Un email de actualización de producto por comprador y tienda cada 24 horas, contando todas las campañas: un comprador que ya recibió uno se omite cuando la campaña envía. Los compradores omitidos no figuran en sent_count, failed_count ni suppressed_count. Una campaña que omitió a todos los compradores termina en failed con error: recipients_recently_notified y no consume los 7 días del producto.
• Antes de cada lote de hasta 500 emails, la campaña vuelve a comprobar la tienda y se detiene si la suscripción o el plan de pago dejaron de estar activos, si se desactivaron los emails a clientes, si el envío se suspendió o si Alva desactivó las notificaciones. Si se detiene antes de enviar un email a nadie, queda en failed (plan_required, email_disabled, notifications_suspended o notifications_switched_off) y libera los 7 días; si se detiene más tarde, queda en completed con partial: true. Una campaña en la que fallaron todos los envíos queda en failed con nothing_sent y también libera los 7 días, y una a la que ya no le quedaba nadie a quien enviar el email cuando envió queda en failed con no_eligible_recipients y los libera igualmente.
• Una campaña cuya asignación objetivo tiene una regeneración del ZIP en curso la espera (waiting_for_archive: true; solo una asignación que entrega un archivo ZIP hace esperar a una campaña); una regeneración fallida, o que no avanza durante 60 minutos mientras se ejecuta (6 horas mientras aún está a la espera de empezar o de un nuevo intento), contados desde la regeneración, no desde la creación de la campaña, hace fallar la campaña con cero envíos y libera el límite.
• Ocho códigos de error nuevos: 403 notifications_suspended, 404 notification_not_found, 409 notification_not_cancellable, 422 invalid_message, 422 no_downloadable_content, 422 no_eligible_recipients, 429 notification_cooldown, 429 too_many_active_notifications. mapping_not_found y multiple_mappings_match incorporan error.details.unresolved_variant_ids / ambiguous_variant_ids en este endpoint.

Actualización de acceso - septiembre de 2026

El acceso a la API ya no requiere aprobación.

• Todos los planes de pago (Basic, Pro y Enterprise) pueden usar la API. Crea claves en la aplicación, en Configuraciones → API keys; no hay nada que solicitar.
• En el plan Free, la pestaña API keys está oculta y las claves existentes devuelven 402 plan_required hasta que la tienda cambie a un plan de pago.

Actualización de la v1 - julio de 2026

Adiciones aditivas de códigos de error y campos de respuesta al contrato v1 existente.

• Nuevo error 422 withdrawal_consent_required en el endpoint de download-urls de pedidos: se devuelve cuando la tienda tiene activado el consentimiento del derecho de desistimiento de la UE y el pedido aún no tiene un registro de consentimiento; las URL de descarga se emiten en cuanto el cliente da su consentimiento.
• Nuevo error 422 key_limit_reached al crear claves de API: una tienda puede tener como máximo 25 claves de API activas; revoca una primero.
• Nuevo error 409 delivery_not_yet_released en los endpoints download-urls y resend de pedidos: se devuelve cuando el producto tiene configurado un retraso de entrega de la descarga y los archivos del comprador aún no se han desbloqueado. No se emite ninguna URL de descarga ni se envía ningún correo hasta que transcurre el retraso.
• Nuevo objeto error.details en el sobre de error: solo está presente en los códigos que aportan contexto seguro para quien llama. Hoy delivery_not_yet_released es el único que lo produce, y lleva release_at, el instante ISO 8601 en el que se desbloquean las descargas. Trata el objeto como abierto: pueden aparecer claves nuevas sin un cambio de versión mayor.
• Nuevos campos delivery_pending y release_at en el objeto de compra del estado del pedido: delivery_pending es true mientras una compra sigue retenida por un retraso de entrega de la descarga, y release_at es el instante ISO 8601 de desbloqueo, o null cuando no hay nada pendiente.
• El endpoint grant-downloads ahora libera de inmediato las compras retenidas del pedido, de modo que un comerciante puede anular un retraso de entrega de la descarga a través de la API.

v1.0.0 - junio de 2026

Superficie inicial de la API piloto, con acceso solo mediante aprobación.

• Claves de API para tiendas aprobadas.
• Claves de idempotencia obligatorias en las solicitudes de escritura.
• Importación de recursos desde URL remota, subidas directas, listado de recursos, actualizaciones de recursos y eliminación de recursos.
• Categorías planas, asignaciones de productos, packs y etiquetas de claves de licencia.
• Asignaciones de pedidos que hacen visibles las descargas mapeadas en las cuentas de cliente de Shopify.
• Controles de acceso a pedidos: revocar, restaurar, conceder descargas y reenviar el email.
• Endpoints de estado de trabajos y pedidos.
• Descargas de la especificación OpenAPI y la colección de Postman.

Política de versionado

El contrato de la v1 es solo aditivo: pueden añadirse nuevos endpoints, campos opcionales y nuevos códigos de error. Los cambios incompatibles usarán una futura ruta /api/v2.