--- title: "Get document" description: "Retrieve one document by its public documentRef. Sales receipt details include stable lineRef values and remaining refundable amounts for sales receipt refunds." language: en canonical_url: "https://exac.mx/docs/en/mcp/tools/get_document" md_url: "https://exac.mx/docs/en/mcp/tools/get_document.md" --- # Get document Retrieve one document by its public documentRef. Sales receipt details include stable lineRef values and remaining refundable amounts for sales receipt refunds. Tool: `get_document` ## Purpose Retrieve one document by its public documentRef. ### Use when You have a documentRef returned by search_documents. ### Do not use when You need to discover a document without a known reference. | Detail | Value | | --- | --- | | Permissions | invoices:read / employees:read / receipts:read / receipts:read:all / quotes:read / expenses:read / sat:read | | Side effects | None | | Idempotency | Idempotent | ## Input schema ```json { "type": "object", "properties": { "documentRef": { "type": "string", "pattern": "^(?:cfdi|withholding|sales_receipt|quote|expense|declaration|tax_compliance_opinion|sales_receipt_refund):.+$", "description": "DocumentRef returned by search_documents" } }, "required": [ "documentRef" ], "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false } ``` ## Output schema ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "documentRef": { "type": "string" }, "category": { "type": "string", "enum": [ "cfdi", "withholding", "sales_receipt", "quote", "expense", "declaration", "tax_compliance_opinion", "sales_receipt_refund" ] }, "status": { "type": "string" }, "direction": { "type": "string", "enum": [ "issued", "received" ] }, "counterpartyName": { "type": "string" }, "total": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ], "additionalProperties": false } }, "required": [ "documentRef", "category" ], "additionalProperties": true }, "error": { "$schema": "http://json-schema.org/draft-07/schema#", "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" ] }, "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 } }, "required": [ "code", "message" ], "additionalProperties": false } }, "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "oneOf": [ { "required": [ "data" ] }, { "required": [ "error" ] } ] } ``` ## Canonical output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "direction": { "$ref": "#/definitions/__schema0" }, "status": { "$ref": "#/definitions/__schema1" }, "archived": { "$ref": "#/definitions/__schema2" }, "uuid": { "$ref": "#/definitions/__schema3" }, "counterpartyName": { "$ref": "#/definitions/__schema4" }, "total": { "$ref": "#/definitions/__schema5" }, "settlementTerms": { "$ref": "#/definitions/__schema6" }, "receivablePlanId": { "$ref": "#/definitions/__schema8" }, "documentRef": { "$ref": "#/definitions/__schema9" }, "category": { "$ref": "#/definitions/__schema10" }, "issuedLocalDateTime": { "$ref": "#/definitions/__schema11" }, "inventoryImpact": { "$ref": "#/definitions/__schema13" }, "customerId": { "$ref": "#/definitions/__schema15" }, "series": { "$ref": "#/definitions/__schema16" }, "folio": { "$ref": "#/definitions/__schema17" }, "fiscal": { "$ref": "#/definitions/__schema18" }, "relatedDocuments": { "$ref": "#/definitions/__schema20" }, "kind": { "$ref": "#/definitions/__schema21" }, "cfdiType": { "$ref": "#/definitions/__schema22" }, "issuer": { "$ref": "#/definitions/__schema23" }, "receiver": { "$ref": "#/definitions/__schema23" }, "items": { "$ref": "#/definitions/__schema24" }, "payment": { "$ref": "#/definitions/__schema25" }, "detail": { "$ref": "#/definitions/__schema27" } }, "required": [ "direction", "status", "archived", "total", "documentRef", "category", "kind", "cfdiType", "issuer", "receiver", "items", "payment", "detail" ], "additionalProperties": false }, { "type": "object", "properties": { "direction": { "$ref": "#/definitions/__schema0" }, "status": { "$ref": "#/definitions/__schema1" }, "archived": { "$ref": "#/definitions/__schema2" }, "uuid": { "$ref": "#/definitions/__schema3" }, "counterpartyName": { "$ref": "#/definitions/__schema4" }, "total": { "$ref": "#/definitions/__schema5" }, "settlementTerms": { "$ref": "#/definitions/__schema6" }, "receivablePlanId": { "$ref": "#/definitions/__schema8" }, "documentRef": { "$ref": "#/definitions/__schema9" }, "category": { "$ref": "#/definitions/__schema10" }, "issuedLocalDateTime": { "$ref": "#/definitions/__schema11" }, "inventoryImpact": { "$ref": "#/definitions/__schema13" }, "customerId": { "$ref": "#/definitions/__schema15" }, "series": { "$ref": "#/definitions/__schema16" }, "folio": { "$ref": "#/definitions/__schema17" }, "fiscal": { "$ref": "#/definitions/__schema18" }, "relatedDocuments": { "$ref": "#/definitions/__schema20" }, "kind": { "$ref": "#/definitions/__schema21" }, "cfdiType": { "$ref": "#/definitions/__schema22" }, "issuer": { "allOf": [ { "$ref": "#/definitions/__schema23" } ] }, "receiver": { "allOf": [ { "$ref": "#/definitions/__schema23" } ] }, "items": { "allOf": [ { "$ref": "#/definitions/__schema24" } ] }, "payment": { "allOf": [ { "$ref": "#/definitions/__schema25" } ] }, "detail": { "$ref": "#/definitions/__schema28" } }, "required": [ "direction", "status", "archived", "total", "documentRef", "category", "kind", "cfdiType", "detail" ], "additionalProperties": false } ] }, { "anyOf": [ { "type": "object", "properties": { "direction": { "$ref": "#/definitions/__schema0" }, "status": { "$ref": "#/definitions/__schema1" }, "archived": { "$ref": "#/definitions/__schema2" }, "uuid": { "$ref": "#/definitions/__schema3" }, "counterpartyName": { "$ref": "#/definitions/__schema4" }, "total": { "$ref": "#/definitions/__schema5" }, "settlementTerms": { "$ref": "#/definitions/__schema6" }, "receivablePlanId": { "$ref": "#/definitions/__schema8" }, "documentRef": { "$ref": "#/definitions/__schema9" }, "category": { "$ref": "#/definitions/__schema10" }, "issuedLocalDateTime": { "$ref": "#/definitions/__schema11" }, "inventoryImpact": { "$ref": "#/definitions/__schema13" }, "customerId": { "$ref": "#/definitions/__schema15" }, "series": { "$ref": "#/definitions/__schema16" }, "folio": { "$ref": "#/definitions/__schema17" }, "fiscal": { "$ref": "#/definitions/__schema18" }, "relatedDocuments": { "type": "array", "items": { "type": "object", "properties": { "relationshipType": { "type": "string" }, "uuids": { "type": "array", "items": { "type": "string" } } }, "required": [ "relationshipType", "uuids" ], "additionalProperties": false } }, "kind": { "$ref": "#/definitions/__schema30" }, "cfdiType": { "$ref": "#/definitions/__schema31" }, "issuer": { "$ref": "#/definitions/__schema23" }, "receiver": { "$ref": "#/definitions/__schema23" }, "items": { "$ref": "#/definitions/__schema24" }, "payment": { "allOf": [ { "$ref": "#/definitions/__schema25" } ] }, "detail": { "$ref": "#/definitions/__schema27" } }, "required": [ "direction", "status", "archived", "total", "documentRef", "category", "relatedDocuments", "kind", "cfdiType", "issuer", "receiver", "items", "detail" ], "additionalProperties": false }, { "type": "object", "properties": { "direction": { "$ref": "#/definitions/__schema0" }, "status": { "$ref": "#/definitions/__schema1" }, "archived": { "$ref": "#/definitions/__schema2" }, "uuid": { "$ref": "#/definitions/__schema3" }, "counterpartyName": { "$ref": "#/definitions/__schema4" }, "total": { "$ref": "#/definitions/__schema5" }, "settlementTerms": { "$ref": "#/definitions/__schema6" }, "receivablePlanId": { "$ref": "#/definitions/__schema8" }, "documentRef": { "$ref": "#/definitions/__schema9" }, "category": { "$ref": "#/definitions/__schema10" }, "issuedLocalDateTime": { "$ref": "#/definitions/__schema11" }, "inventoryImpact": { "$ref": "#/definitions/__schema13" }, "customerId": { "$ref": "#/definitions/__schema15" }, "series": { "$ref": "#/definitions/__schema16" }, "folio": { "$ref": "#/definitions/__schema17" }, "fiscal": { "$ref": "#/definitions/__schema18" }, "relatedDocuments": { "type": "array", "items": { "type": "object", "properties": { "relationshipType": { "type": "string" }, "uuids": { "type": "array", "items": { "type": "string" } } }, "required": [ "relationshipType", "uuids" ], "additionalProperties": false } }, "kind": { "$ref": "#/definitions/__schema30" }, "cfdiType": { "$ref": "#/definitions/__schema31" }, "issuer": { "allOf": [ { "$ref": "#/definitions/__schema23" } ] }, "receiver": { "allOf": [ { "$ref": "#/definitions/__schema23" } ] }, "items": { "allOf": [ { "$ref": "#/definitions/__schema24" } ] }, "payment": { "allOf": [ { "$ref": "#/definitions/__schema25" } ] }, "detail": { "$ref": "#/definitions/__schema28" } }, "required": [ "direction", "status", "archived", "total", "documentRef", "category", "kind", "cfdiType", "detail" ], "additionalProperties": false } ] }, { "anyOf": [ { "type": "object", "properties": { "direction": { "$ref": "#/definitions/__schema0" }, "status": { "$ref": "#/definitions/__schema1" }, "archived": { "$ref": "#/definitions/__schema2" }, "uuid": { "$ref": "#/definitions/__schema3" }, "counterpartyName": { "$ref": "#/definitions/__schema4" }, "total": { "$ref": "#/definitions/__schema5" }, "settlementTerms": { "$ref": "#/definitions/__schema6" }, "receivablePlanId": { "$ref": "#/definitions/__schema8" }, "documentRef": { "$ref": "#/definitions/__schema9" }, "category": { "$ref": "#/definitions/__schema10" }, "issuedLocalDateTime": { "$ref": "#/definitions/__schema11" }, "inventoryImpact": { "$ref": "#/definitions/__schema13" }, "customerId": { "$ref": "#/definitions/__schema15" }, "series": { "$ref": "#/definitions/__schema16" }, "folio": { "$ref": "#/definitions/__schema17" }, "fiscal": { "$ref": "#/definitions/__schema18" }, "relatedDocuments": { "$ref": "#/definitions/__schema20" }, "kind": { "$ref": "#/definitions/__schema32" }, "cfdiType": { "$ref": "#/definitions/__schema33" }, "issuer": { "$ref": "#/definitions/__schema23" }, "receiver": { "$ref": "#/definitions/__schema23" }, "items": { "$ref": "#/definitions/__schema24" }, "detail": { "$ref": "#/definitions/__schema27" } }, "required": [ "direction", "status", "archived", "total", "documentRef", "category", "kind", "cfdiType", "issuer", "receiver", "items", "detail" ], "additionalProperties": false }, { "type": "object", "properties": { "direction": { "$ref": "#/definitions/__schema0" }, "status": { "$ref": "#/definitions/__schema1" }, "archived": { "$ref": "#/definitions/__schema2" }, "uuid": { "$ref": "#/definitions/__schema3" }, "counterpartyName": { "$ref": "#/definitions/__schema4" }, "total": { "$ref": "#/definitions/__schema5" }, "settlementTerms": { "$ref": "#/definitions/__schema6" }, "receivablePlanId": { "$ref": "#/definitions/__schema8" }, "documentRef": { "$ref": "#/definitions/__schema9" }, "category": { "$ref": "#/definitions/__schema10" }, "issuedLocalDateTime": { "$ref": "#/definitions/__schema11" }, "inventoryImpact": { "$ref": "#/definitions/__schema13" }, "customerId": { "$ref": "#/definitions/__schema15" }, "series": { "$ref": "#/definitions/__schema16" }, "folio": { "$ref": "#/definitions/__schema17" }, "fiscal": { "$ref": "#/definitions/__schema18" }, "relatedDocuments": { "$ref": "#/definitions/__schema20" }, "kind": { "$ref": "#/definitions/__schema32" }, "cfdiType": { "$ref": "#/definitions/__schema33" }, "issuer": { "allOf": [ { "$ref": "#/definitions/__schema23" } ] }, "receiver": { "allOf": [ { "$ref": "#/definitions/__schema23" } ] }, "items": { "allOf": [ { "$ref": "#/definitions/__schema24" } ] }, "detail": { "$ref": "#/definitions/__schema28" } }, "required": [ "direction", "status", "archived", "total", "documentRef", "category", "kind", "cfdiType", "detail" ], "additionalProperties": false } ] }, { "anyOf": [ { "type": "object", "properties": { "direction": { "$ref": "#/definitions/__schema0" }, "status": { "$ref": "#/definitions/__schema1" }, "archived": { "$ref": "#/definitions/__schema2" }, "uuid": { "$ref": "#/definitions/__schema3" }, "counterpartyName": { "$ref": "#/definitions/__schema4" }, "total": { "$ref": "#/definitions/__schema5" }, "settlementTerms": { "$ref": "#/definitions/__schema6" }, "receivablePlanId": { "$ref": "#/definitions/__schema8" }, "documentRef": { "$ref": "#/definitions/__schema9" }, "category": { "$ref": "#/definitions/__schema10" }, "issuedLocalDateTime": { "$ref": "#/definitions/__schema11" }, "inventoryImpact": { "$ref": "#/definitions/__schema13" }, "customerId": { "$ref": "#/definitions/__schema15" }, "series": { "$ref": "#/definitions/__schema16" }, "folio": { "$ref": "#/definitions/__schema17" }, "fiscal": { "$ref": "#/definitions/__schema18" }, "relatedDocuments": { "$ref": "#/definitions/__schema20" }, "items": { "$ref": "#/definitions/__schema34" }, "kind": { "$ref": "#/definitions/__schema35" }, "cfdiType": { "$ref": "#/definitions/__schema36" }, "issuer": { "$ref": "#/definitions/__schema23" }, "receiver": { "$ref": "#/definitions/__schema23" }, "paymentComplement": { "$ref": "#/definitions/__schema37" }, "detail": { "$ref": "#/definitions/__schema27" } }, "required": [ "direction", "status", "archived", "total", "documentRef", "category", "kind", "cfdiType", "issuer", "receiver", "paymentComplement", "detail" ], "additionalProperties": false }, { "type": "object", "properties": { "direction": { "$ref": "#/definitions/__schema0" }, "status": { "$ref": "#/definitions/__schema1" }, "archived": { "$ref": "#/definitions/__schema2" }, "uuid": { "$ref": "#/definitions/__schema3" }, "counterpartyName": { "$ref": "#/definitions/__schema4" }, "total": { "$ref": "#/definitions/__schema5" }, "settlementTerms": { "$ref": "#/definitions/__schema6" }, "receivablePlanId": { "$ref": "#/definitions/__schema8" }, "documentRef": { "$ref": "#/definitions/__schema9" }, "category": { "$ref": "#/definitions/__schema10" }, "issuedLocalDateTime": { "$ref": "#/definitions/__schema11" }, "inventoryImpact": { "$ref": "#/definitions/__schema13" }, "customerId": { "$ref": "#/definitions/__schema15" }, "series": { "$ref": "#/definitions/__schema16" }, "folio": { "$ref": "#/definitions/__schema17" }, "fiscal": { "$ref": "#/definitions/__schema18" }, "relatedDocuments": { "$ref": "#/definitions/__schema20" }, "items": { "$ref": "#/definitions/__schema34" }, "kind": { "$ref": "#/definitions/__schema35" }, "cfdiType": { "$ref": "#/definitions/__schema36" }, "issuer": { "allOf": [ { "$ref": "#/definitions/__schema23" } ] }, "receiver": { "allOf": [ { "$ref": "#/definitions/__schema23" } ] }, "paymentComplement": { "allOf": [ { "$ref": "#/definitions/__schema37" } ] }, "detail": { "$ref": "#/definitions/__schema28" } }, "required": [ "direction", "status", "archived", "total", "documentRef", "category", "kind", "cfdiType", "detail" ], "additionalProperties": false } ] }, { "anyOf": [ { "type": "object", "properties": { "direction": { "$ref": "#/definitions/__schema0" }, "status": { "$ref": "#/definitions/__schema1" }, "archived": { "$ref": "#/definitions/__schema2" }, "uuid": { "$ref": "#/definitions/__schema3" }, "counterpartyName": { "$ref": "#/definitions/__schema4" }, "total": { "$ref": "#/definitions/__schema5" }, "settlementTerms": { "$ref": "#/definitions/__schema6" }, "receivablePlanId": { "$ref": "#/definitions/__schema8" }, "documentRef": { "$ref": "#/definitions/__schema9" }, "category": { "$ref": "#/definitions/__schema10" }, "issuedLocalDateTime": { "$ref": "#/definitions/__schema11" }, "inventoryImpact": { "$ref": "#/definitions/__schema13" }, "customerId": { "$ref": "#/definitions/__schema15" }, "series": { "$ref": "#/definitions/__schema16" }, "folio": { "$ref": "#/definitions/__schema17" }, "fiscal": { "$ref": "#/definitions/__schema18" }, "relatedDocuments": { "$ref": "#/definitions/__schema20" }, "kind": { "$ref": "#/definitions/__schema38" }, "cfdiType": { "$ref": "#/definitions/__schema39" }, "employeeId": { "$ref": "#/definitions/__schema40" }, "issuer": { "$ref": "#/definitions/__schema41" }, "receiver": { "$ref": "#/definitions/__schema42" }, "payroll": { "$ref": "#/definitions/__schema43" }, "detail": { "$ref": "#/definitions/__schema27" } }, "required": [ "direction", "status", "archived", "total", "documentRef", "category", "kind", "cfdiType", "payroll", "detail" ], "additionalProperties": false }, { "type": "object", "properties": { "direction": { "$ref": "#/definitions/__schema0" }, "status": { "$ref": "#/definitions/__schema1" }, "archived": { "$ref": "#/definitions/__schema2" }, "uuid": { "$ref": "#/definitions/__schema3" }, "counterpartyName": { "$ref": "#/definitions/__schema4" }, "total": { "$ref": "#/definitions/__schema5" }, "settlementTerms": { "$ref": "#/definitions/__schema6" }, "receivablePlanId": { "$ref": "#/definitions/__schema8" }, "documentRef": { "$ref": "#/definitions/__schema9" }, "category": { "$ref": "#/definitions/__schema10" }, "issuedLocalDateTime": { "$ref": "#/definitions/__schema11" }, "inventoryImpact": { "$ref": "#/definitions/__schema13" }, "customerId": { "$ref": "#/definitions/__schema15" }, "series": { "$ref": "#/definitions/__schema16" }, "folio": { "$ref": "#/definitions/__schema17" }, "fiscal": { "$ref": "#/definitions/__schema18" }, "relatedDocuments": { "$ref": "#/definitions/__schema20" }, "kind": { "$ref": "#/definitions/__schema38" }, "cfdiType": { "$ref": "#/definitions/__schema39" }, "employeeId": { "$ref": "#/definitions/__schema40" }, "issuer": { "$ref": "#/definitions/__schema41" }, "receiver": { "$ref": "#/definitions/__schema42" }, "payroll": { "allOf": [ { "$ref": "#/definitions/__schema43" } ] }, "detail": { "$ref": "#/definitions/__schema28" } }, "required": [ "direction", "status", "archived", "total", "documentRef", "category", "kind", "cfdiType", "detail" ], "additionalProperties": false } ] }, { "anyOf": [ { "type": "object", "properties": { "direction": { "$ref": "#/definitions/__schema0" }, "status": { "$ref": "#/definitions/__schema1" }, "archived": { "$ref": "#/definitions/__schema2" }, "uuid": { "$ref": "#/definitions/__schema3" }, "counterpartyName": { "$ref": "#/definitions/__schema4" }, "total": { "$ref": "#/definitions/__schema5" }, "documentRef": { "$ref": "#/definitions/__schema44" }, "category": { "$ref": "#/definitions/__schema45" }, "issuedLocalDateTime": { "$ref": "#/definitions/__schema46" }, "withholding": { "type": "object", "properties": { "withholdingTypeCode": { "type": "string" }, "description": { "type": "string" }, "internalFolio": { "type": "string" }, "period": { "type": "object", "properties": { "fromMonth": { "type": "number" }, "toMonth": { "type": "number" }, "year": { "type": "number" } }, "required": [ "fromMonth", "toMonth", "year" ], "additionalProperties": false }, "totals": { "type": "object", "properties": { "operation": { "type": "number" }, "gravable": { "type": "number" }, "exempt": { "type": "number" }, "retained": { "type": "number" } }, "additionalProperties": false }, "taxes": { "type": "array", "items": { "type": "object", "properties": { "tax": { "type": "string" }, "amount": { "type": "number" }, "paymentType": { "type": "string" } }, "required": [ "tax", "amount" ], "additionalProperties": false } } }, "required": [ "withholdingTypeCode", "period", "totals", "taxes" ], "additionalProperties": false }, "detail": { "$ref": "#/definitions/__schema27" } }, "required": [ "direction", "status", "archived", "total", "documentRef", "category", "withholding", "detail" ], "additionalProperties": false }, { "type": "object", "properties": { "direction": { "$ref": "#/definitions/__schema0" }, "status": { "$ref": "#/definitions/__schema1" }, "archived": { "$ref": "#/definitions/__schema2" }, "uuid": { "$ref": "#/definitions/__schema3" }, "counterpartyName": { "$ref": "#/definitions/__schema4" }, "total": { "$ref": "#/definitions/__schema5" }, "documentRef": { "$ref": "#/definitions/__schema44" }, "category": { "$ref": "#/definitions/__schema45" }, "issuedLocalDateTime": { "$ref": "#/definitions/__schema46" }, "detail": { "$ref": "#/definitions/__schema28" } }, "required": [ "direction", "status", "archived", "total", "documentRef", "category", "detail" ], "additionalProperties": false } ] }, { "type": "object", "properties": { "category": { "type": "string", "const": "sales_receipt" }, "folio": { "type": "string" }, "customerName": { "type": "string" }, "locationName": { "type": "string" }, "total": { "$ref": "#/definitions/__schema5" }, "paymentForm": { "type": "string" }, "settlementTerms": { "allOf": [ { "$ref": "#/definitions/__schema7" } ] }, "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": { "$ref": "#/definitions/__schema14" }, "businessDate": { "$ref": "#/definitions/__schema26" }, "paymentDueDate": { "allOf": [ { "$ref": "#/definitions/__schema26" } ] }, "saleType": { "type": "string", "enum": [ "paid", "credit", "courtesy" ] } }, "required": [ "category", "folio", "total", "invoiceRequested", "documentRef", "status", "createdAt", "businessDate", "saleType" ], "additionalProperties": false }, { "type": "object", "properties": { "folioNumber": { "type": "number" }, "currency": { "type": "string", "const": "MXN" }, "customerId": { "type": "string" }, "customerName": { "type": "string" }, "customerEmail": { "type": "string" }, "locationId": { "type": "string" }, "locationName": { "type": "string" }, "notes": { "type": "string" }, "settlementTerms": { "allOf": [ { "$ref": "#/definitions/__schema7" } ] }, "receivablePlanId": { "type": "string" }, "revisionNumber": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "documentRef": { "type": "string", "pattern": "^quote:.+$" }, "category": { "type": "string", "const": "quote" }, "status": { "type": "string", "enum": [ "draft", "sent", "accepted", "converted", "expired", "canceled" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "lineRef": { "type": "string" }, "productId": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "discount": { "type": "number" }, "taxIncluded": { "type": "boolean" }, "taxability": { "type": "string", "enum": [ "standard", "zero", "exempt" ] }, "taxRate": { "type": "number" }, "satProductCode": { "type": "string" }, "satUnitCode": { "type": "string" }, "unitName": { "type": "string" } }, "required": [ "description", "quantity", "unitPrice" ], "additionalProperties": false } }, "totals": { "$ref": "#/definitions/__schema47" }, "issueDate": { "$ref": "#/definitions/__schema26" }, "validUntil": { "$ref": "#/definitions/__schema26" }, "sentAt": { "allOf": [ { "$ref": "#/definitions/__schema14" } ] }, "lastPublishedAt": { "allOf": [ { "$ref": "#/definitions/__schema14" } ] }, "acceptance": { "type": "object", "properties": { "acceptedAt": { "$ref": "#/definitions/__schema14" }, "invoiceRequested": { "type": "boolean" }, "fiscalTreatment": { "type": "string", "enum": [ "public_general", "specific_counterparty" ] }, "fiscalTotals": { "$ref": "#/definitions/__schema47" }, "fiscalCustomer": { "type": "object", "properties": { "rfc": { "type": "string" }, "legalName": { "type": "string" }, "taxSystem": { "type": "string" }, "postalCode": { "type": "string" }, "cfdiUse": { "type": "string" }, "email": { "type": "string" } }, "required": [ "rfc", "legalName", "taxSystem", "postalCode", "cfdiUse", "email" ], "additionalProperties": false } }, "required": [ "acceptedAt", "invoiceRequested", "fiscalTreatment", "fiscalTotals" ], "additionalProperties": false }, "createdAt": { "$ref": "#/definitions/__schema14" }, "updatedAt": { "$ref": "#/definitions/__schema14" }, "receiptDocumentRef": { "type": "string", "pattern": "^sales_receipt:.+$" }, "payment": { "type": "object", "properties": { "paymentId": { "type": "string" }, "source": { "type": "string", "enum": [ "manual", "online" ] }, "amount": { "type": "number" }, "currency": { "type": "string", "const": "MXN" }, "paymentForm": { "type": "string" }, "applicationStatus": { "type": "string", "enum": [ "pending", "processing", "applied", "failed", "conflict" ] }, "applicationErrorCode": { "type": "string", "enum": [ "payment_form_required", "fiscal_drift", "location_resolution_required", "duplicate_payment", "application_failed" ] }, "invoiceStatus": { "type": "string", "enum": [ "pending", "processing", "issued", "failed" ] }, "salesReceiptDocumentRef": { "type": "string", "pattern": "^sales_receipt:.+$" }, "cfdiDocumentRef": { "type": "string", "pattern": "^cfdi:.+$" }, "paidAt": { "$ref": "#/definitions/__schema14" } }, "required": [ "paymentId", "source", "amount", "currency", "applicationStatus", "paidAt" ], "additionalProperties": false } }, "required": [ "folioNumber", "currency", "customerName", "documentRef", "category", "status", "items", "totals", "issueDate", "validUntil", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "object", "properties": { "category": { "type": "string", "const": "expense" }, "description": { "type": "string" }, "supplierName": { "type": "string" }, "expenseCategory": { "type": "string" }, "locationName": { "type": "string" }, "settlementMode": { "type": "string", "enum": [ "credit", "paid" ] }, "paymentForm": { "type": "string" }, "total": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "const": "MXN" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "notes": { "type": "string" }, "documentRef": { "type": "string", "pattern": "^expense:.+$" }, "occurredAt": { "$ref": "#/definitions/__schema14" }, "businessDate": { "$ref": "#/definitions/__schema26" } }, "required": [ "category", "description", "expenseCategory", "settlementMode", "paymentForm", "total", "documentRef", "occurredAt", "businessDate" ], "additionalProperties": false }, { "type": "object", "properties": { "category": { "type": "string", "const": "declaration" }, "fiscalYear": { "type": "number" }, "period": { "type": "number" }, "periodicity": { "type": "string" }, "declarationType": { "type": "string" }, "complementaryType": { "type": "string" }, "operationNumber": { "type": "string" }, "captureLine": { "type": "string" }, "status": { "type": "string" }, "total": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "const": "MXN" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "paidAmount": { "type": "number" }, "documentRef": { "type": "string", "pattern": "^declaration:.+$" }, "scrapedAt": { "$ref": "#/definitions/__schema14" }, "filedAt": { "$ref": "#/definitions/__schema26" }, "paymentDate": { "allOf": [ { "$ref": "#/definitions/__schema26" } ] } }, "required": [ "category", "fiscalYear", "period", "periodicity", "declarationType", "operationNumber", "documentRef", "scrapedAt", "filedAt" ], "additionalProperties": false }, { "type": "object", "properties": { "category": { "type": "string", "const": "tax_compliance_opinion" }, "status": { "type": "string", "enum": [ "positive", "negative", "unknown" ] }, "pdfAvailable": { "type": "boolean" }, "documentRef": { "type": "string", "pattern": "^tax_compliance_opinion:.+$" }, "issuedLocalDateTime": { "$ref": "#/definitions/__schema12" }, "retrievedAt": { "$ref": "#/definitions/__schema14" } }, "required": [ "category", "status", "pdfAvailable", "documentRef", "issuedLocalDateTime", "retrievedAt" ], "additionalProperties": false }, { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "commercial_refund", "resico_reconciliation" ] }, "settlementMethod": { "type": "string", "enum": [ "cash", "transfer", "original_method", "customer_credit" ] }, "fiscalTreatment": { "type": "string", "enum": [ "none", "credit_note" ] }, "total": { "$ref": "#/definitions/__schema5" }, "note": { "type": "string" }, "documentRef": { "type": "string", "pattern": "^sales_receipt_refund:.+$" }, "category": { "type": "string", "const": "sales_receipt_refund" }, "receiptDocumentRef": { "type": "string", "pattern": "^sales_receipt:.+$" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "recovery_required", "canceled" ] }, "businessDate": { "allOf": [ { "$ref": "#/definitions/__schema26" } ] }, "createdAt": { "$ref": "#/definitions/__schema14" }, "completedAt": { "allOf": [ { "$ref": "#/definitions/__schema14" } ] } }, "required": [ "reason", "settlementMethod", "fiscalTreatment", "total", "documentRef", "category", "receiptDocumentRef", "status", "createdAt" ], "additionalProperties": false } ] }, "error": { "$schema": "http://json-schema.org/draft-07/schema#", "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" ] }, "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 } }, "required": [ "code", "message" ], "additionalProperties": false } }, "additionalProperties": false, "definitions": { "__schema0": { "type": "string", "enum": [ "issued", "received" ] }, "__schema1": { "type": "string", "enum": [ "draft", "valid", "canceled" ] }, "__schema2": { "type": "boolean" }, "__schema3": { "type": "string" }, "__schema4": { "type": "string" }, "__schema5": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "__schema6": { "allOf": [ { "$ref": "#/definitions/__schema7" } ] }, "__schema7": { "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 }, "__schema8": { "type": "string" }, "__schema9": { "type": "string", "pattern": "^cfdi:.+$" }, "__schema10": { "type": "string", "const": "cfdi" }, "__schema11": { "allOf": [ { "$ref": "#/definitions/__schema12" } ] }, "__schema12": { "type": "string", "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})T(\\d{2}):(\\d{2}):(\\d{2})(?:\\.(\\d{1,9}))?$" }, "__schema13": { "type": "object", "properties": { "locationId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "deducted", "reversed" ] }, "appliedAt": { "allOf": [ { "$ref": "#/definitions/__schema14" } ] }, "reversedAt": { "allOf": [ { "$ref": "#/definitions/__schema14" } ] } }, "required": [ "status" ], "additionalProperties": false }, "__schema14": { "type": "string", "format": "date-time" }, "__schema15": { "type": "string" }, "__schema16": { "type": "string" }, "__schema17": { "type": "string" }, "__schema18": { "type": "object", "properties": { "subtotal": { "type": "number" }, "ivaTransferred": { "type": "number" }, "ivaWithheld": { "type": "number" }, "isrWithheld": { "type": "number" }, "exchangeRate": { "type": "number" }, "totalMxn": { "type": "number" }, "placeOfIssue": { "type": "string" }, "exportation": { "type": "string" }, "taxes": { "type": "object", "properties": { "transfers": { "type": "array", "items": { "$ref": "#/definitions/__schema19" } }, "withholdings": { "type": "array", "items": { "$ref": "#/definitions/__schema19" } } }, "required": [ "transfers", "withholdings" ], "additionalProperties": false }, "globalInformation": { "type": "object", "properties": { "frequency": { "type": "string" }, "months": { "type": "string" }, "year": { "type": "number" } }, "required": [ "frequency", "months", "year" ], "additionalProperties": false }, "cfdiUse": { "type": "string" }, "stampedLocalDateTime": { "allOf": [ { "$ref": "#/definitions/__schema12" } ] } }, "additionalProperties": false }, "__schema19": { "type": "object", "properties": { "tax": { "type": "string" }, "factorType": { "type": "string" }, "rateOrFee": { "type": "string" }, "amount": { "type": "string" }, "base": { "type": "string" } }, "required": [ "tax", "factorType" ], "additionalProperties": false }, "__schema20": { "type": "array", "items": { "type": "object", "properties": { "relationshipType": { "type": "string" }, "uuids": { "type": "array", "items": { "type": "string" } } }, "required": [ "relationshipType", "uuids" ], "additionalProperties": false } }, "__schema21": { "type": "string", "const": "income" }, "__schema22": { "type": "string", "const": "I" }, "__schema23": { "type": "object", "properties": { "rfc": { "type": "string" }, "legalName": { "type": "string" }, "taxSystem": { "type": "string" }, "postalCode": { "type": "string" }, "cfdiUse": { "type": "string" } }, "required": [ "rfc", "legalName", "taxSystem" ], "additionalProperties": false }, "__schema24": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "discount": { "type": "number" }, "unitName": { "type": "string" }, "taxObject": { "type": "string" }, "taxes": { "type": "object", "properties": { "transfers": { "type": "array", "items": { "$ref": "#/definitions/__schema19" } }, "withholdings": { "type": "array", "items": { "$ref": "#/definitions/__schema19" } } }, "required": [ "transfers", "withholdings" ], "additionalProperties": false }, "satProductCode": { "type": "string" }, "satUnitCode": { "type": "string" } }, "required": [ "description", "quantity", "unitPrice" ], "additionalProperties": false } }, "__schema25": { "type": "object", "properties": { "timing": { "type": "string", "enum": [ "single_payment", "deferred_or_installments" ] }, "formCode": { "type": "string" }, "methodCode": { "type": "string" }, "dueDate": { "allOf": [ { "$ref": "#/definitions/__schema26" } ] }, "remainingBalance": { "type": "number" }, "effectiveRemainingBalance": { "type": "number" }, "manualAdjustmentNeedsReview": { "type": "boolean" }, "conditions": { "type": "string" } }, "required": [ "timing" ], "additionalProperties": false }, "__schema26": { "type": "string", "format": "date" }, "__schema27": { "type": "object", "properties": { "availability": { "type": "string", "const": "complete" } }, "required": [ "availability" ], "additionalProperties": false }, "__schema28": { "type": "object", "properties": { "availability": { "type": "string", "const": "partial" }, "missing": { "minItems": 1, "type": "array", "items": { "$ref": "#/definitions/__schema29" } } }, "required": [ "availability", "missing" ], "additionalProperties": false }, "__schema29": { "type": "string", "minLength": 1 }, "__schema30": { "type": "string", "const": "credit_note" }, "__schema31": { "type": "string", "const": "E" }, "__schema32": { "type": "string", "const": "transfer" }, "__schema33": { "type": "string", "const": "T" }, "__schema34": { "allOf": [ { "$ref": "#/definitions/__schema24" } ] }, "__schema35": { "type": "string", "const": "payment_complement" }, "__schema36": { "type": "string", "const": "P" }, "__schema37": { "type": "object", "properties": { "version": { "type": "string" }, "totalPayments": { "type": "number" }, "payments": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "amount": { "type": "number" }, "exchangeRate": { "type": "number" }, "relatedCfdis": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string" }, "series": { "type": "string" }, "folio": { "type": "string" }, "currency": { "type": "string" }, "taxObject": { "type": "string" }, "installment": { "type": "string" }, "balances": { "type": "object", "properties": { "previous": { "type": "number" }, "paid": { "type": "number" }, "remaining": { "type": "number" } }, "additionalProperties": false }, "taxes": { "type": "object", "properties": { "transfers": { "type": "array", "items": { "$ref": "#/definitions/__schema19" } }, "withholdings": { "type": "array", "items": { "$ref": "#/definitions/__schema19" } } }, "required": [ "transfers", "withholdings" ], "additionalProperties": false } }, "required": [ "uuid", "currency" ], "additionalProperties": false } }, "formCode": { "type": "string" }, "paidLocalDateTime": { "$ref": "#/definitions/__schema12" } }, "required": [ "currency", "amount", "relatedCfdis", "formCode", "paidLocalDateTime" ], "additionalProperties": false } } }, "required": [ "version", "totalPayments", "payments" ], "additionalProperties": false }, "__schema38": { "type": "string", "const": "payroll" }, "__schema39": { "type": "string", "const": "N" }, "__schema40": { "type": "string" }, "__schema41": { "allOf": [ { "$ref": "#/definitions/__schema23" } ] }, "__schema42": { "allOf": [ { "$ref": "#/definitions/__schema23" } ] }, "__schema43": { "type": "object", "properties": { "paidDays": { "type": "number" }, "earnings": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "taxableAmount": { "type": "number" }, "exemptAmount": { "type": "number" } }, "additionalProperties": false } }, "deductions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "amount": { "type": "number" } }, "additionalProperties": false } }, "otherPayments": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "amount": { "type": "number" }, "employmentSubsidy": { "type": "number" } }, "additionalProperties": false } }, "totals": { "type": "object", "properties": { "earnings": { "type": "number" }, "deductions": { "type": "number" }, "otherPayments": { "type": "number" }, "net": { "type": "number" } }, "additionalProperties": false }, "employee": { "type": "object", "properties": { "curp": { "type": "string" }, "employeeNumber": { "type": "string" }, "socialSecurityNumber": { "type": "string" }, "contractType": { "type": "string" }, "regimeType": { "type": "string" }, "paymentFrequency": { "type": "string" }, "stateCode": { "type": "string" }, "positionRisk": { "type": "string" }, "integratedDailySalary": { "type": "number" }, "employmentStartedOn": { "allOf": [ { "$ref": "#/definitions/__schema26" } ] } }, "additionalProperties": false }, "period": { "type": "object", "properties": { "paidOn": { "$ref": "#/definitions/__schema26" }, "startedOn": { "allOf": [ { "$ref": "#/definitions/__schema26" } ] }, "endedOn": { "allOf": [ { "$ref": "#/definitions/__schema26" } ] } }, "required": [ "paidOn" ], "additionalProperties": false } }, "required": [ "earnings", "deductions", "otherPayments", "totals", "employee", "period" ], "additionalProperties": false }, "__schema44": { "type": "string", "pattern": "^withholding:.+$" }, "__schema45": { "type": "string", "const": "withholding" }, "__schema46": { "allOf": [ { "$ref": "#/definitions/__schema12" } ] }, "__schema47": { "type": "object", "properties": { "subtotal": { "type": "number" }, "discount": { "type": "number" }, "taxes": { "type": "number" }, "total": { "type": "number" }, "taxBreakdown": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "IVA", "ISR" ] }, "factor": { "type": "string", "enum": [ "Tasa", "Exento" ] }, "rate": { "type": "number" }, "withholding": { "type": "boolean" }, "base": { "type": "number" }, "amount": { "type": "number" }, "label": { "type": "string" } }, "required": [ "type", "factor", "rate", "withholding", "base", "amount", "label" ], "additionalProperties": false } } }, "required": [ "subtotal", "taxes", "total", "taxBreakdown" ], "additionalProperties": false } }, "oneOf": [ { "required": [ "data" ] }, { "required": [ "error" ] } ] } ``` ## Related tools - [`search_documents`](/docs/en/mcp/tools/search_documents.md) — **Search documents**: Search one public document family at a time. Use cfdi for income, credit-note, transfer, payroll, and payment-complement documents; use withholding, sales_receipt, quote, expense, declaration, tax_compliance_opinion, or sales_receipt_refund for the other families. - [`get_document_file`](/docs/en/mcp/tools/get_document_file.md) — **Get document file**: Retrieve one document file as an MCP binary resource. Use preview_pdf to render an unstamped CFDI draft before stamping; the preview has no fiscal validity. CFDIs also support pdf, xml, zip, cancellation_pdf, and cancellation_xml; withholdings support pdf, xml, and zip; sales receipts and quotes support pdf; declarations support pdf, payment_pdf, and full_pdf; opinions support pdf. ## Related workflow [See the canonical workflows in the introduction](/docs/en.md) ## Equivalent REST operations - [`GET /v1/cfdis/{documentRef}`](/docs/en/api/documents/cfdi/get-cfdi.md) - [`GET /v1/withholdings/{documentRef}`](/docs/en/api/documents/withholding-documents/get-withholding.md) - [`GET /v1/sales-receipts/{documentRef}`](/docs/en/api/documents/sales-receipts/get-sales-receipt.md) - [`GET /v1/expenses/{documentRef}`](/docs/en/api/documents/expenses/get-expense.md) - [`GET /v1/declarations/{documentRef}`](/docs/en/api/documents/sat/get-declaration.md) - [`GET /v1/tax-compliance-opinions/{documentRef}`](/docs/en/api/documents/sat/get-tax-compliance-opinion.md) - [`GET /v1/sales-receipt-refunds/{documentRef}`](/docs/en/api/documents/sales-receipts/get-sales-receipt-refund.md) - [`GET /v1/quotes/{documentRef}`](/docs/en/api/documents/quotes/get-quote.md) Complete documentation: https://exac.mx/docs/en.md Agent documentation index: https://exac.mx/docs/en/llms.txt