Representational State Transfer API

Definición

Una REST API (Representational State Transfer API) es un estilo de arquitectura de interfaz estandarizado que se apoya en el protocolo HTTP para permitir el intercambio de datos entre sistemas distintos. En el contexto del comercio electrónico directo al consumidor (DTC) y el cross-border e-commerce, una REST API funciona como el "sistema nervioso" que conecta tu tienda online con tu ERP, tu WMS, tus plataformas de anuncios y tus pasarelas de pago.

A diferencia de una API SOAP (basada en XML y con contratos rígidos), una REST API utiliza los verbos HTTP estándar —GET, POST, PUT, PATCH, DELETE— para operar sobre recursos identificados mediante URLs. Cada recurso representa una entidad de negocio: un pedido, un SKU, un nivel de stock, una campaña publicitaria o una transacción.

En términos prácticos: cuando tu sistema de inventario necesita saber cuántas unidades del SKU CAMISETA-NEGRA-M quedan en el almacén de Madrid, no consulta una base de datos directamente, sino que hace una petición GET /api/v1/inventory/CAMISETA-NEGRA-M y recibe una respuesta JSON con el dato actualizado.

Analogía

Imagina que tu negocio DTC es un restaurante con varias cocinas (almacenes) y varios camareros (sistemas). La REST API es el sistema de comandas estandarizado: el camarero no entra a la cocina a gritar, sino que escribe la comanda en un formato acordado, la deja en un punto concreto y la cocina la procesa. Cada plato tiene un nombre único (recurso), cada acción tiene un verbo (pedir, modificar, cancelar) y siempre se responde con un estado (pedido recibido, en preparación, listo).

Si cada cocina usara un idioma distinto para las comandas, el restaurante sería un caos. Eso es exactamente lo que ocurre cuando conectas Shopify con un ERP legacy sin una REST API bien definida.

Fórmula

La estructura básica de una petición REST se puede expresar así:

Petición = Método HTTP + URL del recurso + Cabeceras + Cuerpo (opcional)

Respuesta = Código de estado + Cabeceras + Cuerpo (normalmente JSON)

Y el coste operativo de sincronización se estima con:

Coste de sincronización = (Nº de peticiones × Latencia media) + (Nº de errores × Coste de reintento)

Ejemplo con datos reales:

- 10.000 pedidos/día × 1 petición por pedido = 10.000 peticiones

- Latencia media: 180 ms

- Tasa de error: 0,5% → 50 reintentos

- Coste de reintento: 0,002 € por petición

Coste = (10.000 × 0,180 s) + (50 × 0,002 €) = 1.800 s + 0,10 €

Es decir, 30 minutos de procesamiento diario y 0,10 € en reintentos. Si la tasa de error sube al 5%, el coste de reintentos se multiplica por 10.

Tabla comparativa

Aplicaciones en DTC y cross-border

1. Sincronización de pedidos multicanal

Cuando vendes en Shopify, Amazon y TikTok Shop, cada plataforma expone una REST API distinta. Un middleware hace GET /orders?since=2024-01-01 en cada una y consolida los pedidos en tu OMS. Sin REST API, tendrías que importar CSV manualmente cada 2 horas, con riesgo de duplicados y errores humanos.

2. Actualización de stock en tiempo real

Cada vez que se vende una unidad, tu WMS dispara un PATCH /inventory/{sku} a todas las plataformas. Si no lo haces, vendes stock que no tienes y recibes penalizaciones por cancelación. En Amazon, una tasa de cancelación superior al 2,5% puede suspender tu cuenta.

3. Sincronización de campañas publicitarias

Las REST APIs de Meta Ads, Google Ads y TikTok Ads permiten ajustar presupuestos y públicos automáticamente. Por ejemplo, si el ROAS de un conjunto de anuncios cae por debajo de 1,8, puedes pausarlo vía POST /campaigns/{id}/pause en menos de 200 ms.

4. Pasarelas de pago y fraude

Stripe, Adyen y PayPal ofrecen REST APIs para crear cargos, reembolsos y consultar el estado de una transacción. Un POST /payment_intents con un payload JSON es hoy el estándar en checkout.

5. Logística y tracking

Transportistas como DHL, SEUR o UPS exponen REST APIs para generar etiquetas y consultar tracking. Un GET /shipments/{tracking_number} te devuelve el estado sin scraping.

Errores comunes

1. Confundir REST con "cualquier API HTTP". REST exige recursos identificables, uso correcto de verbos y statelessness. Una API que usa POST /getOrders no es REST, es RPC disfrazado.

2. Ignorar los códigos de estado. Un 200 OK con un cuerpo de error es una trampa. Debes manejar 4xx (error del cliente) y 5xx (error del servidor) con lógica de reintento exponencial.

3. No implementar rate limiting. Shopify permite 2 peticiones/segundo en el plan Basic y 4 en Plus. Amazon SP-API tiene límites por operación. Si los ignoras, recibirás 429 Too Many Requests y tu sincronización se detendrá.

4. Falta de idempotencia. Si reintentas un POST /orders sin una clave de idempotencia, puedes crear pedidos duplicados. Usa el header Idempotency-Key con un UUID.

5. No versionar la API. Cambiar /api/orders sin avisar rompe integraciones. Usa /api/v1/, /api/v2/ y mantén compatibilidad hacia atrás al menos 12 meses.

6. Exponer datos sensibles en URLs. Nunca pongas tokens en query strings (?api_key=...), porque quedan en logs. Usa headers Authorization: Bearer.

7. Asumir que todos los JSON son iguales. Las fechas pueden venir en ISO 8601, Unix timestamp o formato local. Normaliza antes de insertar en tu base de datos.

Términos relacionados

- Webhook: notificación push que un sistema envía a otro cuando ocurre un evento. Complementa a REST API, que es pull.

- GraphQL: alternativa a REST que permite consultas declarativas y evita over-fetching.

- Rate limiting: control de peticiones por ventana de tiempo.

- Idempotencia: propiedad que garantiza que repetir una petición no altera el resultado.

- OAuth 2.0: estándar de autorización usado por Shopify, Amazon y Meta para REST APIs.

- Middleware / iPaaS: capa que orquesta múltiples REST APIs (Zapier, Make, Celigo, n8n).

- JSON:API: especificación que estandariza la estructura de respuestas REST.

- OpenAPI / Swagger: formato para documentar y generar clientes de REST APIs.