> ## Documentation Index > Fetch the complete documentation index at: https://docs.payana.la/llms.txt > Use this file to discover all available pages before exploring further. # Download Document XML > Descargar el XML (CFDI) de un documento fiscal de México Descarga el **XML del CFDI** de un documento sincronizado desde el SAT. La respuesta es el archivo binario (`application/xml`), no JSON. ## Requisitos * Compañía de **México** (la API key debe pertenecer a esa compañía). * Documento con origen **`fiscal_entity`** (creado por sincronización SAT, no manual ni CSV). * `{reference}`: UUID interno de Payana. Obtenelo con [`GET /documents`](/api-reference/documents/list) o [`GET /documents/{reference}`](/api-reference/documents/get). ## Comportamiento 1. Si Payana ya tiene el XML almacenado, lo devuelve desde el cache. 2. Si no, lo obtiene del SAT en el momento, lo guarda en Payana y lo devuelve en la misma respuesta. 3. El nombre del archivo viene en `Content-Disposition` (típicamente `{fiscal_reference}.xml`). ## Ejemplo ```bash theme={null} curl -X POST "https://api.prod.payana.cloud/public/api/v1/documents/aaea7db4-647c-4d92-9f86-89e34a68e1aa/xml" \ -H "api-key: YOUR_API_KEY" \ -o factura.xml ``` Guardá la respuesta como archivo (flag `-o` en curl). No esperes un cuerpo JSON en `200`. ## Errores | Código HTTP | Código de error | Cuándo | | ----------- | ----------------------------------- | ------------------------------------------------------------ | | `404` | `document_not_found` | La referencia no existe o no pertenece a tu compañía. | | `422` | `document_not_mexico` | La compañía de la API key no es México. | | `422` | `document_wrong_origin` | El documento no proviene del SAT (`fiscal_entity`). | | `422` | `document_missing_satws_reference` | El documento no tiene referencia Satws para obtener el CFDI. | | `422` | `mexico_document_xml_upload_failed` | Falló almacenar el XML en Payana tras obtenerlo del SAT. | | `422` | `mexico_document_xml_fetch_failed` | Falló leer el XML previamente cacheado. | Para marcar el documento como recibido sin descargar el XML, usá [`POST /documents/{reference}/acknowledge`](/api-reference/documents/acknowledge). ## OpenAPI ````yaml POST /documents/{reference}/xml openapi: 3.1.0 info: title: Payana Accounts Payable API description: >- API pública para gestionar cuentas por pagar (payments) y beneficiarios (beneficiaries) en Payana, incluyendo notificaciones por webhooks cuando se procesan pagos. version: 1.0.0 servers: - url: https://api.prod.payana.cloud/public/api/v1 description: Production - url: https://api.develop.payana.cloud/public/api/v1 description: Develop security: - apiKeyAuth: [] tags: - name: Payments description: Crear y listar pagos - name: Beneficiaries description: Crear, listar y consultar beneficiarios - name: Webhooks description: Eventos de webhooks enviados por Payana - name: Banks description: Listar y consultar bancos - name: Transactions In description: Transacciones entrantes (polling, mismo formato que webhooks) - name: Documents description: Listar, consultar y operar documentos (cuentas por pagar) - name: DIAN Events description: >- Encolar eventos DIAN (030 Acuse de recibo, 031 Reclamo, 032 Recibo del bien, 033 Aceptación expresa, 034 Aceptación tácita) para documentos identificados por CUFE. El procesamiento es asíncrono. - name: Fiscal Sync description: >- Disparar y consultar sincronización de documentos fiscales desde el SAT (México) o la DIAN (Colombia). - name: Workflow Steps description: >- Resolver el paso en que está parado un documento dentro de su flujo: aprobación, clasificación o etiquetado. paths: /documents/{reference}/xml: post: tags: - Documents summary: Download Mexico document CFDI XML description: >- Descarga el XML (CFDI) de un documento fiscal de México como archivo adjunto (`application/xml`). **Disponibilidad:** solo compañías de México y documentos con origen `fiscal_entity` (sincronizados desde el SAT). **Comportamiento:** - Si Payana ya almacenó el XML, lo devuelve desde el archivo cacheado. - Si aún no existe, lo obtiene on-demand del SAT (vía Satws), lo guarda en Payana y lo devuelve en la misma respuesta. - El nombre del archivo viene en el header `Content-Disposition` (típicamente `{fiscal_reference}.xml`). **Autenticación:** API key de compañía en el header `api-key` (misma que el resto de la API pública). **Errores frecuentes (`422`):** compañía no México (`document_not_mexico`), origen distinto de fiscal (`document_wrong_origin`), documento sin referencia Satws (`document_missing_satws_reference`), o fallo al obtener/almacenar el XML (`mexico_document_xml_upload_failed`, `mexico_document_xml_fetch_failed`). parameters: - name: reference in: path required: true description: >- Referencia interna del documento en Payana (UUID, ej. `aaea7db4-647c-4d92-9f86-89e34a68e1aa`). Obtenela con `GET /documents` o `GET /documents/{reference}`. schema: type: string responses: '200': description: Archivo XML del CFDI content: application/xml: schema: type: string format: binary headers: Content-Disposition: description: >- Nombre sugerido del archivo descargado (ej. `attachment; filename="550e8400-e29b-41d4-a716-446655440000.xml"`). schema: type: string '401': description: API key ausente o inválida content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Documento no encontrado content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: Document not found code: document_not_found '422': description: >- El documento no puede generar XML (compañía no México, origen incorrecto, referencia Satws ausente, o error al obtener/almacenar el XML) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notMexico: summary: Compañía no México value: message: Document company is not Mexico code: document_not_mexico wrongOrigin: summary: Origen distinto de fiscal_entity value: message: Document origin is not a fiscal entity code: document_wrong_origin missingSatwsReference: summary: Sin referencia Satws value: message: Document has no Satws reference code: document_missing_satws_reference '429': description: Rate limited content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: ErrorResponse: type: object required: - success - error properties: success: type: boolean const: false error: $ref: '#/components/schemas/ErrorObject' example: success: false error: code: VALIDATION_ERROR message: The request contains invalid data details: amount: - Amount must be greater than 0 beneficiary_id: - Beneficiary does not exist ErrorObject: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string details: anyOf: - $ref: '#/components/schemas/ErrorDetails' - type: 'null' ErrorCode: type: string enum: - VALIDATION_ERROR - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - RATE_LIMITED - INTERNAL_ERROR ErrorDetails: type: object additionalProperties: type: array items: type: string securitySchemes: apiKeyAuth: type: apiKey in: header name: api-key description: API key provista por Payana. ````