Cómo diseñar una arquitectura sencilla basada en APIs corporativas

Introducción

Una arquitectura basada en APIs corporativas permite que distintas aplicaciones colaboren sin convertir sus bases de datos, contraseñas o reglas internas en recursos compartidos. Para diseñarla con criterio conviene partir de cinco principios: simplicidad, responsabilidades, contratos, seguridad y trazabilidad.

Imagina una pequeña empresa de servicios que utiliza un CRM para gestionar contactos y un ERP para registrar pedidos y facturas. Su personal necesita consultar un cliente y crear un pedido desde una aplicación interna. Es tentador conectar todas las herramientas entre sí, pero esa solución puede terminar produciendo datos contradictorios, errores difíciles de localizar y dependencias de una persona concreta.

El objetivo no es desplegar muchos servicios ni adoptar todas las tecnologías disponibles. Es dibujar un recorrido de información comprensible, definir quién responde por cada operación y conseguir que un fallo pueda identificarse y repararse sin alterar otros procesos. En esta guía construiremos esa arquitectura paso a paso, con un caso práctico, un esquema de componentes, ejemplos de contratos y criterios para decidir cuándo conviene ampliar el diseño.

Índice de contenidos

Qué significa diseñar una arquitectura basada en APIs corporativas

Una API corporativa es una interfaz mediante la cual una aplicación ofrece operaciones o información a otra siguiendo reglas definidas. Esas reglas especifican qué se puede solicitar, cómo se identifica quien llama, qué datos se intercambian y qué respuestas pueden recibirse.

La arquitectura es algo más amplio que la API. Describe qué componentes intervienen, quién se comunica con quién, qué decisiones toma cada uno y dónde se aplican los controles. Dos empresas pueden consumir la misma API y, sin embargo, tener arquitecturas muy distintas.

La diferencia entre una llamada y una arquitectura

Una llamada HTTP puede ser tan sencilla como consultar el estado de un pedido. Una arquitectura debe responder también a cuestiones que esa llamada, por sí sola, no resuelve:

• ¿Qué aplicación es responsable del pedido y puede cambiarlo?
• ¿Quién tiene autorización para realizar la consulta?
• ¿Qué sucede si la respuesta llega tarde o no llega?
• ¿Cómo se evita repetir una creación cuando hay un error de conexión?
• ¿Qué parte debe modificarse si cambia la API del ERP?
• ¿Quién puede investigar una incidencia sin acceder a información confidencial?

Por tanto, el resultado del diseño no debería limitarse a un dibujo de cajas y flechas. Debe incluir decisiones comprobables sobre responsabilidades, contratos, seguridad y recuperación.

Lo que no hace falta asumir desde el principio

Trabajar con APIs no implica adoptar microservicios, contenedores, un bus de eventos, un API Gateway o una plataforma de integración. Una aplicación con módulos bien separados puede resolver perfectamente el problema inicial. La complejidad añadida solo tiene sentido cuando responde a una necesidad que puede explicarse y medirse.

Delimitar una necesidad empresarial concreta antes de dibujar servidores

El primer trabajo consiste en escribir el resultado que necesita la persona usuaria, no una lista de productos tecnológicos. En nuestro ejemplo, la necesidad es esta: desde una aplicación interna, un empleado autorizado debe localizar un cliente del CRM y registrar un pedido en el ERP, obteniendo una confirmación fiable.

Escribir un alcance pequeño y verificable

Conviene dejar por escrito qué entrará en la primera versión y qué quedará fuera.

• Entrada: referencia del cliente, artículos o servicios solicitados y cantidades.
• Consulta: existencia y datos estrictamente necesarios del cliente en el CRM.
• Acción: creación del pedido por medio de la API oficial del ERP.
• Salida: identificador del pedido creado, estado confirmado o incidencia comprensible.
• Usuarios: personal interno con permisos definidos.
• Fuera de alcance: sincronizar todos los contactos, replicar la base de datos, emitir facturas automáticamente o implantar una nueva gestión de clientes.

