> For the complete documentation index, see [llms.txt](https://api.qvalia.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.qvalia.io/api-documentation/apis/transaction-api/document-upload-apis.md). # Document Upload APIs Send invoices and credit notes in formats other than Peppol BIS, and download them in those formats ## Upload an outgoing invoice or credit note in another format > Send an invoice or credit note in a format other than Peppol BIS. Qvalia converts it to\ > Peppol BIS Billing 3.0, and from there it is handled exactly like a \`POST\` to\ > \`/invoices/outgoing\` or \`/creditnotes/outgoing\`: the same validation, the same duplicate\ > check (\`409\`, or \`overwrite=true\` to send it again) and the same \`delivery\_method\`.\ > \ > Qvalia stores the converted Peppol document. The format you uploaded is remembered, so\ > \`GET /transaction/{accountRegNo}/document/download\` gives the document back in that format.\ > Svefaktura 1.0 and EDIFACT are the exceptions, downloaded as Peppol BIS by default: Svefaktura\ > 1.0 can be uploaded but not produced, and EDIFACT is only produced as INVOIC D.96A (EANCOM\ > 1997\), which may not be the version you uploaded. Ask for \`format=edifact\` to get the D.96A.\ > \ > \*\*Need another format?\*\* We add formats on request: another e-invoice standard, another\ > EDIFACT subset or trading partner guide, a national format, or a customer's or ERP system's\ > own format. Contact with a few sample documents.\ > \ > \| \`format\` | What to send |\ > \| --- | --- |\ > \| \`svefaktura1\` | Svefaktura 1.0 XML |\ > \| \`xrechnung\` | XRechnung, in either UBL or CII syntax |\ > \| \`cii\` | UN/CEFACT Cross Industry Invoice (EN 16931) XML |\ > \| \`zugferd\`, \`facturx\` | The CII XML of a ZUGFeRD or Factur-X invoice. The PDF itself is not accepted: send the XML embedded in it. |\ > \| \`edifact\` | A UN/EDIFACT INVOIC message: an invoice, or a credit note (BGM 381, 383 or 396). Directory versions D.93A to D.16B are accepted, including EANCOM 1997 (D.96A) and EANCOM 2002 (D.01B). Send one message per upload, UTF-8 encoded, as \`application/edifact\` or \`text/plain\`. |\ > \| \`cxml\` | A cXML \`InvoiceDetailRequest\`, as SAP Ariba and Coupa use it: an invoice, or a credit memo (\`purpose="creditMemo"\` or \`"lineLevelCreditMemo"\`), as \`application/xml\`. cXML carries no Peppol participant ids, so give them with \`receivingPeppolId\` / \`sendingPeppolId\` unless the document has them, and an invoice without a purchase order needs \`buyerReference\`. |\ > \| \`finvoice3\` | Finvoice 3.0 (Finland): an invoice or a credit note, as \`application/xml\`. |\ > \ > A document that cannot be converted, or that is not valid Peppol BIS once converted, is\ > answered with \`422\` and the reason.\ > \ > \`sendingPeppolId\` and \`receivingPeppolId\` set the sender's and receiver's Peppol participant\ > IDs, whatever the document says. Use them for a format with no Peppol address (Svefaktura,\ > often EDIFACT), or to send to another participant than the one in the document. For a CII\ > document, the kept original gets the same IDs, so the original CII is no longer byte for\ > byte what was uploaded.\ > \ > For EDIFACT, give each party an identifier with its scheme, because Peppol routes on it.\ > A GLN (\`NAD+BY+7300000000000::9\`) becomes scheme 0088. Another scheme can be given as its\ > ISO 6523 code in the code list qualifier, for example \`NAD+BY+5599000295:0007\` for a\ > Swedish organisation number. Without one, a Swedish, Norwegian or Danish party's\ > organisation number is read from its VAT number (\`RFF+VA\`). Totals, the VAT breakdown and\ > line amounts that the message leaves out are calculated by the EN 16931 rules.\ > \ > If you upload XML without an \`Accept\` header, the response is XML, as for any XML \`POST\`.\ > Send \`Accept: application/json\` to get the JSON response instead. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Transaction API","version":"1.0.0"},"tags":[{"name":"Document Upload APIs","description":"Send invoices and credit notes in formats other than Peppol BIS, and download them in those formats"}],"servers":[{"url":"https://api-test.qvalia.com"},{"url":"https://api.qvalia.com"}],"security":[{"api_key":[]},{"jwt":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","name":"Authorization","in":"header"},"jwt":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT-based authentication. The Authorization header must be set as:\nAuthorization: Bearer \nObtain a token via POST /token/{accountRegNo} (see Authentication API).\n"}},"parameters":{"accountRegNo":{"name":"accountRegNo","in":"path","required":true,"schema":{"type":"string","description":"","default":""},"description":"Account registration number issued by Qvalia"},"uploadType":{"name":"type","in":"query","required":true,"schema":{"type":"string","enum":["invoice","creditnote"]},"description":"The kind of document you upload."},"uploadFormat":{"name":"format","in":"query","required":true,"schema":{"type":"string","enum":["svefaktura1","xrechnung","cii","zugferd","facturx","edifact","cxml","finvoice3"]},"description":"The format of the document you upload. See the endpoint description for what each one takes."},"deliveryMethod":{"name":"delivery_method","in":"query","required":false,"schema":{"type":"string","default":"peppol","enum":["peppol","email","postal","edi","internetbank","kivra","billo","minameddelanden","finvoice","dynamic_routing"]},"description":"How the document reaches the receiver. Leave it out to send over Peppol.\n\nTaken only on `POST /invoices/outgoing`, `POST /creditnotes/outgoing` and `POST /document/upload`.\nAny other endpoint (an incoming document, an order, …) answers `400` when it is given.\n\nDelivery methods must be added to your account before you can use them, except for `peppol`, which\nis the default and always enabled. Using a method outside your agreement results in a\n`403 Forbidden` error naming the refused delivery method. Contact your Qvalia sales representative,\nor Qvalia sales, to add delivery methods to your agreement.\n\n- `peppol`: over the Peppol network. The receiver must be registered in Peppol.\n- `email`: needs the buyer's e-mail address in\n `AccountingCustomerParty > Party > Contact > ElectronicMail`.\n- `postal`: printed and posted. Needs the buyer's name and a complete postal address in\n `AccountingCustomerParty > Party > PostalAddress`.\n- `internetbank`, `kivra`, `billo`, `minameddelanden`: to a consumer. Needs a Swedish\n personal number (`[YY]YYMMDD[-]nnnn`) or an FMI address (`[YY]YYMMDDnnnn..SE`) in\n `AccountingCustomerParty > Party > PartyIdentification`.\n- `edi`: over EDI, as agreed with Qvalia for your account.\n- `finvoice`: as Finvoice (3.0, or 2 if your account is set up for it), over the Finnish e-invoicing\n network through Qvalia's Finnish operator partner. Needs the buyer's Finnish business ID or OVT code.\n- `dynamic_routing`: Qvalia chooses the channel for each receiver, from your account's\n set-up and how the receiver can be reached: Peppol, a digital mailbox or internet bank,\n e-mail or print.\n\nA document missing what its delivery method needs is answered with `422`.\n\nWhatever the delivery method, the document is validated as Peppol BIS Billing 3.0. Only\n`peppol`, or no `delivery_method`, also checks that the receiver is registered in Peppol,\nso you can send to a receiver outside Peppol with any other method.\n\nAccepted on outgoing invoices and credit notes."},"overwrite":{"name":"overwrite","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"For POST requests, chose to overwrite upon a `409 Conflict` response to reprocess the message with the same document ID and receiver (i.e. send the same message again)"},"validateOnly":{"name":"validateOnly","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Convert and validate the document without storing or sending it. The response is the\nPeppol validation result: `200` when the converted document is valid, `422` when it is not."},"sendingPeppolId":{"name":"sendingPeppolId","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{4}:[a-zA-Z0-9._-]{4,}$"},"description":"The sender's Peppol participant ID, `:`. It replaces the seller's\nelectronic address in the document (BT-34, `cbc:EndpointID` in the converted Peppol\ndocument, and the seller's `ram:URIID` in a CII original). Use it when the uploaded\nformat has no Peppol address, or a different one."},"receivingPeppolId":{"name":"receivingPeppolId","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{4}:[a-zA-Z0-9._-]{4,}$"},"description":"The receiver's Peppol participant ID, `:`. It replaces the buyer's\nelectronic address in the document (BT-49), which is where the document is sent over\nPeppol. The receiver must be registered on Peppol for the document type, as for any\noutgoing document."},"uploadBuyerReference":{"name":"buyerReference","in":"query","required":false,"schema":{"type":"string","maxLength":200},"description":"The buyer reference (BT-10) for a `cxml` upload. A cXML invoice without a purchase order carries none,\nand Peppol BIS then requires one."},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w.:@+-]+$"},"description":"Optional. Send a unique value you generate per submission (a UUID is recommended!)\nand a repeat of the same request returns the original response, with the original\n`integrationId`, instead of creating a second document.\n\nThis is what makes a submission safe to retry after a timeout: if the connection\nbreaks after we accept the POST but before the response reaches you, repeating it\nwith the same key tells you whether the document was created, without a\nreconciling `GET`.\n\n- Same key, same body, request finished: the original response is replayed.\n- Same key, same body, original still in flight: `409`.\n- Same key, different body: `400`.\n- Key older than 24 hours: treated as new.\n\nA request that fails releases its key, so you can retry the same key after an\nerror. Keys are scoped to your account."}},"requestBodies":{"documentUpload":{"description":"The document in the format named by `format`, as the raw document: XML as XML, not wrapped\nin JSON.","required":true,"content":{"application/xml":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"}},"application/edifact":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object"}}}}},"responses":{"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized. Returned when the API key or Bearer token is missing, malformed\nor not valid for the account in the URI.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden. The credentials are valid, but the account is not permitted to\nperform this action — typically because the required integration feature or\nscope is not enabled on the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":""},"type":{"type":"string","description":""},"data":{"type":"string","description":"Human-readable reason the submission was rejected."},"metadata":{"type":"object","description":"","properties":{"integrationId":{"type":"string","format":"uuid","description":"The document this submission collided with. Present on a duplicate\nrejection, so you can reconcile the submission against the document\nalready stored without a follow-up `GET` — this is the same id the\noriginal, successful submission returned.\n\nRe-submit with `overwrite=true` if you intend to replace it. To avoid\nthe duplicate in the first place, send an `Idempotency-Key`."},"debug_error_message":{"type":"string","description":""},"debug_error_code":{"type":"integer","description":""}}}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":""},"type":{"type":"string","description":""},"data":{"type":"string","description":""},"metadata":{"type":"object","description":"","properties":{"description":{"type":"string","description":""},"details":{"type":"object","description":"","properties":{}}}}}}}}},"500":{"description":"Internal Server Error. `metadata` is deliberately omitted on a 500 — no\ninternal detail is returned. Try again; if the problem persists contact\nhelp@qvalia.com.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"type":{"type":"string"},"data":{"type":"string"}}}}}},"200-post":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/transactionPostResponse"}},"application/xml":{"schema":{"$ref":"#/components/schemas/transactionPostResponseXML"}}}},"TooManyRequests":{"description":"Too Many Requests. The account has exceeded its request budget, which is counted\nper account across all Qvalia APIs.\n\nRead `Retry-After` and wait at least that many seconds before retrying — retrying\nimmediately is simply rejected again. `RateLimit-Remaining` on every response tells\nyou how much of the budget is left, so a well-behaved client need not hit this at\nall. Contact [Qvalia Helpdesk](https://qvalia.com/help/) if your integration needs\na higher limit.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"transactionPostResponse":{"type":"object","properties":{"status":{"type":"string"},"data":{"type":"object","properties":{"message":{"type":"string","description":"Confirmation message. Names the transaction type of the endpoint\nyou called, e.g. `Invoice 100-1000 sent`."},"integrationId":{"type":"string"}},"additionalProperties":{"type":"string","description":"The submitted document's own identifier, under a key named after the\ntransaction type of the endpoint you called — `invoice_id` for\n`/invoices/...`, `creditnote_id` for `/creditnotes/...`, and so on."}}},"xml":{"name":"success"}},"transactionPostResponseXML":{"type":"object","properties":{"message":{"type":"string","description":"Confirmation message. Names the transaction type of the endpoint you\ncalled, e.g. `Invoice 100-1000 sent`."},"integrationId":{"type":"string"}},"additionalProperties":{"type":"string","description":"The submitted document's own identifier, under a key named after the\ntransaction type of the endpoint you called, e.g. `invoice_id`."},"xml":{"name":"success"}},"Error":{"type":"object","description":"Every error returned by the Qvalia APIs uses this envelope. `type` is a\nstable machine-readable code — branch on it rather than on `data`, which is\na human-readable message whose wording may change.","properties":{"status":{"type":"string","description":"Always `error` on a failed request."},"type":{"type":"string","description":"Stable error code. One of `E_BAD_REQUEST` (400),\n`E_UNAUTHORIZED_CLIENT` / `E_CLIENT_UNSUCCESSFUL_AUTHENTICATION` (401),\n`E_MISSING_PERMISSION` (403), `E_MISSING` (404), `E_CONFLICT` (409),\n`E_VALIDATION` / `E_PEPPOL_PARTICIPANT_SMP_LOOKUP` (422),\n`E_RATE_LIMITED` (429), `E_NOT_IMPLEMENTED` (501) or\n`E_INTERNAL_PROXY_ERROR` (500)."},"data":{"type":"string","description":"Human-readable description of what went wrong."},"metadata":{"type":"object","description":"Additional detail about the failure. The shape varies by error type — a `429`\ncarries `limit` and `retryAfterSeconds`, a `409` carries the colliding\n`integrationId` — and it is omitted entirely on a `500`. Treat it as an open\nmap and read only the keys you need.","additionalProperties":true,"properties":{"debug_error_message":{"type":"string","description":"Longer explanation intended for a developer reading a log."},"debug_error_code":{"type":"integer","description":"Echoes the HTTP status code."}}}}}}},"paths":{"/transaction/{accountRegNo}/document/upload":{"post":{"tags":["Document Upload APIs"],"summary":"Upload an outgoing invoice or credit note in another format","description":"Send an invoice or credit note in a format other than Peppol BIS. Qvalia converts it to\nPeppol BIS Billing 3.0, and from there it is handled exactly like a `POST` to\n`/invoices/outgoing` or `/creditnotes/outgoing`: the same validation, the same duplicate\ncheck (`409`, or `overwrite=true` to send it again) and the same `delivery_method`.\n\nQvalia stores the converted Peppol document. The format you uploaded is remembered, so\n`GET /transaction/{accountRegNo}/document/download` gives the document back in that format.\nSvefaktura 1.0 and EDIFACT are the exceptions, downloaded as Peppol BIS by default: Svefaktura\n1.0 can be uploaded but not produced, and EDIFACT is only produced as INVOIC D.96A (EANCOM\n1997), which may not be the version you uploaded. Ask for `format=edifact` to get the D.96A.\n\n**Need another format?** We add formats on request: another e-invoice standard, another\nEDIFACT subset or trading partner guide, a national format, or a customer's or ERP system's\nown format. Contact help@qvalia.com with a few sample documents.\n\n| `format` | What to send |\n| --- | --- |\n| `svefaktura1` | Svefaktura 1.0 XML |\n| `xrechnung` | XRechnung, in either UBL or CII syntax |\n| `cii` | UN/CEFACT Cross Industry Invoice (EN 16931) XML |\n| `zugferd`, `facturx` | The CII XML of a ZUGFeRD or Factur-X invoice. The PDF itself is not accepted: send the XML embedded in it. |\n| `edifact` | A UN/EDIFACT INVOIC message: an invoice, or a credit note (BGM 381, 383 or 396). Directory versions D.93A to D.16B are accepted, including EANCOM 1997 (D.96A) and EANCOM 2002 (D.01B). Send one message per upload, UTF-8 encoded, as `application/edifact` or `text/plain`. |\n| `cxml` | A cXML `InvoiceDetailRequest`, as SAP Ariba and Coupa use it: an invoice, or a credit memo (`purpose=\"creditMemo\"` or `\"lineLevelCreditMemo\"`), as `application/xml`. cXML carries no Peppol participant ids, so give them with `receivingPeppolId` / `sendingPeppolId` unless the document has them, and an invoice without a purchase order needs `buyerReference`. |\n| `finvoice3` | Finvoice 3.0 (Finland): an invoice or a credit note, as `application/xml`. |\n\nA document that cannot be converted, or that is not valid Peppol BIS once converted, is\nanswered with `422` and the reason.\n\n`sendingPeppolId` and `receivingPeppolId` set the sender's and receiver's Peppol participant\nIDs, whatever the document says. Use them for a format with no Peppol address (Svefaktura,\noften EDIFACT), or to send to another participant than the one in the document. For a CII\ndocument, the kept original gets the same IDs, so the original CII is no longer byte for\nbyte what was uploaded.\n\nFor EDIFACT, give each party an identifier with its scheme, because Peppol routes on it.\nA GLN (`NAD+BY+7300000000000::9`) becomes scheme 0088. Another scheme can be given as its\nISO 6523 code in the code list qualifier, for example `NAD+BY+5599000295:0007` for a\nSwedish organisation number. Without one, a Swedish, Norwegian or Danish party's\norganisation number is read from its VAT number (`RFF+VA`). Totals, the VAT breakdown and\nline amounts that the message leaves out are calculated by the EN 16931 rules.\n\nIf you upload XML without an `Accept` header, the response is XML, as for any XML `POST`.\nSend `Accept: application/json` to get the JSON response instead.","operationId":"document-upload-apis/post-document-upload","parameters":[{"$ref":"#/components/parameters/accountRegNo"},{"$ref":"#/components/parameters/uploadType"},{"$ref":"#/components/parameters/uploadFormat"},{"$ref":"#/components/parameters/deliveryMethod"},{"$ref":"#/components/parameters/overwrite"},{"$ref":"#/components/parameters/validateOnly"},{"$ref":"#/components/parameters/sendingPeppolId"},{"$ref":"#/components/parameters/receivingPeppolId"},{"$ref":"#/components/parameters/uploadBuyerReference"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"$ref":"#/components/requestBodies/documentUpload"},"responses":{"200":{"$ref":"#/components/responses/200-post"},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"409":{"$ref":"#/components/responses/409"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/500"}}}}}} ``` ## Download an outgoing invoice or credit note in another format > Get one of your outgoing invoices or credit notes in the format you choose. Qvalia stores\ > every document as Peppol BIS and converts it when you download it.\ > \ > Without \`format\`, you get the document back in the format it was uploaded in through\ > \`POST /transaction/{accountRegNo}/document/upload\` (except Svefaktura 1.0 and EDIFACT, which\ > come back as Peppol BIS). A document that was sent as CII comes back as the original CII. A document that was sent as Peppol comes back as Peppol BIS XML.\ > \ > The response is the document itself, without the usual \`status\`/\`data\` envelope:\ > \- The XML formats are returned as XML (\`application/xml\`).\ > \- \`edifact\` is returned as an EDIFACT interchange (\`application/edifact\`, UTF-8).\ > \- \`zugferd\` and \`facturx\` are PDFs. They are returned as JSON (\`application/json\`):\ > \`{ "filename", "mimeType", "content" }\`, with the PDF base64-encoded in \`content\`.\ > \ > The document must meet the chosen format's own rules. For example, XRechnung needs a\ > Leitweg-ID (BT-10, \`BuyerReference\`). If it does not, the answer is \`422\` with what is\ > missing.\ > \ > Downloading does not mark the document as read.\ > \ > \*\*Need another format?\*\* We add formats on request. Contact . ```json {"openapi":"3.0.2","info":{"title":"Qvalia Transaction API","version":"1.0.0"},"tags":[{"name":"Document Upload APIs","description":"Send invoices and credit notes in formats other than Peppol BIS, and download them in those formats"}],"servers":[{"url":"https://api-test.qvalia.com"},{"url":"https://api.qvalia.com"}],"security":[{"api_key":[]},{"jwt":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","name":"Authorization","in":"header"},"jwt":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT-based authentication. The Authorization header must be set as:\nAuthorization: Bearer \nObtain a token via POST /token/{accountRegNo} (see Authentication API).\n"}},"parameters":{"accountRegNo":{"name":"accountRegNo","in":"path","required":true,"schema":{"type":"string","description":"","default":""},"description":"Account registration number issued by Qvalia"},"downloadType":{"name":"type","in":"query","required":true,"schema":{"type":"string","enum":["invoice","creditnote"]},"description":"The kind of document to download."},"downloadIntegrationId":{"name":"integrationId","in":"query","required":true,"schema":{"type":"string","format":"uuid"},"description":"The document's `integrationId`, as returned when it was sent (or uploaded). Only your\nown outgoing documents can be downloaded. Any other id is answered with `404`."},"downloadFormat":{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["peppol","xrechnung","xrechnungcii","cii","zugferd","facturx","finvoice2","finvoice3","cxml","edifact"]},"description":"The format to download the document in. Leave it out to get the format it was uploaded\nin, or Peppol BIS XML for a document that was sent as Peppol.\n\n| `format` | You get |\n| --- | --- |\n| `peppol` | Peppol BIS Billing 3.0 UBL XML, as Qvalia stores it |\n| `xrechnung` | XRechnung, UBL syntax |\n| `xrechnungcii` | XRechnung, CII syntax |\n| `cii` | UN/CEFACT Cross Industry Invoice (EN 16931) XML. For a document sent as CII, the original as it was sent. |\n| `zugferd`, `facturx` | A ZUGFeRD / Factur-X PDF/A-3 with the CII XML embedded, as JSON (see the response) |\n| `finvoice2` | Finvoice 2 XML. Invoices only: a credit note is answered with `400`. |\n| `finvoice3` | Finvoice 3.0 XML, an invoice or a credit note. |\n| `cxml` | A cXML `InvoiceDetailRequest`; a credit note as a credit memo (`purpose=\"creditMemo\"`). |\n| `edifact` | A UN/EDIFACT INVOIC D.96A, EANCOM 1997 (`EAN008`) interchange: one message, UTF-8 (UNOC). A credit note has BGM 381. |"}},"responses":{"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized. Returned when the API key or Bearer token is missing, malformed\nor not valid for the account in the URI.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden. The credentials are valid, but the account is not permitted to\nperform this action — typically because the required integration feature or\nscope is not enabled on the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":""},"type":{"type":"string","description":""},"data":{"type":"string","description":""},"metadata":{"type":"object","description":"","properties":{"description":{"type":"string","description":""},"details":{"type":"object","description":"","properties":{}}}}}}}}},"500":{"description":"Internal Server Error. `metadata` is deliberately omitted on a 500 — no\ninternal detail is returned. Try again; if the problem persists contact\nhelp@qvalia.com.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"type":{"type":"string"},"data":{"type":"string"}}}}}},"documentDownload":{"description":"The document in the requested format, without the usual response envelope. The XML formats\nare returned as XML, `edifact` as EDIFACT; `zugferd` and `facturx` as JSON carrying the PDF.","content":{"application/xml":{"schema":{"type":"string","description":"The document, e.g. an XRechnung or Finvoice XML."}},"application/edifact":{"schema":{"type":"string","description":"The EDIFACT INVOIC D.96A interchange (`edifact`)."}},"application/json":{"schema":{"type":"object","description":"A PDF format (`zugferd`, `facturx`).","properties":{"filename":{"type":"string"},"mimeType":{"type":"string"},"content":{"type":"string","format":"byte","description":"The PDF, base64-encoded. Truncated in this example."}}}}}},"TooManyRequests":{"description":"Too Many Requests. The account has exceeded its request budget, which is counted\nper account across all Qvalia APIs.\n\nRead `Retry-After` and wait at least that many seconds before retrying — retrying\nimmediately is simply rejected again. `RateLimit-Remaining` on every response tells\nyou how much of the budget is left, so a well-behaved client need not hit this at\nall. Contact [Qvalia Helpdesk](https://qvalia.com/help/) if your integration needs\na higher limit.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","description":"Every error returned by the Qvalia APIs uses this envelope. `type` is a\nstable machine-readable code — branch on it rather than on `data`, which is\na human-readable message whose wording may change.","properties":{"status":{"type":"string","description":"Always `error` on a failed request."},"type":{"type":"string","description":"Stable error code. One of `E_BAD_REQUEST` (400),\n`E_UNAUTHORIZED_CLIENT` / `E_CLIENT_UNSUCCESSFUL_AUTHENTICATION` (401),\n`E_MISSING_PERMISSION` (403), `E_MISSING` (404), `E_CONFLICT` (409),\n`E_VALIDATION` / `E_PEPPOL_PARTICIPANT_SMP_LOOKUP` (422),\n`E_RATE_LIMITED` (429), `E_NOT_IMPLEMENTED` (501) or\n`E_INTERNAL_PROXY_ERROR` (500)."},"data":{"type":"string","description":"Human-readable description of what went wrong."},"metadata":{"type":"object","description":"Additional detail about the failure. The shape varies by error type — a `429`\ncarries `limit` and `retryAfterSeconds`, a `409` carries the colliding\n`integrationId` — and it is omitted entirely on a `500`. Treat it as an open\nmap and read only the keys you need.","additionalProperties":true,"properties":{"debug_error_message":{"type":"string","description":"Longer explanation intended for a developer reading a log."},"debug_error_code":{"type":"integer","description":"Echoes the HTTP status code."}}}}}}},"paths":{"/transaction/{accountRegNo}/document/download":{"get":{"tags":["Document Upload APIs"],"summary":"Download an outgoing invoice or credit note in another format","description":"Get one of your outgoing invoices or credit notes in the format you choose. Qvalia stores\nevery document as Peppol BIS and converts it when you download it.\n\nWithout `format`, you get the document back in the format it was uploaded in through\n`POST /transaction/{accountRegNo}/document/upload` (except Svefaktura 1.0 and EDIFACT, which\ncome back as Peppol BIS). A document that was sent as CII comes back as the original CII. A document that was sent as Peppol comes back as Peppol BIS XML.\n\nThe response is the document itself, without the usual `status`/`data` envelope:\n- The XML formats are returned as XML (`application/xml`).\n- `edifact` is returned as an EDIFACT interchange (`application/edifact`, UTF-8).\n- `zugferd` and `facturx` are PDFs. They are returned as JSON (`application/json`):\n `{ \"filename\", \"mimeType\", \"content\" }`, with the PDF base64-encoded in `content`.\n\nThe document must meet the chosen format's own rules. For example, XRechnung needs a\nLeitweg-ID (BT-10, `BuyerReference`). If it does not, the answer is `422` with what is\nmissing.\n\nDownloading does not mark the document as read.\n\n**Need another format?** We add formats on request. Contact help@qvalia.com.","operationId":"document-upload-apis/get-document-download","parameters":[{"$ref":"#/components/parameters/accountRegNo"},{"$ref":"#/components/parameters/downloadType"},{"$ref":"#/components/parameters/downloadIntegrationId"},{"$ref":"#/components/parameters/downloadFormat"}],"responses":{"200":{"$ref":"#/components/responses/documentDownload"},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/500"}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://api.qvalia.io/api-documentation/apis/transaction-api/document-upload-apis.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.