Integração com Zapier

O Zapier permite enviar arquivos do Dropbox, Gmail, Slack, Google Drive e milhares de outros apps para a Transloadit sem escrever código. A Transloadit então executa um Template salvo para cada ação do Zapier, como converter um vídeo, extrair texto de um documento, otimizar uma imagem ou armazenar um arquivo finalizado no seu bucket na nuvem.

Para novos fluxos de trabalho, use a ação Create Assembly do Zapier. Ela funciona com qualquer Template salvo da Transloadit. As ações predefinidas da integração, como Optimize Video, continuam disponíveis para Zaps antigos, mas os Templates permitem controlar todo o fluxo de processamento de arquivos.

O modelo mental importante é:

1. Primeiro, crie e teste o fluxo de processamento de arquivos na Transloadit.
2. Salve esse fluxo como um Template.
3. Conecte o Zapier ao Workspace da Transloadit ao qual o Template pertence.
4. No Zapier, escolha o Template e mapeie arquivos ou campos da etapa anterior do Zap.

Para um exemplo completo de fluxo de trabalho, veja nosso tutorial sobre como inserir logotipos automaticamente em vídeos assim que são adicionados ao Google Drive.

O caminho mais rápido para um Zap bem-sucedido

Use esta lista para validar a conexão antes de montar seu fluxo de produção:

1. Crie um Template chamado zapier-smoke-test usando o JSON abaixo.
2. Crie uma Auth Key no mesmo Workspace com as permissões templates:read, assemblies:read e assemblies:write. O acesso completo também funciona, mas concede mais acesso do que esta integração precisa.
3. No Zapier, crie e teste o gatilho do app de origem com um arquivo novo e pequeno.
4. Adicione a ação Create Assembly da Transloadit e conecte a Auth Key e o Auth Secret correspondente.
5. Selecione zapier-smoke-test em Template ID e mapeie o arquivo de origem para File(s).
6. Teste a ação e verifique se a Assembly aparece na sua página de Assemblies e chega a ASSEMBLY_COMPLETED.

Quando isso funcionar, selecione seu Template de produção. Se uma etapa posterior do Zap precisar do arquivo processado, siga Usar um resultado finalizado em outro app antes de ativar o fluxo.

Criar um Template para teste básico

Crie um Template chamado zapier-smoke-test com estas Instructions:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "metadata": {
      "use": ":original",
      "robot": "/meta/read",
      "result": true
    }
  }
}

Este Template aceita um upload e lê seus metadados sem armazená-lo nem transformá-lo. É uma forma rápida e de baixo custo de isolar a autenticação do Zapier e o mapeamento de arquivos da complexidade do seu fluxo real.

Antes de abrir o Zapier

Prepare estes valores antes de abrir o Zapier:

• Um Workspace da Transloadit com uma Auth Key ativa e um Auth Secret. Você pode encontrá-los na página de credenciais. Uma chave com escopo restrito precisa de templates:read para o Zapier preencher a lista de Templates, assemblies:read para testar a conexão e consultar periodicamente os gatilhos de conclusão, e assemblies:write para criar Assemblies.
• Um Template salvo no mesmo Workspace. O Zapier executa o Template; ele não substitui o Template Editor.
• Um arquivo de teste do app que inicia o Zap, como um arquivo do Dropbox ou Google Drive, um anexo de e-mail ou uma URL de upload de formulário. Use dados de teste recentes do gatilho e mantenha o primeiro arquivo bem abaixo de 100 MB para que o Zapier possa obtê-lo de forma confiável.

Se você usa Workspaces separados da Transloadit para homologação e produção, nomeie a conexão do Zapier de acordo com o ambiente. Por exemplo, use Transloadit staging para uma Auth Key de homologação e Transloadit production para uma Auth Key de produção. Isso ajuda a evitar que você teste um Zap em um Workspace e depois fique sem entender por que o Template de produção não aparece.

Conectar o Zapier à Transloadit

