Empezar con Blume
Blume
Empezar con Blume
Saltar a la documentación
Recursos técnicos · API pública

Documentación de la API de Blume

Integre Blume con apps externas, canales B2B, ERPs, inventario, clientes, pedidos y carritos abandonados usando una API REST simple, versionada y lista para producción.

Empezar en Postman Ver endpoints
Base URL https://xapi.madebyblume.com Versión v1 Auth Bearer token Formato JSON 
curl -X POST "https://xapi.madebyblume.com/v1/developer/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$BLUME_CLIENT_ID" \
  -d "client_secret=$BLUME_CLIENT_SECRET" \
  -d "scope=catalog:read locations:read carts:read customers:read orders:read discounts:read"

INICIO RÁPIDO

Importe la colección y consulte la API

27 operaciones del Developer API, agrupadas por recurso. Los ejemplos utilizan datos ficticios y deben adaptarse a su cuenta de prueba.

Descargar colección Postman ↗Descargar entorno ↗
  1. Importe los dos archivos en Postman. Seleccione el entorno Blume · entorno local de Postman.
  2. Prepare sus credenciales. Abra Configuración → Developer API. Complete client_id y client_secret en sus variables locales de Postman. No publique ni comparta el secreto.
  3. Solicite solo el permiso necesario. El entorno empieza con scope=catalog:read; su cliente debe tener ese permiso habilitado.
  4. Ejecute auth → POST /auth/token. El script guarda access_token en el entorno al recibir una respuesta válida.
  5. Ejecute catalog → GET /catalog/products. El Bearer token se hereda de la colección. La respuesta lista productos e incluye stock.

Las peticiones apuntan a la API real, no a un sandbox. Las escrituras y envíos están bloqueados por defecto en la colección: revise cada cuerpo y habilite allow_writes=true únicamente cuando quiera ejecutar esas operaciones en su cuenta de prueba. No es necesario habilitarlo para consultar catálogo.

Las credenciales pertenecen a una compañía y sus scopes. El acceso de su cuenta y la habilitación del cliente se administran en Blume.

PREPARAR UNA CONSULTA

Genere un comando cURL de consulta

Elija una lectura y complete sus parámetros. El ejemplo usa $BLUME_TOKEN; esta página no solicita credenciales ni ejecuta llamadas a su cuenta.

cURL · pegar en terminal o importar en Postman
curl 'https://xapi.madebyblume.com/v1/developer/catalog/products' \
  -H "Authorization: Bearer $BLUME_TOKEN"

Para importar cURL: Postman → Import → pegue el comando. Sustituya la variable del token por {{access_token}} dentro de Postman.

Overview

Recursos y operaciones de la API

La API de Blume está pensada para aplicaciones externas que necesitan leer catálogo, consultar inventario por ubicación, leer y crear clientes, leer y crear pedidos, verificar descuentos y actualizar estados operativos sin entrar al admin.

Quickstart

Su primera consulta al catálogo.

POST
/v1/developer/auth/token Obtenga un access token y úselo para consultar el catálogo.
  1. Cree credenciales desde Configuración → Developer API en el admin.
  2. Solicite un token con grant_type=client_credentials.
  3. Incluya el token en cada request autenticado.
Content-Type application/x-www-form-urlencoded Token Bearer
Primera llamada
TOKEN=$(curl -s -X POST "https://xapi.madebyblume.com/v1/developer/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$BLUME_CLIENT_ID" \
  -d "client_secret=$BLUME_CLIENT_SECRET" \
  -d "scope=catalog:read" | jq -r .access_token)

curl "https://xapi.madebyblume.com/v1/developer/catalog/products?brand=Marca%20de%20ejemplo" \
  -H "Authorization: Bearer $TOKEN"
Enlace a esta operación ↗

Authentication

Autenticación con client credentials.

El endpoint de token no requiere Bearer token. Todos los demás endpoints requieren un token válido.

