@herrkin/bluexpress-sdk

SDK no oficial de Node.js/TypeScript para integrar BlueX en cualquier sistema (no dependiente de WooCommerce), construido mediante ingeniería inversa del plugin oficial BlueX for WooCommerce 3.1.6.

Disclaimer

• Este proyecto no es un producto oficial de BlueX.
• Los contratos fueron inferidos desde el comportamiento/código del plugin oficial de WooCommerce.
• BlueX puede cambiar endpoints, payloads o reglas sin previo aviso.

Quickstart (20 segundos)

1. Instala:

npm install @herrkin/bluexpress-sdk

2. Exporta variables:

export BLUEXPRESS_ENV=qa
export BLUEXPRESS_API_KEY="tu_key"
export BLUEXPRESS_ACCOUNT_NAME="https://tu-tienda.com/"

3. Copia/pega y ejecuta:

import { BluexpressClient } from "@herrkin/bluexpress-sdk";

const client = new BluexpressClient({
  environment: process.env.BLUEXPRESS_ENV,
  apiKey: process.env.BLUEXPRESS_API_KEY,
  accountName: process.env.BLUEXPRESS_ACCOUNT_NAME
});

const pricing = await client.getPricing({
  from: { country: "CL", district: "SCL" },
  to: { country: "CL", state: "13", district: "PRO" },
  serviceType: "EX",
  bultos: [{ largo: 10, ancho: 10, alto: 10, sku: "SKU-001", pesoFisico: 1, cantidad: 1 }],
  declaredValue: 10000,
  familiaProducto: "PAQU"
});

console.log(pricing);

4. Respuesta esperada (shape típico):

{
  "code": "00",
  "message": "OK",
  "data": {
    "total": 1990,
    "promiseDay": 1,
    "nameService": "Express",
    "isShipmentFree": false
  }
}

Cobertura actual

| Capacidad | Estado | |---|---| | Pricing | ✅ | | Geolocation | ✅ | | Integration status | ✅ | | Update credentials | ✅ | | Order webhook | ✅ | | Log webhook | ✅ | | Labels | ❌ | | Tracking operativo completo | ❌ |

Casos de uso típicos

• Cotizar envío en checkout (getPricing).
• Validar integración de tienda (validateIntegrationStatus).
• Enviar orden a BlueX (sendOrderWebhook).
• Reportar error operativo (sendLogWebhook).

Runtime y compatibilidad

• Node.js >= 18
• ESM ("type": "module")
• HTTP con fetch nativo
• Runtime dependency: solo zod

Entornos

• production -> https://eplin.api.blue.cl
• qa -> https://eplin.api.qa.blue.cl
• dev -> https://eplin.api.dev.blue.cl

También puedes forzar baseUrl manualmente.

Autenticación

Header requerido en todas las llamadas:

• x-api-key: <tu-api-key>

getPricing agrega además:

• price: <declaredValue>

API (resumen)

• getPricing(...): cotiza envío (pricing) con bultos, origen/destino, servicio y valor declarado.
• getGeolocation(...): resuelve códigos geográficos para comuna (bxgeo), con modo PUDO opcional.
• validateIntegrationStatus(...): revisa estado de integración ecommerce.
• updateIntegrationCredentials(...): actualiza credenciales de integración (accessToken/secretKey).
• sendOrderWebhook(...): envía payload de orden al webhook de BlueX.
• sendLogWebhook(...): reporta errores al endpoint de logs.

Limitaciones conocidas

• Basado en contratos inferidos del plugin WooCommerce 3.1.6.
• Requiere x-api-key válida en el entorno target.
• No probado exhaustivamente en producción pública (recomendado validar primero en QA).
• No incluye adapters específicos de framework (NestJS/Express/Next wrappers).
• No implementa flujos de etiquetas ni tracking operacional completo.

Errores

• BluexpressConfigError: configuración inválida del cliente.
• BluexpressApiError: error HTTP/red/timeout.
• BluexpressValidationError: request o response fuera de contrato.

Testing

El proyecto separa pruebas en 3 niveles:

• Unit tests: lógica del cliente con fetch mockeado.
• Contract tests: validación de schemas zod con fixtures.
• Integration tests: llamadas reales a BlueX (se ejecutan solo con env vars).

Comandos:

npm run test:unit
npm run test:contract
npm run test:integration
npm test

Para habilitar integration tests reales:

BLUEXPRESS_API_KEY=...
BLUEXPRESS_ENV=qa
# opcional:
# BLUEXPRESS_BASE_URL=https://eplin.api.qa.blue.cl
# BLUEXPRESS_ACCOUNT_NAME=https://tu-tienda.com/

Sin esas variables, la suite de integración se salta automáticamente.

Versionamiento

Se usa Changesets para controlar bump de versión/changelog.

npm run changeset
npm run version-packages
npm run release

Si habilitas automation en GitHub, necesitas NPM_TOKEN con permisos de publish para @herrkin/bluexpress-sdk.

Documentación ampliada

• Contratos observados: docs/contracts.md
• Entornos y autenticación: docs/auth-and-environments.md
• Workflows y ejemplos: docs/methods-and-workflows.md

Desarrollo

npm install
npm run build
npm test

Licencia

MIT. Ver LICENSE.