La última línea es importante. Muchos proyectos crecen por intentar resolver necesidades futuras que aún no existen. Es mejor diseñar un límite claro y revisar después si realmente se necesita ampliarlo.

Identificar las restricciones de operación

Antes de elegir componentes, hay que confirmar condiciones muy concretas: si las APIs están disponibles en el plan contratado, qué operaciones permiten, qué límites aplican, cómo se autentican, qué disponibilidad necesita el negocio, si hay entornos de prueba y quién administrará la integración.

También conviene acordar qué significa «funciona correctamente». En este caso no basta con recibir una respuesta HTTP satisfactoria: el pedido debe existir una sola vez en el ERP y poder localizarse por su referencia. El diseño se evaluará frente a ese resultado empresarial.

Repartir responsabilidades y fuentes de información

Las APIs conectan aplicaciones, pero no deciden por sí solas cuál tiene autoridad sobre cada dato. Si el CRM y el ERP pueden modificar libremente el mismo atributo sin reglas, aparecerán divergencias aunque todas las conexiones funcionen.

Para nuestro caso se propone una distribución inicial:

Esta tabla es una decisión de diseño para un caso ficticio, no una regla universal. En otra organización el ERP podría ser también el propietario de la ficha de cliente. Lo esencial es que la responsabilidad se encuentre documentada y no dependa de suposiciones.

Evitar que la aplicación de enlace se convierta en otro maestro de datos

La aplicación interna puede guardar un identificador de operación, el pedido asociado o una referencia técnica. Eso no significa que deba crear una copia editable de toda la información del CRM o del ERP. Cada copia añade preguntas sobre actualización, acceso, conservación y eliminación.

Si el CRM utiliza CLI-042 y el ERP asigna otro identificador al mismo cliente, la correspondencia debe quedar definida. Puede resolverse mediante una referencia externa admitida por el ERP o una tabla de equivalencias controlada. No es seguro deducir identidades únicamente por nombres parecidos o correos coincidentes.

Para profundizar específicamente en la propiedad, estructura y movimiento de los datos, puede consultarse cómo diseñar una arquitectura de datos para una pequeña empresa. Aquí nos centraremos en los componentes y decisiones que permiten intercambiar operaciones a través de APIs.

Elegir una estructura proporcionada al problema

Hay distintas maneras de conectar las aplicaciones. La elección no depende tanto del tamaño aparente del diagrama como de las responsabilidades que conviene separar.

Opción 1: conexión directa desde un backend existente

Si solo una aplicación necesita consultar el CRM y crear pedidos en el ERP, su backend puede incluir dos adaptadores: uno para la API del CRM y otro para la del ERP. Los adaptadores conocen las particularidades de cada proveedor; la lógica de negocio no necesita hacerlo.

Es una buena opción inicial cuando hay pocos flujos, un equipo pequeño y un único consumidor. Los módulos pueden desplegarse juntos sin estar mezclados en el código.

Opción 2: pequeño servicio de integración compartido

Si varias aplicaciones distintas deben ejecutar la misma operación empresarial, puede tener sentido extraerla a un servicio con una API interna propia. Su función sería centralizar una capacidad concreta, no convertirse automáticamente en intermediario obligatorio de todo el tráfico.

Esta opción introduce despliegues, permisos, disponibilidad y supervisión adicionales. Conviene utilizarla cuando la reutilización real compense esos costes. El artículo cómo integrar aplicaciones sin crear dependencias innecesarias desarrolla el problema del acoplamiento entre sistemas.

Opción 3: incorporar infraestructura específica cuando exista un motivo

Un API Gateway puede ayudar a aplicar políticas de entrada, publicar APIs o dirigir peticiones cuando existen varios servicios y consumidores. Una cola puede ser útil cuando hay tareas que deben quedar pendientes durante una interrupción. Ninguna de las dos es obligatoria por utilizar APIs.

