Recursos técnicos · API pública

Blume Developer API

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

Empezar en 5 minutos 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"

const params = new URLSearchParams({
  grant_type: "client_credentials",
  client_id: process.env.BLUME_CLIENT_ID,
  client_secret: process.env.BLUME_CLIENT_SECRET,
  scope: "catalog:read locations:read"
});

const res = await fetch("https://xapi.madebyblume.com/v1/developer/auth/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: params
});

const token = await res.json();
console.log(token.access_token);

using var client = new HttpClient();

var body = new Dictionary<string, string>
{
    ["grant_type"] = "client_credentials",
    ["client_id"] = Environment.GetEnvironmentVariable("BLUME_CLIENT_ID")!,
    ["client_secret"] = Environment.GetEnvironmentVariable("BLUME_CLIENT_SECRET")!,
    ["scope"] = "catalog:read locations:read"
};

var res = await client.PostAsync(
    "https://xapi.madebyblume.com/v1/developer/auth/token",
    new FormUrlEncodedContent(body));

res.EnsureSuccessStatusCode();
var json = await res.Content.ReadAsStringAsync();

Overview

Lo esencial para empezar.

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

Quickstart

Haga la primera llamada en 5 minutos.

POST

/v1/developer/auth/token Obtenga un access token y úselo para consultar el catálogo.

Cree credenciales desde Configuración → Developer API en el admin.
Solicite un token con grant_type=client_credentials.
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=Nike" \
  -H "Authorization: Bearer $TOKEN"

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"

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 tiendas/ubicaciones y productos por ubicación.	`/locations/*`
`customers:read`	Verificar si un cliente existe.	`/customers/verify`
`customers:write`	Crear clientes y direcciones.	`/customers`
`orders:write`	Crear órdenes, actualizar estados permitidos y actualizar líneas de una orden.	`/orders`
`emails:send`	Enviar emails transaccionales con plantillas aprobadas para la compañía.	`/emails/*`
`giftcards:read`	Verificar gift cards sin consumirlas.	`/gift-cards/verify`
`giftcards:write`	Verificar y canjear gift cards.	`/gift-cards/*`

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.
`404`	Recurso no encontrado para la compañía del token.	Valide IDs externos y pertenencia a la tienda.
`409`	Intento de crear un recurso que ya existe.	Use verify primero o maneje el registro existente.

Las llamadas de token se registran como no facturables. Las llamadas de negocio se registran por cliente, tienda 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.

POST/v1/developer/customers/verifyVerifica cliente existente.

POST/v1/developer/ordersCrea una orden retail.

PATCH/v1/developer/orders/{orderId}/statusActualiza estados permitidos.

POST/v1/developer/orders/items/updateReemplaza líneas y totales de una orden.

POST/v1/developer/emails/template/sendEnvía email con plantilla aprobada.

GET/v1/developer/gift-cards/verifyVerifica una gift card.

POST/v1/developer/gift-cards/useCanjea una gift card válida.

GET/v1/developer/locations/nearestUbicaciones cercanas por coordenadas.

Catalog

Productos e inventario.

Use estos endpoints para listar productos, expandir detalle y consultar stock por tienda o bodega.

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=Nike&family=Zapatos" \
  -H "Authorization: Bearer $TOKEN"

POST

/v1/developer/catalog/products/searchVersión JSON para filtros más cómodos desde backend.

Request

{
  "filters": [
    "brand=Nike",
    "family=Zapatos",
    "gender=Mujer"
  ]
}

Response shape

{
  "success": true,
  "data": [
    {
      "referenceCode": "ABC123",
      "colorCode": "001",
      "title": "Tênis ejemplo",
      "brand": "Nike",
      "price": 59900,
      "discountPrice": 49900,
      "externalId": 12345,
      "images": ["https://..."]
    }
  ]
}

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.

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,
    "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
      }
    ]
  }
}

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

Customers

Clientes y direcciones.

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

POST

/v1/developer/customersCrea un cliente. Si ya existe, responde 409 Conflict.

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

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

Orders

Crear órdenes y actualizar estados.

La creación de órdenes usa el mismo flujo validado del checkout retail: cliente, dirección, items, transacción y totales.

POST

/v1/developer/ordersCrea una orden 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

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

POST

/v1/developer/orders/items/updateReemplaza las líneas de una orden 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": "cachos",
  "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

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": "d-aebc802e5344497a9e085b68bdf8bf51",
  "fromName": "Plusshop Cashback",
  "customer": {
    "name": "Ana Cliente",
    "email": "[email protected]",
    "phone": "8888-8888",
    "documentId": "1-1111-1111"
  },
  "store": {
    "chain": "plusshop",
    "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

Gift cards

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=POPS%20Escazu" \
  -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

POST

/v1/developer/gift-cards/useCanjea una gift card válida y la marca como usada.

Request

{
  "code": "ABCD1234",
  "usedPlace": "POPS Escazú"
}

Response

{
  "success": true,
  "data": {
    "apiStatus": "approved",
    "isApproved": true,
    "data": {
      "code": "ABCD1234",
      "used": true,
      "usedDate": "2026-05-05T10:30:00",
      "usedPlace": "POPS Escazú"
    }
  }
}

Scope giftcards:write

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

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.

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,
      "referenceCode": "ABC123",
      "colorCode": "001",
      "title": "Producto ejemplo",
      "brand": "Nike",
      "price": 59900,
      "stockAmount": 5,
      "primaryImageUrl": "https://..."
    }
  ]
}

¿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.

Contactar soporte Empezar ahora

No encontramos endpoints que coincidan con ese filtro.