Integraciones y APIs
Si una persona mueve información entre dos sistemas, probablemente falta una integración.
Integración de sistemas a medida: diseñamos integraciones y APIs para que aplicaciones, plataformas y servicios intercambien datos y acciones automáticamente, sin depender de copiar, exportar, comprobar y volver a introducir información.
Primero entendemos qué información debe moverse, cuándo, en qué dirección y qué debe ocurrir si algo no encaja. Después diseñamos la conexión adecuada.
Muchas integraciones ya existen.Solo que las está haciendo una persona.
Cada vez que alguien exporta, copia, comprueba o vuelve a teclear información entre dos herramientas, está ejecutando una integración a mano. Funciona hasta que deja de funcionar: la información existe dos veces, los estados se separan y alguien tiene que decidir cuál es la buena.
- 01Abrir A
- 02Copiar los campos
- 03Pegar en B
Mismo cliente, dos estados. Alguien tendrá que darse cuenta.
Escenario conceptual · datos ficticios
Lo que hoy hace una persona
Copiar campo a campo
Cada campo que se copia a mano es un campo que puede llegar mal, tarde o no llegar. Y nadie sabe cuáles se copiaron ya.
- 01La información existe dos veces
- 02Los estados se separan
- 03Una persona los reconcilia
Nuestro trabajo es que esa integración deje de vivir en la cabeza y en las manos de alguien.
Así viaja un datocuando la integración existe.
Un único registro ficticio recorre el camino completo entre dos sistemas. Cada parada existe por una razón, y en cada una puede fallar algo distinto. Selecciona una etapa para ver qué ocurre.
CRM · registro de cliente
Facturación · cuenta
Dirección
La dirección importa tanto como el dato.
Antes de escribir una línea hay que decidir en qué sentido viaja la información y qué espera cada sistema a cambio.
A → B
La información nace en A y se refleja en B. B no devuelve nada. Es la forma más simple y, muchas veces, la correcta.
Encaja cuando un sistema es claramente el dueño del dato.
Mecanismos
No todo se conecta igual.
Una API es la vía más limpia, pero no es la única y no siempre está disponible. El mecanismo depende de lo que cada sistema permita.
- APIEl sistema expone funciones para leer, crear y actualizar. Permite integraciones completas y en tiempo real.
- WebhookEl sistema avisa cuando algo ocurre. Evita preguntar cada minuto si hay novedades.
- Archivo / importaciónExportaciones periódicas e importaciones programadas. Menos inmediato, pero fiable cuando no hay API.
- Base de datosLectura o escritura controlada en la base de datos del sistema. Solo cuando se tiene control y garantías.
- Sincronización programadaUn proceso revisa cambios cada cierto tiempo y los propaga. Sencillo de operar, con un retraso conocido.
- Adaptador a medidaCuando el sistema ofrece algo distinto a todo lo anterior, se construye la pieza que traduce entre ambos.
Lo primero es verificar qué expone cada sistema.Después se decide qué integración se puede construir.
- API oficialPermite una integración completa: lectura, escritura y avisos.
- Acceso parcialSe integra lo que el sistema permite y se documenta lo que queda fuera.
- Importar y exportarA veces es la opción más segura, con un ritmo conocido.
- Sin accesoEl sistema no expone lo necesario. Se diseña la alternativa viable; no se promete lo imposible.
Una integración no está terminadacuando funciona una vez.
El camino limpio es la parte fácil. Lo que distingue una integración de producción es lo que hace cuando el destino no responde, el dato no encaja o el mismo evento llega dos veces. Provoca un fallo y mira qué decide.
Provocar un fallo
- Recibir
- Validar
- Traducir
- Reglas
- Entregar · falla aquí
- Confirmar
Cómo se gestiona
- 01Reintentar con espera creciente
- 02Registrar cada intento
- 03Encolar si persiste
Reintentar tiene sentido: el fallo es transitorio y la operación se puede repetir sin efectos dobles. Si persiste, el dato espera en una cola con su traza.
Ninguna estrategia vale para todo. Cada fallo tiene su respuesta, y decidirla es parte del diseño.
Antes de sincronizar información,hay que decidir quién manda.
Una integración no debe crear verdades que compiten. Para cada dato, un sistema es la fuente y los demás tienen copias.
- Perfil del cliente CRMFuente de verdad FacturaciónCopia
- Estado del pago FacturaciónFuente de verdad CRMCopia
- Disponibilidad CalendarioFuente de verdad CRMCopia
Conectar datos también significasaber cuándo dos registros son la misma cosa.
El cliente 1827 en un sistema y el contacto a91f… en otro son la misma persona. La integración guarda esa relación y la usa siempre: así actualiza en vez de duplicar.
customer_id = 1827
contact_id = a91f…
Referencia externa guardada en ambos lados
- Identificadores externos: cada sistema guarda el id del otro.
- Referencias estables: se enlaza por identificador, no por nombre ni por correo.
- Mapeo explícito: la relación se crea una vez y se reutiliza siempre.
Una API define cómo otros sistemaspueden trabajar con el tuyo.
A veces no se trata de conectarse a una API, sino de construirla: tu sistema tiene información y funciones que otros necesitan usar. Una API es el contrato que dice qué se puede hacer, quién y con qué garantías.
Una API también marca límites
- Quién puede conectarse
- Credenciales por integrador, revocables sin tocar a los demás.
- Qué puede ver
- Solo los recursos y los campos que su función necesita.
- Qué puede cambiar
- Escritura acotada; el resto se lee y no se toca.
- Cómo se autentica
- Claves de API por entorno, o firmas cuando el mensaje debe poder verificarse.
- Qué queda restringido
- Reembolsos, borrados, cambios de permisos: operaciones aparte, con controles aparte.
- GETleer¿Qué puede saber otro sistema?
- POSTcrear¿Qué puede crear?
- PATCHactualizar¿Qué puede cambiar?
- EVENTcustomer.updated¿Qué se le avisa cuando algo ocurre?
- Correo con formato válido y único
- Referencia obligatoria
- Los estados solo cambian por transiciones permitidas
- Una credencial por integrador
- Alcance de lectura o de escritura
- Operaciones sensibles restringidas
FivoAsí está construida la API de Fivo: claves por entorno (live y test), webhooks firmados con HMAC-SHA256 y marca de tiempo, y registro de cada entrega.
No es documentación técnica. Es la decisión de qué puede hacer cada sistema con el tuyo.
No necesitas reemplazar todopara conseguir un sistema mejor.
Las herramientas que ya usáis suelen funcionar. Lo que falla es el espacio entre ellas. En lugar de sustituirlas por una plataforma nueva, se añade una capa fina que las hace comportarse como un solo sistema.
- Se queda
- Cada herramienta, con su equipo, sus datos y sus costumbres.
- Se añade
- Una capa que escucha, traduce y entrega entre ellas.
- Cambia
- Nadie vuelve a mover información a mano.
Cuando la integración necesita un servicio propio en medio, lo construimos. La intención sigue siendo la misma: que estos sistemas trabajen juntos.
- CRM
- ERP
- Web
- Pagos
- Calendario
- Documentos
Sistemas distintos.La misma responsabilidad: que los datos lleguen bien.
Dos sistemas reales que hemos construido y que viven de sus integraciones. Uno mueve pagos y eventos; el otro, operaciones y plataformas externas.
Traza A
Un comercio crea un cobro, un cliente paga desde otra red y el comercio recibe el resultado firmado.
Fivo es una infraestructura de pagos en stablecoins. Su valor para el comercio es exactamente una integración: una API para crear cobros y un webhook que le cuenta qué pasó.
- Claves de API por entorno, guardadas como hash y mostradas una sola vez
- Un pago no se registra dos veces: el hash de la transacción es único
- Un escáner revisa la cadena cada pocos minutos y recupera pagos aunque el navegador del cliente se cerrara
- ComercioCrea una sesión de checkout desde su servidorPOST /checkout/sessions · X-API-Key · cs_live_…
- ClientePaga desde la red donde tiene fondosUSDC en 9 redes · EURC en 3
- CircleEl importe cruza de red y llega a la wallet del comercioBridge Kit · CCTP v2 · sin custodia intermedia
- FivoVerifica la transacción en cadena antes de registrar nadacontrato · emisor · receptor · importe → completed
- WebhookAviso firmado al sistema del comercio, con reintentospayment.completed · HMAC-SHA256 · 1 s / 5 s / 25 s
- ComercioSu sistema recibe el evento y su panel lo muestra en tiempo realX-Fivo-Signature verificada · ack
Hechos verificados en los repositorios de cada sistema. Sin cifras de rendimiento inventadas.
¿Qué ocurre hoyentre los dos sistemas?
Elige la situación que más se parece a la vuestra. No es un diagnóstico cerrado: es lo primero que miraríamos.
Situación
Los estados se descuadran
Patrón probable
Definir la fuente de verdad, mapear los estados y diseñar la dirección de la sincronización con manejo de conflictos.
Lo primero que revisaríamos
- 01Qué sistema manda para cada estado
- 02Qué transiciones existen en cada lado
- 03Qué pasa hoy cuando no coinciden
No prometemos la solución antes de mirar los sistemas. El patrón probable es un punto de partida.
Para empezarbasta con esto.
No necesitas venir con documentación de API. Dinos qué herramienta utilizáis, cuál necesita recibir la información y qué hacéis hoy manualmente entre ambas.
- 01Sistema Adónde nace la información
- 02Sistema Bdónde debería terminar
- 03Qué debe moverseregistros, estados, documentos
- 04Cuándoal instante, cada hora, cada noche
- 05Qué sistema tiene razóncuando los dos difieren
- 06Qué ocurre hoyquién lo hace a mano y cuánto tarda
Tus sistemas
Cuéntanos qué herramientas tienen que hablar entre ellas.
Explícanos dónde nace la información, dónde debería terminar y qué hace hoy una persona para moverla. Revisaremos qué acceso ofrecen los sistemas y qué tipo de integración tiene sentido construir.