El contrato de datos de la integración

🌐 También en 19 idiomas

English · 日本語 · Português (Brasil) · Français · Deutsch · Italiano · 한국어 · 简体中文 · Português (Portugal) · 繁體中文 · Bahasa Indonesia · Türkçe · Polski · Tiếng Việt · ไทย · Українська · Español (México) · Français (Canada) · Deutsch (Schweiz)

Imagen generada con IA

Traducido con IA. Aún no revisado por la comunidad. Leer en inglés Esta sección cambió en inglés y aún no se ha vuelto a traducir. (4)

Módulo 4 de 4 del capítulo Integración y movimiento de datos, capítulo 9 del curso Data Architect. Cada módulo se sostiene por sí solo. Anterior: Prueba de entrega · Siguiente: el próximo capítulo, Migración y sincronización

La pregunta que responde este módulo: ¿cómo dejas por escrito lo que cada integración puede hacerles a los datos?

A estas alturas le hemos hecho muchas preguntas a una flecha: quién la inicia, hacia dónde se mueven los datos, con qué frescura, cuánto, qué clave, quién es dueño de cada campo, qué patrón, qué mecanismo, quién demuestra que llegó. Esas decisiones no deberían vivir solo en la cabeza del arquitecto, ni dispersas entre un diagrama, una historia en el backlog, una especificación de API, una hoja de cálculo, tres hilos de chat y la memoria de quien lo construyó. Quiero un pequeño contrato de arquitectura para cada flecha importante: el contrato de datos de la integración.

Cada flecha importante recibe un contrato

Aquí está el panorama de Steve Trucking una vez más, en los mismos lugares que en el módulo 1. En el capítulo 4 aprendimos a ver las flechas. En este capítulo hemos aprendido a preguntar qué significa cada una. Ahora dale un número a cada flecha importante.

Clic para ampliar

El panorama es el índice. Cada número abre un contrato.

Nueve flechas, nueve contratos. Fíjate en que cada socio tiene dos: los manifiestos de entrada y el estado de salida son integraciones distintas, con distintos iniciadores, tiempos, claves, campos y gestión de fallos. Una flecha de doble punta etiquetada “sincronización con el socio” lo escondería todo. Prefiero dos contratos claros que uno “bidireccional” vago.

Una flecha necesita más que una etiqueta

Una etiqueta como “Sincronización de cuentas” no dice casi nada. ¿Envía el ERP o pregunta Salesforce? ¿Cada hora, cada noche, según ocurre? ¿Diez cuentas al día o diez millones? ¿Emparejadas por el ID de Salesforce, el número de cliente o el nombre? ¿Qué campos puede cambiar el ERP? ¿Y si falla el registro 4.291? La etiqueta esconde cada una de esas decisiones. El contrato las saca a la luz.

Las primeras líneas son las preguntas del módulo 1, ahora escritas como decisiones. Luego dos líneas que rellena el arquitecto de integración, y dos que añade la propia guía Well-Architected de Salesforce:

Línea	La decisión
Iniciador	¿Quién inicia la conversación?
Dirección de los datos	¿Hacia dónde se mueven los datos de negocio?
Frescura	¿Cuán actuales deben ser los datos, con una cifra?
Volumen y forma	¿Cuánto, y uno a uno, por conjuntos o masivo?
Clave	¿Cómo identificamos el mismo registro en los distintos sistemas?
Autoridad de escritura	¿Qué sistema es dueño de qué campos, y puede escribirlos?
Patrón	¿Solicitud y respuesta, disparar y olvidar, lote o eventos?
Mecanismo	¿Qué lo implementa?
Prueba de entrega	¿Quién demuestra que llegó, y es responsable de la recuperación?
Sensibilidad y recorrido	¿Cuán sensibles son los datos, y por dónde pasan?
Cambio	¿Cómo cambia el contrato sin romper el otro lado?

Amplía el inventario del panorama del capítulo 4, una fila por flecha. No es una especificación de API: los endpoints, las cargas útiles, los esquemas, la autenticación y los códigos de respuesta importan todos, más adelante. Primero quiero saber qué se supone que significa la integración para los datos de la empresa.

