Reintentos seguros en una API de archivos: evita duplicados

El problema: el timeout no dice si la operación ocurrió

El caso peligroso en una integración de archivos no es el error claro, sino la respuesta que nunca llega. Tu backend llama a una API para crear una carpeta, subir un archivo, lanzar una transformación o preparar una descarga compartida; la conexión se corta por timeout; y el cliente no sabe si el servidor ejecutó la acción. Si repites sin más, puedes crear dos carpetas, registrar dos copias del mismo archivo, encolar dos transformaciones o publicar dos enlaces equivalentes.

La primera decisión operativa es separar lecturas de escrituras. En HTTP, métodos como GET, HEAD y OPTIONS se consideran seguros porque el cliente no solicita un cambio de estado. En cambio, las acciones que crean, modifican, mueven, eliminan o encolan trabajo deben tratarse como escrituras. RFC 9110 define una petición idempotente como aquella cuyo efecto previsto al repetir varias peticiones idénticas es el mismo que al ejecutarla una sola vez; por eso, ante un fallo de comunicación, solo conviene repetir automáticamente cuando la operación está diseñada para soportarlo.

• Lecturas: consultar listados, detalle, estado de un trabajo o resultados ya generados.
• Escrituras: crear carpetas, subir archivos, actualizar metadatos, mover elementos, enviar a papelera, encolar transformaciones o crear accesos compartidos.
• Zona gris: cuando no recibiste respuesta, no asumas ni éxito ni fallo; guarda el intento y confirma por consulta.

Qué operaciones de archivos necesitan protección

En Apification Cloud, la integración mediante API REST servidor a servidor permite gestionar recursos Cloud, usuarios, configuración y trabajos de transformación desde el backend de un producto integrador. Cloud está descrito como un espacio organizado y versionado para gestionar archivos, servicios y proyectos digitales preparados para compartir. Algunas operaciones son naturalmente consultivas; otras cambian el estado del workspace donde viven archivos, servicios y proyectos digitales.

Las transformaciones también requieren cuidado. Apification permite procesar documentos, imágenes, vídeo, audio y datos mediante un asistente guiado, y su integración permite gestionar trabajos de transformación desde el backend. Crear o enviar un trabajo de transformación es una escritura asíncrona: puede que tu aplicación pierda la respuesta y no sepa si el trabajo quedó registrado. Si repites sin estado local ni una identidad lógica estable, puedes terminar pagando el coste operativo de dos procesos equivalentes o mezclando resultados de versiones distintas del archivo.

• Protege toda acción que cambie estado como candidata a repetición controlada.
• No repitas transformaciones costosas sin comprobar si ya existe un trabajo asociado al intento lógico.
• Considera mover un elemento como cambio de organización, no de identidad: en Cloud, sus propiedades y reglas de acceso continúan asociadas al mismo elemento.

Modelo recomendado: identidad externa, estado local y confirmación

El patrón más fiable empieza en tu propia aplicación. Antes de llamar a Apification, crea un registro local de operación con un identificador externo estable del sistema origen, el tipo de acción, la versión lógica del contenido y un estado inicial. Ese registro no sustituye a la API; sirve para que tu backend recuerde qué intentó hacer, con qué payload y qué espera encontrar después. En integraciones multi-tenant, esta tabla evita que dos clientes, proyectos o versiones compartan accidentalmente la misma deduplicación.

Después de una llamada incierta, no decidas solo por el código de error del cliente HTTP. Si la operación era una lectura, puedes repetir con normalidad. Si era una escritura, consulta primero lo que puedas: detalle del elemento, estado del trabajo, historial de versiones o registros locales previos. Apification Cloud permite revisar historial de elementos, descargar versiones anteriores y restaurar contenido; eso ayuda a reconstruir qué contenido terminó activo cuando hubo una carrera entre reintentos, actualizaciones o movimientos.

• Estados mínimos: pendiente, enviado, aceptado, confirmado, fallido, requiere revisión.
• Campos mínimos: tenant, objeto origen, versión lógica, acción, payload normalizado, clave de operación local, recurso Cloud resultante y marca temporal local.
• Regla práctica: no borres el registro local al fallar la red; es precisamente la evidencia que necesitarás para decidir el siguiente paso.

Diseñar una clave idempotente que no dependa del nombre

Aunque HTTP define qué significa que una petición sea idempotente, cada API concreta debe consultarse en su propio contrato. En Apification, la página de integración indica que el documento OpenAPI descargable contiene los esquemas de petición y respuesta; úsalo para validar cómo se construye cada llamada y qué datos devuelve. Además, conserva en tu base de datos una clave de operación local para reconocer cuándo dos reintentos pertenecen al mismo intento lógico.

