> ## Documentation Index > Fetch the complete documentation index at: https://spidocs.chargebee.com/llms.txt > Use this file to discover all available pages before exploring further. # Download Document > Retrieves the document content associated with the provided documentId from the connected e-invoicing provider. A document_id by itself is not always sufficient for the provider to determine which document formats or variants to return. Chargebee includes additional query parameters — such as country, transaction_type, and model — so the adapter can accurately identify and fetch the correct document representations. If the mime_type query parameter is not provided, the adapter MUST retrieve all available document representations for the specified document_id. When a specific mime_type is supplied, the adapter MUST return only the matching representation(s). The document may be returned either as a pre-signed URL or as a direct binary stream (such as a PDF or XML file), depending on the provider’s capabilities and the SPI implementation. In Chargebee, this endpoint is called after the document has been successfully processed either to send it via email to the end customer or when the merchant initiates a download from the Chargebee UI. Implementing this endpoint is MANDATORY to support document retrieval operations. ## OpenAPI ````yaml get /einvoicing/documents/{document_id}/download openapi: 3.0.0 info: description: > ## E-invoicing Service Provider Interface (SPI) - Overview Chargebee streamlines e-invoicing compliance across regions by facilitating the following operations throughout the billing lifecycle. 1) Retrieve E-invoicing Activations: - Retrieves the list of country and network activations that are configured in the connected e-invoicing provider platform. - Each activation reflects a country and e-invoicing network that has been set up and made available by the provider. - Chargebee uses this operation during provider enablement to determine which activations can be offered to merchants. 2) Document Submission: - Submits invoices and credit notes to external e-invoicing systems for validation, compliance processing, and delivery to tax authorities or trading partners. 3) Status Tracking: - Supports asynchronous document lifecycle tracking through webhook notifications sent by the e-invoicing adapter. These updates reflect real-time status changes as documents move through validation, compliance, and regulatory delivery stages. - Allows on-demand status checks to retrieve the latest processing state of submitted documents, ensuring continued visibility even if webhook delivery is delayed or disrupted. 4) Final Document Retrieval: - Retrieves finalized and regulator-approved documents for archiving, auditing or customer-facing use. Chargebee leverages external e-invoicing services to execute these operations effectively. These external e-invoicing servies are the certified vendors offering APIs to handle e-invoicing compliance and document exchange with tax authorities. ## The Role of the E-invoicing Adapter App: To connect with external e-invoicing systems, Chargebee uses an E-invoicing Adapter App - a bridge that enables secure and standardized communication between Chargebee and the e-invoicing system. This communication is governed by the E-invoicing Service Provider Interface (SPI). ## Building an E-invoicing Adapter App To integrate an e-invoicing system with Chargebee, you must implement the E-invoicing SPI by developing an adapter app. This is required in the following scenarios: - As an E-invoicing Provider: - Connect your compliance platform to Chargebee so merchants can automatically submit billing documents in a regulator-approved format. - As a System Integrator: - Build a connector that bridges a third-party e-invoicing provider and Chargebee, enabling seamless integration for merchants. By implementing the E-invoicing SPI, you enable Chargebee to support global regulatory compliance through a scalable and region-agnostic architecture. title: E-Invoicing Service Provider Interface version: 1.0.0 servers: - description: Production server (replace with actual service URL) url: https://api.example.com - description: Sandbox server for testing url: https://sandbox.example.com security: - ApiKeyAuth: [] tags: - description: Operations related to e-invoicing activations name: Activations - description: Operations related to e-invoicing documents name: Documents paths: /einvoicing/documents/{document_id}/download: get: tags: - Documents summary: Download Document description: > Retrieves the document content associated with the provided documentId from the connected e-invoicing provider. A document_id by itself is not always sufficient for the provider to determine which document formats or variants to return. Chargebee includes additional query parameters — such as country, transaction_type, and model — so the adapter can accurately identify and fetch the correct document representations. If the mime_type query parameter is not provided, the adapter MUST retrieve all available document representations for the specified document_id. When a specific mime_type is supplied, the adapter MUST return only the matching representation(s). The document may be returned either as a pre-signed URL or as a direct binary stream (such as a PDF or XML file), depending on the provider’s capabilities and the SPI implementation. In Chargebee, this endpoint is called after the document has been successfully processed either to send it via email to the end customer or when the merchant initiates a download from the Chargebee UI. Implementing this endpoint is MANDATORY to support document retrieval operations. operationId: einvoicingDocumentDownload parameters: - explode: false in: path name: document_id required: true schema: type: string style: simple - description: > Optional MIME type filter for the document representation to download. When provided, the adapter MUST return only the document(s) matching this MIME type (for example, `application/xml`, `application/pdf`, or a country-specific UBL MIME type). When omitted, the adapter MUST attempt to retrieve and return all available representations for the given document_id from the underlying e-invoicing provider. explode: true in: query name: mime_type required: false schema: example: application/xml type: string style: form - description: > The ISO 3166-1 alpha-2 country code representing the country for which the e-invoicing data input fields need to be retrieved. Different countries may have varying e-invoicing requirements. explode: true in: query name: country required: true schema: example: DE type: string style: form - description: > The transaction type for which the data input fields need to be retrieved. Required fields may vary depending on the type: B2B (Business to Business), B2C (Business to Consumer), or B2G (Business to Government). explode: true in: query name: transaction_type required: true schema: enum: - B2B - B2C - B2G example: B2B type: string style: form - description: > Indicates the eInvoicing flow model that governs the document exchange and processing mechanism. Different countries adopt different models based on legal, technical, and administrative mandates. Supported values: - PEPPOL: A standardized, secure eInvoicing network enabling cross-border electronic document exchange between businesses and governments. - EINVOICE: Traditional eInvoicing model where invoices are digitally exchanged between businesses and sometimes stored. - CLEARANCE: Invoices must be pre-approved by a tax authority before they are sent to the buyer. - REPORTING: Invoices are shared with tax authorities after issuance, usually for compliance and audit purposes. - ZUGFERD: A hybrid eInvoicing format used in Germany combining PDF and XML for human and machine readability. - CTC: Continuous Transaction Controls involve real-time or near-real-time invoice validation and transmission to tax authorities. - NEMHANDEL: Denmark’s national infrastructure for eInvoicing that supports secure delivery via specific formats like OIOUBL. - FACE: Spain’s centralized system (FACe/FACeB2B) for routing invoices to government or private recipients. - VERIFACTU: Spain’s mechanism for validating and reporting sales invoices directly to the tax agency. explode: true in: query name: model required: true schema: enum: - PEPPOL - EINVOICE - CLEARANCE - REPORTING - ZUGFERD - CTC - NEMHANDEL - FACE - VERIFACTU example: PEPPOL type: string style: form - description: Type of business document. explode: true in: query name: document_type required: true schema: example: ubl-invoice type: string style: form responses: '200': content: application/json: examples: einvoice_document_download_url_response: description: >- A sample response with pre-signed S3 URL for document download. summary: Download via pre-signed URL value: document_id: DOC-20250402-0001 request_id: a3d56940-2827-4b87-a229-00d8b95cbe77 documents: - mime_type: application/xml document_url: >- https://your-bucket.s3.amazonaws.com/invoice-20250402.xml?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EXAMPLE expires_at: '2025-03-28T09:24:29.000Z' model: PEPPOL einvoice_document_download_stream_response: description: >- A sample response with Base64-encoded XML and PDF document content. summary: Download via embedded Base64 content value: document_id: DOC-20250402-0001 request_id: a3d56940-2827-4b87-a229-00d8b95cbe77 documents: - mime_type: application/xml document_content: PHh...Q0w+ expires_at: '2025-03-28T09:24:29.000Z' - mime_type: application/pdf document_content: JVBERi0xLjQKJ...CiUlRU9GCg== expires_at: '2025-03-28T09:24:29.000Z' model: PEPPOL schema: $ref: '#/components/schemas/download_document_response' description: Document downloaded successfully. '400': content: application/json: example: errors: - code: INVALID_OPERATION message: The provided mime_type is not supported for this document. help_url: https://docs.example.com/errors#INVALID_OPERATION schema: $ref: '#/components/schemas/bad_request_error_response' description: Bad Request – The request is invalid or malformed. '401': description: Unauthorized '403': description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/not_found_error_response' description: Not found '500': content: application/json: schema: $ref: '#/components/schemas/500_error_response' description: Unexpected error while processing request. components: schemas: download_document_response: example: request_id: a3d56940-2827-4b87-a229-00d8b95cbe77 documents: - mime_type: application/xml document_url: https://provider.com/downloads/invoice-20250402.xml expires_at: '2025-03-28T09:24:29.000Z' model: peppol properties: document_id: type: string request_id: type: string documents: items: $ref: '#/components/schemas/download_document_response_documents_inner' type: array model: description: > Indicates the eInvoicing flow model that governs the document exchange and processing mechanism. Different countries adopt different models based on legal, technical, and administrative mandates. Supported values: - PEPPOL: A standardized, secure eInvoicing network enabling cross-border electronic document exchange between businesses and governments. - EINVOICE: Traditional eInvoicing model where invoices are digitally exchanged between businesses and sometimes stored. - CLEARANCE: Invoices must be pre-approved by a tax authority before they are sent to the buyer. - REPORTING: Invoices are shared with tax authorities after issuance, usually for compliance and audit purposes. - ZUGFERD: A hybrid eInvoicing format used in Germany combining PDF and XML for human and machine readability. - CTC: Continuous Transaction Controls involve real-time or near-real-time invoice validation and transmission to tax authorities. - NEMHANDEL: Denmark’s national infrastructure for eInvoicing that supports secure delivery via specific formats like OIOUBL. - FACE: Spain’s centralized system (FACe/FACeB2B) for routing invoices to government or private recipients. - VERIFACTU: Spain’s mechanism for validating and reporting sales invoices directly to the tax agency. schema: type: string enum: - PEPPOL - EINVOICE - CLEARANCE - REPORTING - ZUGFERD - CTC - NEMHANDEL - FACE - VERIFACTU example: "PEPPOL" required: - document_id - documents type: object bad_request_error_response: example: errors: - code: MISSING_REQUIRED_DATA message: The request did not contain a required property 'taxAmount' help_url: https://docs.example.com/errors#MISSING_REQUIRED_PARAMETER properties: errors: items: $ref: '#/components/schemas/bad_request_error_response_errors_inner' type: array provider_interaction: $ref: >- #/components/schemas/document_submission_response_provider_interaction type: object not_found_error_response: example: errors: - code: NOT_FOUND message: The requested document is not found. help_url: https://docs.example.com/errors#INVALID_OPERATION properties: errors: description: >- A list of errors explaining why the requested resource was not found. items: $ref: '#/components/schemas/not_found_error_response_errors_inner' type: array required: - errors type: object 500_error_response: description: An unexpected error occurred while processing your request. properties: message: description: A human-readable description of the unexpected error encountered. example: An unexpected error occurred while processing your request. type: string provider_interaction: $ref: >- #/components/schemas/document_submission_response_provider_interaction required: - message download_document_response_documents_inner: properties: mime_type: description: The MIME type of the document. type: string document_url: description: >- Presigned URL to access the document. This param will be preferred if found over document_content. format: uri type: string document_content: description: Base64-encoded document content if URL is not available. format: byte type: string expires_at: description: The time until which the document URL is valid. example: '2025-03-28T09:24:29.000Z' format: date-time type: string required: - mime_type type: object bad_request_error_response_errors_inner: properties: code: description: >- The error codes classify the type of exception that occurred during processing the request. enum: - INVALID_OPERATION - SERVICE_EXCEPTION - SERVICE_UNAVAILABLE - SERVICE_LIMIT_EXCEEDED - MISSING_REQUIRED_DATA - INVALID_DATA type: string message: description: A short message describing the reason for the error. type: string help_url: description: >- The link to the documentation for more information about the error and the corrective action. format: uri type: string required: - message type: object document_submission_response_provider_interaction: description: > Captures the interaction between the adapter and the external e-invoicing provider. Includes both the outbound request details and the inbound response received from the provider. Intended for internally hosted adapters for audit and traceability of SPI transactions. example: request: body: '{}' response: status_code: 0 body: '{}' properties: request: $ref: >- #/components/schemas/document_submission_response_provider_interaction_request response: $ref: >- #/components/schemas/document_submission_response_provider_interaction_response required: - request - response type: object not_found_error_response_errors_inner: properties: code: description: Application-specific error code enum: - NOT_FOUND type: string message: description: A short message describing the reason for the error. type: string help_url: description: >- The link to the documentation for more information about the error and the corrective action. format: uri type: string required: - code - message type: object document_submission_response_provider_interaction_request: description: >- Details of the HTTP request sent by the adapter to the external provider. example: body: '{}' properties: body: description: > The request payload sent to the provider API, typically serialized as JSON. This should exclude any sensitive or personally identifiable information. type: object type: object document_submission_response_provider_interaction_response: description: Details of the HTTP response received from the external provider. example: status_code: 0 body: '{}' properties: status_code: description: The HTTP status code returned by the provider. type: integer body: description: | The response body returned by the provider. type: object type: object securitySchemes: ApiKeyAuth: in: header name: Authorization type: apiKey ````