Las dos últimas líneas salen directamente del marco de Salesforce. Su guía de protección de datos espera “la clasificación de los datos preservada a través de las fronteras entre sistemas” y “las rutas de tránsito de los datos evaluadas para el cumplimiento de la residencia, no solo la ubicación de almacenamiento”; uno de sus antipatrones es un middleware de integración que se ejecuta en una región fuera de la frontera de cumplimiento (Data Protection Patterns (se abre en una pestaña nueva)). Y para los eventos dice que “los esquemas de eventos se convierten en contratos entre productores y consumidores”: añade campos nuevos en lugar de cambiar los existentes, y versiona de forma explícita cuando no se puede evitar un cambio incompatible (Operational Excellence (se abre en una pestaña nueva); ambas consultadas el 2026-10-27).

Contrato C1: los manifiestos de Redrock

Ahora acércate a C1. En el módulo 1 le hicimos siete preguntas a la flecha de Redrock. Estas son las respuestas como contrato y, junto a cada línea, cómo sabremos que se cumple.

Clic para ampliar

El contrato C1. Una línea solo está terminada cuando la puedes comprobar.

Fíjate en dos cosas. Primera, tomamos casi todas las decisiones de datos antes de elegir la tecnología. La línea del mecanismo dice “la elección del arquitecto de integración, que encaje con las líneas anteriores”, y eso es sano: qué, por qué, quién, cuánto, con qué frescura, de quién es el valor, quién demuestra que llegó. Luego el arquitecto de integración elige el mecanismo que cumple el contrato.

Segunda, mira la columna de la derecha. Cada línea tiene una prueba. “Una revisión está en la orden de trabajo en 15 minutos” se puede medir cada día. “Enviados igual a aceptados más rechazados” se puede comprobar cada tarde. Una línea del contrato que no puedes comprobar es una esperanza, no un requisito.

Primero los requisitos, luego el patrón, luego el mecanismo

Cuando enseño integración, doy a la gente el orden en el que pensar. Primero los requisitos: la dirección de la acción, quién la inicia, que puede ser distinta de hacia dónde fluyen los datos; el origen y el destino; el tiempo, tiempo real, casi tiempo real o por lotes; y el volumen. Luego el patrón: disparar y olvidar, solicitud y respuesta, sincronización de datos por lotes, virtualización, llamada remota entrante, una actualización de la interfaz de usuario cuando cambian los datos. Luego el mecanismo. Y solo hay unas cuantas formas de entrar y salir de Salesforce: las API REST, SOAP, Bulk, Streaming y Pub/Sub, los eventos de plataforma, Change Data Capture, la mensajería saliente, las llamadas salientes desde Apex, Flow o External Services, Salesforce Connect, Heroku Connect. Esas son las puertas. Elige una solo cuando sepas qué tiene que pasar por ella.

Este es C1 recorrido en ese orden.

Clic para ampliar

Requisito, patrón, mecanismo. Cada opción descartada tiene un motivo que puedes decir en voz alta.

Las dos cosas se confunden continuamente. “Usamos REST” no me dice la arquitectura: quién llama a quién, cuándo, con qué frecuencia, cuánto, qué pasa si falla. REST es un mecanismo; el contrato le da significado. Y no dejes que el mecanismo se convierta en el requisito. “Necesitamos una integración REST” probablemente no es el requisito. “Cuando se revisa una entrega, el coordinador lo ve en la orden de trabajo en 15 minutos” sí lo es. Ahora podemos diseñar: quizá REST, quizá eventos, quizá la plataforma de integración ya lo hace, quizá Salesforce debería ir a buscar el valor en lugar de guardarlo. Requisito, patrón, mecanismo. Empieza por el mecanismo y te habrás saltado la arquitectura.

Y construye para más de lo que se pide. Cada integración tiene requisitos implícitos que nadie escribe: habrá errores, los volúmenes crecerán, el negocio añadirá un segundo flujo el año que viene. Planifica para tres años, no solo para la puesta en producción. El contrato es donde esos requisitos implícitos se hacen explícitos.

Conocimiento para el examen. Separa el patrón (cómo interactúan los sistemas) del mecanismo (lo que lo implementa). Espera un escenario que describe requisitos (quién la inicia, hacia dónde se mueven los datos, con qué rapidez, cuánto) y pide el patrón o el mecanismo de Salesforce que encaja: por ejemplo, casi tiempo real desde Salesforce sin esperar respuesta apunta a los eventos de plataforma; millones de registros apunta a Bulk API.

