michangarrito/docs/_quick/QUICK-API.yml

# Navegacion Rapida de API - MiChangarrito
# Proyecto: michangarrito
# Fecha: 2026-01-16

version: "1.0.0"
proyecto: "michangarrito"

# ============================================================================
# ENDPOINTS POR MODULO
# ============================================================================
por_modulo:
  auth:
    base: "/api/v1/auth"
    endpoints:
      - { method: "POST", path: "/login", descripcion: "Login usuario" }
      - { method: "POST", path: "/register", descripcion: "Registro nuevo usuario" }
      - { method: "POST", path: "/refresh", descripcion: "Refresh token" }
      - { method: "POST", path: "/logout", descripcion: "Cerrar sesion" }
      - { method: "GET", path: "/me", descripcion: "Obtener usuario actual" }

  stores:
    base: "/api/v1/stores"
    endpoints:
      - { method: "GET", path: "/", descripcion: "Listar tiendas del usuario" }
      - { method: "POST", path: "/", descripcion: "Crear nueva tienda" }
      - { method: "GET", path: "/:id", descripcion: "Obtener tienda por ID" }
      - { method: "PATCH", path: "/:id", descripcion: "Actualizar tienda" }
      - { method: "DELETE", path: "/:id", descripcion: "Eliminar tienda" }

  products:
    base: "/api/v1/products"
    endpoints:
      - { method: "GET", path: "/", descripcion: "Listar productos" }
      - { method: "POST", path: "/", descripcion: "Crear producto" }
      - { method: "GET", path: "/:id", descripcion: "Obtener producto" }
      - { method: "PATCH", path: "/:id", descripcion: "Actualizar producto" }
      - { method: "DELETE", path: "/:id", descripcion: "Eliminar producto" }
      - { method: "PATCH", path: "/:id/stock", descripcion: "Actualizar stock" }

  sales:
    base: "/api/v1/sales"
    endpoints:
      - { method: "GET", path: "/", descripcion: "Listar ventas" }
      - { method: "POST", path: "/", descripcion: "Crear venta (POS)" }
      - { method: "GET", path: "/:id", descripcion: "Obtener venta" }
      - { method: "POST", path: "/:id/cancel", descripcion: "Cancelar venta" }
      - { method: "GET", path: "/report/daily", descripcion: "Reporte diario" }

  customers:
    base: "/api/v1/customers"
    endpoints:
      - { method: "GET", path: "/", descripcion: "Listar clientes" }
      - { method: "POST", path: "/", descripcion: "Crear cliente" }
      - { method: "GET", path: "/:id", descripcion: "Obtener cliente" }
      - { method: "PATCH", path: "/:id", descripcion: "Actualizar cliente" }

  fiados:
    base: "/api/v1/fiados"
    endpoints:
      - { method: "GET", path: "/", descripcion: "Listar fiados activos" }
      - { method: "POST", path: "/", descripcion: "Crear fiado" }
      - { method: "GET", path: "/:id", descripcion: "Obtener fiado" }
      - { method: "POST", path: "/:id/payment", descripcion: "Registrar pago" }
      - { method: "GET", path: "/customer/:customerId", descripcion: "Fiados por cliente" }

  orders:
    base: "/api/v1/orders"
    endpoints:
      - { method: "GET", path: "/", descripcion: "Listar pedidos" }
      - { method: "POST", path: "/", descripcion: "Crear pedido" }
      - { method: "GET", path: "/:id", descripcion: "Obtener pedido" }
      - { method: "PATCH", path: "/:id/status", descripcion: "Actualizar estado" }
      - { method: "POST", path: "/:id/delivery", descripcion: "Asignar entrega" }

  subscriptions:
    base: "/api/v1/subscriptions"
    endpoints:
      - { method: "GET", path: "/plans", descripcion: "Listar planes disponibles" }
      - { method: "GET", path: "/current", descripcion: "Suscripcion actual" }
      - { method: "POST", path: "/subscribe", descripcion: "Suscribirse a plan" }
      - { method: "POST", path: "/cancel", descripcion: "Cancelar suscripcion" }

  tokens:
    base: "/api/v1/tokens"
    endpoints:
      - { method: "GET", path: "/packages", descripcion: "Paquetes de tokens" }
      - { method: "GET", path: "/balance", descripcion: "Balance actual" }
      - { method: "POST", path: "/purchase", descripcion: "Comprar tokens" }
      - { method: "GET", path: "/usage", descripcion: "Historial de uso" }

# ============================================================================
# ENDPOINTS POR METODO
# ============================================================================
por_metodo:
  GET:
    - "/api/v1/auth/me"
    - "/api/v1/stores"
    - "/api/v1/products"
    - "/api/v1/sales"
    - "/api/v1/customers"
    - "/api/v1/fiados"
    - "/api/v1/orders"
  POST:
    - "/api/v1/auth/login"
    - "/api/v1/auth/register"
    - "/api/v1/sales"
    - "/api/v1/orders"
    - "/api/v1/fiados"
  PATCH:
    - "/api/v1/stores/:id"
    - "/api/v1/products/:id"
    - "/api/v1/orders/:id/status"
  DELETE:
    - "/api/v1/stores/:id"
    - "/api/v1/products/:id"

# ============================================================================
# AUTENTICACION
# ============================================================================
autenticacion:
  tipo: "JWT Bearer"
  header: "Authorization"
  formato: "Bearer {token}"
  endpoints_publicos:
    - "/api/v1/auth/login"
    - "/api/v1/auth/register"
    - "/api/v1/health"
    - "/api/docs"

# ============================================================================
# ERRORES COMUNES
# ============================================================================
errores:
  400: "Bad Request - Datos invalidos"
  401: "Unauthorized - Token invalido o expirado"
  403: "Forbidden - Sin permisos para esta accion"
  404: "Not Found - Recurso no encontrado"
  409: "Conflict - Recurso ya existe"
  422: "Unprocessable Entity - Validacion fallida"
  500: "Internal Server Error"

# ============================================================================
# REFERENCIAS
# ============================================================================
referencias:
  swagger: "http://localhost:3141/api/docs"
  postman: "docs/api-contracts/"
  services: "@MCH_DEF_SERVICES"