Autenticación y claves de API

Tanto la API REST como el servidor MCP utilizan la misma credencial: una clave de API creada en la página «Desarrollador» de la aplicación.

URL base

Todas las solicitudes deben dirigirse a:

text

https://shopify.workflow-transactional-email.app

Cada punto final que se indica a continuación es relativo a ese host, por lo que la ruta completa del índice es https://shopify.workflow-transactional-email.app/api/v1.

Creación de una clave

Abra Developer en la aplicación, seleccione un nivel de acceso y cree la clave. El valor completo se muestra una sola vez, en el momento de la creación. Cópielo entonces y guárdelo en su gestor de contraseñas o en su tienda de secretos; no podrá recuperarlo posteriormente, ya que solo se conserva un hash SHA-256 del mismo.

Las claves siempre comienzan por fak_, lo que facilita su identificación en un escáner de claves secretas.

Envíelo como un token al portador:

vbnet

GET /api/v1/me HTTP/1.1
Host: shopify.workflow-transactional-email.app
Authorization: Bearer fak_your_key_here

GET /api/v1/me Es la forma más rápida de comprobar si una llave funciona y de ver qué nivel tiene.

Niveles de acceso

Los niveles están ordenados y son acumulativos: cada uno incluye todo lo que se encuentra por debajo de él.

Nivel	Qué aporta
Solo lectura	Leer diseños de correo electrónico, remitentes, nombres ocultos, archivos adjuntos, solicitudes HTTP, historial y estadísticas
Lectura y escritura	Crear, editar y eliminar solicitudes HTTP, así como eliminar los archivos subidos que no se utilicen
Leer, escribir y ejecutar	Realice una solicitud HTTP dirigida a su destino real

Fíjese en lo limitados que son los dos niveles superiores. Todo lo relacionado con el correo electrónico es de solo lectura y no se puede modificar en ningún nivel; véase más abajo.

Lo que una clave de escritura puede y no puede modificar

Puede: crear, editar, eliminar y ejecutar solicitudes HTTP, así como eliminar archivos subidos a los que no haga referencia ningún otro elemento.

No es posible: modificar nada que determine lo que reciben sus clientes. Los diseños de correo electrónico, los remitentes y los datos confidenciales no disponen de ningún punto final de escritura en ningún nivel de acceso, y no existe ningún punto final para el envío de correo electrónico. El correo electrónico se envía cuando su flujo de trabajo de Shopify Flow ejecuta la acción «Enviar correo electrónico transaccional»; la API únicamente lo registra y lo notifica posteriormente.

La eliminación de un archivo tampoco se permite mientras haya alguna plantilla o configuración preestablecida que siga utilizando dicho archivo, por lo que una tecla de escritura no puede alterar un correo electrónico activo al eliminar su logotipo.

Si necesita modificar una plantilla o configurar un remitente, hágalo en la aplicación.

¿Por qué la ejecución es independiente?

Al ejecutar una solicitud HTTP, se envía una solicitud real a un sistema de terceros real. Mantener esto en un nivel separado significa que una clave que se facilite a un script - o a un asistente de IA - para leer y editar la configuración no podrá enviar solicitudes a sus integraciones activas.

Asigne claves de lectura de forma predeterminada. Añada derechos de escritura o de ejecución únicamente cuando un trabajo concreto los requiera.

Los secretos nunca son legibles, a ningún nivel

Los valores secretos, los nombres de usuario y las contraseñas de SMTP, así como los tokens de buzones conectados, no pueden recuperarse a través de ninguna de las dos interfaces. Ni con una clave de escritura, ni con una clave de ejecución, ni a través de MCP. No existe ningún punto final ni ninguna herramienta que los devuelva.

En su lugar, se le proporcionan indicadores y nombres secretos del tipo hasValue, hasUsername y hasPassword, lo cual es suficiente para que un asistente pueda hacer referencia a {{ secrets.stripeApiKey }} sin llegar a ver nunca el valor. Siempre puede establecer un nuevo valor; nunca podrá recuperar uno anterior.

La consecuencia práctica: si se filtra una clave de lectura, se expone su configuración, no sus credenciales.

Revocación de una clave

Elimine la clave en la página «Desarrollador». La revocación surtirá efecto en la siguiente solicitud; no hay que esperar a que se actualice la caché.

Revoque y vuelva a emitir la clave si esta se ha guardado en un repositorio, se ha pegado en un documento compartido o se ha facilitado a un colaborador que ya no la necesita.

Buenos hábitos

En sus solicitudes HTTP, haga referencia a las credenciales como {{ secrets.KEY }}, en lugar de pegarlas en un encabezado o en el cuerpo de la solicitud. Las credenciales literales se ocultan en las respuestas de la API, pero es preferible hacer referencia a un secreto.
Utilice una clave por consumidor, de modo que pueda revocar una sola integración sin que ello afecte a las demás.
Mantenga las claves de ejecución fuera de los ordenadores portátiles de los desarrolladores y fuera de las configuraciones de los asistentes de IA, a menos que desee específicamente que el asistente pueda enviar solicitudes en tiempo real.