Autenticação e chaves de API

Tanto a API REST quanto o servidor MCP utilizam a mesma credencial: uma chave de API criada na página “Desenvolvedor” dentro do aplicativo.

URL base

Todas as solicitações devem ser encaminhadas para:

text

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

Cada endpoint abaixo é relativo a esse host; portanto, o caminho completo para o índice é https://shopify.workflow-transactional-email.app/api/v1.

Criação de uma chave

Abra o Developer na aplicação, escolha um nível de acesso e crie a chave. O valor completo é exibido uma única vez, no momento da criação. Copie-o nesse momento e armazene-o em seu gerenciador de senhas ou repositório de segredos - ele não poderá ser recuperado posteriormente, pois apenas um hash SHA-256 dele é mantido.

As chaves sempre começam com fak_, o que facilita sua identificação em um verificador de senhas.

Envie-o como um token ao 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 é a maneira mais rápida de confirmar se uma chave funciona e de verificar qual nível ela possui.

Níveis de acesso

Os níveis são hierárquicos e cumulativos: cada um inclui tudo o que está abaixo dele.

Nível	O que isso acrescenta
Somente leitura	Leia layouts de e-mails, remetentes de e-mails, nomes secretos, arquivos enviados, solicitações HTTP, histórico e estatísticas
Leitura e gravação	Criar, editar e excluir solicitações HTTP, bem como excluir arquivos enviados que não estejam em uso
Ler, gravar e executar	Execute uma solicitação HTTP direcionada ao seu destino real

Observe como os dois níveis superiores são restritos. Tudo o que diz respeito ao e-mail é de leitura, e nada é de gravação, em nenhum nível - veja abaixo.

O que uma chave de gravação pode e não pode alterar

Pode: criar, editar, excluir e executar solicitações HTTP, bem como excluir arquivos enviados aos quais nenhum outro arquivo faça referência.

Não é possível: alterar nada que determine o que seus clientes recebem. Os layouts de e-mail, os remetentes de e-mail e os segredos não possuem endpoint de gravação em nenhum nível de acesso, e não há nenhum endpoint para envio de e-mail. O e-mail é enviado quando o seu fluxo de trabalho Shopify Flow executa a ação “Enviar e-mail transacional”; a API apenas registra e relata isso posteriormente.

A exclusão do arquivo também é recusada enquanto qualquer layout ou predefinição ainda estiver utilizando o arquivo; portanto, uma tecla de gravação não pode danificar um e-mail ativo ao remover seu logotipo.

Caso precise alterar um layout ou conectar um remetente, faça isso no aplicativo.

Por que a execução é separada

A execução de uma solicitação HTTP envia uma solicitação real a um sistema de terceiros real. Manter isso em um nível separado significa que uma chave que o senhor fornece a um script - ou a um assistente de IA - para leitura e edição da configuração não pode enviar solicitações às suas integrações ativas.

Conceda permissões de leitura por padrão. Adicione permissões de gravação ou execução somente quando uma tarefa específica as necessitar.

Revogação de uma chave

Exclua a chave na página “Desenvolvedor”. A revogação entra em vigor na próxima solicitação - não há cache a ser aguardado.

Revogue e reemita a chave caso ela tenha sido enviada para um repositório, colada em um documento compartilhado ou fornecida a um prestador de serviços que não precise mais dela.

Bons hábitos

Faça referência às credenciais como {{ secrets.KEY }} em suas solicitações HTTP, em vez de colá-las no cabeçalho ou no corpo da solicitação. As credenciais literais são ocultadas nas respostas da API, mas é preferível fazer referência a um segredo.
Utilize uma chave por consumidor, para que você possa revogar uma única integração sem afetar as demais.
Mantenha as chaves de execução fora dos laptops dos desenvolvedores e fora das configurações do assistente de IA, a menos que você deseje especificamente que o assistente possa enviar solicitações em tempo real.