Referencia de la API REST
Todas las rutas son relativas a https://shopify.workflow-transactional-email.app. Todos los puntos finales, excepto el índice, requieren Authorization: Bearer fak_...; consulte Autenticación y claves de API.
Las respuestas están en formato JSON. Los errores siguen siempre el mismo formato:
{ "error": "Invalid or missing API key" }Índice e identidad
| Método | Ruta | Nivel | Objetivo |
|---|---|---|---|
| OBTENER | /api/v1 |
ninguno | Índice de la API. Confirma que la API está operativa e indica la versión actual |
| OBTENER | /api/v1/me |
leer | Compruebe si una clave funciona y consulte su nivel de acceso |
El índice no necesita clave, por lo que constituye una prueba de estado segura a la que dirigir un monitor.
Diseños de correo electrónico
| Método | Ruta | Nivel | Objetivo |
|---|---|---|---|
| OBTENER | /api/v1/email-templates |
leer | Lista de plantillas de correo electrónico. En q se pueden buscar por nombre, asunto y descripción; en category=transactional o category=marketing se muestra un tipo de correo electrónico. |
| PUBLICAR | /api/v1/email-templates |
escribir | Crear un diseño |
| OBTENER | /api/v1/email-templates/:id |
leer | Una maquetación con su diseño o sus anexos, los textos del pie de página y la lista de idiomas |
| PUT / PATCH | /api/v1/email-templates/:id |
escribir | Modificar un diseño. Solo se modifican los campos que envíe. |
| BORRAR | /api/v1/email-templates/:id |
escribir | Eliminar un diseño junto con sus traducciones y versiones |
| OBTENER | /api/v1/layout-schema |
leer | Cómo escribir una maquetación: el formato de diseño, los valores predeterminados de cada bloque, el código Liquid que puede utilizar, las limitaciones y un ejemplo |
La lista admite page (valor predeterminado: 1), limit (valor predeterminado: 25, máximo: 100) y q, que realiza búsquedas por nombre, asunto y descripción. No existe ningún filtro por tipo en la API; consulte category para obtener información sobre cada diseño.
Una plantilla cuenta con los siguientes campos:
| Campo | Notas |
|---|---|
name, description |
Nombre obligatorio, máximo 200 caracteres; descripción, máximo 2000 |
bodyType |
visual (por defecto) o text. Se corrige una vez creada |
defaultLocale |
El idioma del contenido propio de la maquetación, en, salvo que se especifique lo contrario |
category |
transactional (por defecto) o marketing. Véase más abajo |
subject, previewText |
Se permite llevar líquidos. Es obligatorio presentar el documento correspondiente. |
bodyDesign |
Maquetaciones visuales: { blocks, global?, header?, footer?, testVariables? }. Envíe el diseño completo cuando lo modifique; el código HTML body se genera a partir de él. |
body |
Diseños de texto: el cuerpo del HTML |
attachments |
Diseños de texto: [{ filename, fileKey, sendAsLink? }] para archivos subidos (véanse los archivos a continuación) o [{ filename, url }] para un archivo obtenido a través de https cuando se envía el correo electrónico |
marketingTexts |
Los textos del pie de página de una maquetación de marketing, o null. Véase más abajo. |
El texto «Liquid» del asunto, el texto de vista previa, el cuerpo y todos los bloques de texto deben analizarse, y cada fileKey debe pertenecer a su tienda; de lo contrario, la escritura se rechazará con un código de error 400 que especifique el campo en cuestión. Lea GET /api/v1/layout-schema antes de crear un diseño visual: este se genera a partir del propio generador, por lo que no puede desviarse.
Cada operación de escritura realizada a través de esta API queda registrada en el historial de versiones del diseño, exactamente igual que cuando se guarda en la aplicación.
Diseños transaccionales y de marketing
category explica para qué sirve una plantilla. Una plantilla transaccional se envía a todos los destinatarios sin modificaciones. Una plantilla de marketing omite a los destinatarios que se han dado de baja (un paso en el que no se envía el mensaje «Todos los destinatarios del campo "Para" se han dado de baja» y que aparece en el historial como SKIPPED), se envía como un mensaje por cada destinatario del campo «Para» con su propio enlace de baja (un máximo de 20 por paso) y finaliza con la frase de baja y los datos de su empresa. {{ unsubscribe_url }} y {{ unsubscribe_link }}: introduzca usted mismo el enlace; en las plantillas transaccionales, ambos campos están vacíos. La información para los comerciantes se encuentra en Correos electrónicos de marketing y bajas de la lista de suscriptores.
marketingTexts ¿Es el texto del pie de página que utiliza una plantilla de marketing en lugar de los textos generales de la tienda que se configuran en «Ajustes»?
{
"marketingTexts": {
"unsubscribeText": "You get this because you shop with us. {{ unsubscribe_link }}",
"unsubscribeLinkLabel": "Unsubscribe",
"companyDetails": "Example GmbH, Musterstrasse 1, 10115 Berlin"
}
}Todos los campos son opcionales. Si se rellena un campo, se sustituye el texto de configuración correspondiente a ese campo; el resto permanece tal y como está. null (valor por defecto) significa que se utilizan los textos de configuración del idioma del correo electrónico. Límites: unsubscribeText y companyDetails tienen un límite de 2000 caracteres, mientras que unsubscribeLinkLabel tiene un límite de 100. Un unsubscribeText debe contener {{ unsubscribe_link }} o {{ unsubscribe_url }}; de lo contrario, se rechaza la escritura. El campo se almacena para cualquier plantilla, pero solo se envía con las de marketing.
La eliminación de un diseño nunca se bloquea. Si algún paso de Shopify Flow sigue haciendo referencia a él, la respuesta incluye un warning que indica cuántos; dichos pasos fallarán hasta que utilicen otro diseño.
Traducciones
| Método | Ruta | Nivel | Objetivo |
|---|---|---|---|
| OBTENER | /api/v1/email-templates/:id/translations |
leer | Cada idioma de una maquetación con su contenido |
| OBTENER | /api/v1/email-templates/:id/translations/:locale |
leer | Un idioma |
| PUT | /api/v1/email-templates/:id/translations/:locale |
escribir | Crear o sustituir un idioma |
| BORRAR | /api/v1/email-templates/:id/translations/:locale |
escribir | Elimine un idioma. En ese caso, se volverá a utilizar el diseño predeterminado. |
| PUBLICAR | /api/v1/email-templates/:id/translations/:locale/promote |
escribir | Establezca ese idioma como el idioma principal de la maquetación |
:locale Es un código de idioma como, por ejemplo, de, fr o pt-br; no importa si se escribe en mayúsculas o minúsculas, ni el separador. Se admiten hasta 30 idiomas por plantilla. El campo «Idioma» del paso Shopify Flow selecciona uno en el momento del envío: primero la configuración regional exacta, luego el idioma base, después una variante regional y, en su defecto, la propia plantilla.
Un archivo PUT recoge todo el contenido traducido: subject (obligatorio), previewText y bodyDesign (imágenes) o body (texto). Mantenga sin cambios las etiquetas Liquid y las URL. Hay dos campos específicos de la traducción:
| Campo | Diseños de texto | Significado |
|---|---|---|
attachments |
sí | Una lista (con la misma estructura que la de la plantilla) = archivos adjuntos propios de este idioma; [] = ninguno en este idioma; null = enviar los archivos adjuntos de la plantilla. Omitido = mantener la opción actual; un nuevo idioma utiliza los de la plantilla. Las plantillas visuales incluyen sus archivos adjuntos como bloques en el archivo bodyDesign de cada idioma y rechazan este campo. |
marketingTexts |
cualquiera | Los textos del pie de página de este idioma se superponen a los del diseño, campo por campo. null = los del diseño. «Omitido» = mantener la opción actual |
Se devuelve una traducción con los mismos dos campos: attachments es null, aunque utiliza el diseño de la página, y marketingTexts es null, aunque utiliza el diseño de la página.
promote Intercambia la maquetación y la traducción: la maquetación adopta el contenido y la configuración regional de la traducción, y el contenido que tenía pasa a ser la traducción del idioma en el que se encontraba anteriormente. Los archivos adjuntos y los textos del pie de página también intercambian sus posiciones, de modo que cada idioma sigue enviando lo que enviaba anteriormente. La respuesta incluye promoted, previousMainLanguage y el diseño. Se trata de una única versión, por lo que se puede deshacer.
Versiones
| Método | Ruta | Nivel | Objetivo |
|---|---|---|---|
| OBTENER | /api/v1/email-templates/:id/versions |
leer | Versiones guardadas, ordenadas de más reciente a más antigua. La aplicación conserva las 25 más recientes |
| OBTENER | /api/v1/email-templates/:id/versions/:version |
leer | La instantánea completa de una versión: maquetación y todas las traducciones |
| PUBLICAR | /api/v1/email-templates/:id/versions/:version/restore |
escribir | Vuelva a poner esa versión. Se ha grabado como una nueva versión. |
| OBTENER | /api/v1/email-templates/:id/versions/github?page= |
leer | Todas las versiones almacenadas en el repositorio de GitHub vinculado, 20 por página |
| OBTENER | /api/v1/email-templates/:id/versions/github/:sha |
leer | El diseño tal y como estaba en una revisión concreta |
| PUBLICAR | /api/v1/email-templates/:id/versions/github/:sha/restore |
escribir | Restaurar una versión de GitHub, como si se tratara de un guardado |
Los puntos de conexión de GitHub devuelven el código de estado 409 cuando no hay ningún repositorio conectado en la página «Desarrollador». Consulte Historial de versiones del diseño y Guarde un historial ilimitado de diseños en GitHub.
Remitentes de correo electrónico
| Método | Ruta | Nivel | Objetivo |
|---|---|---|---|
| OBTENER | /api/v1/smtp-configs |
leer | Lista de remitentes SMTP |
| OBTENER | /api/v1/senders |
leer | Mostrar una lista de los buzones de correo conectados (Microsoft 365, Google) |
Los remitentes SMTP indican hasUsername y hasPassword en lugar de la credencial en sí; ambas partes se ocultan, ya que el nombre de usuario forma parte de la credencial tanto como la contraseña. Un remitente sigue siendo identificable por su nombre, su servidor y su dirección de origen. Los buzones de correo conectados indican una dirección parcialmente enmascarada, como so***@example.com, y nunca revelan sus tokens de inicio de sesión.
Solo lectura. Conecte y edite los remitentes en la aplicación.
Secretos
| Método | Ruta | Nivel | Objetivo |
|---|---|---|---|
| OBTENER | /api/v1/secrets |
leer | Enumere los nombres secretos y sus descripciones |
Devuelve hasValue, nunca el valor. No existe ningún punto final que permita recuperar un secreto. Cree y actualice los secretos en la aplicación.
Archivos subidos
| Método | Ruta | Nivel | Objetivo |
|---|---|---|---|
| OBTENER | /api/v1/files |
leer | Lista de logotipos, imágenes y archivos adjuntos cargados |
| BORRAR | /api/v1/files |
escribir | Eliminar uno, de key en el cuerpo del texto |
La lista admite page, limit (máximo 100) y q para realizar búsquedas por nombre de archivo.
Añada «?usage=true» y cada archivo indicará además inUse, además de una matriz usedBy en la que se enumeran los diseños y los ajustes preestablecidos que hacen referencia a él. Así es como puede identificar todo lo que puede eliminar con total seguridad en una sola solicitud. La función analiza sus diseños y ajustes preestablecidos, por lo que es una opción que debe activarse manualmente, en lugar de estar activada por defecto.
La función de subida no está disponible aquí; añada los archivos a través del selector de archivos multimedia de la aplicación.
Solicitudes HTTP
| Método | Ruta | Nivel | Objetivo |
|---|---|---|---|
| OBTENER | /api/v1/http-requests |
leer | Listar solicitudes HTTP |
| PUBLICAR | /api/v1/http-requests |
escribir | Cree uno |
| OBTENER | /api/v1/http-requests/:id |
leer | Consiga uno |
| PUT / PATCH | /api/v1/http-requests/:id |
escribir | Primera actualización |
| BORRAR | /api/v1/http-requests/:id |
escribir | Elimine uno |
| PUBLICAR | /api/v1/http-requests/:id/test |
ejecutar | Pruebe el programa con el objetivo real |
«List» admite los mismos parámetros que los diseños de correo electrónico: page, limit y q.
La dirección de destino url debe ser http:// o https://. Si se utiliza cualquier otro esquema, se rechazará al guardar.
Las credenciales literales incluidas en el encabezado o en el cuerpo se ocultan en todas las respuestas. Los valores a los que se hace referencia como {{ secrets.KEY }} se devuelven tal y como están escritos, ya que la propia referencia no es confidencial.
Historia y estadísticas
Abarca tanto el envío de correos electrónicos como las solicitudes HTTP.
| Método | Ruta | Nivel | Objetivo |
|---|---|---|---|
| OBTENER | /api/v1/history |
leer | Ejecución de listas |
| OBTENER | /api/v1/history/:id |
leer | Obtenga una ejecución con los datos de la solicitud y la respuesta |
| OBTENER | /api/v1/stats |
leer | Totales y tasa de éxito |
History admite page, limit (máx. 100), actionType, status (PENDING, SUCCESS, FAILED, SKIPPED) y actionConfigId para filtrar por un único diseño o una única solicitud.
SKIPPED Se trata de un correo electrónico de marketing cuyos destinatarios se habían dado de baja en su totalidad: no se envió nada, no se consumió cuota alguna y no se tiene en cuenta a la hora de calcular la tasa de éxito.
actionType Debe ser exactamente EMAIL o HTTP_REQUEST. Un valor no reconocido se ignora en lugar de rechazarse, por lo que un error tipográfico devuelve todos los resultados en lugar de generar un error.
La variable «Stats» admite valores de days (valor predeterminado: 30; máximo: 365).
Códigos de estado
| Código | Significado |
|---|---|
| 200 | Éxito |
| 201 | Creado |
| 400 | Solicitud incorrecta o validación fallida. El parámetro error indica el nombre del campo; por ejemplo, subject: required |
| 401 | Clave de API ausente, con formato incorrecto o revocada |
| 403 | La clave es válida, pero su nivel es demasiado bajo para este punto final. |
| 404 | No se ha encontrado o pertenece a otra tienda |
| 405 | Método incorrecto para esta ruta |
| 409 | Se ha rechazado porque el registro sigue en uso (eliminación de archivos) o porque GitHub no está conectado (versiones de GitHub) |
| 429 | Límite de frecuencia: véase más abajo |
| 502 | La solicitud se ha ejecutado, pero el destino de terceros ha fallado |
Un registro perteneciente a otra tienda devuelve un código 404 en lugar de un 403, por lo que la API nunca confirma que un identificador exista en otro lugar.
Límites de frecuencia
Dos presupuestos independientes, ambos por llave:
- 300 solicitudes cada 60 segundos en todos los puntos de acceso.
- Además, se realizan 60 llamadas por hora, que abarcan
POST /api/v1/http-requests/:id/test.
Si se supera cualquiera de los dos límites, se devuelve el código de error 429 con la explicación error. El presupuesto de ejecución es deliberadamente ajustado: un bucle sin control que envíe solicitudes reales a un proveedor de pagos supone un fallo mucho más grave que un script lento.
Los presupuestos se establecen por clave, no por tienda, por lo que una integración no puede agotar la asignación de otra.