La regla práctica es simple: separar primero responsabilidades lógicas; multiplicar componentes desplegables solo cuando aporte una ventaja operativa clara.

Dibujar los componentes y los flujos de información

Con las responsabilidades fijadas podemos representar una primera arquitectura. En el ejemplo, el navegador del empleado solo habla con el backend de la aplicación interna. Ese backend contiene la lógica del proceso y dos adaptadores para las APIs externas.

          [Empleado autorizado]
                    |
           HTTPS / sesión usuario
                    |
          [Aplicación interna]
          [Backend y permisos]
                    |
           [Proceso: pedido]
                    |
              +-----+-----+
              |           |
       [Adaptador CRM] [Adaptador ERP]
              |           |
        HTTPS / API   HTTPS / API
              |           |
            [CRM]        [ERP]
           Clientes     Pedidos

Las flechas del esquema indican comunicación lógica, no que todos los sistemas deban estar en servidores distintos. Los dos adaptadores pueden ser módulos del mismo programa y compartir despliegue, manteniendo separados sus contratos.

Por qué no enviar las credenciales del ERP al navegador

El navegador es un entorno bajo control del dispositivo del usuario. Incluir ahí una clave técnica de integración, aunque el código esté ofuscado, permitiría su extracción. Por eso las credenciales privadas del CRM o del ERP deben custodiarse en un componente servidor autorizado.

La autenticación del empleado ante la aplicación tampoco sustituye la autorización de la acción. Alguien puede haber iniciado sesión correctamente y, aun así, no tener permiso para crear pedidos.

Qué debe pasar por cada límite

• Empleado → aplicación: datos del formulario, identidad del usuario y petición de crear un pedido.
• Aplicación → CRM: consulta limitada a un cliente identificado, con credenciales técnicas propias.
• Aplicación → ERP: solicitud de creación de pedido validada y vinculada al identificador correcto del cliente.
• Aplicación → empleado: resultado entendible y referencia que permita localizar la operación.

Este dibujo es suficiente para empezar a revisar cuestiones importantes. Si no se puede explicar qué dato cruza una flecha, con qué permisos y para qué, ese enlace necesita más definición antes de programarlo.

Definir contratos que la aplicación pueda cumplir

Un contrato de API no es solo una URL. Incluye el propósito de una operación, los datos obligatorios, los resultados posibles, sus límites, la autenticación y las garantías que el consumidor puede esperar.

Contrato interno: crear un pedido

La aplicación podría exponer a su propia interfaz una operación POST /api/pedidos. El ejemplo siguiente es ilustrativo: no representa los endpoints reales de ningún CRM o ERP.

POST /api/pedidos
Content-Type: application/json
Idempotency-Key: op-2026-0017

{
  "referencia_cliente": "CLI-042",
  "lineas": [
    {
      "codigo_servicio": "SERV-01",
      "cantidad": 2
    }
  ]
}

El backend debe validar el formato, verificar que el usuario puede realizar esa acción y comprobar que la referencia de cliente corresponde a un registro permitido. Los importes o impuestos definitivos no deberían aceptarse ciegamente desde el navegador: deben quedar bajo el control del sistema empresarial responsable.

Una confirmación podría adoptar esta forma:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id_pedido": "PED-1042",
  "estado": "confirmado",
  "referencia_operacion": "op-2026-0017"
}

Conviene especificar también lo que sucede cuando la operación no puede completarse: datos inválidos, usuario sin permiso, cliente inexistente, limitación del proveedor, indisponibilidad temporal o resultado aún no confirmado. No todos esos casos deben presentarse como un simple «error del servidor».

Dos contratos distintos: el que ofrecemos y el que consumimos

La aplicación interna tiene un contrato con su interfaz. Cada adaptador, por su parte, se comunica con una API ajena. Separar ambos contratos evita trasladar directamente los nombres de campos, códigos y peculiaridades de un proveedor a todas las pantallas.

