Referência da API REST

Todos os caminhos são relativos a https://shopify.workflow-transactional-email.app. Todos os pontos finais, com exceção do índice, requerem Authorization: Bearer fak_... - consulte Autenticação e chaves de API.

As respostas são em formato JSON. Os erros apresentam sempre a mesma estrutura:

{ "error": "Invalid or missing API key" }

Índice e identidade

Método	Caminho	Nível	Objetivo
OBTER	/api/v1	nenhum	Índice da API. Confirma que a API está operacional e indica a versão atual
OBTER	/api/v1/me	ler	Verifique se uma chave funciona e veja o seu nível de acesso

O índice não necessita de chave, pelo que constitui uma verificação de estado segura à 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 apresenta um único tipo de e-mail
PUBLICAÇÃO	/api/v1/email-templates	escrever	Criar um layout
OBTER	/api/v1/email-templates/:id	ler	Um modelo com o seu design ou anexos, os textos do rodapé e a lista dos idiomas disponíveis
PUT / PATCH	/api/v1/email-templates/:id	escrever	Alterar um layout. Apenas os campos que enviar serão alterados
ELIMINAR	/api/v1/email-templates/:id	escrever	Eliminar um layout com as respetivas traduções e versões
OBTER	/api/v1/layout-schema	ler	Como escrever um layout: o formato de design, as predefinições de cada bloco, o Liquid que pode utilizar, os limites e um exemplo

A lista aceita page (valor predefinido 1), limit (valor predefinido 25, máximo 100) e q, que pesquisa por nome, assunto e descrição. Não existe um filtro por tipo na API; em vez disso, consulte category para cada layout.

Um layout inclui os seguintes campos:

Campo	Notas
name, description	Nome obrigatório, no máximo 200 caracteres; descrição no máximo 2000
bodyType	visual (padrão) ou text. Fixo após a criação
defaultLocale	A língua do próprio conteúdo do layout, en, a menos que seja definida
category	transactional (padrão) ou marketing. Ver abaixo
subject, previewText	É permitido o consumo de bebidas. É obrigatório o cumprimento desta regra.
bodyDesign	Layouts visuais: { blocks, global?, header?, footer?, testVariables? }. Envie o design completo sempre que o alterar; o código HTML body é gerado a partir desse design
body	Disposição do texto: o corpo do HTML
attachments	Formatos de texto: [{ filename, fileKey, sendAsLink? }] para ficheiros carregados (ver ficheiros abaixo) ou [{ filename, url }] para um ficheiro obtido via https quando o e-mail for enviado
marketingTexts	Os textos do rodapé de um layout de marketing, ou null. Ver abaixo

O «Liquid» no assunto, no texto de pré-visualização, no corpo e em todos os blocos de texto tem de ser analisado, e todos os fileKey têm de pertencer à sua loja; caso contrário, a gravação é recusada com um código de erro 400 que indica o campo em questão. Consulte GET /api/v1/layout-schema antes de criar um design visual: este é gerado pelo próprio construtor, pelo que não pode sofrer alterações.

Cada gravação efetuada através desta API é registada no histórico de versões do layout, tal como acontece quando se guarda na aplicação.

Layouts transacionais e de marketing

category explica qual é a finalidade de um layout. Um layout transacional é enviado a todos os destinatários, sem alterações. Um modelo de marketing ignora os destinatários que cancelaram a subscrição (uma etapa em que a mensagem «Todos os destinatários do campo "Para" cancelaram a subscrição» não é enviada e aparece como SKIPPED no histórico), é enviado como uma mensagem por destinatário do campo «Para», com o seu próprio link de cancelamento de subscrição (no máximo 20 por etapa), e termina com a frase de cancelamento de subscrição e os dados da sua empresa. {{ unsubscribe_url }} e {{ unsubscribe_link }} insira o link você mesmo; nos layouts transacionais, ambos estão em branco. A parte relativa ao lojista encontra-se em E-mails de marketing e cancelamentos de subscrição.

marketingTexts O texto do rodapé é aquele que um layout de marketing utiliza em vez dos textos aplicáveis a toda a loja, definidos em «Definiçõ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 das «Definições» para esse campo; os restantes permanecem inalterados. null (o valor predefinido) significa os textos das «Definições» para o idioma do e-mail. Limites: unsubscribeText e companyDetails têm um limite de 2000 caracteres; unsubscribeLinkLabel tem um limite de 100. Um unsubscribeText deve conter {{ unsubscribe_link }} ou {{ unsubscribe_url }}; caso contrário, a gravação é recusada. O campo é armazenado para qualquer layout, mas apenas enviado com os layouts de marketing.

