> ## Documentation Index > Fetch the complete documentation index at: https://docs.smartpyme.app/llms.txt > Use this file to discover all available pages before exploring further. # Listar ventas > Obtiene una lista paginada de ventas con filtros opcionales. Soporta filtros por fecha, estado y ordenamiento personalizado. ## OpenAPI ````yaml /openapi.yaml get /sales openapi: 3.0.0 info: title: SmartPYME External API description: > API Externa de SmartPYME para proveedores terceros. Permite consultar y registrar ventas, consultar inventario y devoluciones, e importar paquetes usando autenticación por API Key. ## Autenticación Todas las requests requieren un API Key válido en el header Authorization: ``` Authorization: Bearer {tu_api_key} ``` ## Rate Limiting - Sin filtros de fecha: 1000 requests/hora - Con filtros de fecha: 2000 requests/hora ## Paginación Todos los endpoints de lista soportan paginación: - `page`: Número de página (default: 1) - `per_page`: Registros por página (1-200, default: 100) version: 1.4.0 contact: name: SmartPYME Support email: soporte@smartpyme.com license: name: Propietario url: https://smartpyme.com/terms servers: - url: https://tu-dominio.com/api/external/v1 description: Servidor de Producción - url: http://localhost/api/external/v1 description: Servidor de Desarrollo security: - ApiKeyAuth: [] paths: /sales: get: tags: - Ventas summary: Listar ventas description: | Obtiene una lista paginada de ventas con filtros opcionales. Soporta filtros por fecha, estado y ordenamiento personalizado. parameters: - name: fecha_inicio in: query description: Fecha de inicio (formato Y-m-d) schema: type: string format: date example: '2025-01-01' - name: fecha_fin in: query description: Fecha de fin (formato Y-m-d) schema: type: string format: date example: '2025-01-31' - name: estado in: query description: Estado de la venta schema: type: string enum: - Completada - Pendiente - Anulada - Cotizacion example: Completada - name: page in: query description: Número de página schema: type: integer minimum: 1 default: 1 - name: per_page in: query description: Registros por página schema: type: integer minimum: 1 maximum: 200 default: 100 - name: order_by in: query description: Campo de ordenamiento schema: type: string enum: - fecha - total - correlativo - created_at default: fecha - name: order_direction in: query description: Dirección del ordenamiento schema: type: string enum: - asc - desc default: desc responses: '200': description: Lista de ventas obtenida exitosamente content: application/json: schema: $ref: '#/components/schemas/SalesListResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimitExceeded' '500': $ref: '#/components/responses/InternalServerError' components: schemas: SalesListResponse: allOf: - $ref: '#/components/schemas/BaseResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/Sale' pagination: $ref: '#/components/schemas/Pagination' BaseResponse: type: object properties: success: type: boolean description: Indica si la operación fue exitosa meta: $ref: '#/components/schemas/Meta' required: - success Sale: type: object properties: id: type: integer example: 12345 fecha: type: string format: date example: '2025-01-15' correlativo: type: string nullable: true example: FAC-001 referencia: type: string nullable: true example: ORD-2025-00042 referencia_externa: type: string nullable: true example: ORD-2025-00042 cotizacion: type: boolean example: false estado: type: string enum: - Completada - Pendiente - Anulada - Cotizacion example: Completada forma_pago: type: string nullable: true example: Efectivo total: type: number format: float example: 150.75 iva: type: number format: float nullable: true example: 13.5 sub_total: type: number format: float nullable: true example: 137.25 descuento: type: number format: float nullable: true example: 0 nombre_cliente: type: string nullable: true example: Juan Pérez nombre_usuario: type: string nullable: true example: Admin User nombre_vendedor: type: string nullable: true example: Vendedor 1 saldo: type: number format: float nullable: true example: 0 created_at: type: string format: date-time updated_at: type: string format: date-time detalles: type: array items: $ref: '#/components/schemas/SaleDetail' required: - fecha - estado - total Pagination: type: object properties: current_page: type: integer example: 1 per_page: type: integer example: 100 total: type: integer example: 1250 total_pages: type: integer example: 13 has_next: type: boolean example: true has_prev: type: boolean example: false from: type: integer nullable: true example: 1 to: type: integer nullable: true example: 100 required: - current_page - per_page - total - total_pages - has_next - has_prev ValidationErrorResponse: allOf: - $ref: '#/components/schemas/ErrorResponse' - type: object properties: details: type: object description: Detalles de errores de validación example: fecha_inicio: - El campo fecha inicio debe ser una fecha válida. per_page: - El campo per page no puede ser mayor que 200. ErrorResponse: type: object properties: success: type: boolean example: false error: type: string description: Mensaje de error code: type: integer description: Código de error HTTP required: - success - error - code Meta: type: object properties: empresa: type: string description: Nombre de la empresa example: Mi Empresa S.A. timestamp: type: string format: date-time description: Timestamp de la respuesta filters_applied: type: object description: Filtros aplicados en la consulta required: - empresa - timestamp SaleDetail: type: object properties: descripcion: type: string nullable: true example: Producto A cantidad: type: number format: float example: 2 precio: type: number format: float example: 75 total: type: number format: float example: 150 nombre_producto: type: string nullable: true example: Producto A codigo: type: string nullable: true example: PROD-001 created_at: type: string format: date-time updated_at: type: string format: date-time required: - cantidad - precio - total responses: BadRequest: description: Parámetros inválidos content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' Unauthorized: description: API Key inválido o faltante content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: API key inválido o empresa inactiva code: 401 RateLimitExceeded: description: Rate limit excedido content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: >- Rate limit excedido. Máximo 1000 requests por hora (2000 con filtros de fecha). code: 429 InternalServerError: description: Error interno del servidor content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: Error interno del servidor code: 500 securitySchemes: ApiKeyAuth: type: http scheme: bearer description: | API Key de la empresa en formato Bearer token. Ejemplo: `Authorization: Bearer G8RCjH11DabBNjnX7wO5` ````