API de Cannahub

La API de Cannahub te permite integrar programáticamente la gestión de clubs de cannabis, incluyendo miembros, productos, pedidos, inventario y más. Esta documentación cubre tanto los endpoints públicos como las rutas internas del BFF (Backend for Frontend).

Arquitectura

Cannahub utiliza una arquitectura de múltiples capas que abstrae la complejidad del backend Medusa y proporciona una interfaz simplificada para los clientes.

Loading diagram...

Capas de la Arquitectura

  • Name
    Clientes
    Type
    Frontend
    Description

    Aplicaciones web (Next.js) y móviles (React Native) que consumen la API.

  • Name
    BFF Layer
    Type
    Next.js API Routes
    Description

    Capa intermedia que orquesta llamadas, transforma datos y agrega lógica de negocio.

  • Name
    Transformadores
    Type
    TypeScript
    Description

    Funciones que convierten tipos de Medusa a tipos de dominio de Cannahub.

  • Name
    Medusa
    Type
    Backend
    Description

    Plataforma de e-commerce headless que maneja productos, pedidos y clientes.

Flujo de datos típico

// Cliente solicita productos
GET /api/products

// BFF transforma la respuesta
const medusaProducts = await medusa.products.list()
const products = medusaProducts.map(parseMedusaProduct)

// Cliente recibe datos simplificados
{
  products: Product[],
  count: number
}

URLs Base

Cannahub utiliza diferentes URLs según el entorno y el tipo de API:

  • Name
    Producción
    Type
    https://api.cannahub.tech
    Description

    API de producción para aplicaciones en vivo.

  • Name
    Staging
    Type
    https://staging-api.cannahub.tech
    Description

    Entorno de pruebas pre-producción.

  • Name
    Desarrollo
    Type
    http://localhost:9000
    Description

    Servidor local de Medusa para desarrollo.

  • Name
    BFF Local
    Type
    http://localhost:3000/api
    Description

    Rutas API de Next.js en desarrollo local.

Ejemplo de request

# Producción
curl https://api.cannahub.tech/store/products \
  -H "Authorization: Bearer {token}"

# Desarrollo local
curl http://localhost:9000/store/products \
  -H "Authorization: Bearer {token}"

Autenticación

Todas las solicitudes a la API requieren autenticación. Cannahub utiliza JWT tokens almacenados en cookies HTTP-only.

Tipos de Tokens

  • Name
    cannahubToken
    Type
    JWT
    Description

    Token de miembro/cliente. Expira en 7 días.

  • Name
    cannahubAdminToken
    Type
    JWT
    Description

    Token de administrador/staff. Expira en 7 días.

Headers Requeridos

  • Name
    Authorization
    Type
    string
    Description

    Bearer token para autenticación: Bearer {token}

  • Name
    Content-Type
    Type
    string
    Description

    application/json para requests con body.

  • Name
    x-publishable-api-key
    Type
    string
    Description

    API key pública para endpoints de store (opcional).

Autenticación

curl -X POST https://api.cannahub.tech/auth/customer/emailpass \
  -H "Content-Type: application/json" \
  -d '{
    "email": "miembro@ejemplo.com",
    "password": "contraseña_segura"
  }'

Respuesta exitosa

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Para más detalles sobre autenticación, consulta la guía de autenticación.

Endpoints Disponibles

Endpoints Públicos (Store)

EndpointMétodoDescripción
/store/productsGETLista productos del catálogo
/store/products/:idGETDetalle de un producto
/store/cartsPOSTCrear carrito
/store/carts/:idGETObtener carrito
/store/carts/:id/line-itemsPOSTAgregar item al carrito
/store/carts/:id/completePOSTCompletar orden

Endpoints Administrativos

EndpointMétodoDescripción
/admin/customersGET, POSTGestión de miembros
/admin/productsGET, POSTGestión de productos
/admin/ordersGET, POSTGestión de pedidos
/admin/inventory-itemsGET, PUTGestión de inventario
/admin/customer-groupsGET, POSTGestión de membresías

Endpoints BFF (Next.js)

La capa BFF orquesta múltiples llamadas a Medusa y otros servicios, reduciendo significativamente la latencia y complejidad del cliente.

