Business APIReferenciaSDK v0.4.02 canales

Referencia

Endpoints, OpenAPI y errores. Elige un SDK o integra con cURL; todos los ejemplos usan la misma autenticación HMAC.

Inicio Seguridad Pagos Catálogo API Agentes

$npm install @hanix.io/business

Ver paquete

Viendo ejemplos en Node.js(Disponible)

@hanix.io/business

Referencia

Endpoints Business

Rutas alineadas con la colección Postman «HANIX - BACK» → carpeta Business. Base: https://api.hanix.io/api/v1.

Método	Ruta	SDK	Descripción
Órdenes de pago
POST	/business/payment-orders	createPaymentOrder	Crea una orden de pago. Con items[] opcional calcula montos desde el catálogo (sin sales_order).
GET	/business/payment-orders	listPaymentOrders	Lista órdenes del comercio.
GET	/business/payment-orders/:payment_order_id	getPaymentOrder	Detalle de una orden por UUID.
POST	/business/payment-orders/:payment_order_id/attempts	createPaymentAttempt	Crea un intento de pago y devuelve datos de checkout del PSP.
GET	/business/payment-orders/:payment_order_id/attempts	listPaymentOrderAttempts	Intentos de pago de una orden.
POST	/business/payment-orders/:payment_order_id/cancel	cancelBusinessPaymentOrder	Cancela una orden de pago del comercio.
GET	/business/payment-orders/:payment_order_id/checkout	getBusinessPaymentOrderCheckout	Vista enriquecida para UI de checkout: métodos PSP, intentos, contexto legal Wompi.
GET	/business/payment-orders/by-public-token/:public_token/checkout	getBusinessPaymentOrderCheckoutByPublicToken	Vista enriquecida de checkout por public_token (solo órdenes del comercio autenticado).
PSP — Config (solo backend)
GET	/business/merchant-payment-settings/psp-methods	listMerchantPspMethods	Configuración PSP del comercio (credenciales, webhooks). Solo backend — nunca en frontend del comprador.
Catálogo — Categorías
GET	/business/merchant-catalog/categories	listCatalogCategories	Lista categorías del catálogo.
PUT	/business/merchant-catalog/categories/bulk	upsertCatalogCategories	Crea o actualiza categorías en lote.
DELETE	/business/merchant-catalog/categories/bulk	deleteCatalogCategories	Elimina categorías por id.
POST	/business/merchant-catalog/categories/images/direct-uploads	requestCatalogCategoryImageDirectUploads	Solicita URLs de subida directa a Cloudflare.
PUT	/business/merchant-catalog/categories/images/bulk	registerCatalogCategoryImages	Registra imágenes de categoría ya subidas.
DELETE	/business/merchant-catalog/categories/images/bulk	deleteCatalogCategoryImages	Quita imágenes de categorías.
Catálogo — Productos
GET	/business/merchant-catalog/currencies	listCatalogCurrencies	Monedas disponibles para productos del comercio.
POST	/business/merchant-catalog/products	createCatalogProduct	Crea un producto con al menos una variante obligatoria.
GET	/business/merchant-catalog/products	listCatalogProducts	Lista productos con filtros y paginación.
GET	/business/merchant-catalog/products/:product_id	getCatalogProduct	Detalle de producto con variantes e imágenes.
PATCH	/business/merchant-catalog/products/:product_id	updateCatalogProduct	Actualiza nombre, slug, categoría, estado, etc.
DELETE	/business/merchant-catalog/products/bulk	deleteCatalogProducts	Elimina productos por id.
PATCH	/business/merchant-catalog/products/:product_id/variants/:variant_id	updateCatalogProductVariant	Actualiza SKU, precio, stock, opciones, etc.
PATCH	/business/merchant-catalog/products/:product_id/variants/:variant_id/warehouse-stock	setCatalogVariantWarehouseStock	Stock físico en almacén (solo panel / integraciones).
PUT	/business/merchant-catalog/variants/bulk	upsertCatalogVariants	Crea o actualiza variantes en lote.
DELETE	/business/merchant-catalog/variants/bulk	deleteCatalogVariants	Elimina variantes por id.
POST	/business/merchant-catalog/images/direct-uploads	requestCatalogImageDirectUploads	Solicita URLs de subida directa para imágenes de producto.
PUT	/business/merchant-catalog/images/bulk	registerCatalogImages	Registra imágenes de producto ya subidas.
PATCH	/business/merchant-catalog/images/bulk	updateCatalogImages	Actualiza imágenes de producto (isPrimary = imagen de tarjeta, variantId, altText, sortOrder).
DELETE	/business/merchant-catalog/images/bulk	deleteCatalogImages	Elimina imágenes de producto por id.
POST	/business/merchant-catalog/inventory/adjustments/bulk	adjustCatalogInventory	Ajusta inventario de variantes en lote.
Checkout — Carrito
POST	/business/cart/quote	quoteBusinessCart	Cotiza sin persistir y devuelve discount_in_cents, applied_coupon, tax_in_cents y taxes[] calculados por el servidor.
Checkout — Pedidos
POST	/business/sales-orders	createBusinessSalesOrder	Crea el pedido con cupón e impuestos del servidor; devuelve discount_in_cents y tax_in_cents (applied_coupon y taxes[] se consultan en quote).
GET	/business/sales-orders	listBusinessSalesOrders	Lista pedidos con discount_in_cents y tax_in_cents; applied_coupon y taxes[] pertenecen al quote previo.
GET	/business/sales-orders/:sales_order_id	getBusinessSalesOrder	Detalle con discount_in_cents y tax_in_cents; usa quote para el detalle applied_coupon y taxes[].
POST	/business/sales-orders/:sales_order_id/pay	payBusinessSalesOrder	Crea o reutiliza una orden de pago y devuelve payment_url.
GET	/business/sales-orders/:sales_order_id/tracking	getBusinessSalesOrderTracking	Seguimiento de envío de un pedido de venta.
GET	/business/sales-orders/:sales_order_id/invoice	getBusinessSalesOrderInvoice	Factura o comprobante de un pedido de venta.
POST	/business/sales-orders/:sales_order_id/cancel	cancelBusinessSalesOrder	Cancela un pedido de venta si su estado lo permite.
PATCH	/business/sales-orders/:sales_order_id/fulfillment	changeBusinessSalesOrderFulfillment	Actualiza estado de fulfillment, tracking y foto de envío del pedido.
POST	/business/sales-orders/:sales_order_id/refund	refundBusinessSalesOrder	Reembolsa un pedido de venta y repone inventario si aplica.
Checkout — Pago
GET	/business/checkout/psp-methods	listBusinessCheckoutPspMethods	Métodos PSP con required_fields para formulario de pago (sin credenciales). Usar en checkout del comprador — no confundir con merchant-payment-settings/psp-methods.
Referencia
GET	/business/countries	listBusinessCountries	Países activos del sistema (formularios de envío).
GET	/business/currencies	listBusinessCurrencies	Monedas del sistema.
Tienda
GET	/business/store/settings	getBusinessStoreSettings	Configuración de tienda: modo checkout, WhatsApp, logos, envío.
Webhooks
GET	/business/webhooks/settings	getBusinessWebhookSettings	URL de webhook configurada para el comercio.
PUT	/business/webhooks/settings	updateBusinessWebhookSettings	Actualiza la URL de webhook (HTTPS, anti-SSRF).
Envíos
GET	/business/shipping/settings	getBusinessShippingSettings	Peso por defecto y divisor volumétrico para cotización de envío.
PUT	/business/shipping/settings	updateBusinessShippingSettings	Actualiza configuración de envíos del comercio.
GET	/business/shipping/zones	listBusinessShippingZones	Zonas de envío con tarifas del comercio.
POST	/business/shipping/zones	createBusinessShippingZone	Crea una zona de envío por país.
PUT	/business/shipping/zones/:zone_id	updateBusinessShippingZone	Actualiza una zona de envío.
DELETE	/business/shipping/zones/:zone_id	deleteBusinessShippingZone	Elimina una zona de envío.
POST	/business/shipping/zones/:zone_id/rates	createBusinessShippingRate	Crea una tarifa de envío en una zona.
PUT	/business/shipping/zones/:zone_id/rates/:rate_id	updateBusinessShippingRate	Actualiza una tarifa de envío.
DELETE	/business/shipping/zones/:zone_id/rates/:rate_id	deleteBusinessShippingRate	Elimina una tarifa de envío.
GET	/business/shipping/package-profiles	listBusinessShippingPackageProfiles	Perfiles de empaque del comercio.
POST	/business/shipping/package-profiles	createBusinessShippingPackageProfile	Crea un perfil de empaque.
PUT	/business/shipping/package-profiles/:profile_id	updateBusinessShippingPackageProfile	Actualiza un perfil de empaque.
DELETE	/business/shipping/package-profiles/:profile_id	deleteBusinessShippingPackageProfile	Elimina un perfil de empaque.
Catálogo — Storefront
GET	/business/catalog/products/search	searchBusinessCatalogProducts	Búsqueda de productos públicos del catálogo storefront.
GET	/business/catalog/products/search/facets	getBusinessCatalogProductSearchFacets	Facetas de búsqueda de productos públicos.
GET	/business/catalog/products/by-slug/:slug	getBusinessCatalogProductBySlug	Detalle de producto público por slug.
GET	/business/catalog/categories	listBusinessCatalogCategories	Listado público de categorías del catálogo storefront.

Especificación

OpenAPI

Especificación OpenAPI 3.1 generada desde el catálogo de endpoints Business API. Úsala con generadores de cliente, Postman o validación de contratos.

Descargar OpenAPI JSON

Errores

Manejo de excepciones

Node.js

TypeScript

import {
  HanixBusinessError,
  HanixBusinessNetworkError,
  HanixBusinessConfigError,
} from '@hanix.io/business';

try {
  await client.getPaymentOrder(id);
} catch (error) {
  if (error instanceof HanixBusinessError) {
    console.log(error.status, error.body);
  }
}

HanixBusinessErrorRespuesta 4xx/5xx de la API

HanixBusinessNetworkErrorTimeout o fallo de red

HanixBusinessConfigErrorOpciones inválidas al crear el cliente