Un contrato entre equipos

El contrato no es solo entre sistemas. Es entre equipos. En un proyecto, el equipo de middleware construía las integraciones hacia Salesforce, y tuvimos que tomar una decisión en la primera o segunda semana: ¿llamarían a la API REST estándar de Salesforce, o a una API personalizada que construiríamos para ellos?

Con la API estándar, el equipo de middleware tiene que conocer Salesforce a fondo: tus objetos, tus campos, los valores de tus listas de selección, el orden en que hay que escribir los registros y qué significa cada error. Llaman a las API estándar, y ellos gestionan los problemas.

Clic para ampliar

La API estándar: el equipo de middleware trabaja directamente con tus objetos y campos.

Añade un objeto personalizado, renombra un campo, cambia un valor de una lista de selección, y la integración se rompe, salvo que estén en tus reuniones y cambien rápido su lado.

Clic para ampliar

Una versión renombra un campo, y la integración se rompe.

The other answer is a wrapper. In Salesforce that’s usually Apex: a class exposed as a REST resource, so external applications can call your code instead of your objects (Introduction to Apex REST (se abre en una pestaña nueva), Apex Developer Guide, Winter ‘27, API version 68.0, checked 2026-10-27). Now you write your own REST contract, and the middleware team gets a single endpoint. Three things come with it: ⟲

• Tu propio registro. No dependes solo de los registros estándar. Cada llamada entrante puede llevar una marca de tiempo y guardar su carga útil, para que veas exactamente qué llegó y puedas reproducirlo (el registro de integración del módulo 3).
• Tu propia orquestación. Una llamada puede escribir la orden de trabajo, sus artículos y su estado en el orden correcto, dentro de Salesforce, en lugar de que el equipo de middleware haga cinco llamadas y gestione cada fallo parcial.
• Una puerta estable. Renombra un campo, añade un objeto, cambia un valor de una lista de selección: cambias el código detrás del endpoint, y el contrato sigue igual.

El coste es real. Es código, así que hay que construirlo, probarlo y mantenerlo con buenos desarrolladores de Apex en el lado de Salesforce, y sigue ejecutándose dentro de los límites de Salesforce: la guía de Salesforce dice que las llamadas a clases Apex REST cuentan para los límites de API de la organización y que se aplican todos los límites del regulador estándar de Apex. Ahora tu equipo es dueño de una parte de la integración.

Clic para ampliar

Un endpoint Apex REST personalizado: Salesforce es dueño de un contrato más pequeño, registra cada llamada, y el cambio de nombre se queda dentro. Elegimos el contrato personalizado en más de un proyecto, porque había mucho procesamiento interno que ocultar.

Así que la pregunta de la primera o segunda semana trata tanto de personas como de tecnología: ¿conocerá el equipo externo Salesforce a fondo, y cambiará rápido cuando cambie tu modelo de datos? ¿O pones un envoltorio delante, y te haces cargo de él? Las dos respuestas pueden ser correctas. Lo que no es correcto es no decidir.

Conocimiento para el examen. Sabe cuándo exponer un endpoint Apex REST personalizado en lugar de dejar que el otro sistema llame a las API estándar: para dar a un equipo externo una interfaz estable, para orquestar varias escrituras dentro de Salesforce o para registrar tú mismo cada llamada. Conoce también el coste: código que mantener, y los límites de API de la organización y del regulador de Apex se siguen aplicando. Escríbelo en el contrato: qué interfaz, quién es su dueño y a quién hay que avisar cuando algo cambia. Para eso está la línea de cambio.

Haz concreta cada línea

Volumen: no “alto”. Alto para un equipo son 10.000 al día, para otro 100 millones. Pon cifras: 1.100 entregas al día, un conjunto por centro de distribución cada tarde, un 30 % de crecimiento anual. Esas cifras no solo eligen el mecanismo; dan forma al almacenamiento, la automatización, los bloqueos, el uso compartido, los índices, el archivado, la monitorización y la conservación. El contrato conecta el volumen de integración con la arquitectura de datos.

