> 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/sftp-integration/sftp-integration.md). # SFTP Integration The SFTP setup is done by our helpdesk, and you will require a Qvalia account prior to being able to test the SFTP integration. Qvalia hosts an SFTP Server, and both sending and receiving is done through an SFTP client from your environment. ## Custom format "Custom format" means we can add a transformation for your required format both for outbound (sending) and inbound (receiving) documents. For example, if you use SAP IDoc we can transform incoming Peppol XML to SAP IDoc for you and you'd pick up the ready-made SAP format from our SFTP. Likewise, if you are using outbound, you can upload your SAP IDoc and we will transform it for you. As long as you have structured data we can add a custom format for you, and handle anything you send to us, as long as it is possible to transform into Peppol BIS 3 format. Any custom type message must be uploaded to the `/custom` subdirectory on the SFTP, e.g. `/send/custom/` ## Sending and receiving using SFTP Any inbound (receiving) documents will be uniquely named according to a predefined format including, e.g., the document date and document number, and place in the root directory of your SFTP account. ### Receiving (inbound messages) We recommend that you follow the common SFTP renaming standards for downloading received files to avoid downloading duplicates in case connection would be interrupted: * Connect to the SFTP server * List files * Start processing file list by: * Rename the first file in the list to `{original-filename}.downloading` * Start download of `{original-filename}.downloading` * Once download is completed, delete `{original-filename}.downloading` from SFTP Server * Rename `{original-filename}.downloading` locally back to `{original-filename}` #### Receive Consolidation If you have multiple accounts set up with us, but want to handle all SFTP communication in one and the same account you can use “consolidation”. Helpdesk can help you setting up SFTP Consolidation! ``` [dir] .. ACCNT1_Order_msg_1.xml ACCNT2_Invoice_msg_1.xml ACCNT3_OrderResponse_msg_1.xml ``` ### Sending (outbound messages) Outbound (sending) documents from you to your business party must be uploaded by you to the sub-directory named `/send`. The `send` directory is created automatically for you when you opt for the outbound functionality from Qvalia. {% hint style="warning" %} When you are uploading files to the Qvalia SFTP you **must** upload them with the original filename and extension, e.g. `my_outbound_invoice01.xml` I.e. you may not upload using a temporary filename and then rename the file after it has been uploaded! {% endhint %} #### Dynamic Routing We can utilize “dynamic routing” to determine how to best deliver the message (only supported for Invoice and CreditNote). {% hint style="info" %} You must contact Helpdesk prior to using dynamic routing! {% endhint %} ``` /send/dynamic_routing/ ``` The message will be inspected to find the delivery information according to your account setup (which you will receive from Helpdesk). The fall-back for dynamic routing is always to print the message and send as a letter. #### Custom Routing If you have opted for a custom transformation of messages from Qvalia you will be using the `/custom` directory to upload to. You will receive further instructions from the Qvalia onboarding team on how to handle and package your files. {% hint style="info" %} You must contact Helpdesk prior to using custom routing! {% endhint %} ``` /send/custom/ ``` #### Processed files Once the processing is completed the file will be moved, and renamed, in a sub-directory called `/processed`, meaning you will find your already processed files in `/send/processed/{original-filename}.processed`. When, and if, you remove (delete) the files form `/processed` is up to you but please note that some SFTP clients can't read too large file lists why we recommend emptying the `/processed` sub-directory at a set interval, depending on the number of files you send. #### Consolidation If you have multiple accounts set up with us, but want to handle all SFTP communication in one and the same account you can use “consolidation”. Helpdesk can help you setting up SFTP Consolidation! ``` [dir] .. ACCNT1_Order_msg_1.xml ACCNT2_Invoice_msg_1.xml ACCNT3_OrderResponse_msg_1.xml ``` For your outgoing messages, you can either opt for file naming, or use subdirectories, for sending over a consolidated account. ``` [dir] .. send/ consolidation.ACCNT1.Order1.xml consolidation.ACCNT3.Invoice1.xml ``` ``` [dir] .. send/ ACCNT1/ Order1.xml ACCNT3/ Invoice1.xml ``` ## Error handling When you upload your outbound documents and they should happen to be faulty in some way (e.g. invalid Peppol XML) the file uploaded will be renamed to `{original-filename}.{error type}.error`. It is up to you to download and inspect any `.error` file that will remain on your SFTP area. We never delete `.error` files, so they'll remain in your `/send` directory until you delete them yourself. The error types are * **\*.invalid\_messagetype.error** * A file that we cannot recognize and/or handle. It can also be a zero byte (empty) file. * **\*.validation.error** * The uploaded file is invalid Peppol BIS 3 * **\*.peppol\_recipient.error** * The recipient of the Peppol message is not registered in the Peppol network, or does not accept the uploaded message type * **\*.unknown\_internal.error** * It's on us, not you; We couldn't handle the file for some reason * **\*.envelope\_missing.error** (Svefaktura, Finvoice only!) * We need the SBD envelope with sender and recipient details in the SBDH * **\*.unsupported\_messagetype.error** * The uploaded ZIP archive contains invalid files * **\*.mixed\_messagetypes.error** * The uploaded ZIP archive, or envelope, contains multiple types of files * **\*.invalid\_type.error** * The uploaded data is not supported by the chosen delivery method * **\*.invalid\_path.error** * The file has been uploaded in a directory we do not actively handle --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://api.qvalia.io/sftp-integration/sftp-integration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.