erp-transportistas-v2/docs/_quick/QUICK-API.yml

# QUICK-API.yml - API Endpoints ERP Transportistas
# Version: 1.0.0
# Fecha: 2026-01-26

base_url: "http://localhost:3014/api/v1"
auth_header: "Authorization: Bearer {token}"
tenant_header: "X-Tenant-ID: {tenant_uuid}"

endpoints:
  auth:
    prefix: "/auth"
    routes:
      - method: "POST"
        path: "/login"
        description: "Autenticacion"
        body: "{ email, password }"

      - method: "POST"
        path: "/refresh"
        description: "Refrescar token"

      - method: "POST"
        path: "/logout"
        description: "Cerrar sesion"

  ordenes_transporte:
    prefix: "/ordenes-transporte"
    status: "40% implementado"
    routes:
      - method: "GET"
        path: "/"
        description: "Listar OTs"
        query: "?status=CONFIRMADA&cliente_id=uuid"

      - method: "GET"
        path: "/:id"
        description: "Obtener OT"

      - method: "POST"
        path: "/"
        description: "Crear OT"
        body: "CreateOrdenTransporteDto"

      - method: "PATCH"
        path: "/:id"
        description: "Actualizar OT"

      - method: "PATCH"
        path: "/:id/status"
        description: "Cambiar status"
        body: "{ status: 'CONFIRMADA' }"

      - method: "DELETE"
        path: "/:id"
        description: "Eliminar OT"

  viajes:
    prefix: "/viajes"
    status: "Pendiente"
    routes:
      - method: "GET"
        path: "/"
        description: "Listar viajes"

      - method: "POST"
        path: "/"
        description: "Crear viaje"

      - method: "POST"
        path: "/:id/despachar"
        description: "Despachar viaje"

      - method: "POST"
        path: "/:id/cerrar"
        description: "Cerrar con POD"

  tracking:
    prefix: "/tracking"
    status: "20% implementado"
    routes:
      - method: "POST"
        path: "/eventos"
        description: "Registrar evento GPS"
        body: "{ unidad_id, lat, lng, velocidad, timestamp }"

      - method: "GET"
        path: "/unidades/:id/posicion"
        description: "Ultima posicion"

      - method: "GET"
        path: "/viajes/:id/historial"
        description: "Historial de eventos"

      - method: "GET"
        path: "/viajes/:id/eta"
        description: "ETA dinamico"

  flota:
    prefix: "/flota"
    status: "40% implementado"
    routes:
      - method: "GET"
        path: "/unidades"
        description: "Listar unidades"

      - method: "GET"
        path: "/operadores"
        description: "Listar operadores"

      - method: "GET"
        path: "/disponibilidad"
        description: "Recursos disponibles"
        query: "?fecha=2026-01-26"

  combustible:
    prefix: "/combustible"
    status: "50% implementado"
    routes:
      - method: "POST"
        path: "/cargas"
        description: "Registrar carga"

      - method: "GET"
        path: "/rendimiento/:unidad_id"
        description: "Rendimiento km/litro"

      - method: "GET"
        path: "/anomalias"
        description: "Alertas de fraude"

  facturacion:
    prefix: "/facturacion"
    status: "30% implementado"
    routes:
      - method: "GET"
        path: "/tarifas"
        description: "Listar tarifas"
        query: "?lane=origen-destino"

      - method: "POST"
        path: "/facturas"
        description: "Generar factura"

      - method: "GET"
        path: "/fuel-surcharge"
        description: "Recargo combustible actual"

  carta_porte:
    prefix: "/carta-porte"
    status: "Pendiente"
    routes:
      - method: "POST"
        path: "/"
        description: "Generar complemento"
        body: "{ viaje_id }"

      - method: "POST"
        path: "/:id/timbrar"
        description: "Timbrar con PAC"

      - method: "GET"
        path: "/:id/pdf"
        description: "Descargar PDF"

      - method: "POST"
        path: "/:id/cancelar"
        description: "Cancelar CFDI"

  carriers:
    prefix: "/carriers"
    status: "Pendiente"
    routes:
      - method: "GET"
        path: "/"
        description: "Listar carriers"

      - method: "GET"
        path: "/:id/scorecard"
        description: "Evaluacion"

  mantenimiento:
    prefix: "/mantenimiento"
    status: "Pendiente"
    routes:
      - method: "GET"
        path: "/proximos"
        description: "Proximos mantenimientos"

      - method: "POST"
        path: "/ordenes-trabajo"
        description: "Crear OT mantenimiento"

response_format:
  success:
    example: |
      {
        "success": true,
        "data": { ... },
        "meta": {
          "total": 100,
          "page": 1,
          "limit": 20
        }
      }      

  error:
    example: |
      {
        "success": false,
        "error": {
          "code": "VALIDATION_ERROR",
          "message": "Campo requerido",
          "details": [ ... ]
        }
      }      

pagination:
  query_params:
    - "limit (default: 20, max: 100)"
    - "offset (default: 0)"
    - "sort (campo)"
    - "order (asc|desc)"

last_updated: "2026-01-26"