Sistema de Pedidos B2B

Sistema compuesto por dos APIs REST (Customers y Orders) y un Lambda orquestador para gestionar pedidos B2B. Las APIs se comunican entre sí, validan clientes, gestionan inventario y procesan órdenes con confirmación idempotente.

Stack Tecnológico

• Backend: Node.js 22.x + Express.js
• Base de Datos: MySQL 8.0
• Contenerización: Docker + Docker Compose
• Serverless: AWS Lambda (Serverless Framework)
• Autenticación: JWT + Service Tokens
• Validación: Joi
• Documentación: OpenAPI 3.0

Prerrequisitos

• Docker y Docker Compose instalados
• Node.js 22.x y NPM
• Git

Estructura del Proyecto

b2b-orders-system/
├── customers-api/          # API de gestión de clientes
├── orders-api/             # API de productos y órdenes
├── lambda-orchestrator/    # Función Lambda orquestadora
├── db/                     # Scripts SQL (schema + seed)
├── docker-compose.yml
└── README.md

Configuración e Instalación

1. Clonar el repositorio

git clone <repository-url>
cd b2b-orders-system

2. Configurar variables de entorno

Copia los archivos .env.example y renómbralos a .env en cada servicio:

customers-api/.env

PORT=3001
DB_HOST=db
DB_PORT=3306
DB_USER=root
DB_PASSWORD=root
DB_NAME=b2b_orders
JWT_SECRET=dev-jwt-secret-key
SERVICE_TOKEN=dev-internal-service-token-123

orders-api/.env

PORT=3002
DB_HOST=db
DB_PORT=3306
DB_USER=root
DB_PASSWORD=root
DB_NAME=b2b_orders
JWT_SECRET=dev-jwt-secret-key
SERVICE_TOKEN=dev-internal-service-token-123
CUSTOMERS_API_BASE=http://customers-api:3001/api

lambda-orchestrator/.env

CUSTOMERS_API_BASE=http://localhost:3001/api
ORDERS_API_BASE=http://localhost:3002/api
SERVICE_TOKEN=dev-internal-service-token-123

3. Levantar el entorno con Docker Compose

docker-compose up -d --build

Este comando:

• Construye las imágenes de las APIs
• Levanta MySQL y ejecuta schema.sql y seed.sql
• Inicia customers-api en puerto 3001
• Inicia orders-api en puerto 3002

4. Verificar que las APIs están funcionando

curl http://localhost:3001/health
curl http://localhost:3002/health

Ambas deben responder: {"status": "ok"}

5. Ejecutar el Lambda Orquestador (Local)

cd lambda-orchestrator
npm install
npm run dev

El Lambda estará disponible en: http://localhost:3003/dev/orchestrator/create-and-confirm-order

Uso de las APIs

URLs Base

• Customers API: http://localhost:3001/api
• Orders API: http://localhost:3002/api
• Lambda Orchestrator: http://localhost:3003/dev

Documentación de Endpoints

Consulta los archivos OpenAPI para detalles completos:

• customers-api/openapi.yaml
• orders-api/openapi.yaml

Endpoints Principales

Customers API

• POST /customers - Crear cliente
• GET /customers/:id - Obtener cliente
• GET /customers?search=&cursor=&limit= - Búsqueda paginada

Orders API

• POST /products - Crear producto
• GET /products/:id - Obtener producto
• PATCH /products/:id - Actualizar precio/stock
• POST /orders - Crear orden
• POST /orders/:id/confirm - Confirmar orden (idempotente)
• POST /orders/:id/cancel - Cancelar orden

Ejemplo de Invocación del Lambda

cURL

curl -X POST http://localhost:3003/dev/orchestrator/create-and-confirm-order \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": 1,
    "items": [
      {
        "product_id": 2,
        "qty": 3
      }
    ],
    "idempotency_key": "unique-key-123",
    "correlation_id": "req-789"
  }'

Respuesta Exitosa (201)

{
  "success": true,
  "correlationId": "req-789",
  "data": {
    "customer": {
      "id": 1,
      "name": "ACME Corporation",
      "email": "ops@acme.com",
      "phone": "+1-555-0101"
    },
    "order": {
      "id": 101,
      "status": "CONFIRMED",
      "total_cents": 389700,
      "items": [
        {
          "product_id": 2,
          "qty": 3,
          "unit_price_cents": 129900,
          "subtotal_cents": 389700
        }
      ]
    }
  }
}

Colecciones de Postman

Para facilitar las pruebas, se incluyen colecciones de Postman para cada API. Puedes importarlas directamente en tu cliente Postman.

• Ubicación: /postman_collections
• Archivos:
  • Customers_API.postman_collection.json
  • Orders_API.postman_collection.json

Detener el Entorno

docker-compose down

Para eliminar los volúmenes de datos:

docker-compose down -v

Notas Técnicas

• Idempotencia: La confirmación de órdenes usa X-Idempotency-Key para prevenir duplicados
• Transacciones: Creación y cancelación de órdenes usan transacciones SQL
• Autenticación Inter-Servicios: Las APIs se comunican usando SERVICE_TOKEN
• Paginación: Implementada con cursor-based pagination
• Race Conditions: Prevenidas usando SELECT ... FOR UPDATE

Despliegue en AWS (Lambda)

cd lambda-orchestrator
serverless deploy

Configurar variables de entorno en AWS Lambda Console con las URLs públicas de las APIs.