Por ejemplo, una versión del ERP puede llamar customer_ref a un campo y otra partner_id. Si solo el adaptador conoce esa diferencia, el formulario interno no necesita cambiar necesariamente. Eso no elimina todos los efectos de una actualización, pero reduce el lugar en el que deben investigarse.

Especificar significado, no solo formato

Un JSON válido puede contener información incorrecta. Antes de dar por bueno un contrato es necesario aclarar, entre otras cosas, si «cliente activo» permite registrar pedidos, si una cantidad admite decimales, qué ocurre con un servicio descatalogado y qué estado significa realmente «confirmado».

Cuando la API disponga de una especificación OpenAPI, puede utilizarse como documentación técnica de partida, pero las reglas de negocio, las correspondencias entre identificadores y la gestión del fallo también deben quedar acordadas. Para el consumo de APIs de ERP y CRM en particular, resulta útil el artículo sobre integración de APIs con sistemas ERP y CRM.

Decidir qué debe ser inmediato y qué puede esperar

La arquitectura también determina cómo se comporta el usuario mientras una aplicación espera a otra. No todos los intercambios requieren la misma velocidad ni la misma garantía de entrega.

Comunicación síncrona para una decisión inmediata

Si el empleado necesita comprobar que un cliente existe antes de continuar, una consulta síncrona suele ser razonable: la aplicación solicita la información y espera una respuesta durante un tiempo limitado. Si no la obtiene, informa de que la comprobación no se ha completado.

La creación de un pedido puede seguir un flujo síncrono cuando el ERP responde con la confirmación dentro del tiempo que la aplicación admite. Pero un tiempo de espera agotado no demuestra que el ERP no haya creado el pedido: quizá la creación se produjo y solo se perdió la respuesta.

Procesamiento asíncrono para trabajos que pueden quedar pendientes

Si una tarea puede esperar, puede registrarse de forma persistente y procesarse después mediante una cola o un mecanismo equivalente. La interfaz debe distinguir claramente entre solicitud recibida, trabajo pendiente y operación confirmada por el ERP.

Una respuesta como 202 Accepted indica, en una API diseñada para ello, que se ha aceptado el procesamiento; no certifica que el pedido ya exista. Es necesario ofrecer un mecanismo de consulta del estado y una forma de gestionar las operaciones que nunca terminan correctamente.

Elegir según el efecto de negocio

• Consulta de cliente: normalmente síncrona, porque condiciona el siguiente paso.
• Crear pedido: síncrona si puede confirmarse con fiabilidad, o asíncrona si el proceso y la experiencia del usuario están preparados.
• Generar un informe nocturno: candidato habitual a ejecución diferida.
• Actualizar un panel informativo: puede admitir datos con una antigüedad explícita, si los usuarios la conocen.

Elegir procesamiento asíncrono no elimina la necesidad de controlar duplicados, conservar los trabajos pendientes y conciliar resultados. Simplemente cambia dónde se espera y cómo se informa del avance.

Diseñar accesos y límites de seguridad desde el principio

La seguridad de una arquitectura pequeña no depende de añadir muchas herramientas. Depende de proteger cada punto de entrada, limitar permisos y evitar que una aplicación obtenga acceso a información que no necesita.

Separar identidad humana e identidad técnica

El empleado se identifica ante la aplicación interna. La aplicación, por su parte, se identifica ante el CRM y el ERP mediante los mecanismos que cada proveedor admita. Son relaciones distintas y conviene poder revocar una sin inutilizar todas las demás.

En una integración real se deben escoger los mecanismos de autenticación soportados por el proveedor, configurar permisos mínimos y custodiar los secretos fuera del código fuente, los archivos públicos y los registros. Los mecanismos con tokens Bearer requieren un tratamiento cuidadoso; la guía sobre uso de tokens Bearer para acceder a APIs aborda ese aspecto concreto.

Comprobar autorización antes de actuar