POST
/v1/developer/auth/token Intercambia client_id y client_secret por un access token.
Campo Tipo Requerido Descripción
grant_type string Sí Debe ser client_credentials.
client_id string Sí Identificador generado en el admin de Blume.
client_secret string Sí Se muestra una sola vez al crear o rotar credenciales.
scope string No Scopes separados por espacio. Si se omite, se intentan conceder los scopes permitidos al cliente.
Request
curl -X POST "https://xapi.madebyblume.com/v1/developer/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=blume_live_xxxxx" \
  -d "client_secret=blume_secret_xxxxx" \
  -d "scope=catalog:read locations:read carts:read customers:read orders:read discounts:read"
Response
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "catalog:read locations:read",
  "companyId": "company-guid",
  "clientId": "blume_live_xxxxx"
}

Scopes

Solicite solo los permisos que necesita.

Scope Permite Endpoints principales
catalog:read Leer catálogo, detalle de productos e inventario. /catalog/*
locations:read Leer ubicaciones y productos por ubicación. /locations/*
carts:read Leer resumen, lista y detalle de carritos abandonados. /carts/*
customers:read Listar clientes, consultar detalle y verificar si un cliente existe. /customers/*
customers:write Crear clientes y direcciones. /customers
orders:read Listar pedidos y consultar detalle con cliente, dirección, totales e items. /orders
orders:write Crear pedidos, actualizar estados permitidos y actualizar líneas de un pedido. /orders
discounts:read Verificar descuentos activos usando la misma lógica del carrito/checkout. /discounts/verify
emails:send Enviar emails transaccionales con plantillas aprobadas para la compañía. /emails/*
giftcards:read Verificar tarjetas de regalo sin consumirlas. /gift-cards/verify
giftcards:write Verificar y canjear tarjetas de regalo. /gift-cards/*

Webhooks

Eventos para integraciones instaladas.

Para recibir eventos en tiempo real, instale y configure la app/integración correspondiente desde el admin de Blume. La app define el webhookUrl, el secreto de firma y los eventos habilitados.

POST
Webhook URL configurado en la appBlume envía eventos al endpoint configurado en la instalación de la app.

Los webhooks usan application/json. El receptor debe responder con status 2xx para considerar el evento entregado. Si falla, Blume reintenta automáticamente con backoff.

Header Descripción
X-Blume-Event-Id Identificador único del evento. Úselo para idempotencia.
X-Blume-Topic Nombre del evento, por ejemplo order.created.
X-Blume-Timestamp Unix timestamp en segundos usado para la firma.
X-Blume-Signature Firma HMAC-SHA256. Se envía como sha256=<hex> cuando la app tiene signingSecret configurado.

La firma se calcula sobre el body crudo, antes de parsear JSON:

payloadToSign = timestamp + "." + rawBody signature = sha256=HMAC_SHA256(secret, payloadToSign)
Verificación Node.js
import crypto from "crypto";

function verifyBlumeSignature({ rawBody, timestamp, signature, secret }) {
  const payload = `${timestamp}.${rawBody}`;
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(payload, "utf8").digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature || "")
  );
}
EVENTS
Topics soportadosEventos disponibles para apps de integración.
Topic Cuándo se envía
order.created Cuando se crea un pedido.
order.paid Cuando un pedido queda pagado.
order.cancelled Cuando un pedido se cancela o rechaza.
cart.abandoned Cuando un carrito con contacto capturado pasa a abandonado.
cart.recovered Cuando un carrito abandonado se recupera y termina en orden.
JSON
Envelope del eventoTodos los eventos usan la misma estructura base.
Envelope
{
  "eventId": "evt_01J2XYZABC123",
  "topic": "order.created",
  "companyId": "company-guid",
  "createdAt": "2026-06-23T18:30:00Z",
  "source": "blume",
  "productMatchKey": "externalId",
  "data": {}
}

productMatchKey indica cómo debe la integración relacionar productos. El valor recomendado y predeterminado es externalId. Si la empresa lo configura, también puede ser barcode.

Default externalId Opcional barcode
EXAMPLE
order.createdEjemplo de payload para un pedido creada.
Payload
{
  "eventId": "evt_01J2XYZABC123",
  "topic": "order.created",
  "companyId": "company-guid",
  "createdAt": "2026-06-23T18:30:00Z",
  "source": "blume",
  "productMatchKey": "externalId",
  "data": {
    "orderId": "8123",
    "orderNumber": 1044,
    "urlCode": "order-url-guid",
    "status": "pending",
    "internalStatus": "created",
    "paymentStatus": "pending",
    "placedAt": "2026-06-23T18:29:55Z",
    "paidAt": null,
    "currency": "CRC",
    "subtotal": 25000,
    "discount": 0,
    "tax": 0,
    "shippingCost": 2500,
    "totalAmount": 27500,
    "paymentMethod": "moneytransfer",
    "couponCode": "",
    "channel": "web",
    "customer": {
      "customerId": "customer-guid",
      "fullName": "María Rodríguez",
      "email": "[email protected]",
      "phone": "88888888",
      "documentId": "1-1111-1111"
    },
    "shippingAddress": {
      "type": "shipping",
      "methodType": "delivery",
      "methodName": "Envío estándar",
      "country": "Costa Rica",
      "state": "San José",
      "city": "Escazú",
      "postalCode": "10201",
      "coordinates": "9.9325,-84.0796",
      "locationDescription": "Frente al parque",
      "status": "created",
      "trackingNumber": ""
    },
    "lineItems": [
      {
        "itemId": "10001",
        "productId": 12345,
        "externalId": 12345,
        "barcode": "7440000000000",
        "referenceCode": "ABC123",
        "colorCode": "001",
        "name": "Producto ejemplo",
        "description": "Producto ejemplo",
        "quantity": 1,
        "unitPrice": 25000,
        "lineTotal": 25000,
        "imageUrl": "https://...",
        "isDiscountPrice": false
      }
    ]
  }
}

Response format

Formato consistente de respuesta.

Los endpoints autenticados responden con el mismo sobre de respuesta para facilitar integración y manejo de errores.

Success
{
  "success": true,
  "data": {
    "id": 123,
    "status": "created"
  },
  "error": null,
  "meta": null
}
Error
{
  "success": false,
  "data": null,
  "error": {
    "code": "ORDER_VALIDATION_FAILED",
    "message": "The subtotal or total does not match."
  },
  "meta": null
}

Errors

Códigos de estado y errores comunes.

Status Cuándo ocurre Qué hacer
200 Solicitud exitosa. Leer data.
400 Body inválido, campos requeridos faltantes o validación fallida. Revise error.code y error.message.
401 Credenciales inválidas o token faltante/expirado. Solicite un token nuevo.
403 El token no tiene el scope requerido. Solicite scopes adicionales desde el admin.
400 · recurso ausente Recurso no encontrado para la compañía del token. Valide IDs externos y pertenencia al comercio.
400 · conflicto de negocio Intento de crear un recurso que ya existe. Use verify primero o maneje el registro existente.

429 · límite de uso: respete Retry-After cuando esté presente y aplique espera progresiva. Reutilice el token hasta su vencimiento (expires_in); no emita uno por petición. Los límites efectivos dependen de la configuración del servicio. No reintente escrituras automáticamente sin verificar el resultado anterior.

Las llamadas de token se registran como no facturables. Las llamadas de negocio se registran por cliente, comercio y endpoint para métricas de uso.

API reference

Endpoints disponibles.

GET/v1/developer/catalog/productsLista productos con filtros simples.
POST/v1/developer/catalog/products/searchLista productos con filtros en JSON.
POST/v1/developer/catalog/products/expandDetalle de producto por referencia y color.
GET/v1/developer/catalog/products/{externalId}/availabilityInventario por ubicación.
GET/v1/developer/catalog/products/{externalId}/nearest-locationsUbicaciones cercanas con stock del producto.
GET/v1/developer/customersLista clientes con métricas básicas.
GET/v1/developer/customers/{customerId}Detalle de cliente, métricas y direcciones.
POST/v1/developer/customers/verifyVerifica cliente existente.
POST/v1/developer/customersCrea un cliente.
POST/v1/developer/customers/{customerId}/addressesCrea dirección para un cliente.
GET/v1/developer/carts/summaryResumen de carritos abandonados, valor potencial y recuperación.
GET/v1/developer/carts/abandonedLista carritos abandonados filtrables.
GET/v1/developer/carts/{cartId}Detalle de carrito con productos y recovery URL.
GET/v1/developer/ordersLista pedidos con filtros básicos.
GET/v1/developer/orders/{orderId}Detalle de orden con cliente, dirección, totales e items.
POST/v1/developer/ordersCrea un pedido retail.
PATCH/v1/developer/orders/{orderId}/statusActualiza estados permitidos.
POST/v1/developer/orders/items/updateReemplaza líneas y totales de un pedido.
GET/v1/developer/discounts/verifyVerifica un descuento activo por código.
POST/v1/developer/discounts/verifyVerifica un descuento contra items del carrito.
POST/v1/developer/emails/template/sendEnvía email con plantilla aprobada.
GET/v1/developer/gift-cards/verifyVerifica una tarjeta de regalo.
POST/v1/developer/gift-cards/useCanjea una tarjeta de regalo válida.
GET/v1/developer/locationsLista ubicaciones configuradas.
GET/v1/developer/locations/nearestUbicaciones cercanas por coordenadas.
GET/v1/developer/locations/{externalWarehouseId}/productsProductos con stock en una ubicación.

Para integraciones que reciben eventos en tiempo real por webhook, instale y configure la app correspondiente desde el admin de Blume, por ejemplo Hilo u Odoo.

Catalog

Productos e inventario.

Para sincronizar el catálogo use GET /catalog/products, que incluye stock. Reserve expand para una ficha individual; no recorra todo el catálogo con expand. Use estos endpoints para listar productos, expandir detalle y consultar stock por local o bodega. Para integraciones, externalId es el identificador recomendado por defecto; barcode se devuelve como identificador alternativo cuando esté configurado.

GET
/v1/developer/catalog/productsLista productos visibles usando query params o tokens filter.
Scope catalog:read

Filtros soportados: brand, color, model, style, productType, size, gender, family, subFamily y campos custom.

Request
curl "https://xapi.madebyblume.com/v1/developer/catalog/products?brand=Marca%20de%20ejemplo&family=Zapatos" \
  -H "Authorization: Bearer $TOKEN"
Enlace a esta operación ↗
POST
/v1/developer/catalog/products/searchVersión JSON para filtros más cómodos desde backend.
Request
{
  "filters": [
    "brand=Marca%20de%20ejemplo",
    "family=Zapatos",
    "gender=Mujer"
  ]
}
Response shape
{
  "success": true,
  "data": [
    {
      "referenceCode": "ABC123",
      "colorCode": "001",
      "title": "Tênis ejemplo",
      "brand": "Marca de ejemplo",
      "price": 59900,
      "discountPrice": 49900,
      "externalId": 12345,
      "barcode": "7440000000000",
      "images": ["https://..."]
    }
  ]
}
Enlace a esta operación ↗
POST
/v1/developer/catalog/products/expandObtiene tallas, imágenes y variaciones de color por producto.
Request
{
  "referenceCode": "ABC123",
  "colorCode": "001"
}
Required referenceCodeRequired colorCode

La respuesta incluye products, images y colorVariations. Cada producto puede incluir externalId, barCode y barcode.

Enlace a esta operación ↗
GET
/v1/developer/catalog/products/{externalId}/availabilityConsulta stock total y por ubicación/bodega.

Usa Product.ExternalId, WarehouseStock.ExternalProductId y StoreLocation.ExternalWarehouseId para responder con stock por ubicación.

Scope catalog:read
Response
{
  "success": true,
  "data": {
    "externalId": 12345,
    "barcode": "7440000000000",
    "referenceCode": "ABC123",
    "colorCode": "001",
    "title": "Producto ejemplo",
    "productStock": 18,
    "totalAvailable": 18,
    "available": true,
    "locations": [
      {
        "storeLocationId": 7,
        "externalWarehouseId": 20,
        "name": "Escazú",
        "coordinates": "9.9325,-84.0796",
        "amount": 5,
        "available": true
      }
    ]
  }
}
Enlace a esta operación ↗
GET
/v1/developer/catalog/products/{externalId}/nearest-locationsUbicaciones cercanas que tienen stock suficiente para un producto.
Request
curl "https://xapi.madebyblume.com/v1/developer/catalog/products/12345/nearest-locations?latitude=9.9325&longitude=-84.0796&quantity=1&maxResults=5" \
  -H "Authorization: Bearer $TOKEN"

No requiere Google Maps cuando el cliente envía latitud/longitud. La cercanía se calcula por distancia geográfica.

Scope catalog:readScope locations:read
Enlace a esta operación ↗

Customers

Clientes y direcciones.

GET
/v1/developer/customersLista clientes con datos de contacto y métricas básicas.

Filtros soportados: search y limit.

Scope customers:readMax 200
Request
curl "https://xapi.madebyblume.com/v1/developer/customers?search=maria&limit=50"   -H "Authorization: Bearer $TOKEN"
Response shape
{
  "success": true,
  "data": {
    "count": 1,
    "limit": 50,
    "customers": [
      {
        "customerId": "customer-guid",
        "fullName": "María Rodríguez",
        "email": "[email protected]",
        "phone": "88888888",
        "createdAt": "2026-06-11T10:00:00",
        "metrics": {
          "totalOrders": 4,
          "totalSpent": 120000,
          "averageOrderValue": 30000,
          "lastOrderAt": "2026-06-10T14:00:00",
          "daysSinceLastOrder": 1
        }
      }
    ]
  }
}
Enlace a esta operación ↗
GET
/v1/developer/customers/{customerId}Detalle de cliente con métricas y direcciones.
Request
curl "https://xapi.madebyblume.com/v1/developer/customers/customer-guid"   -H "Authorization: Bearer $TOKEN"

La respuesta incluye datos de contacto, newsletter, métricas de compra y direcciones guardadas.

Scope customers:read
Enlace a esta operación ↗
POST
/v1/developer/customers/verifyVerifica si un cliente existe y devuelve su customerId.
Request
{
  "email": "[email protected]",
  "documentId": "1-1111-1111",
  "phone": "88888888"
}
Response
{
  "success": true,
  "data": {
    "exists": true,
    "customerId": "customer-guid",
    "matchedBy": "email"
  }
}
Scope customers:read
Enlace a esta operación ↗
POST
/v1/developer/customersCrea un cliente. Si ya existe, devuelve un error de negocio con 400.
Request
{
  "fullName": "María Rodríguez",
  "documentId": "1-1111-1111",
  "email": "[email protected]",
  "phone": "88888888",
  "subscribedNewsletter": true
}
Response
{
  "success": true,
  "data": {
    "customerId": "customer-guid",
    "created": true
  }
}
Scope customers:write
Enlace a esta operación ↗
POST
/v1/developer/customers/{customerId}/addressesCrea una dirección para el cliente.
Request
{
  "isDefault": true,
  "country": "Costa Rica",
  "state": "San José",
  "city": "Escazú",
  "zipCode": "10201",
  "coordinates": "9.9325,-84.0796",
  "locationDescription": "Frente al parque, casa azul."
}

Si isDefault es true, las direcciones previas del cliente se marcan como no predeterminadas.

Scope customers:write
Enlace a esta operación ↗

Carts

Carritos abandonados.

Use estos endpoints para consultar carritos abandonados, productos, contacto capturado, paso donde el cliente abandonó y enlaces de recuperación.

GET
/v1/developer/carts/summaryResumen de carritos abandonados y recuperación para el comercio del token.
Request
curl "https://xapi.madebyblume.com/v1/developer/carts/summary?range=7d" \
  -H "Authorization: Bearer $TOKEN"
Response
{
  "success": true,
  "data": {
    "range": "7d",
    "activeCount": 8,
    "abandonedCount": 18,
    "recoveredCount": 4,
    "potentialRevenue": 420000,
    "recoveredRevenue": 95000,
    "recoveryRate": 22.22,
    "emailSentCount": 12
  }
}
Scope carts:readLegacy b2b:read
Enlace a esta operación ↗
GET
/v1/developer/carts/abandonedLista carritos abandonados con contacto, totales y productos.

Filtros soportados: status, hasPhone, hasEmail, abandonedSince, updatedSince y limit.

Scope carts:readMax 200
Request
curl "https://xapi.madebyblume.com/v1/developer/carts/abandoned?hasPhone=true&updatedSince=2026-06-11T00:00:00&limit=50" \
  -H "Authorization: Bearer $TOKEN"
Response shape
{
  "success": true,
  "data": {
    "count": 1,
    "limit": 50,
    "carts": [
      {
        "cartId": "123",
        "status": "abandoned",
        "checkoutStep": "payment",
        "customerName": "María Rodríguez",
        "customerEmail": "[email protected]",
        "customerPhoneE164": "+50688888888",
        "abandonedAt": "2026-06-11T10:35:00",
        "total": 27500,
        "currency": "CRC",
        "recoveryUrl": "https://store.com/checkout/recover/...",
        "items": [
          {
            "productId": 12345,
            "barcode": "7440000000000",
            "referenceCode": "ABC123",
            "colorCode": "001",
            "description": "Producto ejemplo",
            "quantity": 1,
            "unitPrice": 25000,
            "lineTotal": 25000,
            "imageUrl": "https://..."
          }
        ]
      }
    ]
  }
}
Enlace a esta operación ↗
GET
/v1/developer/carts/{cartId}Detalle completo de un carrito específico.
Request
curl "https://xapi.madebyblume.com/v1/developer/carts/123" \
  -H "Authorization: Bearer $TOKEN"

La respuesta incluye contacto capturado, timestamps, totales, recoveryUrl, UTMs/referrer e items del carrito.

Scope carts:read
Enlace a esta operación ↗

Orders

Pedidos, detalle y estados.

La creación de pedidos usa el mismo flujo validado del checkout retail. La lectura devuelve cliente, dirección, totales e items con externalId y barcode cuando está disponible, y en customerMessage lo que el cliente escribió al pagar: una nota al comercio, vacía si no escribió nada. En tiendas de tarjetas de regalo ese campo trae los datos del destinatario en lugar de una nota libre.

GET
/v1/developer/ordersLista pedidos con filtros básicos.

Filtros soportados: customerId, status, paymentStatus, placedSince y limit.

Scope orders:readMax 200
Request
curl "https://xapi.madebyblume.com/v1/developer/orders?paymentStatus=complete&limit=50"   -H "Authorization: Bearer $TOKEN"
Response shape
{
  "success": true,
  "data": {
    "count": 1,
    "limit": 50,
    "orders": [
      {
        "orderId": "8123",
        "orderNumber": 1044,
        "customerId": "customer-guid",
        "status": "paid",
        "internalStatus": "created",
        "paymentStatus": "complete",
        "placedAt": "2026-06-11T10:00:00",
        "paidAt": "2026-06-11T10:05:00",
        "totalAmount": 27500,
        "currency": "CRC",
        "customerMessage": "Hace unos minutos hice otro pedido, agréguenme a ese para pagar un solo envío"
      }
    ]
  }
}
Enlace a esta operación ↗
GET
/v1/developer/orders/{orderId}Detalle de orden con cliente, dirección, totales, items y mensaje del cliente.
Request
curl "https://xapi.madebyblume.com/v1/developer/orders/8123"   -H "Authorization: Bearer $TOKEN"
Line item shape
{
  "productId": 12345,
  "externalId": 12345,
  "barcode": "7440000000000",
  "referenceCode": "ABC123",
  "colorCode": "001",
  "name": "Producto ejemplo",
  "quantity": 1,
  "unitPrice": 25000,
  "lineTotal": 25000
}
Scope orders:read
Enlace a esta operación ↗
POST
/v1/developer/ordersCrea un pedido retail para la tienda asociada al token.
Request
{
  "customer": {
    "fullName": "María Rodríguez",
    "documentId": "1-1111-1111",
    "email": "[email protected]",
    "phone": "88888888"
  },
  "address": {
    "country": "Costa Rica",
    "state": "San José",
    "city": "Escazú",
    "locationDescription": "Frente al parque",
    "coordinates": "9.9325,-84.0796"
  },
  "order": {
    "deliveryMethod": "Envío estándar",
    "deliveryType": "delivery",
    "paymentMethod": "moneytransfer",
    "currency": "CRC",
    "subtotal": 25000,
    "deliveryCost": 2500,
    "discount": 0,
    "tax": 0,
    "total": 27500,
    "items": [
      {
        "productId": 12345,
        "description": "Producto ejemplo",
        "quantity": 1,
        "unitPrice": 25000,
        "total": 25000,
        "isDiscountPrice": false
      }
    ]
  },
  "transactionLog": {
    "paymentMethod": "moneytransfer",
    "clientIp": "190.0.0.1"
  }
}
Response
{
  "success": true,
  "data": {
    "id": 8123,
    "total": 27500,
    "urlCode": "order-url-guid",
    "isGiftCard": false
  }
}
Scope orders:writeCreatedBy developer-api:clientId
Enlace a esta operación ↗
PATCH
/v1/developer/orders/{orderId}/statusActualiza uno de los estados públicos permitidos.
deliveryStatus Efecto interno Email
enproceso Orden en preparación. Sí, si sendEmail es true.
facturado Pago completo y orden facturada. Sí, si sendEmail es true.
rechazado Pago rechazado / orden cancelada. No envía email.
entregadocte Entregado al cliente. Sí, si sendEmail es true.
entregadomsj En tránsito con mensajero. Requiere entrega. Sí, si sendEmail es true.
Request
{
  "deliveryStatus": "facturado",
  "trackingNumber": "ABC123",
  "sendEmail": true
}
Response
{
  "success": true,
  "data": {
    "orderId": 8123,
    "number": 1044,
    "urlCode": "order-url-guid",
    "status": "created",
    "paymentStatus": "complete",
    "deliveryStatus": "created",
    "trackingNumber": "ABC123",
    "emailSent": true
  }
}
Scope orders:write
Enlace a esta operación ↗
POST
/v1/developer/orders/items/updateReemplaza las líneas de un pedido y actualiza subtotal, descuento y total.

Este endpoint reemplaza el flujo legacy de ASP orderItemUpdate. El campo orderNumber conserva el nombre legacy, pero debe contener el Order.Id interno de Blume.

Request
{
  "storeName": "demo-blume",
  "orderNumber": "8123",
  "subtotal": 24000,
  "discount": 1000,
  "total": 23000,
  "items": [
    {
      "description": "Zapato negro",
      "productId": 12345,
      "quantity": 1,
      "unitPrice": 24000,
      "total": 24000,
      "isDiscountPrice": false
    }
  ]
}
Response
{
  "success": true,
  "data": {
    "apiStatus": "approved",
    "isApproved": true,
    "data": {
      "orderNumber": "8123",
      "subtotal": 24000,
      "discount": 1000,
      "total": 23000,
      "items": []
    }
  }
}
Scope orders:writeBusiness status data.isApproved
Enlace a esta operación ↗

Discounts

Verificación de descuentos.

Estos endpoints usan la misma lógica de descuentos que el carrito y checkout de storefront.

GET
/v1/developer/discounts/verifyVerifica si un descuento manual está activo por código.
Request
curl "https://xapi.madebyblume.com/v1/developer/discounts/verify?code=WELCOME10"   -H "Authorization: Bearer $TOKEN"
Response
{
  "success": true,
  "data": {
    "isValid": true,
    "code": "WELCOME10",
    "discountAmount": 0,
    "discount": {
      "discountId": 10,
      "code": "WELCOME10",
      "name": "Bienvenida",
      "type": "percent",
      "applyTo": "subtotal",
      "value": 10,
      "validUntil": "2026-12-31T23:59:59"
    }
  }
}
Scope discounts:read
Enlace a esta operación ↗
POST
/v1/developer/discounts/verifyVerifica el descuento contra los items del carrito y calcula monto aplicable.
Request
{
  "code": "WELCOME10",
  "items": [
    {
      "productId": 12345,
      "description": "Producto ejemplo",
      "quantity": 1,
      "unitPrice": 25000,
      "total": 25000,
      "isDiscountPrice": false
    }
  ]
}

Use esta versión cuando necesite validar reglas por subtotal, cantidad de items o productos aplicables.

Scope discounts:read
Enlace a esta operación ↗

Emails

Emails con plantillas aprobadas.

Use este endpoint para eventos externos como compras en tienda física, cashback, encuestas u otras notificaciones operativas. Si no envía templateId, se usa la plantilla actual de cashback.

POST
/v1/developer/emails/template/sendEnvía un email usando una plantilla aprobada para la compañía.
Request
{
  "templateId": "SU_TEMPLATE_ID",
  "fromName": "Tienda de ejemplo",
  "customer": {
    "name": "Ana Cliente",
    "email": "[email protected]",
    "phone": "8888-8888",
    "documentId": "1-1111-1111"
  },
  "store": {
    "chain": "demo-blume",
    "name": "Tienda Escazú"
  },
  "order": {
    "number": "F001-100",
    "subtotal": "24000",
    "discount": "0",
    "tax": "0",
    "total": "24000",
    "cashback": "1200",
    "cashbackRedeem": "0",
    "items": [
      { "description": "Compra en tienda", "unitPrice": "24000", "quantity": "1", "total": "24000" }
    ]
  }
}
Response
{
  "success": true,
  "data": {
    "apiStatus": "success",
    "isApproved": true
  }
}
Scope emails:sendDefault template disponible
Enlace a esta operación ↗

Tarjetas de regalo

Verificación y canje.

Estos endpoints reemplazan el flujo legacy de ICG usando Bearer token y scopes. La respuesta mantiene apiStatus e isApproved para facilitar migración.

GET
/v1/developer/gift-cards/verifyVerifica una gift card sin marcarla como usada.
Request
curl "https://xapi.madebyblume.com/v1/developer/gift-cards/verify?code=ABCD1234&usedPlace=Sucursal%20de%20ejemplo" \
  -H "Authorization: Bearer $BLUME_TOKEN"
Response
{
  "success": true,
  "data": {
    "apiStatus": "approved",
    "isApproved": true,
    "data": {
      "orderNumber": 1044,
      "id": 9001,
      "campaignId": 1536,
      "code": "ABCD1234",
      "used": false,
      "itemDescription": "Gift card ₡10.000",
      "type": "regalia",
      "valorProducto": "10000.00",
      "codigoMaterial": ["MAT-001"]
    }
  }
}
Scope giftcards:read o giftcards:write
Enlace a esta operación ↗
POST
/v1/developer/gift-cards/useCanjea una gift card válida y la marca como usada.
Request
{
  "code": "ABCD1234",
  "usedPlace": "Sucursal de ejemplo"
}
Response
{
  "success": true,
  "data": {
    "apiStatus": "approved",
    "isApproved": true,
    "data": {
      "code": "ABCD1234",
      "used": true,
      "usedDate": "2026-05-05T10:30:00",
      "usedPlace": "Sucursal de ejemplo"
    }
  }
}
Scope giftcards:write
Enlace a esta operación ↗

Locations

Tiendas, bodegas y cercanía.

Las coordenadas se leen como latitude,longitude. Para cercanía, el cliente debe enviar latitud y longitud.

GET
/v1/developer/locationsLista ubicaciones configuradas de la tienda.
Response
{
  "success": true,
  "data": [
    {
      "id": 7,
      "externalWarehouseId": 20,
      "name": "Escazú",
      "address": "San José, Escazú",
      "coordinates": "9.9325,-84.0796",
      "phone": "8888-8888",
      "schedule": "L-S 10am-7pm",
      "directionsUrl": "https://..."
    }
  ]
}
Scope locations:read
Enlace a esta operación ↗
GET
/v1/developer/locations/nearestOrdena ubicaciones por cercanía a coordenadas del cliente.
Request
curl "https://xapi.madebyblume.com/v1/developer/locations/nearest?latitude=9.9325&longitude=-84.0796&maxResults=5" \
  -H "Authorization: Bearer $TOKEN"

Respuesta incluye distanceKm. Esto calcula distancia directa, no tiempo de manejo.

Enlace a esta operación ↗
GET
/v1/developer/locations/{externalWarehouseId}/productsProductos con stock en una ubicación específica.
Scope locations:readScope catalog:read
Response shape
{
  "success": true,
  "data": [
    {
      "externalId": 12345,
      "barcode": "7440000000000",
      "referenceCode": "ABC123",
      "colorCode": "001",
      "title": "Producto ejemplo",
      "brand": "Marca de ejemplo",
      "price": 59900,
      "stockAmount": 5,
      "primaryImageUrl": "https://..."
    }
  ]
}
Enlace a esta operación ↗

¿Necesita ayuda para integrar?

Genere credenciales desde el admin, pruebe con el token endpoint y escríbanos si necesita habilitar scopes o revisar un caso de uso específico. Para webhooks de integraciones específicas, instale y configure la app correspondiente desde el marketplace de Blume.

Contactar soporte Empezar ahora
No encontramos endpoints que coincidan con ese filtro.