Referência da API REST
Todos os caminhos são relativos a https://shopify.workflow-transactional-email.app. Todos os pontos finais, exceto o índice, exigem Authorization: Bearer fak_... - consulte Autenticação e chaves de API.
As respostas são em JSON. Os erros seguem o mesmo formato em todos os casos:
{ "error": "Invalid or missing API key" }Índice e identidade
| Método | Caminho | Nível | Objetivo |
|---|---|---|---|
| OBTER | /api/v1 |
nenhum | Índice da API. Confirma se a API está em funcionamento e informa a versão atual |
| OBTER | /api/v1/me |
ler | Verifique se uma chave funciona e veja seu nível de acesso |
O índice não necessita de chave; portanto, é uma verificação de integridade segura para a qual se pode direcionar um monitor.
Layouts de e-mail
| Método | Caminho | Nível | Objetivo |
|---|---|---|---|
| OBTER | /api/v1/email-templates |
ler | Lista de modelos de e-mail. q permite pesquisar por nome, assunto e descrição; category=transactional ou category=marketing exibe um tipo de e-mail |
| POST | /api/v1/email-templates |
escrever | Criar um layout |
| OBTER | /api/v1/email-templates/:id |
ler | Um layout com seu design ou anexos, seus textos de rodapé e a lista de seus idiomas |
| PUT / PATCH | /api/v1/email-templates/:id |
escrever | Alterar um layout. Apenas os campos que o senhor enviar serão alterados |
| EXCLUIR | /api/v1/email-templates/:id |
escrever | Excluir um layout com suas traduções e versões |
| OBTER | /api/v1/layout-schema |
ler | Como criar um layout: o formato de design, as configurações padrão de cada bloco, o Liquid que você pode utilizar, os limites e um exemplo |
A lista aceita page (padrão 1), limit (padrão 25, máximo 100) e q, que realiza a pesquisa por nome, assunto e descrição. Não há filtro por tipo na API; consulte, em vez disso, category para cada layout.
Um layout possui os seguintes campos:
| Campo | Notas |
|---|---|
name, description |
Nome obrigatório, no máximo 200 caracteres; descrição: no máximo 2.000 |
bodyType |
visual (padrão) ou text. Fixo após a criação |
defaultLocale |
O idioma do próprio conteúdo do layout, en, a menos que seja definido |
category |
transactional (padrão) ou marketing. Veja abaixo |
subject, previewText |
É permitido o consumo de bebidas. É obrigatório o cumprimento da disciplina |
bodyDesign |
Layouts visuais: { blocks, global?, header?, footer?, testVariables? }. Envie o design completo ao alterá-lo; o HTML body é gerado a partir dele |
body |
Formatação de texto: o corpo do HTML |
attachments |
Formatações de texto: [{ filename, fileKey, sendAsLink? }] para arquivos enviados (consulte os arquivos abaixo) ou [{ filename, url }] para um arquivo obtido via https no momento do envio do e-mail |
marketingTexts |
Os textos do rodapé de um layout de marketing, ou null. Veja abaixo |
O campo “Liquid” no assunto, no texto de pré-visualização, no corpo e em todos os blocos de texto deve ser analisado, e todos os links fileKey devem pertencer à sua loja; caso contrário, a gravação será recusada com um código de erro 400 que identifica o campo em questão. Leia GET /api/v1/layout-schema antes de criar um design visual: ele é gerado pelo próprio construtor, portanto não pode apresentar divergências.
Cada gravação realizada por meio desta API é mantida no histórico de versões do layout, exatamente como um salvamento no aplicativo.
Layouts transacionais e de marketing
category explica para que serve um layout. Um layout transacional é enviado a todos os destinatários, sem alterações. Um layout de marketing ignora os destinatários que cancelaram a inscrição (uma etapa em que a mensagem “Todos os destinatários do campo ‘Para’ cancelaram a inscrição” não é enviada e aparece como SKIPPED no histórico), é enviado como uma mensagem por destinatário do campo “Para”, com seu próprio link de cancelamento de inscrição (no máximo 20 por etapa), e termina com a frase de cancelamento de inscrição e os dados da sua empresa. {{ unsubscribe_url }} e {{ unsubscribe_link }} - insira o link você mesmo; nos layouts transacionais, ambos os campos ficam em branco. As informações para os lojistas sobre isso estão em E-mails de marketing e cancelamentos de inscrição.
marketingTexts é o texto do rodapé que um layout de marketing utiliza em vez dos textos aplicáveis a toda a loja, definidos em Configurações:
{
"marketingTexts": {
"unsubscribeText": "You get this because you shop with us. {{ unsubscribe_link }}",
"unsubscribeLinkLabel": "Unsubscribe",
"companyDetails": "Example GmbH, Musterstrasse 1, 10115 Berlin"
}
}Todos os campos são opcionais. Um campo definido substitui o texto de “Configurações” referente a esse campo; os demais permanecem inalterados. null (padrão) significa os textos de “Configurações” correspondentes ao idioma do e-mail. Limites: unsubscribeText e companyDetails: 2.000 caracteres; unsubscribeLinkLabel: 100. Um unsubscribeText deve conter {{ unsubscribe_link }} ou {{ unsubscribe_url }}; caso contrário, a gravação será recusada. O campo é armazenado para qualquer layout, mas só é enviado com layouts de marketing.
A exclusão de um layout nunca é bloqueada. Caso ainda haja etapas Shopify Flow que o indiquem, a resposta inclui um warning indicando quantas; essas etapas falharão até que utilizem outro layout.
Traduções
| Método | Caminho | Nível | Objetivo |
|---|---|---|---|
| OBTER | /api/v1/email-templates/:id/translations |
ler | Cada idioma de um layout com seu conteúdo |
| OBTER | /api/v1/email-templates/:id/translations/:locale |
ler | Um idioma |
| PUT | /api/v1/email-templates/:id/translations/:locale |
escrever | Criar ou substituir um idioma |
| EXCLUIR | /api/v1/email-templates/:id/translations/:locale |
escrever | Remova um idioma. Nesse caso, o sistema recorre ao layout padrão |
| POST | /api/v1/email-templates/:id/translations/:locale/promote |
escrever | Defina esse idioma como o idioma principal do layout |
:locale é um código de idioma, como de, fr ou pt-br; não importa se as letras estão em maiúsculas ou minúsculas, nem o separador. São permitidos até 30 idiomas por layout. O campo “Idioma” da etapa Shopify Flow seleciona um deles no momento do envio: a localidade exata, em seguida o idioma base, depois uma variante regional e, caso contrário, o próprio layout.
Um PUT recebe todo o conteúdo traduzido: subject (obrigatório), previewText e bodyDesign (visual) ou body (texto). Mantenha as tags Liquid e as URLs inalteradas. Dois campos são específicos para uma tradução:
| Campo | Formatação de texto | Significado |
|---|---|---|
attachments |
sim | Uma lista (com o mesmo formato do layout) = anexos próprios deste idioma, [] = nenhum neste idioma. null = enviar os anexos do layout. Omitido = manter a opção atual; um novo idioma utiliza os do layout. Os layouts visuais transportam seus anexos como blocos no bodyDesign de cada idioma e rejeitam este campo |
marketingTexts |
qualquer | Os textos do rodapé deste idioma são exibidos sobre os do layout, campo por campo. null = os do layout. “Omitido” = manter a escolha atual |
É retornada uma tradução com os mesmos dois campos: attachments é null, embora utilize o layout, e marketingTexts é null, embora utilize o layout.
promote troca o layout e a tradução: o layout assume o conteúdo e a localização da tradução, e o conteúdo que ele possuía passa a ser a tradução para o idioma em que estava anteriormente. Os anexos e os textos do rodapé também trocam de lugar, de modo que cada idioma continua enviando o que enviava anteriormente. A resposta informa promoted, previousMainLanguage e o layout. Trata-se de uma única versão, portanto, pode ser desfeita.
Versões
| Método | Caminho | Nível | Objetivo |
|---|---|---|---|
| OBTER | /api/v1/email-templates/:id/versions |
ler | Versões salvas, com as mais recentes em primeiro lugar. O aplicativo mantém as 25 mais recentes |
| OBTER | /api/v1/email-templates/:id/versions/:version |
ler | O instantâneo completo de uma versão: layout e todas as traduções |
| POST | /api/v1/email-templates/:id/versions/:version/restore |
escrever | Coloque essa versão de volta. Gravada como uma nova versão |
| OBTER | /api/v1/email-templates/:id/versions/github?page= |
ler | Todas as versões armazenadas no repositório do GitHub vinculado, 20 por página |
| OBTER | /api/v1/email-templates/:id/versions/github/:sha |
ler | O layout tal como estava em um commit |
| POST | /api/v1/email-templates/:id/versions/github/:sha/restore |
escrever | Reverter para uma versão anterior do GitHub, como se fosse um salvamento |
Os endpoints do GitHub retornam o código de erro 409 quando nenhum repositório está conectado na página do Desenvolvedor. Consulte Histórico de versões do layout e Mantenha um histórico ilimitado de layouts no GitHub.
Remetentes de e-mail
| Método | Caminho | Nível | Objetivo |
|---|---|---|---|
| OBTER | /api/v1/smtp-configs |
ler | Listar remetentes SMTP |
| OBTER | /api/v1/senders |
ler | Listar caixas de correio conectadas (Microsoft 365, Google) |
Os remetentes SMTP informam hasUsername e hasPassword em vez da credencial propriamente dita - ambas as partes são ocultadas, uma vez que o nome de usuário faz parte da credencial tanto quanto a senha. Um remetente permanece identificável por meio de seu nome, host e endereço de origem. As caixas de correio conectadas informam um endereço parcialmente mascarado, como so***@example.com, e nunca seus tokens de login.
Somente leitura. Conecte-se e edite os remetentes no aplicativo.
Segredos
| Método | Caminho | Nível | Objetivo |
|---|---|---|---|
| OBTER | /api/v1/secrets |
ler | Liste nomes secretos e descrições |
Retorna hasValue, nunca o valor. Não há nenhum endpoint que leia um segredo de volta. Crie e atualize segredos no aplicativo.
Arquivos enviados
| Método | Caminho | Nível | Objetivo |
|---|---|---|---|
| OBTER | /api/v1/files |
ler | Lista de logotipos, imagens e anexos enviados |
| EXCLUIR | /api/v1/files |
escrever | Excluir um, por key no corpo do texto |
A lista aceita page, limit (máximo de 100) e q para realizar pesquisas por nome de arquivo.
Adicione ?usage=true e cada arquivo também exibirá inUse, além de uma matriz usedBy que lista os layouts e predefinições que o referenciam. É assim que você identifica tudo o que pode ser excluído com segurança em uma única solicitação. O recurso verifica seus layouts e predefinições; portanto, é opcional e não vem ativado por padrão.
O envio de arquivos não está disponível aqui - adicione arquivos por meio do seletor de mídia do aplicativo.
Solicitações HTTP
| Método | Caminho | Nível | Objetivo |
|---|---|---|---|
| OBTER | /api/v1/http-requests |
ler | Listar solicitações HTTP |
| POST | /api/v1/http-requests |
escrever | Crie um |
| OBTER | /api/v1/http-requests/:id |
ler | Adquira um |
| PUT / PATCH | /api/v1/http-requests/:id |
escrever | Atualização 1 |
| EXCLUIR | /api/v1/http-requests/:id |
escrever | Excluir um |
| POST | /api/v1/http-requests/:id/test |
executar | Execute-o no alvo real |
A função “List” aceita os mesmos parâmetros page, limit e q que os layouts de e-mail.
O endereço de destino url deve ser http:// ou https://. Outros esquemas são rejeitados ao salvar.
As credenciais literais inseridas no cabeçalho ou no corpo são ocultadas em todas as respostas. Os valores referenciados como {{ secrets.KEY }} são retornados exatamente como foram escritos, pois a referência em si não contém informações confidenciais.
História e estatísticas
Abrange tanto o envio de e-mails quanto as solicitações HTTP.
| Método | Caminho | Nível | Objetivo |
|---|---|---|---|
| OBTER | /api/v1/history |
ler | Execuções de listas |
| OBTER | /api/v1/history/:id |
ler | Obter uma execução com os dados da solicitação e da resposta |
| OBTER | /api/v1/stats |
ler | Totais e taxa de sucesso |
A propriedade “history” aceita os valores page, limit (máximo de 100), actionType, status (PENDING, SUCCESS, FAILED, SKIPPED) e actionConfigId para filtrar por um único layout ou solicitação.
SKIPPED trata-se de um e-mail de marketing cujos destinatários haviam cancelado o recebimento: nada foi enviado, nenhuma cota foi utilizada e isso não conta para a taxa de sucesso.
actionType deve ser exatamente EMAIL ou HTTP_REQUEST. Um valor não reconhecido é ignorado, em vez de ser rejeitado; portanto, um erro de digitação retorna todos os resultados, em vez de gerar um erro.
O Stats aceita days (padrão: 30; máximo: 365).
Códigos de status
| Código | Significado |
|---|---|
| 200 | Sucesso |
| 201 | Criado |
| 400 | Solicitação inválida ou falha na validação. O parâmetro error indica o nome do campo; por exemplo, subject: required |
| 401 | Chave de API ausente, com formato incorreto ou revogada |
| 403 | A chave é válida, mas seu nível é muito baixo para este endpoint |
| 404 | Não encontrado ou pertence a outra loja |
| 405 | Método incorreto para este caminho |
| 409 | Recusado porque o registro ainda está em uso (exclusão de arquivo) ou porque o GitHub não está conectado (versões do GitHub) |
| 429 | Limitação de taxa - veja abaixo |
| 502 | A solicitação foi executada, mas o destino de terceiros apresentou falha |
Um registro pertencente a outra loja retorna o código 404 em vez de 403; portanto, a API nunca confirma se um ID existe em outro lugar.
Limites de taxa
Dois orçamentos independentes, ambos por chave:
- 300 solicitações a cada 60 segundos em todos os pontos de extremidade.
- Além disso, são realizadas 60 chamadas por hora, abrangendo
POST /api/v1/http-requests/:id/test.
O excedimento de qualquer um desses limites retorna o código 429, acompanhado da mensagem explicativa error. O orçamento de execução é deliberadamente restrito: um loop descontrolado que envia solicitações ativas a um provedor de pagamentos representa uma falha muito mais grave do que um script lento.
Os orçamentos são definidos por chave, e não por loja; portanto, uma integração não pode esgotar o limite de outra.