No basta con ocultar el botón «Crear pedido» para ciertos usuarios. El backend debe verificar los permisos en cada operación, incluso si alguien construye la petición HTTP manualmente. También debe validar que el usuario está autorizado a trabajar con el cliente o el ámbito empresarial solicitado.

Proteger cada conexión y minimizar la exposición

• Utilizar HTTPS con verificación válida del certificado del servidor.
• No desactivar la comprobación TLS para resolver problemas de conexión.
• No exponer claves técnicas en JavaScript, repositorios o respuestas al navegador.
• Separar credenciales y permisos de desarrollo, pruebas y producción.
• Enviar a cada API únicamente los campos necesarios para la operación.
• Evitar que las respuestas de error revelen tokens, configuraciones internas o datos de otros clientes.
• Establecer un procedimiento para cambiar y revocar credenciales.

Si se consulta información personal, el diseño debe considerar también finalidad del tratamiento, minimización, acceso y conservación. Para una visión complementaria sobre intercambio seguro, puede leerse cómo compartir datos entre aplicaciones de forma segura.

Preparar los fallos antes de que aparezcan

Una arquitectura útil no es la que promete que ningún componente fallará. Es la que puede distinguir qué se confirmó, qué se rechazó y qué resultado sigue siendo desconocido. Esa diferencia evita actuaciones precipitadas.

Distinguir errores que permiten repetir la operación

Una consulta de lectura suele poder repetirse cuando el diseño no introduce efectos secundarios y se respetan límites y condiciones de la API. Una creación o un cobro, en cambio, pueden producir duplicados si se reenvían automáticamente después de un tiempo de espera.

Por eso conviene analizar los resultados posibles y definir un comportamiento para cada uno:

Usar una referencia estable para evitar duplicaciones

El ejemplo incorpora Idempotency-Key porque expresa una intención importante: un mismo intento lógico de creación no debería generar varios pedidos por repetición de la petición. Esa cabecera no garantiza idempotencia por sí sola. Debe existir una implementación que la reconozca y la aplique.

Si el ERP admite claves de idempotencia, se utiliza su contrato documentado. Si no las admite, el backend puede necesitar una referencia externa única, un registro persistente de operaciones y una conciliación antes de repetir escrituras. El mecanismo exacto depende de lo que permita el ERP y del riesgo de duplicación.

Diseñar la recuperación con límites

Una política útil incluye tiempos de espera definidos, número máximo de reintentos, esperas progresivas, registro del último resultado fiable y un procedimiento manual para los casos inciertos. Si el proveedor limita el consumo, se debe actuar dentro de sus cuotas; el artículo cómo controlar los límites de uso y cuotas de una API desarrolla esta cuestión.

No hay que convertir cada error en otro intento indefinido. Un bucle de reintentos puede saturar un servicio, agravar una incidencia y multiplicar operaciones incorrectas.

Hacer visible el funcionamiento sin almacenar información innecesaria

Cuando una operación atraviesa varias aplicaciones, el diagnóstico se complica si cada una utiliza identificadores distintos y nadie conserva la relación entre ellos. La arquitectura debe facilitar la trazabilidad desde el primer día, aunque inicialmente solo existan unas pocas operaciones.

Asignar un identificador de correlación

Al recibir una solicitud, el backend puede generar o normalizar un identificador de correlación que acompañe sus registros internos y, cuando sea posible, las llamadas a las APIs. Ese identificador permite responder preguntas como «¿qué ocurrió con el pedido que intenté crear esta mañana?» sin buscar indiscriminadamente entre datos personales.

Un registro operativo útil podría contener:

momento_utc: 2026-10-25T10:15:00Z
correlacion: req-84f2
operacion: crear_pedido
destino: erp
resultado: pendiente_de_confirmacion
duracion_ms: 2400
referencia_operacion: op-2026-0017

Los valores son ficticios y muestran solo la estructura. En producción deben definirse qué campos se registran, quién puede verlos y cuánto tiempo se conservan. No se deben guardar contraseñas, tokens ni cuerpos completos con información sensible por comodidad de depuración.