Frescura: no “tiempo real”. Escribe “una revisión está en la orden de trabajo en 15 minutos”, o “el manifiesto del socio está en Salesforce al menos un día antes de su fecha de entrega”, o “la conciliación de finanzas termina cada noche antes de que empiecen los informes”. Ahora se puede probar. “Tiempo real” es un adjetivo; “en 15 minutos” es un requisito.

Clave: no enterrada en el mapeo de campos. Escribe el campo de clave, si es único, quién lo asigna y si la relación es de verdad uno a uno. Si una cosa del negocio tiene varios registros externos, nombra el diseño: añade registros, no campos, como jerarquía, pares o un objeto hijo (módulo 2 y capítulo 6). Las claves no deberían ser una sorpresa de la implementación.

Autoridad de escritura: quizá la línea de datos más importante. No “objetos: Work Order”, sino “Redrock puede escribir los artículos, la dirección y la fecha de entrega; Salesforce es dueño de la cita, el equipo y la ruta”. Ahora la integración se puede probar contra el modelo de autoridad. Si alguien añade más tarde el equipo a la carga útil de Redrock, el contrato pregunta: ¿por qué? Se convierte en un control de gobierno.

“Pero el usuario de integración puede editarlo.” Me da igual. Un usuario de integración puede tener permisos amplios porque la implementación los necesita; eso no significa que cada integración que use esa identidad deba escribir todos los campos que puede. El permiso dice puede; la arquitectura dice debe. Los buenos sistemas necesitan ambos. Y leerlo todo también tiene una cara de rendimiento: el caso de estudio de la propia Salesforce sobre un usuario de integración lento está en el capítulo 8 (Cuando va lento).

Prueba de entrega: no “TI”. Nombra el lado que sabe lo que debería llegar, y que por tanto demuestra que llegó (módulo 3). Para C1 es Redrock, a partir de los resultados por registro de Salesforce. Para C2, el estado de salida, es Salesforce, con acuses de recibo. Para una extracción programada, es el cliente que pregunta. El contrato lo hace explícito para cada flecha.

Sensibilidad y recorrido: no “seguro”. Di qué hay en la carga útil y cuán sensible es (C1 lleva nombres, direcciones y números de teléfono de los destinatarios), y cada lugar por el que pasa: la capa de integración, sus registros, su cola de reintentos. Los datos que deben quedarse en un país también tienen que viajar por él.

Clic para ampliar

Cada lugar donde reposan los datos es una copia con una ubicación. Cuenta los registros y las colas.

Cambio: no “ya nos coordinaremos”. Di cómo evoluciona el contrato: los campos nuevos se añaden, nunca se renombran; un cambio incompatible recibe una versión nueva; el otro lado recibe un aviso. Un contrato que no puede cambiar con seguridad acabará rompiéndose en silencio.

El contrato no es el mapeo

La implementación también tendrá un mapeo de campos: el campo A de Redrock al campo B de Salesforce, transformaciones, tipos, valores por defecto. Útil. El contrato está un nivel por encima: por qué se mueven los datos, quién es su dueño, con qué frescura, cuánto, cómo se identifican, quién puede cambiarlos, qué forma tiene la interacción, quién demuestra que llegaron. Le da su contexto al mapeo.

Varias orgs, y “no lo muevas”

El panorama tiene Salesforce Norteamérica, Salesforce Europa y la organización de una empresa adquirida. Quizá estemos consolidando, sincronizando registros seleccionados, manteniendo algunos datos en local o construyendo una capa común de clientes o de análisis. No empieces por “¿cómo sincronizamos tres organizaciones?”. Empieza por los contratos. Para cada movimiento: ¿qué datos, en qué dirección, qué organización tiene la autoridad, cuál es la clave de empresa, con qué frescura, qué volumen, por qué copiarlo, quién puede escribirlo, quién demuestra que llegó? Que todas las cajas tengan un logotipo de Salesforce no simplifica las preguntas sobre los datos. Siguen siendo sistemas separados. El capítulo 14 trata los patrones de varias organizaciones.

Y a veces el contrato correcto dice no lo muevas. ¿Un gran conjunto de datos externo que solo se necesita de vez en cuando, con la autoridad en otro sitio, caro de copiar, que cambia constantemente y que sobre todo se consulta? ¿Para qué sincronizar otra copia? La virtualización puede ser mejor (Parte 3). El contrato fuerza esa conversación porque pregunta por qué existe la copia. Recuerda FleetLink en el módulo 1: C8 lleva solo la última posición, porque el contrato preguntó por qué se iban a copiar 73 millones de lecturas al año.

