Retentativas seguras em uma API de arquivos: evite duplicados

O problema: o timeout não informa se a operação ocorreu

O caso perigoso em uma integração de arquivos não é o erro claro, mas a resposta que nunca chega. Seu backend chama uma API para criar uma pasta, enviar um arquivo, iniciar uma transformação ou preparar um download compartilhado; a conexão é interrompida por timeout; e o cliente não sabe se o servidor executou a ação. Se você simplesmente repetir, pode criar duas pastas, registrar duas cópias do mesmo arquivo, enfileirar duas transformações ou publicar dois links equivalentes.

A primeira decisão operacional é separar leituras de escritas. Em HTTP, métodos como GET, HEAD e OPTIONS são considerados seguros porque o cliente não solicita uma mudança de estado. Já as ações que criam, modificam, movem, eliminam ou enfileiram trabalho devem ser tratadas como escritas. A RFC 9110 define uma requisição idempotente como aquela cujo efeito pretendido ao repetir várias requisições idênticas é o mesmo que ao executá-la uma única vez; por isso, diante de uma falha de comunicação, só convém repetir automaticamente quando a operação foi projetada para suportar isso.

• Leituras: consultar listas, detalhes, estado de um trabalho ou resultados já gerados.
• Escritas: criar pastas, enviar arquivos, atualizar metadados, mover itens, enviar para a lixeira, enfileirar transformações ou criar acessos compartilhados.
• Zona cinzenta: quando você não recebeu resposta, não assuma nem sucesso nem falha; guarde a tentativa e confirme por consulta.

Quais operações de arquivos precisam de proteção

Na Apification Cloud, a integração por API REST servidor a servidor permite gerenciar recursos Cloud, usuários, configuração e trabalhos de transformação a partir do backend de um produto integrador. O Cloud é descrito como um espaço organizado e versionado para gerenciar arquivos, serviços e projetos digitais preparados para compartilhamento. Algumas operações são naturalmente consultivas; outras alteram o estado do workspace onde vivem arquivos, serviços e projetos digitais.

As transformações também exigem cuidado. A Apification permite processar documentos, imagens, vídeo, áudio e dados por meio de um assistente guiado, e sua integração permite gerenciar trabalhos de transformação a partir do backend. Criar ou enviar um trabalho de transformação é uma escrita assíncrona: sua aplicação pode perder a resposta e não saber se o trabalho ficou registrado. Se você repetir sem estado local nem uma identidade lógica estável, pode acabar pagando o custo operacional de dois processos equivalentes ou misturando resultados de versões diferentes do arquivo.

• Proteja toda ação que altere estado como candidata a repetição controlada.
• Não repita transformações custosas sem verificar se já existe um trabalho associado à tentativa lógica.
• Considere mover um item como mudança de organização, não de identidade: no Cloud, suas propriedades e regras de acesso continuam associadas ao mesmo item.

Modelo recomendado: identidade externa, estado local e confirmação

O padrão mais confiável começa na sua própria aplicação. Antes de chamar a Apification, crie um registro local de operação com um identificador externo estável do sistema de origem, o tipo de ação, a versão lógica do conteúdo e um estado inicial. Esse registro não substitui a API; ele serve para que seu backend se lembre do que tentou fazer, com qual payload e o que espera encontrar depois. Em integrações multi-tenant, essa tabela evita que dois clientes, projetos ou versões compartilhem acidentalmente a mesma deduplicação.

Depois de uma chamada incerta, não decida apenas pelo código de erro do cliente HTTP. Se a operação era uma leitura, você pode repetir normalmente. Se era uma escrita, consulte primeiro o que puder: detalhe do item, estado do trabalho, histórico de versões ou registros locais anteriores. A Apification Cloud permite revisar histórico de itens, baixar versões anteriores e restaurar conteúdo; isso ajuda a reconstruir qual conteúdo acabou ativo quando houve uma corrida entre retentativas, atualizações ou movimentos.

• Estados mínimos: pendente, enviado, aceito, confirmado, falhou, requer revisão.
• Campos mínimos: tenant, objeto de origem, versão lógica, ação, payload normalizado, chave de operação local, recurso Cloud resultante e marca temporal local.
• Regra prática: não apague o registro local quando a rede falhar; ele é justamente a evidência de que você precisará para decidir o próximo passo.

Projetar uma chave idempotente que não dependa do nome

Embora o HTTP defina o que significa uma requisição ser idempotente, cada API concreta deve ser consultada em seu próprio contrato. Na Apification, a página de integração indica que o documento OpenAPI baixável contém os esquemas de requisição e resposta; use-o para validar como cada chamada é construída e quais dados retorna. Além disso, preserve no seu banco de dados uma chave de operação local para reconhecer quando duas retentativas pertencem à mesma tentativa lógica.