Observar resultados, no solo solicitudes

Conviene distinguir entre llamadas realizadas, llamadas fallidas y operaciones empresariales completadas. Una tasa elevada de respuestas HTTP 200 no significa necesariamente que todos los pedidos estén correctos.

Para un primer despliegue puede bastar con conocer el número de operaciones confirmadas, pendientes e inciertas; la duración de las llamadas principales; y el momento de la última ejecución correcta. Si necesitas abordar con más detalle el registro técnico de peticiones, consulta cómo registrar todas las llamadas realizadas a una API.

Caso práctico: consultar un cliente y crear un pedido sin duplicarlo

Vamos a reunir las decisiones anteriores en un recorrido concreto. El negocio ficticio tiene cinco empleados que gestionan encargos de asistencia técnica. El CRM contiene las fichas comerciales y el ERP administra los pedidos. La aplicación interna ofrece un formulario reducido para iniciar una operación.

Paso 1. Autorización de la persona usuaria

El empleado inicia sesión en la aplicación. Cuando solicita crear un pedido, el backend comprueba su permiso y el ámbito de clientes que puede gestionar. No se confía en una comprobación realizada únicamente en la interfaz.

Paso 2. Localización del cliente en el CRM

El adaptador del CRM consulta la referencia indicada. Si el cliente no existe o no está autorizado para el proceso, la operación se detiene con un mensaje claro. Si aparece una ambigüedad entre identificadores, se resuelve de forma controlada: no se selecciona automáticamente «el cliente más parecido».

Paso 3. Preparación del pedido

El backend valida los servicios y cantidades enviados, aplica las reglas de entrada acordadas y resuelve el identificador que espera el ERP. El cálculo definitivo de precios, impuestos y condiciones comerciales permanece en el sistema que tiene esa responsabilidad.

Paso 4. Envío con una referencia estable

La aplicación asigna una referencia única a ese intento lógico y conserva su estado técnico. A continuación solicita la creación al ERP. Si este admite un mecanismo nativo de idempotencia, se utiliza según su documentación; si no, se aplica una estrategia de conciliación compatible con su API.

Paso 5. Interpretación del resultado

Hay tres salidas sustancialmente diferentes:

• Confirmado: el ERP devuelve o permite verificar un identificador inequívoco del pedido.
• Rechazado: el ERP comunica una causa definitiva, como un dato incorrecto o una condición comercial no válida.
• Desconocido: se pierde la conexión durante la escritura y no puede afirmarse si el pedido existe.

En el tercer caso la interfaz no debe mostrar «pedido no creado» si esa conclusión no está demostrada, ni permitir duplicar ciegamente la operación. Puede mostrar un estado pendiente de comprobación y ofrecer una referencia al personal autorizado para resolver la incidencia.

Paso 6. Comprobación y cierre

La aplicación registra la referencia externa y el resultado confirmado. Cuando existe incertidumbre, ejecuta la conciliación prevista o remite el caso a revisión. El empleado puede localizar el estado mediante una referencia estable, sin necesitar acceso a las credenciales ni a los registros técnicos del ERP.

El valor de este recorrido está en que conecta decisiones de negocio y mecanismos técnicos: quién está autorizado, quién crea, cómo se identifica, qué se confirma y cómo se recupera. Esa es la diferencia entre una conexión que funciona durante una prueba y una arquitectura que puede operarse.

Validar y poner en funcionamiento la arquitectura sin saltarse etapas

El diagrama puede parecer correcto y aun así fallar por problemas de identificación, permisos, datos reales o comportamiento inesperado de una API. Antes del despliegue es necesario probar el recorrido completo, no solo verificar que cada endpoint responde.

Comenzar con datos sintéticos y entorno controlado