A eliminação de um layout nunca é bloqueada. Se ainda houver etapas de Shopify Flow associadas a esse layout, a resposta inclui um parâmetro warning que indica o número dessas etapas; essas etapas falham até que seja utilizado outro layout.

Traduções

Método	Caminho	Nível	Objetivo
OBTER	/api/v1/email-templates/:id/translations	ler	Cada idioma de um layout com o seu conteúdo
OBTER	/api/v1/email-templates/:id/translations/:locale	ler	Uma língua
PUT	/api/v1/email-templates/:id/translations/:locale	escrever	Criar ou substituir um idioma
ELIMINAR	/api/v1/email-templates/:id/translations/:locale	escrever	Remova um idioma. Nesse caso, o sistema recorre ao layout
PUBLICAÇÃO	/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 são maiúsculas ou minúsculas, nem o separador. Até 30 idiomas por layout. O campo «Idioma» da etapa Shopify Flow seleciona um no momento do envio: a localização exata, depois o idioma base, depois uma variante regional e, caso contrário, o próprio layout.

Um ficheiro PUT inclui todo o conteúdo traduzido: subject (obrigatório), previewText e bodyDesign (imagem) ou body (texto). Mantenha as tags Liquid e os URLs inalterados. Dois campos são específicos de uma tradução:

Campo	Formatação de texto	Significado
attachments	sim	Uma lista (com a mesma estrutura que a do layout) = anexos próprios deste idioma, [] = nenhum neste idioma. null = enviar os anexos do layout. Omitido = manter a escolha atual; um novo idioma utiliza os do layout. Os layouts visuais incluem os seus anexos como blocos no ficheiro bodyDesign de cada idioma e rejeitam este campo
marketingTexts	qualquer	Os textos do rodapé deste idioma sobrepõem-se aos do layout, campo a campo. null = os do layout. «Omitido» = manter a escolha atual

É devolvida uma tradução com os mesmos dois campos: attachments corresponde a null, embora utilize o layout, e marketingTexts corresponde a null, embora utilize o layout.

promote troca o layout e a tradução: o layout passa a ter o conteúdo e a configuração regional da tradução, e o conteúdo que tinha passa a ser a tradução para o idioma em que se encontrava anteriormente. Os anexos e os textos do rodapé também trocam de lugar, para que cada idioma continue a enviar o que enviava anteriormente. A resposta indica promoted, previousMainLanguage e o layout. Trata-se de uma única versão, pelo que pode ser desfeita.

Versões

Método	Caminho	Nível	Objetivo
OBTER	/api/v1/email-templates/:id/versions	ler	Versões guardadas, com as mais recentes em primeiro lugar. A aplicação guarda 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
PUBLICAÇÃO	/api/v1/email-templates/:id/versions/:version/restore	escrever	Volte a colocar essa versão. Gravada como uma nova versão
OBTER	/api/v1/email-templates/:id/versions/github?page=	ler	Todas as versões guardadas no repositório GitHub associado, 20 por página
OBTER	/api/v1/email-templates/:id/versions/github/:sha	ler	O layout tal como se apresentava numa determinada versão
PUBLICAÇÃO	/api/v1/email-templates/:id/versions/github/:sha/restore	escrever	Reverter para uma versão anterior do GitHub, como se fosse um registo

Os pontos de acesso do GitHub devolvem o código de erro 409 quando não há nenhum repositório associado na página «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	Lista de remetentes SMTP
OBTER	/api/v1/senders	ler	Listar caixas de correio associadas (Microsoft 365, Google)

Os remetentes SMTP indicam hasUsername e hasPassword em vez da credencial propriamente dita - ambas as partes são ocultadas, uma vez que o nome de utilizador faz parte da credencial tanto quanto a palavra-passe. Um remetente continua a ser identificável pelo seu nome, anfitrião e endereço de origem. As caixas de correio ligadas indicam um endereço parcialmente mascarado, como so***@example.com, e nunca os seus tokens de início de sessão.

Apenas para leitura. Ligue e edite os remetentes na aplicação.

