--- title: "Consultar reporte" method: POST path: "/api/v1/reports/query" tags: ["API"] --- # Consultar reporte `POST /api/v1/reports/query` Ejecuta una consulta analítica agrupada sobre ventas, compras, pagos o inventario. El campo `source` determina qué dimensiones y métricas están disponibles. ## Request body - union - SalesReportRequest - `source` 'sales', required - `period` ReportPeriod, required - `start_date` string, date, required — Period start date (YYYY-MM-DD) - `end_date` string, date, required — Period end date (YYYY-MM-DD, inclusive) - `dimensions` union[] — Dimensiones de agrupación. Máximo 12. Acepta product_metafield: para campos personalizados select de producto y contact_metafield: para campos personalizados select de contacto. - union - 'date' | 'week' | 'weekOfYear' | 'month' | 'monthOfYear' | 'dayOfWeek' | 'year' | 'quarter' | 'hourOfDay' | 'customer' | 'customerName' | 'customerEmail' | 'customerTaxCategory' | 'province' | 'city' | 'product' | 'productName' | 'variant' | 'variantSku' | 'category' | 'subcategory' | 'defaultSupplierName' | 'productType' | 'salesperson' | 'pointOfSale' | 'warehouse' | 'register' | 'integrationSource' | 'voucherType' | 'currency' | 'paymentStatus' | 'caeStatus' | 'invoiceStatus' | 'formattedInvoiceNumber' | 'taxRate' | 'saleLineType' - string — Product select custom field dimension. Use product_metafield:, for example product_metafield:season. - string — Contact select custom field dimension. Use contact_metafield:, for example contact_metafield:customer_segment. - `measures` string[], required — Medidas a calcular. Al menos una. - `dimension_filters` object — Filtros por dimensión. Cada clave debe ser una dimensión filtrable para la fuente. También acepta product_metafield: para campos personalizados select de producto y contact_metafield: para campos personalizados select de contacto cuando la fuente lo soporta. El valor es un array de IDs o valores a incluir. - `customer` string[] - `customer_name` string[] - `customer_email` string[] - `customer_tax_category` string[] - `province` string[] - `city` string[] - `product` string[] - `product_name` string[] - `variant_sku` string[] - `category` string[] - `subcategory` string[] - `default_supplier_name` string[] - `product_type` string[] - `salesperson` string[] - `point_of_sale` string[] - `warehouse` string[] - `register` string[] - `integration_source` string[] - `voucher_type` string[] - `currency` string[] - `payment_status` string[] - `cae_status` string[] - `invoice_status` string[] - `formatted_invoice_number` string[] - `tax_rate` string[] - `sale_line_type` string[] - `customer_status` string[] - `product_status` string[] - `warehouse_status` string[] - `point_of_sale_status` string[] - `register_status` string[] - `include_totals` boolean — Si es true, la respuesta incluye totales agregados en el campo `totals`. - `date_basis` 'commercial' | 'fiscal' — `commercial` usa la fecha de venta. `fiscal` usa la fecha contable del comprobante. - PurchasesReportRequest - `source` 'purchases', required - `period` ReportPeriod, required - `start_date` string, date, required — Period start date (YYYY-MM-DD) - `end_date` string, date, required — Period end date (YYYY-MM-DD, inclusive) - `dimensions` union[] — Dimensiones de agrupación. Máximo 12. Acepta product_metafield: para campos personalizados select de producto y contact_metafield: para campos personalizados select de contacto. - union - 'date' | 'week' | 'month' | 'quarter' | 'year' | 'supplier' | 'supplierName' | 'supplierTaxCategory' | 'supplierProvince' | 'supplierCity' | 'product' | 'variant' | 'category' | 'subcategory' | 'productType' | 'warehouse' | 'voucherType' | 'currency' | 'taxRate' - string — Product select custom field dimension. Use product_metafield:, for example product_metafield:season. - string — Contact select custom field dimension. Use contact_metafield:, for example contact_metafield:customer_segment. - `measures` string[], required — Medidas a calcular. Al menos una. - `dimension_filters` object — Filtros por dimensión. Cada clave debe ser una dimensión filtrable para la fuente. También acepta product_metafield: para campos personalizados select de producto y contact_metafield: para campos personalizados select de contacto cuando la fuente lo soporta. El valor es un array de IDs o valores a incluir. - `supplier` string[] - `supplier_name` string[] - `supplier_tax_category` string[] - `supplier_province` string[] - `supplier_city` string[] - `product` string[] - `category` string[] - `subcategory` string[] - `product_type` string[] - `warehouse` string[] - `voucher_type` string[] - `currency` string[] - `tax_rate` string[] - `supplier_status` string[] - `product_status` string[] - `warehouse_status` string[] - `include_totals` boolean — Si es true, la respuesta incluye totales agregados en el campo `totals`. - PaymentsReportRequest - `source` 'payments', required - `period` ReportPeriod, required - `start_date` string, date, required — Period start date (YYYY-MM-DD) - `end_date` string, date, required — Period end date (YYYY-MM-DD, inclusive) - `dimensions` union[] — Dimensiones de agrupación. Máximo 12. Acepta contact_metafield: para campos personalizados select de contacto. - union - 'date' | 'week' | 'weekOfYear' | 'month' | 'monthOfYear' | 'dayOfWeek' | 'year' | 'quarter' | 'hourOfDay' | 'paymentContact' | 'paymentContactName' | 'paymentContactTaxCategory' | 'paymentContactProvince' | 'paymentContactCity' | 'createdBy' | 'pointOfSale' | 'register' | 'posSession' | 'safe' | 'paymentType' | 'paymentRecordStatus' | 'currency' | 'settlementCurrency' | 'formattedPaymentNumber' | 'paymentMethod' | 'paymentMethodType' - string — Contact select custom field dimension. Use contact_metafield:, for example contact_metafield:customer_segment. - `measures` string[], required — Medidas a calcular. Al menos una. - `dimension_filters` object — Filtros por dimensión. Cada clave debe ser una dimensión filtrable para la fuente. También acepta product_metafield: para campos personalizados select de producto y contact_metafield: para campos personalizados select de contacto cuando la fuente lo soporta. El valor es un array de IDs o valores a incluir. - `payment_contact` string[] - `payment_contact_name` string[] - `payment_contact_tax_category` string[] - `payment_contact_province` string[] - `payment_contact_city` string[] - `created_by` string[] - `point_of_sale` string[] - `register` string[] - `pos_session` string[] - `safe` string[] - `payment_type` string[] - `payment_record_status` string[] - `currency` string[] - `settlement_currency` string[] - `formatted_payment_number` string[] - `payment_method` string[] - `payment_method_type` string[] - `payment_contact_status` string[] - `point_of_sale_status` string[] - `register_status` string[] - `safe_status` string[] - `payment_method_status` string[] - `include_totals` boolean — Si es true, la respuesta incluye totales agregados en el campo `totals`. - InventoryReportRequest - `source` 'inventory', required - `period` object — Obligatorio cuando se piden métricas históricas de inventario, métricas derivadas de ventas o métricas de movimientos. - `start_date` string, date, required — Period start date (YYYY-MM-DD) - `end_date` string, date, required — Period end date (YYYY-MM-DD, inclusive) - `dimensions` union[] — Dimensiones de agrupación. Máximo 12. Acepta product_metafield: para campos personalizados select de producto. - union - 'date' | 'week' | 'weekOfYear' | 'month' | 'monthOfYear' | 'dayOfWeek' | 'year' | 'quarter' | 'product' | 'productName' | 'variant' | 'variantSku' | 'category' | 'subcategory' | 'defaultSupplierName' | 'productType' | 'warehouse' | 'currency' - string — Product select custom field dimension. Use product_metafield:, for example product_metafield:season. - `measures` string[], required — Measures to calculate. Inventory analytics measures are period-based; use endingInventoryUnits for the inventory balance at the end of the requested period. - `dimension_filters` object — Filtros por dimensión. Cada clave debe ser una dimensión filtrable para la fuente. También acepta product_metafield: para campos personalizados select de producto y contact_metafield: para campos personalizados select de contacto cuando la fuente lo soporta. El valor es un array de IDs o valores a incluir. - `product` string[] - `product_name` string[] - `variant_sku` string[] - `category` string[] - `subcategory` string[] - `default_supplier_name` string[] - `product_type` string[] - `warehouse` string[] - `currency` string[] - `product_status` string[] - `warehouse_status` string[] - `sale_line_type` string[] - `include_totals` boolean — Si es true, la respuesta incluye totales agregados en el campo `totals`. - `date_basis` 'commercial' | 'fiscal' — Aplica solo cuando se usan métricas derivadas de ventas. `commercial` usa la fecha de venta; `fiscal` usa la fecha contable. ## Response `200` Reporte ejecutado exitosamente - ReportQueryResponse - `request_id` string, required - `data` object, required - `rows` object[], required - `id` string, required - `ids` string[], required - `labels` string[], required - `measures` object, required - `totals` object, nullable, required — Aggregated totals for all rows. Present only when `includeTotals: true` is sent. - `metadata` object, required - `source` 'sales' | 'purchases' | 'payments' | 'inventory', required - `dimensions` string[], required - `measures` string[], required - `period` object - `start_date` string, required - `end_date` string, required - `date_basis` 'commercial' | 'fiscal' ## Other responses - `400` — Solicitud inválida - `401` — API key faltante o inválida - `403` — Scopes insuficientes - `429` — Límite de solicitudes excedido para la organización - `500` — Error interno del servidor --- [API](https://skmtc.net/lapyme/apis/la-pyme-api.md) · [All operations](https://skmtc.net/lapyme/apis/la-pyme-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lapyme/la-pyme-api/versions/414f57f28498/schema)