Cuando existan entornos de prueba del CRM o ERP, deben utilizarse sin mezclar credenciales de producción. Si un proveedor solo permite operaciones reales, la estrategia de pruebas tendrá que limitarse cuidadosamente y contar con autorizaciones y mecanismos de reversión adecuados.

Construir pruebas de aceptación que representen decisiones reales

1. Cliente válido y pedido correcto: se registra una sola operación y se conserva la referencia del ERP.
2. Cliente inexistente: se explica el problema y no se crea el pedido.
3. Usuario sin autorización: la acción se rechaza en el backend.
4. Datos de entrada incorrectos: la validación detecta el problema antes de escribir en el ERP, cuando sea posible.
5. ERP temporalmente inaccesible: se muestra un estado fiel al resultado conocido.
6. Respuesta perdida después de una escritura: la recuperación comprueba el resultado sin crear un duplicado.
7. Cambio incompatible de un campo de la API: la prueba del adaptador falla antes de dar por buena la integración.
8. Repetición de la misma solicitud: se aplica la política definida para impedir efectos duplicados.

Un sistema no está suficientemente probado porque una llamada manual haya devuelto 200. Tampoco basta con probar la ruta feliz si un fallo real puede crear dos pedidos. El artículo cómo detectar errores habituales al consumir APIs aporta un método específico para investigar incidencias durante las pruebas y la operación.

Publicar por etapas y conservar una salida

La puesta en producción puede comenzar con unos pocos usuarios autorizados y operaciones de bajo riesgo. Antes de ampliarla, conviene confirmar que se pueden revisar los resultados en el ERP, desactivar temporalmente la integración, revocar sus credenciales y recuperar los estados inciertos.

También hay que saber qué ocurre al volver a una versión anterior. Si una nueva versión ha cambiado datos, contratos o estados persistidos, revertir el código no siempre basta. La recuperación debe pensarse como parte del despliegue y no como una decisión tomada bajo presión.

Saber cuándo cambiar la arquitectura y cuándo conservarla

La primera versión puede ser una aplicación monolítica bien organizada con dos adaptadores. Es una estructura válida mientras las necesidades de negocio, el volumen y la operación sigan estando cubiertos.

Señales que justifican estudiar una evolución

• Otras aplicaciones necesitan utilizar la misma operación empresarial y duplicarían código y reglas.
• El proceso admite espera, pero depende demasiado de que dos sistemas estén disponibles al mismo tiempo.
• Una parte necesita capacidad o disponibilidad distinta del resto de la aplicación.
• Se requiere publicar varias APIs con políticas comunes para consumidores autorizados.
• El equipo dispone de mecanismos reales para supervisar y mantener componentes adicionales.

En esas condiciones se puede evaluar extraer un servicio, incorporar una cola persistente o establecer una entrada gestionada. La decisión debe incluir tanto los beneficios como el coste de nuevos despliegues, permisos, fallos y tareas de mantenimiento.

Señales de que todavía no conviene dividirla

Si solo existe un consumidor, el flujo es comprensible, los adaptadores están aislados y los cambios pueden probarse sin afectar a otras funciones, dividir el sistema probablemente aumentará el trabajo. La evolución saludable consiste en responder a un problema comprobado, no en alcanzar un número de servicios considerado moderno.

Cuando realmente aparezcan varias integraciones reutilizables, puede ser útil estudiar cómo construir una biblioteca corporativa de integraciones mediante APIs. Esa práctica resuelve un problema distinto: organizar y compartir recursos una vez que existen.

Errores frecuentes al diseñar arquitecturas corporativas con APIs

Unir todas las aplicaciones con todas

Las conexiones indiscriminadas generan flujos difíciles de entender. Antes de añadir una relación, hay que indicar su necesidad, la información que intercambia y el responsable de resolver sus fallos.

Permitir que cualquier sistema modifique los mismos datos

Dos aplicaciones no deberían convertirse accidentalmente en propietarias del mismo dato. La fuente responsable, las reglas de actualización y los identificadores deben estar definidos.

