--- title: "Listar recibos de venta" description: "Lista recibos de venta de caja/POS con filtros y paginación por cursor, incluido su estado de facturación y cancelación." language: es-MX canonical_url: "https://exac.mx/docs/api/documents/sales-receipts/list-sales-receipts" md_url: "https://exac.mx/docs/api/documents/sales-receipts/list-sales-receipts.md" --- # Listar recibos de venta Lista recibos de venta de caja/POS con filtros y paginación por cursor, incluido su estado de facturación y cancelación. ## Solicitud `GET /v1/sales-receipts` - **Autorización:** Permiso requerido: `receipts:read`. - **Entornos:** Producción y prueba - **Idempotencia:** No requerida ## Contrato canónico para máquinas Este fragmento se genera desde la operación canónica y los contratos Zod que utiliza la ruta. ```json { "method": "GET", "path": "/v1/sales-receipts", "operation": { "operationId": "listSalesReceipts", "tags": [ "Sales receipts" ], "summary": "Listar recibos de venta", "description": "Lista recibos de venta de caja/POS con filtros y paginación por cursor, incluido su estado de facturación y cancelación.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "dateFrom", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "dateTo", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "invoiced", "global_invoiced", "canceled" ] } } ], "responses": { "200": { "description": "Operación completada.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SalesReceipt" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "example": { "data": [ { "category": "sales_receipt", "folio": "R-1001", "customerName": "Estudio Jacaranda", "total": { "amount": 1250, "currency": "MXN" }, "invoiceRequested": false, "documentRef": "sales_receipt:receipt-example", "status": "open", "createdAt": "2026-07-15T12:00:00.000Z", "businessDate": "2026-01-31", "saleType": "paid" } ], "pagination": { "nextCursor": null, "hasMore": false } } } } }, "400": { "description": "Solicitud inválida.\n\n`validation_error`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Credencial inválida o ausente.\n\n`unauthenticated`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "La credencial no incluye el permiso `receipts:read`.\n\n`forbidden`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Método no permitido.\n\n`method_not_allowed`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Allow": { "$ref": "#/components/headers/Allow" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Demasiadas solicitudes.\n\n`rate_limited`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Error interno del servidor.\n\n`internal`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Servicio temporalmente no disponible.\n\n`provider_unavailable`", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-exac-environments": [ "production", "sandbox" ] }, "components": { "schemas": { "ApiError": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ProgrammaticError" } }, "required": [ "error" ], "additionalProperties": false }, "ProgrammaticError": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "validation_error", "unauthenticated", "forbidden", "not_found", "method_not_allowed", "conflict", "idempotency_conflict", "operation_in_progress", "recovery_required", "rate_limited", "provider_unavailable", "internal" ], "description": "Acción recomendada por código:\n\n- `validation_error` — Corrige cada elemento de details.issues usando su path y código estable.\n- `unauthenticated` — Proporciona una API key o un token de acceso OAuth válido.\n- `forbidden` — Usa una credencial con el permiso requerido.\n- `not_found` — Verifica el identificador del recurso dentro de la organización.\n- `method_not_allowed` — Usa el método HTTP documentado.\n- `conflict` — Actualiza el recurso y resuelve su estado actual.\n- `idempotency_conflict` — Usa otra clave de idempotencia para una solicitud modificada.\n- `operation_in_progress` — Espera el tiempo de Retry-After y repite la misma solicitud.\n- `recovery_required` — No reintentes automáticamente; reconcilia el resultado del proveedor.\n- `rate_limited` — Espera el tiempo de Retry-After antes de reintentar.\n- `provider_unavailable` — Reintenta solo cuando la respuesta marque la falla como reintentable.\n- `internal` — Reintenta después y contacta a soporte si el error persiste." }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "code", "message", "status" ], "additionalProperties": false }, "Pagination": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hasMore": { "type": "boolean" } }, "required": [ "nextCursor", "hasMore" ], "additionalProperties": false }, "SalesReceipt": { "type": "object", "properties": { "category": { "type": "string", "const": "sales_receipt" }, "folio": { "type": "string" }, "customerName": { "type": "string" }, "locationName": { "type": "string" }, "total": { "$ref": "#/components/schemas/Money" }, "paymentForm": { "type": "string" }, "settlementTerms": { "type": "object", "properties": { "installmentCount": { "type": "integer", "minimum": 1, "maximum": 60 }, "firstDue": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "transaction_date" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "months_after_transaction" }, "months": { "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "kind", "months" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fixed_date" }, "date": { "type": "string" } }, "required": [ "kind", "date" ], "additionalProperties": false } ] }, "recurrence": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "anchor_day" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "day_of_month" }, "day": { "type": "integer", "minimum": 1, "maximum": 31 } }, "required": [ "kind", "day" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "last_day" } }, "required": [ "kind" ], "additionalProperties": false } ] } }, "required": [ "installmentCount", "firstDue", "recurrence" ], "additionalProperties": false }, "receivablePlanId": { "type": "string" }, "operationalBalance": { "type": "number" }, "invoiceRequested": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "lineRef": { "type": "string" }, "productId": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "number" }, "refundableQuantity": { "type": "number" }, "unitPrice": { "type": "number" }, "discount": { "type": "number" }, "lineTotal": { "type": "number" }, "refundableAmount": { "type": "number" } }, "required": [ "lineRef", "description", "quantity", "refundableQuantity", "unitPrice", "lineTotal", "refundableAmount" ], "additionalProperties": false } }, "documentRef": { "type": "string", "pattern": "^sales_receipt:.+$" }, "status": { "type": "string", "enum": [ "open", "invoiced", "global_invoiced", "canceled" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "businessDate": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "paymentDueDate": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "saleType": { "type": "string", "enum": [ "paid", "credit", "courtesy" ] } }, "required": [ "category", "folio", "total", "invoiceRequested", "documentRef", "status", "createdAt", "businessDate", "saleType" ], "additionalProperties": false }, "Money": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ], "additionalProperties": false } } } } ``` [OpenAPI 3.1](/openapi.json) ## Herramientas MCP equivalentes - [`search_documents`](/docs/mcp/tools/search_documents.md) Documentación completa: https://exac.mx/docs.md Índice para agentes: https://exac.mx/docs/llms.txt