Cómo se construye una integración por API REST, paso a paso

En el artículo sobre integraciones contamos qué conecta IANALITICS y para qué le sirve a una empresa. Este es la otra mitad: cómo se hace. Está pensado para quien va a estar del lado técnico del proyecto, y también para quien quiere entender qué le están cotizando cuando le hablan de una integración a la medida.

Nuestras integraciones se construyen sobre API REST y se programan en Python. Los pasos de abajo sirven para casi cualquier sistema: un CRM, un ERP, una hoja de cálculo de Google o un sistema de facturación.

Qué es una API REST, en concreto

Una API REST organiza la información de un sistema en recursos, y cada recurso tiene su propia dirección web: los clientes, las facturas, los productos. Para trabajar con ellos se usan los mismos métodos del protocolo HTTP que usa tu navegador, y los datos viajan casi siempre en formato JSON.

Cada respuesta trae un código que dice cómo salió todo. Vale la pena conocerlos, porque la integración decide qué hacer según el código que recibe:

• 200 o 201: todo bien; en el caso del 201, se creó el registro.
• 400: la petición está mal armada. Falta un dato o el formato no es el esperado.
• 401 o 403: la credencial no es válida o no tiene permiso para esa operación.
• 404: lo que buscas no existe.
• 429: hiciste demasiadas peticiones seguidas. Hay que esperar.
• 500 en adelante: falló el otro sistema. Se puede reintentar.

Así se ve una petición real

Crear un contacto en un CRM, con datos de ejemplo:

POST https://api.ejemplo-crm.com/v1/contacts
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "name": "Distribuidora Andina SAS",
  "tax_id": "900123456-7",
  "email": "compras@ejemplo.com",
  "city": "Medellín"
}

Y lo que responde el CRM si todo salió bien:

HTTP/1.1 201 Created

{
  "id": "c_48213",
  "name": "Distribuidora Andina SAS",
  "created_at": "2026-09-13T10:42:05-05:00"
}

Eso es todo lo que pasa por debajo. Una integración es, en el fondo, un programa que arma peticiones como esa en el momento correcto y sabe qué hacer con la respuesta.

Paso 1. Definir el flujo antes de escribir código

La mitad de los problemas de una integración se resuelven o se crean aquí. Hay que dejar por escrito:

• Qué evento dispara el envío. Una venta confirmada, una factura emitida, un cliente nuevo.
• Qué datos viajan y en qué dirección. ¿El CRM le pasa clientes a IANALITICS, IANALITICS le pasa ventas al CRM, o las dos cosas?
• Quién manda en cada dato. Si el correo de un cliente se cambia en los dos sistemas el mismo día, ¿cuál gana? Sin esa regla, los sistemas se pisan entre ellos.
• Cada cuánto y con qué volumen. No es lo mismo diez ventas al día que diez mil.

Paso 2. Leer la documentación de la otra API

Aquí se descubre qué tan sencilla va a ser la integración. Lo primero que hay que buscar:

• Cómo se autentica.
• Los límites de uso: cuántas peticiones permite por minuto o por día.
• La paginación: las listas largas llegan por partes, y hay que pedirlas una por una.
• Si tiene ambiente de pruebas (sandbox), para no ensayar con datos reales.
• Si ofrece webhooks o si toca consultar cada cierto tiempo para enterarse de los cambios.

Si el sistema no tiene API, todavía hay caminos, como leer su base de datos (SQL Server, MySQL) o intercambiar archivos. Funcionan, pero son más frágiles, y eso hay que decirlo desde el principio.

Paso 3. Resolver la autenticación

Ninguna API seria responde sin saber quién pregunta. Las formas más comunes son tres:

• API key. Una clave fija que se envía en cada petición. Es simple, pero si se filtra, quien la tenga puede hacer todo lo que esa clave permite hasta que alguien la cambie.
• OAuth 2.0. Alguien de la empresa autoriza la conexión desde una pantalla del proveedor, y la integración recibe un token con permisos limitados que vence y se renueva. Es lo que usan Google (Gmail, Sheets, Calendar), Microsoft (Power BI) y buena parte de los CRM.
• Tokens JWT. El sistema valida las credenciales una vez y entrega un token firmado que acompaña las peticiones siguientes. Es el esquema de la arquitectura de IANALITICS que aparece en el diagrama del inicio.

Sea cual sea el método, dos reglas no se negocian. Las credenciales van en variables de entorno o en un gestor de secretos, nunca escritas en el código ni guardadas en un repositorio. Y se piden solo los permisos necesarios: si la integración solo lee facturas, su credencial no debería poder borrar clientes.

Paso 4. Mapear los campos

Dos sistemas casi nunca le dicen igual a la misma cosa. Un mapeo típico entre la ficha de cliente de IANALITICS y un CRM se ve así:

Los detalles pequeños son los que rompen: fechas en formatos distintos, valores en pesos con o sin decimales, zonas horarias. Una venta registrada a las 11 de la noche en Colombia ya es del día siguiente en hora UTC, y si nadie lo tiene en cuenta aparece en el informe del día equivocado. Por eso IANALITICS pide configurar la zona horaria de la empresa desde los ajustes iniciales.

Paso 5. Escribir la integración