El contrato también debería sobrevivir a la tecnología.

Clic para ampliar

En la puesta en producción: el Middleware A y el contrato C1.

Sustituye el middleware dentro de tres años, y Redrock sigue siendo dueño de los artículos, el coordinador sigue necesitando las revisiones en 15 minutos, la clave es la misma, el volumen se conoce, la prueba de entrega sigue importando.

Clic para ampliar

Tres años después: un middleware nuevo, el mismo contrato.

El mecanismo cambia; el contrato sobrevive casi entero. Esa es la señal de que separaste la arquitectura de la implementación.

Los otros ocho contratos

Podríamos rellenar ahora de C2 a C9: el estado de vuelta a cada socio, los archivos de Keystone, el EDI de Brightwave, FleetLink, Snowflake, el ERP de finanzas. Los dejo a propósito para el Checkpoint 2, donde tomamos el panorama de la Parte 1 y le aplicamos cada capítulo de diseño de la Parte 2. Por ahora, tienes la herramienta y un ejemplo terminado.

Más allá del examen: lo que cambia la IA. No documentes un agente como “el agente tiene herramientas”. Cada acción importante es un contrato de integración: a qué sistema llama, qué clave identifica el registro, qué puede leer y escribir, quién es dueño de esos campos, el volumen esperado, qué pasa al reintentar o ante un fallo parcial, qué evidencia se guarda, cuán sensibles son los datos y adónde van. Quien llama es probabilístico e invoca operaciones empresariales deterministas, así que mantén la identificación de los registros, la autoridad de escritura, la gestión de fallos y la observabilidad fuera de la discreción del modelo.

El contrato se convierte en una herramienta de revisión

Cuando cada flecha importante tiene un contrato, una revisión deja de ser “¿el diagrama se ve bien?” y pasa a ser: ¿conocemos el iniciador y la dirección de los datos?, ¿la frescura es medible?, ¿conocemos los ceros?, ¿hay una clave estable?, ¿la autoridad es explícita?, ¿el patrón encaja con el requisito y el mecanismo con el patrón?, ¿quién demuestra que llegó?, ¿por dónde viajan los datos?, ¿cómo cambiará? Si la respuesta a alguna es “no lo hemos decidido”, bien: has encontrado trabajo de arquitectura antes de que producción lo encontrara por ti.

Lo que decide aquí un arquitecto

• Qué integraciones son lo bastante importantes para necesitar un contrato explícito, y sus números en el panorama.
• El iniciador, la dirección de los datos, la frescura medible y el Número de Ceros de cada una, antes de elegir la tecnología.
• La clave entre sistemas y la autoridad de escritura a nivel de campo que preservan la identidad y la gestión como maestro.
• El patrón, el mecanismo y quién demuestra la entrega en cada dirección.
• Cuán sensibles son los datos, por dónde viajan y cómo cambia el contrato sin romper el otro lado.
• Si los datos deberían moverse en absoluto, y si el contrato sobrevive a un cambio de tecnología.

Un panorama simplifica la complejidad, lo cual es útil, hasta que una flecha esconde las decisiones que mantienen la confianza en los datos. Así que dibuja la flecha, numérala y dale un contrato que puedas comprobar. Ahora significa algo, y cuando cambia la implementación, la arquitectura no desaparece con ella. Esa es la diferencia entre documentar una integración y diseñar el movimiento de los datos de la empresa.

Explora

• Salesforce Architects, Data Integration with Salesforce (se abre en una pestaña nueva) and Integration Patterns (se abre en una pestaña nueva), checked 2026-11-01. ⟲
• Apex Developer Guide, Introduction to Apex REST (se abre en una pestaña nueva), Winter ‘27 (API version 68.0), checked 2026-11-01. ⟲
• Salesforce Architects, Well-Architected, Data Protection Patterns (se abre en una pestaña nueva) and Operational Excellence (se abre en una pestaña nueva), checked 2026-11-01. ⟲
• El curso Integration Architect: Requisitos, Los patrones de integración y Multi-org (coming soon).