openapi: 3.0.3
info:
  title: SOSSYSTEM API
  description: API completa del sistema de gestión empresarial SOSSYSTEM
  version: 1.0.0
  contact:
    name: Soporte SOSSYSTEM
    email: soporte@sossystem.com

servers:
  - url: https://sossystem.test/api
    description: Servidor de desarrollo
  - url: https://api.sossystem.com/api
    description: Servidor de producción

tags:
  - name: Autenticación
    description: Endpoints de autenticación
  - name: API Móvil
    description: Endpoints para aplicación móvil (PWA)
  - name: Usuarios
    description: Gestión de usuarios
  - name: Roles y Permisos
    description: Gestión de roles y permisos
  - name: Empresa
    description: Información de la empresa
  - name: Kardex
    description: Auditoría y registro de acciones
  - name: Plantillas
    description: Gestión de plantillas de documentos
  - name: Notificaciones
    description: Sistema de notificaciones
  - name: Estadísticas
    description: Estadísticas del sistema

paths:
  /health:
    get:
      tags:
        - General
      summary: Health Check
      description: Verifica el estado de la API
      responses:
        '200':
          description: API funcionando correctamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  timestamp:
                    type: string
                    format: date-time
                  version:
                    type: string
                    example: 1.0.0

  /mobile/login:
    post:
      tags:
        - API Móvil
        - Autenticación
      summary: Login para aplicación móvil
      description: Autentica un usuario y genera un token Sanctum
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                  example: usuario@example.com
                password:
                  type: string
                  format: password
                  example: password123
      responses:
        '200':
          description: Autenticación exitosa
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  token:
                    type: object
                    properties:
                      plainTextToken:
                        type: string
                        example: "1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
                  user:
                    type: object
                    properties:
                      id:
                        type: integer
                      name:
                        type: string
                      email:
                        type: string
                      salesman_id:
                        type: integer
                        nullable: true
        '401':
          description: Credenciales inválidas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /mobile/clients:
    get:
      tags:
        - API Móvil
      summary: Obtener clientes
      description: Obtiene la lista de clientes asignados al vendedor autenticado
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Lista de clientes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Client'

  /mobile/clients/search:
    get:
      tags:
        - API Móvil
      summary: Buscar clientes
      description: Busca clientes por término de búsqueda
      security:
        - bearerAuth: []
      parameters:
        - name: q
          in: query
          description: Término de búsqueda
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Lista de clientes encontrados
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Client'

  /mobile/categories:
    get:
      tags:
        - API Móvil
      summary: Obtener categorías
      description: Obtiene la lista de categorías de productos
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Lista de categorías
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Category'

  /mobile/products:
    get:
      tags:
        - API Móvil
      summary: Obtener productos
      description: Obtiene la lista de productos con filtros opcionales
      security:
        - bearerAuth: []
      parameters:
        - name: category
          in: query
          description: ID de categoría
          required: false
          schema:
            type: integer
        - name: search
          in: query
          description: Término de búsqueda
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Lista de productos
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'

  /mobile/invoices/pending/{clientId}:
    get:
      tags:
        - API Móvil
      summary: Obtener facturas pendientes
      description: Obtiene las facturas pendientes de un cliente
      security:
        - bearerAuth: []
      parameters:
        - name: clientId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Lista de facturas pendientes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Invoice'

  /mobile/payments:
    post:
      tags:
        - API Móvil
      summary: Procesar pago
      description: Procesa un pago de factura
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
      responses:
        '200':
          description: Pago procesado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      payment_id:
                        type: integer
                      invoice_id:
                        type: integer
                      amount:
                        type: string

  /mobile/receivables:
    get:
      tags:
        - API Móvil
      summary: Obtener cuentas por cobrar
      description: Obtiene las cuentas por cobrar del vendedor
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Lista de cuentas por cobrar
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Receivable'

  /mobile/payments/history:
    get:
      tags:
        - API Móvil
      summary: Historial de pagos
      description: Obtiene el historial de pagos
      security:
        - bearerAuth: []
      parameters:
        - name: client_id
          in: query
          schema:
            type: integer
        - name: date_from
          in: query
          schema:
            type: string
            format: date
        - name: date_to
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Historial de pagos
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Payment'

  /mobile/notifications:
    get:
      tags:
        - API Móvil
      summary: Obtener notificaciones
      description: Obtiene las notificaciones del usuario
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Lista de notificaciones
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Notification'

  /mobile/notifications/{id}/mark-as-read:
    post:
      tags:
        - API Móvil
      summary: Marcar notificación como leída
      description: Marca una notificación como leída
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Notificación marcada como leída
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string

  /mobile/report-payment:
    post:
      tags:
        - API Móvil
      summary: Reportar pago
      description: Reporta un pago para verificación
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentReportRequest'
      responses:
        '200':
          description: Pago reportado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  verification_id:
                    type: integer

  /mobile/bootstrap-data:
    get:
      tags:
        - API Móvil
      summary: Bootstrap Data
      description: Obtiene todos los datos necesarios para sincronización
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Datos de sincronización
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      clients:
                        type: array
                        items:
                          $ref: '#/components/schemas/Client'
                      products:
                        type: array
                        items:
                          $ref: '#/components/schemas/Product'
                      categories:
                        type: array
                        items:
                          $ref: '#/components/schemas/Category'
                      receivables:
                        type: array
                        items:
                          $ref: '#/components/schemas/Receivable'
                      exchange_rates:
                        type: array
                        items:
                          $ref: '#/components/schemas/ExchangeRate'
                      last_sync:
                        type: string
                        format: date-time

  /mobile/create-order:
    post:
      tags:
        - API Móvil
      summary: Crear pedido
      description: Crea un nuevo pedido (factura o nota)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
      responses:
        '200':
          description: Pedido creado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      order_id:
                        type: integer
                      order_number:
                        type: string

  /mobile/get-rates:
    get:
      tags:
        - API Móvil
      summary: Obtener tasas de cambio
      description: Obtiene las tasas de cambio actuales
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Tasas de cambio
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      rates:
                        type: array
                        items:
                          $ref: '#/components/schemas/ExchangeRate'
                      last_update:
                        type: string
                        format: date-time

  /user:
    get:
      tags:
        - Usuarios
      summary: Información del usuario autenticado
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Información del usuario
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/User'

  /users:
    get:
      tags:
        - Usuarios
      summary: Listar usuarios
      security:
        - bearerAuth: []
      parameters:
        - name: search
          in: query
          schema:
            type: string
        - name: role
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
            enum: [active, inactive]
        - name: per_page
          in: query
          schema:
            type: integer
            default: 15
      responses:
        '200':
          description: Lista de usuarios
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'

    post:
      tags:
        - Usuarios
      summary: Crear usuario
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreateRequest'
      responses:
        '201':
          description: Usuario creado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/User'

  /roles:
    get:
      tags:
        - Roles y Permisos
      summary: Listar roles
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Lista de roles
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Role'

  /permissions:
    get:
      tags:
        - Roles y Permisos
      summary: Listar permisos
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Lista de permisos
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Permission'

  /empresa:
    get:
      tags:
        - Empresa
      summary: Información de la empresa
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Información de la empresa
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Company'

  /kardex:
    get:
      tags:
        - Kardex
      summary: Listar registros de Kardex
      security:
        - bearerAuth: []
      parameters:
        - name: user_id
          in: query
          schema:
            type: integer
        - name: action
          in: query
          schema:
            type: string
        - name: date_from
          in: query
          schema:
            type: string
            format: date
        - name: date_to
          in: query
          schema:
            type: string
            format: date
        - name: per_page
          in: query
          schema:
            type: integer
            default: 15
      responses:
        '200':
          description: Lista de registros de Kardex
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/KardexEntry'
                  pagination:
                    $ref: '#/components/schemas/Pagination'

    post:
      tags:
        - Kardex
      summary: Registrar acción en Kardex
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KardexRequest'
      responses:
        '201':
          description: Acción registrada exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      id:
                        type: integer

  /plantillas:
    get:
      tags:
        - Plantillas
      summary: Listar plantillas
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Lista de plantillas
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Template'

  /plantillas/{id}/generar-pdf:
    post:
      tags:
        - Plantillas
      summary: Generar PDF desde plantilla
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
      responses:
        '200':
          description: Archivo PDF generado
          content:
            application/pdf:
              schema:
                type: string
                format: binary

  /notificaciones:
    get:
      tags:
        - Notificaciones
      summary: Listar notificaciones
      security:
        - bearerAuth: []
      parameters:
        - name: unread_only
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Lista de notificaciones
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Notification'

  /notificaciones/{id}/marcar-leida:
    patch:
      tags:
        - Notificaciones
      summary: Marcar notificación como leída
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Notificación marcada como leída
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string

  /estadisticas:
    get:
      tags:
        - Estadísticas
      summary: Estadísticas del sistema
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Estadísticas del sistema
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      total_users:
                        type: integer
                      total_clients:
                        type: integer
                      total_products:
                        type: integer
                      total_sales:
                        type: string

  /verificar-permisos:
    post:
      tags:
        - Roles y Permisos
      summary: Verificar permisos
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                permissions:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Resultado de verificación de permisos
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    additionalProperties:
                      type: boolean

  /auth/login:
    post:
      tags:
        - Autenticación
      summary: Login API general
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  format: password
      responses:
        '200':
          description: Autenticación exitosa
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      user:
                        $ref: '#/components/schemas/User'
                      token:
                        type: string
        '401':
          description: Credenciales inválidas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /auth/logout:
    post:
      tags:
        - Autenticación
      summary: Logout
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Sesión cerrada exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string

    Client:
      type: object
      properties:
        id:
          type: integer
        business_name:
          type: string
        email:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        max_credit_amount:
          type: string

    Category:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
          nullable: true

    Product:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
          nullable: true
        stock:
          type: number
        category_id:
          type: integer
        selling_price:
          type: string
        wholesale_price:
          type: string
        cost_price:
          type: string
        currency:
          type: string

    Invoice:
      type: object
      properties:
        id:
          type: integer
        invoice_number:
          type: string
        invoice_date:
          type: string
          format: date
        total_amount:
          type: string
        amount_due:
          type: string
        currency:
          type: string

    PaymentRequest:
      type: object
      required:
        - client_id
        - invoice_id
        - amount
        - payment_method
        - payment_date
      properties:
        client_id:
          type: integer
        invoice_id:
          type: integer
        amount:
          type: string
        payment_method:
          type: string
          enum: [cash, transfer, check, card]
        payment_date:
          type: string
          format: date
        notes:
          type: string
          nullable: true

    PaymentReportRequest:
      type: object
      required:
        - client_id
        - invoice_id
        - amount
        - payment_method
        - payment_date
      properties:
        client_id:
          type: integer
        invoice_id:
          type: integer
        amount:
          type: string
        payment_method:
          type: string
        payment_date:
          type: string
          format: date
        verification_code:
          type: string
        notes:
          type: string
          nullable: true

    Receivable:
      type: object
      properties:
        id:
          type: integer
        client_id:
          type: integer
        client_name:
          type: string
        total_amount:
          type: string
        amount_due:
          type: string
        currency:
          type: string

    Payment:
      type: object
      properties:
        id:
          type: integer
        client_id:
          type: integer
        invoice_id:
          type: integer
        amount:
          type: string
        payment_date:
          type: string
          format: date
        payment_method:
          type: string

    Notification:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        message:
          type: string
        type:
          type: string
        read_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time

    ExchangeRate:
      type: object
      properties:
        id:
          type: integer
        from_currency:
          type: string
        to_currency:
          type: string
        rate:
          type: string
        date:
          type: string
          format: date

    OrderRequest:
      type: object
      required:
        - client_id
        - type
        - items
      properties:
        client_id:
          type: integer
        type:
          type: string
          enum: [invoice, order]
        items:
          type: array
          items:
            type: object
            properties:
              product_id:
                type: integer
              quantity:
                type: number
              unit_price:
                type: string
              discount_percentage:
                type: number
        currency:
          type: string
        exchange_rate:
          type: string
        notes:
          type: string
          nullable: true

    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
        email_verified_at:
          type: string
          format: date-time
          nullable: true
        roles:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
              slug:
                type: string
              permissions:
                type: array
                items:
                  type: string
        permissions:
          type: array
          items:
            type: string

    UserCreateRequest:
      type: object
      required:
        - name
        - email
        - password
        - password_confirmation
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        password:
          type: string
          format: password
        password_confirmation:
          type: string
          format: password
        roles:
          type: array
          items:
            type: integer

    Role:
      type: object
      properties:
        id:
          type: integer
        nombre:
          type: string
        slug:
          type: string
        description:
          type: string
          nullable: true

    Permission:
      type: object
      properties:
        id:
          type: integer
        nombre:
          type: string
        slug:
          type: string

    Company:
      type: object
      properties:
        id:
          type: integer
        nombre:
          type: string
        tax_id:
          type: string
        email:
          type: string
        phone:
          type: string

    KardexEntry:
      type: object
      properties:
        id:
          type: integer
        user_id:
          type: integer
        user_name:
          type: string
        action:
          type: string
        description:
          type: string
        ip_address:
          type: string
        created_at:
          type: string
          format: date-time

    KardexRequest:
      type: object
      required:
        - action
        - description
      properties:
        action:
          type: string
        description:
          type: string
        module:
          type: string
        reference_id:
          type: integer

    Template:
      type: object
      properties:
        id:
          type: integer
        nombre:
          type: string
        tipo:
          type: string
        formato:
          type: string

    Pagination:
      type: object
      properties:
        current_page:
          type: integer
        last_page:
          type: integer
        per_page:
          type: integer
        total:
          type: integer