Un ejemplo simplificado en Python que envía un cliente a un CRM. Antes de crear, busca si ya existe por NIT; si existe, lo actualiza. Así, correr la sincronización dos veces no duplica nada.

import os
import time
import requests

CRM_URL = "https://api.ejemplo-crm.com/v1"
TOKEN = os.environ["CRM_TOKEN"]  # la credencial nunca va escrita en el código


def llamar(metodo, ruta, **kwargs):
    for intento in range(4):
        r = requests.request(
            metodo,
            f"{CRM_URL}{ruta}",
            headers={"Authorization": f"Bearer {TOKEN}"},
            timeout=10,
            **kwargs,
        )
        if r.status_code == 429 or r.status_code >= 500:
            time.sleep(2 ** intento)  # espera 1, 2, 4 y 8 segundos
            continue
        r.raise_for_status()  # un 400 o un 401 no se reintenta: se reporta
        return r.json()
    raise RuntimeError(f"{metodo} {ruta} falló después de 4 intentos")


def sincronizar_cliente(cliente):
    datos = {
        "name": cliente["nombre"],
        "tax_id": cliente["nit"],
        "email": cliente["correo"],
    }
    existentes = llamar("GET", "/contacts", params={"tax_id": cliente["nit"]})
    if existentes["data"]:
        contacto_id = existentes["data"][0]["id"]
        llamar("PATCH", f"/contacts/{contacto_id}", json=datos)
    else:
        llamar("POST", "/contacts", json=datos)

Tres detalles de ese código importan más que el resto:

• El tiempo límite. Sin timeout, una API lenta deja el proceso colgado indefinidamente.
• Reintentar solo lo que vale la pena. Un 429 o un 500 pueden resolverse solos si se espera; reintentar un 400 es repetir el mismo error cuatro veces.
• Buscar antes de crear. Es lo que evita que un corte de internet a mitad de la sincronización deje el CRM lleno de clientes repetidos.

Paso 6. Prepararse para cuando falle

Va a fallar en algún momento. La pregunta es si alguien se entera a tiempo. Lo mínimo:

• Registrar cada envío con fecha, datos y respuesta.
• Guardar lo que falló en una lista de pendientes para reenviarlo, en lugar de perderlo.
• Avisarle a una persona cuando los errores se acumulan.
• Mostrar el estado donde la gente trabaja, no solo en un archivo de registro que nadie abre.

Un ejemplo de lo último: en la facturación electrónica de IANALITICS cada documento queda marcado como Emitida o Error en el mismo listado de facturas. El error se ve ahí, y no el día que el cliente llama a reclamar.

Paso 7. Probar y salir a producción de a poco

Primero en el ambiente de pruebas y con casos incómodos, no solo con el cliente perfecto: uno sin correo, un NIT con guion, un producto con tildes y eñes, una venta anulada. Con facturación electrónica esto ni siquiera es opcional, porque la DIAN exige superar un set de pruebas antes de dejar emitir.

Después, salir a producción con poco volumen o con un solo tipo de documento, comparar durante unos días contra el proceso manual y, cuando los números cuadren, ampliar.

Paso 8. Mantenerla viva

Una integración no se termina el día que sale. Las APIs publican versiones nuevas y anuncian cuándo apagan las viejas, los tokens vencen, y el negocio empieza a usar un campo que antes no existía. Ese mantenimiento hay que presupuestarlo desde el principio. Desconfía de una cotización de integración que no lo mencione.

Consultar cada cierto tiempo o esperar un aviso

Hay dos formas de enterarse de que algo cambió en el otro sistema. Consultar a intervalos, lo que en inglés llaman polling, es simple y funciona con cualquier API, pero gasta peticiones aunque no haya novedades y siempre llega con algo de retraso.

Los webhooks invierten la dirección: el otro sistema le avisa a una dirección web tuya cuando pasa algo. Son inmediatos, pero esa dirección queda expuesta a internet, así que hay que verificar la firma de cada aviso y estar preparado para recibir el mismo aviso dos veces.

Cómo encaja todo esto en IANALITICS

Una integración entra a IANALITICS por el mismo camino que un usuario, como muestra el diagrama de arquitectura: se autentica y recibe un token JWT, el sistema verifica que su rol tenga permiso para esa operación, y solo entonces el servidor consulta o actualiza la base de datos MySQL. Cada paso queda en el registro de eventos.

Cuando lo que se necesita es análisis y no intercambio de datos, por ejemplo alimentar tableros en Power BI, la integración publica un endpoint REST con los datos del tablero y Power BI lo lee con su conector web. Es como trabajamos el proyecto de Migtra. Si el cliente prefiere los datos crudos, también se puede dar acceso directo a la base de datos, para consulta o edición, bajo un acuerdo de confidencialidad y protección de datos; para análisis, lo recomendable es que sea de solo lectura.

El plan Performance incluye hasta tres integraciones API a la medida. Lo que incluye cada plan está en la página de precios.

¿Te sirvió? Cada semana compartimos guías como esta en LinkedIn. Sigue a IANALITICS en LinkedIn →

Compártelo: WhatsApp LinkedIn Facebook

También nos encuentras en Facebook e Instagram.