No Zapier, adicione uma ação da Transloadit⁠ e escolha Create Assembly. Quando o Zapier pedir para conectar uma conta da Transloadit, clique em Sign in to Transloadit.

O Zapier então abre uma pequena janela de autenticação. Dependendo da versão do app da Transloadit exibida pelo Zapier, os campos usam os rótulos específicos ou os rótulos genéricos antigos:

• Transloadit Auth Key ou Key é a sua Auth Key da Transloadit.
• Transloadit Auth Secret ou Secret é o Auth Secret correspondente da Transloadit.

A Transloadit não pede ao Zapier a senha da sua conta da Transloadit. O Auth Secret também não é o slug do seu Workspace, o Template ID nem a senha do Zapier.

O Zapier armazena essa conexão na sua conta do Zapier. Zaps futuros podem reutilizá-la, então dê à conexão um nome que deixe claro qual é o Workspace, por exemplo Transloadit production ou Transloadit staging.

Se você rotacionar, desativar ou excluir a Auth Key na Transloadit, reconecte a conta do Zapier com um novo par de chaves. Os Zaps existentes que usam a conexão antiga não poderão mais criar Assemblies.

Configurar a ação Create Assembly

Após a autenticação, o Zapier pergunta como a Assembly da Transloadit deve ser criada.

Configure, no mínimo:

• Template ID: escolha o Template salvo da Transloadit que deve processar o arquivo.
• File(s): para Templates baseados em upload, mapeie o objeto de arquivo ou a URL de download direto da etapa anterior do Zap. Deixe vazio somente quando o Template obtiver sua própria entrada, por exemplo com um Robot de importação ou de geração com IA.
• Assembly Fields: opcionalmente, passe valores como IDs de clientes, IDs de pedidos ou nomes de arquivos para a Assembly, para que apareçam no Assembly Status JSON.

Os apps do Zapier costumam expor vários campos parecidos, como uma URL de prévia, uma URL de visualização na web, um objeto de arquivo e uma URL de download direto. Para a Transloadit, escolha um campo que aponte para os bytes reais do arquivo. Uma página de prévia no navegador não basta. Prefira o objeto de arquivo do app de origem; o Zapier pode exibir seu valor de teste como (Exists but not shown). Se você usar uma URL, ela deve ser acessível publicamente e apontar diretamente para o arquivo, não para uma página de prévia. Veja o guia do Zapier sobre envio de arquivos em fluxos de trabalho de Zaps⁠.

File(s) é um campo de lista. Mapeie cada anexo para um item separado quando uma única Assembly precisar de vários uploads. Não cole várias URLs separadas por vírgulas em um único item, pois o Zapier pode enviar apenas a primeira sem avisar. Uma ação Create Assembly sempre cria uma Assembly; use um loop do Zapier antes da ação se cada arquivo de origem precisar criar uma Assembly separada.

Execute a etapa de teste do Zapier uma vez. Depois, abra a página de Assemblies da Transloadit no mesmo Workspace e confirme que uma nova Assembly apareceu. Ela ainda pode estar em execução quando a ação do Zapier retornar; espere até que chegue a ASSEMBLY_COMPLETED. Se isso acontecer, a autenticação, a seleção do Template e o mapeamento de arquivos estão funcionando.

A ação retorna o Assembly ID, o Assembly Status atual e a Assembly Status URL. Salve o Assembly ID no registro de origem quando precisar de uma referência duradoura para auditoria ou suporte. Essas saídas identificam a Assembly, mas não contêm um arquivo processado enquanto o trabalho assíncrono ainda está em execução.

A Assembly de teste é a fonte da verdade. Se o teste do Zapier passar, mas você não vir uma nova Assembly, o Zap provavelmente está conectado a um Workspace diferente daquele que você está consultando.

Usar um resultado finalizado em outro app

Create Assembly inicia o trabalho de forma assíncrona, e fluxos com vídeos, documentos e imagens maiores podem demorar. Para usar o arquivo processado em uma etapa posterior do Zap, ative Wait for Results na ação:

