Integración por API y webhooks: cómo elegir y comprobar el flujo

API, webhook, consulta periódica y archivo cumplen funciones distintas

Una llamada a una API solicita una operación: consultar una solicitud, crear un registro o actualizar un campo, si el sistema lo permite. Un webhook envía una notificación a una dirección configurada. La notificación puede contener el dato necesario o un identificador para consultar después su estado.

Si el proveedor no ofrece eventos, una consulta periódica puede buscar cambios a intervalos acordados. Si solo permite exportaciones, puede diseñarse un intercambio de archivos con validación y conciliación. La elección comienza revisando documentación, contrato de uso, permisos y restricciones de cada proveedor.

OpenAPI estandariza cómo describir una API HTTP y sus capacidades. Una descripción ayuda a acordar solicitudes, datos y respuestas; no demuestra que tengas el acceso contratado ni que una integración esté implementada.

Cómo elegir el patrón para tu operación

La rapidez debe definirse para el proceso: cuándo el dato necesita estar disponible y qué ocurre mientras está pendiente. «Tiempo real» requiere una condición verificable; no conviene usarlo como sustituto de un límite acordado de actualización.

Desliza la tabla si no ves todas las columnas.

El contrato de datos debe incluir fallas y reintentos

Acuerda qué identifica la operación de negocio, qué campos viajan y qué sistema decide cada estado. El identificador de entrega de un aviso y el identificador del registro cumplen funciones diferentes: recibir el mismo evento nuevamente no debe crear otra operación cuando el alcance requiere una sola.

El RFC 9110 define idempotencia como conservar el mismo efecto solicitado al repetir solicitudes idénticas. También limita el reintento automático de métodos no idempotentes cuando no se puede saber si se aplicaron. Para el proyecto, traduce esto en una regla comprobable: cómo consultar el resultado o evitar duplicarlo cuando se perdió la respuesta.

GitHub recomienda verificar eventos, usar secretos y HTTPS, y recuperar entregas perdidas. Su documentación sirve como ejemplo concreto; los encabezados, tiempos de respuesta y mecanismos de reenvío de GitHub no son condiciones universales de otros proveedores.

• Documenta campos obligatorios, moneda, zona horaria, significado de vacío y versiones del formato.
• Distingue aviso recibido, trabajo pendiente y resultado confirmado; indica quién revisa cada excepción.
• Define cómo validar el emisor según el mecanismo del proveedor y quién administra o revoca las credenciales.
• Acuerda límites de reintento, revisión manual y conciliación; conserva contexto suficiente para investigar sin exponer secretos.

Qué probar además del envío correcto

Ejemplo hipotético: un sistema comunica la aprobación de una solicitud y otro debe crear el registro operativo. Los siguientes criterios propuestos verifican el recorrido completo; no describen pruebas históricas de un cliente.

Haz estas pruebas en un entorno autorizado con datos ficticios o anonimizados. Una prueba que afecte cobros, mensajes, contratos u otros registros reales necesita el alcance y la autorización correspondientes.

• Datos válidos: el registro de destino coincide con los campos y la autorización acordados.
• Entrega repetida: enviar de nuevo el mismo evento no crea una segunda operación de negocio.
• Destino indisponible: el pendiente queda identificable y se recupera de acuerdo con la regla de reintento o revisión.
• Respuesta perdida después de aplicar la acción: el flujo comprueba el resultado antes de intentar duplicarlo.
• Evento anterior recibido después de uno reciente: se aplica la regla de versión y estado, sin sobrescribir el dato vigente indebidamente.
• Dato inválido o permiso revocado: el error informa qué necesita revisión y no muestra un éxito de negocio falso.
• Conciliación: el equipo puede explicar los registros faltantes, repetidos o diferentes entre origen y destino.

Un caso de integración dentro de una operación real

Digital Dev desarrolló software para administración de arriendos con control de ingresos y gastos, portal para propietarios y recaudación integrada. La ficha documenta que en abril de 2025 funcionaba en una operación cliente con identidad reservada.

El caso acredita esa capacidad dentro del proceso de administración. No identifica públicamente una API, un protocolo de eventos, proveedores compatibles ni pruebas de reintento. Estos detalles deben validarse para tus sistemas, sin deducirlos del caso.

Qué preparar antes de cotizar una integración

Identifica los dos sistemas, una operación habitual y una excepción. Reúne documentación pública o autorizada, una muestra anonimizada de los campos y el nombre de quien puede solicitar accesos. No compartas contraseñas o claves en la consulta inicial.

La propuesta debe distinguir configuración o desarrollo, permisos y licencias del proveedor, infraestructura, pruebas, supervisión y mantenimiento ante cambios de API. La compatibilidad y el costo se confirman con esos antecedentes, no por la presencia de un logo o un conector en un catálogo.

Guía institucional de Digital Dev elaborada con asistencia de IA. Las matrices y los criterios de aceptación son propuestas propias para evaluar un proyecto. Las fuentes técnicas y los casos enlazados mantienen su autoría y alcance; no se atribuye revisión personal a integrantes del equipo.