Segredos

Método	Caminho	Nível	Objetivo
OBTER	/api/v1/secrets	ler	Enumere os nomes secretos e as respetivas descrições

Devolve hasValue, nunca o valor. Não existe nenhum ponto de extremidade que permita recuperar um segredo. Crie e atualize segredos na aplicação.

Ficheiros carregados

Método	Caminho	Nível	Objetivo
OBTER	/api/v1/files	ler	Lista de logótipos, imagens e anexos carregados
ELIMINAR	/api/v1/files	escrever	Eliminar um, por key, no corpo do texto

A lista aceita page, limit (máximo de 100) e q para efetuar pesquisas por nome de ficheiro.

Adicione ?usage=true e cada ficheiro apresenta também inUse, além de um conjunto de usedBy que indica os layouts e as predefinições que o referenciam. É assim que pode identificar tudo o que é seguro eliminar numa única solicitação. Esta funcionalidade analisa os seus layouts e predefinições, pelo que é uma opção que deve ativar, não sendo a predefinição.

O envio de ficheiros não está disponível aqui - adicione ficheiros através do seletor de multimédia da aplicação.

Pedidos HTTP

Método	Caminho	Nível	Objetivo
OBTER	/api/v1/http-requests	ler	Listar pedidos HTTP
PUBLICAÇÃO	/api/v1/http-requests	escrever	Criar um
OBTER	/api/v1/http-requests/:id	ler	Adquira um
PUT / PATCH	/api/v1/http-requests/:id	escrever	Primeira atualização
ELIMINAR	/api/v1/http-requests/:id	escrever	Apagar um
PUBLICAÇÃO	/api/v1/http-requests/:id/test	executar	Execute-o no alvo real

A «List» aceita os mesmos parâmetros page, limit e q que os modelos de e-mail.

O endereço de destino url deve ser http:// ou https://. Outros esquemas são rejeitados quando guardar.

As credenciais literais incluídas num cabeçalho ou no corpo da mensagem são ocultadas em todas as respostas. Os valores referenciados como {{ secrets.KEY }} são devolvidos tal como estão, uma vez que a própria referência não é sensível.

História e estatísticas

Abrange tanto o envio de e-mails como os pedidos 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 do pedido e da resposta
OBTER	/api/v1/stats	ler	Totais e taxa de sucesso

O History aceita page, limit (máx. 100), actionType, status (PENDING, SUCCESS, FAILED, SKIPPED) e actionConfigId para filtrar por um único layout ou pedido.

SKIPPED trata-se de um e-mail de marketing cujos destinatários tinham todos cancelado a subscrição: não foi enviado nada, não foi utilizada qualquer cota e 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; assim, um erro ortográfico devolve todos os resultados em vez de gerar um erro.

A função Stats aceita valores de days (valor predefinido: 30; máximo: 365).

Códigos de estado

Código	Significado
200	Sucesso
201	Criado
400	Pedido com formato incorreto ou falha na validação. O parâmetro error indica o nome do campo; por exemplo, subject: required
401	Chave API em falta, com formato incorreto ou revogada
403	A chave é válida, mas o seu nível é demasiado baixo para este ponto final
404	Não foi encontrado ou pertence a outra loja
405	Método incorreto para este caminho
409	Recusado porque o registo ainda está a ser utilizado (eliminação de ficheiros) ou porque o GitHub não está ligado (versões do GitHub)
429	Limitação de taxa - ver abaixo
502	A solicitação foi executada, mas o destino de terceiros falhou

Um registo pertencente a outra loja devolve um código 404 em vez de 403, pelo que a API nunca confirma que um ID exista noutro local.

Limites de taxa

Dois orçamentos independentes, ambos por chave:

• 300 pedidos por cada 60 segundos em todos os pontos de extremidade.
• Além disso, são realizadas 60 chamadas por hora, abrangendo a região de POST /api/v1/http-requests/:id/test.

Se qualquer um destes valores for excedido, é devolvido o código de erro 429, acompanhado da mensagem explicativa error. O orçamento de execução é deliberadamente restrito: um ciclo infinito que envia pedidos em tempo real a um prestador de serviços de pagamento constitui uma falha muito mais grave do que um script lento.

Os orçamentos são por chave, não por loja, pelo que uma integração não pode esgotar a dotação de outra.