API, webhook o archivo: elegir una integración que puedas operar

El criterio que más se olvida: quién lo opera cuando falla

Las comparaciones entre API, webhook y archivos suelen centrarse en velocidad. En una operación de almacén o de tienda, el criterio decisivo es otro: qué sucede cuando el destino no responde, quién se entera y quién puede arreglarlo. Una integración elegante que solo entiende quien la escribió es una deuda con fecha.

Antes de elegir, responde tres preguntas con datos de tu entorno: ¿cuántos eventos por hora habrá en el momento pico?, ¿cuánto tiempo puede esperar el negocio un dato (segundos, minutos, horas)? y ¿qué capacidades reales tiene el sistema destino para recibir datos? Sin esas respuestas, cualquier mecanismo es una apuesta.

Comparación práctica de los tres enfoques

La tabla no declara un ganador. Muchas operaciones combinan: un webhook para eventos urgentes y una conciliación por archivo cada noche para detectar lo que se perdió.

Reintentos sin duplicar el efecto

En cualquier modelo, un envío puede dar tiempo de espera sin que sepas si el receptor lo procesó. La especificación RFC 9110 de HTTP define un método como idempotente cuando varias peticiones idénticas tienen el mismo efecto que una sola; PUT y DELETE lo son, y POST no lo es por definición. Eso significa que un reintento de un POST puede crear dos registros si el receptor no se protege.

Para esos casos se propuso en el IETF el encabezado Idempotency-Key. La versión que revisé (borrador -07 de octubre de 2025) es una propuesta expirada: su vigencia terminó el 18 de abril de 2026, no es un estándar y no verifiqué si existe una revisión posterior. Sirve solo como ilustración de la idea de enviar una clave única para que el servidor reconozca reintentos; no la des por soportada y confirma con el proveedor del destino si ofrece algún mecanismo equivalente propio. El artículo de idempotencia en inventario baja esto a ejemplos concretos.

El contrato que evita discusiones

Sea cual sea el mecanismo, escribe un contrato de una o dos páginas con estos puntos:

• campos, tipos, unidades y zona horaria de cada fecha;
• identificador único del evento y regla para reconocer reenvíos;
• códigos de respuesta o motivos de rechazo y qué debe hacer el emisor con cada uno;
• límite de tamaño y ritmo máximo de envío;
• versión del contrato y cómo se avisan los cambios;
• responsable técnico y de negocio de cada lado, con un canal de escalamiento.

Cuando se comparten eventos con terceros, el estándar EPCIS 2.0 de GS1 ofrece un vocabulario y una interfaz de captura ya definidos, lo que puede ahorrar parte de esta negociación; no es obligatorio y no resuelve la parte operativa de reintentos y propietarios.

Ejemplo hipotético: etiquetas electrónicas y precios

Ejemplo ilustrativo. Una cadena de 12 tiendas quiere enviar cambios de precio desde su sistema central a la plataforma de etiquetas electrónicas. El sistema central solo genera un archivo de precios cada madrugada. La plataforma de etiquetas acepta cargas por API y también archivos. Alguien propone un webhook por cada cambio de precio, pero el origen no emite eventos individuales.

Dado eso, el equipo elige archivo por lote con validación: el archivo se deja en un destino acordado, el receptor valida fila por fila, rechaza las inválidas a un archivo aparte y envía una confirmación con el número de filas aceptadas y rechazadas. Si el archivo no llega antes de la hora acordada, se activa una alerta. Si más adelante el origen sí emite eventos, podrán añadir un webhook para promociones urgentes, manteniendo el archivo nocturno como conciliación.

Seguridad y registros

Las credenciales, firmas y tokens de cualquier mecanismo deben guardarse fuera del código y rotarse con una periodicidad definida. En el registro de la integración, evita escribir tokens o datos personales completos; la hoja de OWASP sobre logging lista explícitamente tokens de acceso, contraseñas y claves entre lo que no debe quedar en texto claro. Registra identificadores de correlación para poder reconstruir un evento sin exponer secretos.

Fallas que deberías ensayar antes de arrancar

• Destino apagado una hora: ¿los eventos se acumulan y se envían ordenados al volver?
• Respuesta lenta con éxito oculto: el receptor procesó, pero el emisor expiró.
• Mismo archivo entregado dos veces.
• Campo nuevo o ausente tras una actualización del destino.
• Certificado o credencial vencida.

Si el proveedor no puede demostrar estos casos en un entorno de prueba, trátalos como riesgos abiertos en el plan.

Siguiente paso

Haz una hoja con los tres o cuatro flujos que conectarás, y para cada uno anota volumen pico, retraso tolerable, capacidades del destino y responsable. Decide mecanismo flujo por flujo, no para todo el proyecto. Si quieres contrastar tu caso con el equipo de ARKCOM, escribe desde garkcom.com/contact.