1. Adicione o gatilho do app de origem e a ação Create Assembly da Transloadit e defina Wait for Results como True.
2. Adicione a ação do app de destino em seguida. Mapeie First Result File para um campo de arquivo, ou First Result URL quando esse app aceitar uma URL pública. Se o Template produzir vários arquivos de resultado, use os campos Result, que o Zapier trata como uma lista.

O Zap pausa em Create Assembly até a Assembly terminar e então continua imediatamente com os resultados. A Transloadit notifica o Zapier pelo notify_url da Assembly, portanto não há atraso de consulta periódica. Se a Assembly falhar, a etapa falha com o erro da Assembly, em vez de continuar sem um arquivo.

Resultados de Assemblies criadas fora do Zap

Quando as Assemblies vêm de outro lugar, como seu site, backend ou um formulário de upload do Uppy, use um segundo Zap que comece com o gatilho Assembly Result da Transloadit. Selecione o Template em Template ID e informe o nome exato do Step de resultado do Template. Para o Template de teste básico acima, o Step é metadata. Mapeie o valor File do gatilho para o campo de arquivo do app de destino, ou use SSL URL quando esse app aceitar uma URL pública.

Use o gatilho Finished Assembly da Transloadit se o segundo Zap precisar apenas de metadados de conclusão, em vez de um arquivo de resultado específico. Esses gatilhos usam consultas periódicas, então o atraso até o Zap iniciar depende do seu plano do Zapier e é separado do tempo de processamento da Transloadit.

Iniciar um Zap instantaneamente quando qualquer Assembly terminar

Para iniciar um Zap assim que uma Assembly terminar, sem consultas periódicas, use o gatilho de webhook do próprio Zapier junto com o notify_url de um Template:

1. Crie um Zap que comece com Webhooks by Zapier → Catch Hook e copie a URL de webhook exibida pelo Zapier.
2. Defina essa URL como notify_url no seu Template, ou passe-a como notify_url quando seu app criar a Assembly.
3. A Transloadit envia o Assembly Status finalizado como uma string JSON no campo transloadit. Adicione uma etapa Formatter ou Code que faça o parsing dela e mapeie seu results para as etapas posteriores.

Isso substitui qualquer notify_url que seu Template já use, portanto apenas um destinatário recebe a notificação, e o Webhooks by Zapier pode exigir um plano pago do Zapier. Veja Webhooks para conhecer o payload e saber como verificar sua assinatura.

Problemas comuns de autenticação

O Zapier informa que as credenciais são inválidas

Verifique se você copiou a Auth Key para o campo Transloadit Auth Key ou Key do Zapier e o Auth Secret correspondente para Transloadit Auth Secret ou Secret. O Auth Secret não é a senha da sua conta nem o slug do Workspace. Confirme também que a chave está ativa e tem acesso assemblies:read, que o Zapier usa para testar a conexão.

O Zapier conecta, mas o Template não aparece ou falha

O motivo mais comum é uma divergência de Workspace. O Zapier autentica no Workspace ao qual a Auth Key pertence. Verifique se o Template que você quer executar pertence ao mesmo Workspace.

Se a lista de Templates estiver vazia, reconecte a Transloadit no Zapier com uma Auth Key do Workspace ao qual seu Template pertence e confirme que a chave tem acesso templates:read. Se o Template aparecer, mas o Zapier não conseguir criar uma Assembly, confirme o acesso assemblies:write. Se uma Assembly for criada, mas falhar, abra-a na Transloadit e inspecione o primeiro Step com erro. Nesse ponto, a autenticação funcionou, e o problema geralmente está na configuração do Template ou em um campo de arquivo de entrada inutilizável.

O Zap funcionava antes, mas agora falha

Verifique se a Auth Key foi rotacionada, desativada, excluída ou teve seus escopos alterados. Reconecte a Transloadit no Zapier após alterações nas credenciais.

