Integração com o 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 na Transloadit. As ações predefinidas da integração, como Optimize Video, continuam disponíveis para Zaps antigos, mas os Templates dão a você controle sobre 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 incorporar logotipos automaticamente aos vídeos conforme são adicionados ao Google Drive EN (English).

O caminho mais rápido para um Zap funcionar

Use esta lista de verificação para validar a conexão antes de criar 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 total 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 atinge o estado 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 pronto em outro app antes de ativar o fluxo de trabalho.

Criar um Template de teste de fumaça

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 de trabalho 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 ativo. Você pode encontrá-los na página de credenciais. Uma chave de escopo restrito precisa de templates:read para que o Zapier possa preencher a lista suspensa de Templates, de assemblies:read para testar a conexão e consultar periodicamente os gatilhos de conclusão, e de 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 do Google Drive, um anexo de e-mail ou uma URL de upload de formulário. Use dados recentes no teste do gatilho e mantenha o primeiro arquivo bem abaixo de 100 MB para que o Zapier consiga obtê-lo de forma confiável.

Se você usa Workspaces separados na Transloadit para homologação e produção, dê à conexão do Zapier um nome que identifique 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 reduz muito a chance de você testar um Zap em um Workspace e depois se perguntar 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 que você conecte 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 rótulos específicos ou os rótulos genéricos mais antigos:

• Transloadit Auth Key ou Key corresponde à sua Auth Key da Transloadit.
• Transloadit Auth Secret ou Secret corresponde ao Auth Secret da Transloadit associado a essa chave.

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 sua 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 identifique claramente o Workspace, por exemplo Transloadit production ou Transloadit staging.

Se você fizer a rotação da Auth Key na Transloadit, desativá-la ou excluí-la, reconecte a conta no 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 na 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 este campo vazio somente quando o Template obtiver sua própria entrada, por exemplo, com um Robot de importação ou de geração por 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 o campo que aponta 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 publicamente acessível 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 do Zap⁠.

File(s) é um campo de lista. Mapeie cada anexo para um item separado da lista quando uma única Assembly precisar de vários uploads. Não cole várias URLs separadas por vírgulas em um único item da lista, 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; aguarde até que atinja 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 Assembly ID, o valor atual de Assembly Status e 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 de verdade. Se o teste do Zapier for bem-sucedido, mas você não vir uma nova Assembly, o Zap provavelmente está conectado a um Workspace diferente daquele que você está verificando.

Usar um resultado pronto em outro app

Create Assembly inicia o trabalho de forma assíncrona. Não mapeie uma URL de resultado dessa ação diretamente para a próxima etapa do Zap. Um teste que apenas lê metadados pode terminar rápido o bastante para fazer isso parecer confiável, enquanto fluxos com vídeos, documentos e imagens maiores terminam mais tarde.

Use dois Zaps quando outro app precisar do arquivo processado:

1. Zap de entrada: gatilho do app de origem → Transloadit Create Assembly.
2. Zap de resultado: gatilho Assembly Result da Transloadit → sua ação no app de destino.

No gatilho Assembly Result, selecione o mesmo Template ID e informe o nome exato do Step de resultado do Template. Para o Template de teste de fumaça 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 como alternativa se o segundo Zap precisar apenas de metadados de conclusão, e não de um arquivo de resultado específico. Esses gatilhos usam polling, então o tempo até o Zap de resultado iniciar depende do seu plano do Zapier e é separado do tempo de processamento da Transloadit.

Problemas comuns de autenticação

O Zapier diz 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 se a chave está ativa e tem acesso assemblies:read, que o Zapier usa para testar a conexão.

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

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

Se a lista suspensa de Templates estiver vazia, reconecte a Transloadit no Zapier com uma Auth Key do Workspace ao qual seu Template pertence e confirme se 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 costuma ser a configuração do Template ou um campo de arquivo de entrada inutilizável.

O Zap funcionava antes, mas agora falha

Verifique se a Auth Key passou por rotação, foi desativada ou 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 posteriores não veem o arquivo de resultado

Use a configuração com dois Zaps em Usar um resultado pronto em outro app. No Zap de resultado, verifique se Step corresponde exatamente ao nome de um Step de resultado no Template; não se trata de um nome de Robot nem de um nome 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 de o arquivo estar disponível ou fornecem uma URL que o Zapier não consegue enviar como um 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 acesso ao arquivo exigir permissões privadas do app, use o objeto de arquivo que o Zapier recebeu da etapa do gatilho, não uma URL do Dropbox ou do Google Drive copiada do navegador. Teste o gatilho novamente se a amostra não mostrar um arquivo ou apresentar 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. Por isso, use um arquivo menor na configuração, mesmo que a Transloadit aceite uploads maiores.

O que coletar antes de entrar em contato com o suporte

Se ainda precisar de ajuda, envie para nós:

• 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, se uma Assembly tiver 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 para uso

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

Criar seus próprios Zaps

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

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

2. Envio de 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 desse campo, enquanto as ações predefinidas mais 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 → envie uma mensagem no Slack”.

Solução de problemas

• Evite loops no Zap: para evitar loops, não dispare ações de Assembly na mesma pasta que recebe os arquivos finalizados dos 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, confira: 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⁠.