Rutas Existentes

EndpointMétodoDescripciónDoc
/api/productsGET, POSTProductos con datos de cepaVer
/api/strainsGETCatálogo de cepas filtrableVer
/api/membershipsGETTipos de membresíaVer
/api/locationsGET, POSTFiliales (Stock Locations)Ver
/api/inventoryGETItems de inventarioVer
/api/statsGETEstadísticas del dashboard-

Rutas BFF Propuestas (Orquestación)

Estas rutas BFF resuelven problemas de N+1 queries y reducen la cantidad de llamadas API desde el cliente:

EndpointMétodoPropósitoReducción
/api/orders/create-and-processPOSTFlujo completo de orden15+ → 1
/api/orders/:id/transitionPOSTTransición de estado de orden3-5 → 1
/api/products/:id/with-inventoryGETProducto con inventario agregado7+ → 1
/api/products/with-inventoryGETLista de productos con inventarioN+1 → 1
/api/inventory/batch-updatePOSTActualización masiva de stockN → 1
/api/stock-locations/setupPOSTCrear ubicación con fulfillment chain7+ → 1
/api/members/:id/completeGETPerfil completo con órdenes y stats4-5 → 1
/api/dashboard/statsGETMétricas agregadas del dashboard5+ → 1

Las rutas BFF están documentadas en sus respectivas páginas de entidad. Por ejemplo, la ruta /api/orders/create-and-process está documentada en API de Pedidos.

Beneficios de la Capa BFF

MétricaSin BFFCon BFFMejora
Llamadas API (orden completa)15+1-93%
Latencia típica (producto + inv)~700ms~200ms-71%
Transformación de datosClienteServidorCentralizado
Manejo de erroresDispersoUnificadoSimplificado

Rate Limiting

La API implementa límites de tasa para proteger el servicio:

  • Name
    Store endpoints
    Type
    1000 req/min
    Description

    Endpoints públicos de tienda.

  • Name
    Admin endpoints
    Type
    500 req/min
    Description

    Endpoints administrativos autenticados.

  • Name
    Auth endpoints
    Type
    10 req/min
    Description

    Endpoints de login para prevenir fuerza bruta.

Cuando excedes el límite, recibirás una respuesta 429 Too Many Requests.

Multi-Tenancy

Cannahub soporta múltiples organizaciones (clubs) en la misma instancia. Cada organización tiene:

  • Name
    Subdomain
    Type
    string
    Description

    Identificador único del club: high-up.cannahub.tech

  • Name
    Sales Channel
    Type
    string
    Description

    Canal de ventas asociado en Medusa.

  • Name
    Stock Locations
    Type
    array
    Description

    Ubicaciones de inventario del club.

  • Name
    Price Lists
    Type
    array
    Description

    Listas de precios por membresía.

Organizaciones soportadas

const organizations = [
  'high-up',
  'don-marcelino',
  'circulo-rojo',
  'superfly',
  'blow',
  'weplant'
]

// Extracción desde subdomain
const org = request.headers
  .get('host')
  ?.split('.')[0]

Guía Rápida

1. Autenticarse

curl -X POST https://api.cannahub.tech/auth/customer/emailpass \
  -H "Content-Type: application/json" \
  -d '{"email": "tu@email.com", "password": "contraseña"}'

2. Listar Productos

curl https://api.cannahub.tech/store/products \
  -H "Authorization: Bearer {tu_token}"

3. Crear un Carrito

curl -X POST https://api.cannahub.tech/store/carts \
  -H "Authorization: Bearer {tu_token}" \
  -H "Content-Type: application/json" \
  -d '{"region_id": "reg_argentina"}'

4. Agregar Producto al Carrito

curl -X POST https://api.cannahub.tech/store/carts/{cart_id}/line-items \
  -H "Authorization: Bearer {tu_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "variant_id": "variant_01HQ_BD_1G",
    "quantity": 1
  }'

Próximos Pasos

AutenticaciónAPI de MiembrosAPI de ProductosAPI de PedidosAPI de FilialesAPI de Inventario

Was this page helpful?