Empiece por el significado de los datos
Dos sistemas pueden intercambiar JSON por HTTP y, aun así, interpretar la información de forma distinta. Uno puede considerar cliente a una persona con contrato activo; otro incluye cualquier contacto de su base. Una fecha marca la creación de la solicitud y otra registra su aprobación. Al principio parecen pequeños problemas de correspondencia entre campos. En producción provocan registros duplicados, estados incorrectos y discusiones sobre dónde se originó el error. Comience con un vocabulario de términos de negocio y casos reales, no con una lista de endpoints.
Para cada dato importante, indique la fuente de referencia, las modificaciones permitidas y quién corrige los errores. Si el CRM crea clientes y el sistema de facturación controla su estado de pago, ambas aplicaciones no deberían decidir por separado el valor del mismo campo sin una regla de conflictos. Incluya el tiempo: ¿cuándo se considera terminado un cambio y qué antigüedad puede tener un valor mostrado? El mecanismo de transporte se decide después. Puede bastar una tabla corta de significados, propietarios y eventos. La precisión importa más que la extensión del documento.
Elija un límite acorde con la experiencia
Una llamada síncrona resulta adecuada cuando la persona necesita respuesta inmediata y se conoce el tiempo de espera aceptable. Un mensaje asíncrono sirve cuando el procesamiento tarda, la demanda llega por ráfagas o el destino no está siempre disponible. No se trata de elegir la tecnología más sofisticada. Recorra el caso concreto: ¿qué puede confirmar honestamente la pantalla, qué debe quedar «en proceso» y cómo conocerá la persona el resultado final? Mostrar «terminado» cuando solo ha prosperado la primera petición crea una promesa falsa.
Separe las órdenes que cambian el estado de las consultas que lo leen. Anote si quien llama necesita coherencia inmediata o acepta una actualización posterior. En un flujo asíncrono debe estar claro cómo se vincula el mensaje recibido con la solicitud inicial y cómo se repara un elemento que falla varias veces. Un proyecto pequeño quizá solo necesite una API bien definida y una cola sencilla. Una plataforma compleja no resuelve por sí misma un proceso de negocio cuyo propietario y resultado siguen indefinidos.
El contrato también describe errores y cambios
El contrato de una API no se limita a los campos de una respuesta correcta. Debe definir datos obligatorios y opcionales, identificadores, paginación, permisos, códigos de error y significado de cada estado. La especificación OpenAPI permite describir operaciones, esquemas, callbacks y webhooks. Úsela como referencia compartida entre cliente, proveedor y pruebas. Sin embargo, un archivo de especificación no sustituye ejemplos concretos cuando el significado comercial depende del contexto. Hay que acordar qué quieren decir «aceptado», «liquidado» o «cancelado».
Cada cambio del contrato afecta a consumidores. Añadir un campo opcional suele ser más sencillo que cambiar el significado de uno existente, pero tampoco es automáticamente seguro para todos. Los eventos necesitan reglas explícitas de compatibilidad y un periodo de transición. La documentación de Schema Registry de Confluent distingue compatibilidad backward, forward, full y transitive. La elección depende de quién despliega primero y cuánto tiempo siguen circulando mensajes antiguos. Pruebe el contrato nuevo con consumidores reales y datos almacenados representativos, no solo con un validador sintáctico.
Un resultado desconocido no equivale a un fracaso
El caso más peligroso aparece cuando se envía una orden sin recibir respuesta. El destino puede haber completado el trabajo y perderse únicamente la respuesta. Repetir la orden a ciegas puede crear otro pago, pedido o cuenta. Para operaciones que modifican el estado, diseñe una clave de idempotencia u otra manera inequívoca de reconocer la misma solicitud lógica. Repetirla debe devolver el resultado ya conocido y no ejecutar de nuevo sus efectos. Defina cuánto tiempo permanece válida la clave y qué ocurre si llega con un contenido diferente.
Repita solo errores transitorios y limite los intentos. La guía de AWS sobre reintentos con espera progresiva explica la importancia de la idempotencia, el riesgo de sobrecarga y la diferencia entre fallos temporales y permanentes. El diseño práctico especifica quién vuelve a intentar, durante cuánto tiempo, con qué intervalo y cuándo interviene una persona. Repetir automáticamente datos permanentemente inválidos desperdicia capacidad. Hace falta un estado visible, un motivo de rechazo comprensible y una forma segura de corregir el problema.
Prepare la recuperación parcial
Los sistemas independientes rara vez comparten una única transacción de base de datos. Imagine la creación de un cliente en el CRM, el registro de su contrato y el alta posterior de un perfil de facturación. Los dos primeros pasos pueden terminar y fallar el tercero. Decida si se compensarán los pasos anteriores, se completará el proceso más tarde o quedará explícitamente pendiente. Cada opción tiene costes y consecuencias comerciales. No existe una respuesta universal; las partes implicadas deben comprender lo que verá el cliente.
Escriba varios escenarios de fallo entre pasos y asigne un responsable para cada decisión. Una acción compensatoria no siempre invierte exactamente la acción original. Un correo enviado no puede retirarse, y un pago liquidado puede requerir un proceso de devolución separado. Si es necesaria la intervención humana, la administración debe mostrar la petición inicial, todos los intentos y las acciones seguras disponibles. Conviene resolverlo antes de programar, pues afecta al modelo de datos, a la interfaz administrativa y a los procedimientos de soporte.
La seguridad pertenece al flujo completo
Las integraciones suelen mover información sensible entre equipos o proveedores. No suponga que una red interna implica confianza por sí sola. Para cada conexión defina la identidad de quien llama, el alcance de sus permisos, la rotación de credenciales y las reglas de registro. El privilegio mínimo tiene una aplicación concreta: un servicio que consulta el estado de un pedido no debe poder cambiar datos bancarios. En los webhooks, compruebe origen y firma conforme al protocolo real del proveedor y tenga en cuenta la entrega repetida.
No copie tokens completos, datos personales o instrucciones de pago a los registros de la aplicación. Un identificador de correlación, la fecha, el paso, la categoría del error y unos metadatos cuidadosamente elegidos suelen bastar para investigar. Evalúe almacenamiento y transporte según la sensibilidad de los datos. Las obligaciones legales dependen del propósito y lugar del tratamiento y requieren una valoración específica. El equipo técnico puede facilitarla con un inventario fiel de flujos y permisos. La seguridad nace del mapa del proceso y no debe añadirse al final.
La operación debe explicar el estado
La métrica «la API responde» resulta insuficiente si una operación comercial puede perderse entre pasos. Observe solicitudes aceptadas y completadas, antigüedad del elemento pendiente más viejo, proporción de reparaciones manuales, errores por socio y diferencias entre registros esperados y reales. Cada medida necesita un responsable y un umbral que inicie una investigación. Un panel sin una acción asociada solo decora. Distinga el fallo técnico de un resultado comercial legítimo, como una solicitud correctamente rechazada.
Cada flujo debería poder rastrearse desde la petición de la persona usuaria hasta su último paso. Un identificador de correlación ayuda, pero la historia de transiciones de estado y versiones del contrato acelera aún más el diagnóstico. Un procedimiento operativo debe explicar cómo detener envíos, reprocesar con seguridad un elemento, conciliar registros y escalar un fallo del socio. Ensáyelo con un error controlado. Si únicamente el desarrollador original puede ejecutarlo, la integración todavía no está lista para entregarse.
Pruebe casos reales, también los difíciles
La petición exitosa es la parte más sencilla de probar. Añada entrega duplicada, tiempo de espera agotado tras una ejecución correcta, una versión antigua del mensaje, ausencia de datos obligatorios, permisos incorrectos y terminación parcial. Pruebe también la migración o reproducción de registros anteriores. Verifique el resultado en la respuesta de la API, la base de datos, el estado visible para la persona y el registro operativo. Esas vistas pueden discrepar aunque una prueba unitaria individual sea satisfactoria.
Antes de lanzar, haga un piloto limitado con datos representativos y una forma prevista de volver atrás. Acuerde quién confirmará la corrección comercial y quién revisará las medidas técnicas. Registre limitaciones conocidas, estados ambiguos y su procedimiento de solución. Una buena arquitectura de integración no promete que nunca habrá errores. Permite detectarlos, explicarlos y repararlos de manera segura para que la organización continúe trabajando sin perder el significado de sus datos.