Confundir una API con un acceso directo a tablas

Leer o modificar directamente la base de datos de un ERP puede eludir sus validaciones y romper compatibilidad. Cuando existe una API oficial adecuada, conviene trabajar a través de ella y respetar su contrato. Si la integración con bases de datos tiene un propósito legítimo diferente, debe diseñarse expresamente; se aborda en cómo integrar APIs con bases de datos corporativas.

Trasladar las claves del proveedor a cada consumidor

Repartir secretos técnicos entre navegadores, hojas de cálculo o scripts personales dificulta la revocación y amplía el alcance de un incidente. Es preferible establecer límites claros y custodiar las credenciales en el entorno autorizado.

Tratar todas las respuestas HTTP como resultado de negocio

Un 200 puede contener un dato inválido; un timeout puede ocultar una escritura completada; y un 202 puede significar que queda trabajo por hacer. El estado de negocio debe interpretarse según el contrato concreto.

Complicar el diseño antes de comprobar la necesidad

Un gateway, un servicio de mensajería y varios microservicios pueden ser adecuados en ciertos escenarios, pero también elevan el número de puntos de fallo. Adoptarlos sin una exigencia verificable puede hacer más difícil una integración que comenzó siendo sencilla.

Diseñar solo el funcionamiento normal

Omitir permisos, trazabilidad, reintentos seguros y conciliación suele salir caro cuando aparece la primera incidencia. Es mejor contemplarlos con soluciones proporcionadas desde el principio.

Lista de comprobación para un primer diseño

Antes de dar por terminado el diseño, conviene comprobar que cualquier persona responsable del proceso puede responder afirmativamente a estos puntos:

1. La necesidad empresarial está escrita en una frase y tiene un resultado observable.
2. Se conoce qué aplicaciones intervienen y cuáles quedan fuera del alcance.
3. Cada dato importante y operación crítica tiene un responsable identificado.
4. El recorrido del usuario y las flechas entre componentes pueden explicarse sin hablar de productos concretos.
5. El backend valida permisos y no entrega credenciales de proveedor al navegador.
6. Cada API consumida tiene contrato, versión conocida y campos relevantes documentados.
7. El significado de «confirmado», «rechazado» y «desconocido» está definido.
8. Las escrituras tienen una estrategia compatible con el proveedor para evitar duplicados.
9. Hay tiempos de espera, límites de reintento y criterios para detener una operación.
10. Se puede localizar una incidencia mediante una referencia sin exponer secretos.
11. Se han probado el éxito, la falta de permisos, la indisponibilidad y la respuesta perdida.
12. Existe un responsable de mantenimiento y una forma segura de desactivar o modificar la integración.

Si no se puede responder a varios de estos puntos, la siguiente tarea normalmente no consiste en instalar más infraestructura, sino en aclarar el proceso y cerrar decisiones. Para una visión específica del cuidado posterior, puede consultarse buenas prácticas para mantener integraciones mediante APIs durante años.

Preguntas frecuentes sobre arquitectura de APIs corporativas

Conclusión: una arquitectura sencilla se reconoce por sus decisiones claras

Diseñar una arquitectura basada en APIs corporativas no consiste en conectar el mayor número posible de sistemas. Consiste en decidir qué proceso se quiere resolver, qué aplicación tiene la autoridad sobre cada operación y cómo circula la información con controles verificables.

En el ejemplo, un backend con dos adaptadores es suficiente para construir un primer recorrido entre CRM y ERP. La calidad del diseño aparece en detalles poco vistosos, pero decisivos: permisos comprobados en el servidor, correspondencia de identificadores, contratos definidos, resultados inciertos tratados con prudencia y capacidad de investigar una incidencia.

La mejor primera versión es aquella que otra persona puede explicar, probar y mantener. Si el negocio crece, esa claridad permitirá introducir nuevas capacidades sin rehacerlo todo; si no crece, habrá evitado una complejidad innecesaria.