A chave não deve ser simplesmente o nome do arquivo nem um timestamp gerado em cada tentativa. O nome muda, se repete entre usuários e costuma conter decisões de apresentação, não identidade de negócio. Um bom desenho combina tenant, identificador do objeto de origem, tipo de ação e versão lógica. Por exemplo, uma chave conceitual poderia ser derivada de “tenant A + contrato 583 + transformar para PDF otimizado + versão 7”. Se o usuário enviar uma nova versão, a chave deve mudar; se apenas se repete a mesma tentativa por timeout, ela deve ser mantida.

• Inclua: tenant ou conta de origem, recurso de negócio, ação exata, versão lógica e, se aplicável, operação de transformação.
• Evite: timestamps por tentativa, UUID aleatório por retentativa, nomes visíveis de arquivo como única identidade e chaves compartilhadas entre ações diferentes.
• Verifique: mesma chave local, mesmo payload, mesma intenção funcional e contrato OpenAPI consultado antes de automatizar retentativas.

Fluxo passo a passo para transformar e publicar um arquivo

Um fluxo robusto de transformação começa antes de enviar a requisição. Primeiro, valide no seu sistema qual arquivo de negócio será processado e qual versão lógica ele representa. Depois, registre ou gerencie o arquivo no Cloud usando a API correspondente segundo o contrato OpenAPI. Guarde a referência retornada junto à sua operação local. Se a resposta se perder, marque a tentativa como incerta e busque confirmação antes de enviar outra cópia.

Para transformar, consulte o contrato da operação quando precisar, prepare uma solicitação compatível com os esquemas documentados e crie o trabalho de transformação por meio da integração servidor a servidor. Quando receber uma aceitação ou referência de trabalho, guarde-a; depois consulte a API segundo o contrato para revisar seu progresso e seus resultados. Só quando o resultado estiver confirmado você deve publicar o download ou gerar a etapa de compartilhamento adequada.

• Preparar: resolver tenant, objeto de origem, versão e pasta de destino.
• Enviar: usar uma chave local estável para a escrita e guardar o payload normalizado.
• Confirmar: consultar o trabalho até ter estado e resultados, sem criar outro job por impaciência.
• Publicar: compartilhar o item ou download transformado somente depois de associar o resultado correto à versão correta.

Quando repetir, consultar ou interromper o fluxo

Repita automaticamente quando a operação for de leitura ou quando a requisição for idempotente no sentido da RFC 9110. Se a escrita depender de regras específicas da API, não presuma garantias não documentadas: consulte o OpenAPI, mantenha o mesmo payload para a mesma tentativa lógica e registre o que o cliente decidiu e por quê. A segurança da retentativa nasce da combinação entre semântica HTTP, contrato da API e estado local.

Consulte antes de repetir quando o erro ocorreu depois de enviar bytes, quando o timeout chegou tarde ou quando seu cliente não sabe se a conexão foi interrompida antes ou depois de a Apification receber a requisição. Interrompa o fluxo para revisão humana quando detectar payload diferente com a mesma intenção, mais de um recurso candidato, versões misturadas ou resultados incompatíveis com o estado local. Nesses casos, repetir pode aumentar o dano: é melhor apresentar um painel interno com a operação, o tenant, os possíveis recursos Cloud, o trabalho de transformação e a ação recomendada.

• Repetir: GET de estado e operações projetadas como idempotentes.
• Consultar: timeout posterior ao envio, resposta perdida, trabalho sem referência local mas com possível aceitação remota.
• Interromper: chaves inconsistentes, duplicados visíveis, versão de origem alterada, transformação já finalizada para outra versão.

Erros frequentes e como a Apification se encaixa

As falhas mais comuns não são sofisticadas: usar timestamps como nomes únicos, gerar uma nova chave a cada retry, misturar o arquivo original com uma versão posterior, repetir transformações assíncronas porque o usuário atualizou a tela, ou considerar que um webhook recebido confirma uma escrita anterior. Um webhook é um evento posterior que deve ser processado com sua própria deduplicação; ele não substitui a confirmação da chamada de saída feita pelo seu backend. Separe os dois circuitos: cliente API para a Apification de um lado, receptor de webhooks do outro.

A Apification se encaixa nesse desenho porque oferece integração por API REST servidor a servidor, um documento OpenAPI com esquemas de requisição e resposta, Cloud organizado e versionado, transformação guiada de arquivos, compartilhamento por links, usuários ou grupos, e webhooks assinados com retentativas, histórico e estatísticas. A recomendação prática é gerar o cliente a partir do contrato OpenAPI ou validá-lo contra ele, guardar estados intermediários no seu banco de dados e usar as consultas de Cloud e transformação para confirmar resultados antes de avançar.

• Não confunda recebimento de eventos com confirmação de escritas iniciadas pelo seu backend.
• Não use o nome visível do arquivo como identificador funcional.
• Não publique um download transformado até saber qual versão lógica produziu o resultado.
• Não prometa ao produto “sem duplicados” só por ter retries; projete estados, chaves, consultas e revisão.

Perguntas frequentes