La clave no debe ser simplemente el nombre del archivo ni un timestamp generado en cada intento. El nombre cambia, se repite entre usuarios y suele contener decisiones de presentación, no identidad de negocio. Un buen diseño combina tenant, identificador del objeto origen, tipo de acción y versión lógica. Por ejemplo, una clave conceptual podría derivarse de “tenant A + contrato 583 + transformar a PDF optimizado + versión 7”. Si el usuario sube una nueva versión, la clave debe cambiar; si solo se repite el mismo intento por timeout, debe mantenerse.

• Incluye: tenant o cuenta origen, recurso de negocio, acción exacta, versión lógica y, si aplica, operación de transformación.
• Evita: timestamps por intento, UUID aleatorio por reintento, nombres visibles de archivo como única identidad y claves compartidas entre acciones distintas.
• Verifica: misma clave local, mismo payload, misma intención funcional y contrato OpenAPI consultado antes de automatizar reintentos.

Flujo paso a paso para transformar y publicar un archivo

Un flujo robusto de transformación empieza antes de enviar la petición. Primero valida en tu sistema qué archivo de negocio se va a procesar y qué versión lógica representa. Después registra o gestiona el archivo en Cloud usando la API correspondiente según el contrato OpenAPI. Guarda la referencia devuelta junto a tu operación local. Si la respuesta se pierde, marca el intento como incierto y busca confirmación antes de enviar otra copia.

Para transformar, consulta el contrato de la operación cuando lo necesites, prepara una solicitud compatible con los esquemas documentados y crea el trabajo de transformación mediante la integración servidor a servidor. Cuando recibas una aceptación o referencia de trabajo, guárdala; luego consulta la API según el contrato para revisar su avance y sus resultados. Solo cuando el resultado esté confirmado deberías publicar la descarga o generar el paso de compartición adecuado.

• Preparar: resolver tenant, objeto origen, versión y carpeta destino.
• Enviar: usar una clave local estable para la escritura y guardar payload normalizado.
• Confirmar: consultar el trabajo hasta tener estado y resultados, sin crear otro job por impaciencia.
• Publicar: compartir el elemento o descarga transformada solo después de asociar el resultado correcto a la versión correcta.

Cuándo reintentar, consultar o detener el flujo

Reintenta automáticamente cuando la operación sea de lectura o cuando la petición sea idempotente en el sentido de RFC 9110. Si la escritura depende de reglas específicas de la API, no supongas garantías no documentadas: consulta el OpenAPI, mantén el mismo payload para el mismo intento lógico y registra qué decidió el cliente y por qué. La seguridad del retry nace de la combinación entre semántica HTTP, contrato de la API y estado local.

Consulta antes de repetir cuando el error ocurrió después de enviar bytes, cuando el timeout llegó tarde o cuando tu cliente no sabe si la conexión se cortó antes o después de que Apification recibiera la petición. Detén el flujo para revisión humana cuando detectes payload distinto con la misma intención, más de un recurso candidato, versiones mezcladas o resultados incompatibles con el estado local. En esos casos, repetir puede aumentar el daño: es mejor presentar un panel interno con la operación, el tenant, los recursos Cloud posibles, el trabajo de transformación y la acción recomendada.

• Reintentar: GET de estado y operaciones diseñadas como idempotentes.
• Consultar: timeout posterior al envío, respuesta perdida, trabajo sin referencia local pero posible aceptación remota.
• Detener: claves inconsistentes, duplicados visibles, versión de origen cambiada, transformación ya finalizada para otra versión.

Errores frecuentes y cómo encaja Apification

Los fallos más comunes no son sofisticados: usar timestamps como nombres únicos, generar una clave nueva en cada retry, mezclar el archivo original con una versión posterior, repetir transformaciones asíncronas porque el usuario refrescó la pantalla, o considerar que un webhook recibido confirma una escritura anterior. Un webhook es un evento posterior que debe procesarse con su propia deduplicación; no reemplaza la confirmación de la llamada saliente que hizo tu backend. Separa ambos circuitos: cliente API hacia Apification por un lado, receptor de webhooks por otro.

Apification encaja en este diseño porque ofrece integración mediante API REST servidor a servidor, un documento OpenAPI con esquemas de petición y respuesta, Cloud organizado y versionado, transformación guiada de archivos, compartición mediante enlaces, usuarios o grupos, y webhooks firmados con reintentos, historial y estadísticas. La recomendación práctica es generar el cliente desde el contrato OpenAPI o validarlo contra él, guardar estados intermedios en tu base de datos y usar las consultas de Cloud y transformación para confirmar resultados antes de avanzar.

• No confundas recepción de eventos con confirmación de escrituras iniciadas por tu backend.
• No uses el nombre visible del archivo como identificador funcional.
• No publiques una descarga transformada hasta saber qué versión lógica produjo el resultado.
• No prometas a producto “sin duplicados” solo por tener retries; diseña estados, claves, consultas y revisión.

Preguntas frecuentes