O Zap cria uma Assembly, mas as etapas seguintes não veem o arquivo de resultado

Ative Wait for Results em Create Assembly e mapeie seus campos de resultado, conforme descrito em Usar um resultado finalizado em outro app. Lembre-se de que Test step não espera a Assembly; use Test run. Se você usar a configuração com dois Zaps, verifique se o Step do Zap de resultado corresponde exatamente ao nome de um Step de resultado no Template; ele não é um nome de Robot nem de arquivo.

O Dropbox ou o Google Drive não fornece uma URL de arquivo utilizável

Alguns gatilhos de apps expõem metadados antes que o arquivo esteja disponível ou fornecem uma URL que o Zapier não consegue enviar como arquivo para download. Use o painel de resultados de teste do Zapier para confirmar que o campo selecionado aponta para o arquivo binário, não apenas para uma página de prévia.

Se o arquivo estiver protegido por permissões privadas do app, use o objeto de arquivo que o Zapier recebeu da etapa de gatilho, não uma URL do Dropbox ou Google Drive copiada do navegador. Teste o gatilho novamente se a amostra não mostrar um arquivo ou mostrar uma referência expirada. O Zapier avisa que arquivos acima de 100 MB podem exceder o tempo limite e que ele precisa obter um arquivo em até 30 segundos, então use um arquivo menor na configuração, mesmo que a própria Transloadit suporte uploads maiores.

O que reunir antes de entrar em contato com o suporte

Se você ainda precisar de ajuda, envie:

• o app e o gatilho do Zapier que você está usando, por exemplo, Dropbox New File in Folder;
• o nome do Workspace da Transloadit;
• o nome do Template ou o Template ID;
• o ID público da Auth Key, mas não o Auth Secret;
• o Assembly ID do teste que falhou, caso uma Assembly tenha sido criada;
• a URL da execução do Zap;
• qual campo do Zapier você mapeou para File(s).

Com esses detalhes, podemos identificar se o problema está na autenticação, na seleção do Workspace, na configuração do Template, no tratamento de resultados assíncronos ou no campo de arquivo de origem.

Zaps prontos

Explore fluxos de trabalho prontos no diretório de integração da Transloadit no Zapier⁠. Escolha um fluxo e siga as etapas de configuração acima para conectar sua conta.

Criar seus próprios Zaps

Estes tutoriais antigos usam uma interface anterior do Zapier, mas ainda demonstram a mesma arquitetura de entrada e resultado com dois Zaps descrita acima.

1. Enviar vídeos do Dropbox para a Transloadit para otimização para iPad:

2. Enviar vídeos de volta da Transloadit para o Dropbox após a otimização para iPad:

Internamente, a integração adiciona um campo zapier_action_type a cada Assembly. Create Assembly usa o Template ID como valor, enquanto as ações predefinidas antigas usam um identificador fixo de ação. Os gatilhos de conclusão usam esse campo para encontrar Assemblies correspondentes, exceto o gatilho sem filtro Finished Assembly. Isso permite fluxos como “quando a conversão para iPad estiver pronta → enviar mensagem ao Slack”.

Solução de problemas

• Evite loops de Zap: para evitar loops, não dispare ações de Assembly na mesma pasta que recebe os arquivos finalizados dos seus Templates. No caso do Dropbox, use uma pasta para entrada e outra para saída. Para mais informações, veja esta página de ajuda do Zapier⁠.
• Se você tiver problemas com o Dropbox e arquivos grandes, consulte: Problemas comuns com o Dropbox no Zapier⁠.
• O processamento da Transloadit não é bloqueante. Use o gatilho Assembly Result em um segundo Zap, em vez de presumir que um arquivo de resultado estará pronto na etapa imediatamente após Create Assembly.

Documentação

Veja os gatilhos e ações do Zapier compatíveis com a Transloadit⁠ e a documentação de campos de arquivo do Zapier⁠.