# KSeF KSeF integration with Ritevo: connecting with a KSeF certificate, sending invoices and corrections online, the KSeF number, reconnecting. The KSeF integration sends invoices and corrections issued in Ritevo to KSeF, the Polish National e-Invoicing System. You connect it with a KSeF certificate, and invoices go to KSeF in online mode. > **Required integration:** You need the company's NIP (Polish tax ID) and a KSeF authentication certificate: the private key file (.key), the password to that key and the certificate file (.pem or .crt). You can add as many KSeF integrations as you like, including several for the same account - for example with different details or different document settings. Each works on its own. Uniqueness is not checked, on purpose: every create call makes a new integration, also for the same `externalId`, so one account can have several integrations with different details or settings. `externalId` is the NIP. You provide a new certificate with `PUT /integrations/accountings/ksef/{id}/certificate` - in any state of the integration. After a successful KSeF sign-in it sets `authError=false` and `active=true`. ## Which documents it sends - **VAT invoice** (API: "VAT invoice" = `INVOICE`; value in `billingType`) - goes to KSeF as a basic invoice. - **Invoice correction** (API: "Invoice correction" = `CORRECTION`; value in `billingType`) - goes to KSeF as a corrective invoice. - **Receipt** (API: "Receipt" = `RECEIPT`; value in `billingType`) - not supported. ## How to get a KSeF certificate You generate the certificate in Aplikacja Podatnika KSeF, the Ministry of Finance's KSeF taxpayer application. The private key password cannot be recovered, so keep it together with both files - you will enter them in Ritevo when adding the integration. If you lose the password or the key file, the only way out is to generate a new certificate with a new key pair. 1. Sign in to Aplikacja Podatnika KSeF, for example with Profil Zaufany (the Polish trusted profile). 2. In the certificates section choose **Wnioskuj o certyfikat** (request a certificate). 3. Choose the authentication certificate, enter its name and set the private key password. 4. Click **Generuj** (generate). The private key file (.key) is saved on your computer. 5. Once the request is approved, download the certificate file (.crt). ## Connecting the account Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Accounting** section pick the **KSeF** tile. 3. In the **Account name** field enter your own name for the integration, and in the **Nip** field the NIP of the company you issue invoices for. 4. Add the **Private key file (.key)**, enter the **Key password** and add the **Certificate file (.pem/.crt)**. 5. Click **Create integration**. We sign in to KSeF with the certificate right away: if it works, the integration is added and its settings open. If not - you will see an error and nothing is saved. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the KSeF tile framed in the Accounting section](https://ritevo.com/docs/integrations/ksef/en-catalogue.webp) ![The KSeF add-integration screen with the Account name and Nip fields, the certificate files and the key password](https://ritevo.com/docs/integrations/ksef/en-add.webp) ## Integration settings On the integration page you will find: - **Invoices are sent in online mode** - every invoice goes to KSeF as soon as you send it. - **Account name** - your own name for the integration. You change it and save it with **Update integration**. - **Update credentials** - you enter new files and a password, for example when the certificate is about to expire. We check them in KSeF the same way as when adding. Creating: `accountName`, `nip`, `certificateBase64` (the .key file in Base64), `certificatePassword` and `certificatePemBase64` (the .pem or .crt file in Base64). You change the name with `PATCH /integrations/accountings/ksef/{id}` with `accountName`, and the certificate with `PUT /integrations/accountings/ksef/{id}/certificate` with the same three certificate fields. ![KSeF integration details: the online mode note, the account name and the Update credentials button](https://ritevo.com/docs/integrations/ksef/en-details.webp) ## Sending documents > **Good to know:** One order can have only one active invoice and one active receipt. You issue another document of the same type only after deleting the previous one. You can issue any number of corrections to an invoice. You issue documents in the order. You send them to KSeF in two ways: - **By hand** - in the document details, in the **External accounting systems** card, click the button with the KSeF account name. The button shows up only on documents this integration supports. - **Automatically** - with the **Send invoice to external accounting** or **Send receipt to external accounting** step in [order actions](https://ritevo.com/en/docs/automations/order-actions). Plan sending documents step by step - first issuing, then sending: - **Invoice** - the first action ends with the **Generate invoice** step. The second starts on the **Invoice (added/removed)** trigger, has the **Has invoice** condition and the **Send invoice to external accounting** step. - **Receipt** - the same: the first action ends with the **Generate receipt** step, and the second starts on the **Receipt (added/removed)** trigger, has the **Has receipt** condition and the **Send receipt to external accounting** step. - **Corrections** - you can issue many corrections to one invoice. Send each right after issuing it, before you issue the next one. > **Good to know:** The send step always sends just one document - the newest non-deleted one of that type. If you first issue all documents and only then turn on sending, only the last one goes out, and you send the others by hand. You cannot send a deleted document. In the same card every sending has its own icon. Hover over it to see the account, the state and the date: - **Sending** (API: "Sending" = `PENDING`; value in `externalTransfers[].status`) - the document is sent and we are waiting for KSeF to confirm it. - **Sent successfully** (API: "Sent successfully" = `SUCCESS`; value in `externalTransfers[].status`) - the document is in KSeF. Click the icon to download or open it. - **Sending failed** (API: "Sending failed" = `FAILED`; value in `externalTransfers[].status`) - the document did not reach KSeF. The reason is shown under the state. > **Good to know:** A document has only one sending to a given integration: you send it there once. If the sending fails, you can retry it with the same button. You send the same document to another accounting integration separately. Order actions: the **Send invoice to external accounting** and **Send receipt to external accounting** steps are `TRANSFER_INVOICE_TO_EXTERNAL_ACCOUNTING` and `TRANSFER_RECEIPT_TO_EXTERNAL_ACCOUNTING` in `actionSteps[].action.type`, with `uuidValue` = the accounting integration id (`GET /integrations/accountings`). The **Invoice sent to external accounting** and **Receipt sent to external accounting** triggers are `triggerType` = `TRANSFERRED_INVOICE_TO_EXTERNAL_ACCOUNTING` and `TRANSFERRED_RECEIPT_TO_EXTERNAL_ACCOUNTING`. The **Has a successful invoice transfer to external accounting** / **Has no successful invoice transfer to external accounting** conditions are `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING` / `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING_NOT`, and for receipts `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING` / `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING_NOT` (`uuidValues` = accounting integration ids). Only a `SUCCESS` transfer counts. The step takes the latest document in the order's `billings[]` with the given `billingType` (`INVOICE` or `RECEIPT`) and `deleted` = `false`. An order has at most one document of a given `billingType` with `deleted` = `false` - issuing a second one returns `BILLING_ALREADY_EXISTS`. Full description: [Order actions](https://ritevo.com/en/docs/automations/order-actions). ### How an invoice reaches KSeF - **Confirmation** - KSeF processes the invoice after receiving it, so at first it is **Sending**. We check the KSeF response every few seconds. If KSeF does not confirm the invoice within 24 hours, the sending ends with an error. - **Numbers and date** - the invoice carries the number assigned in Ritevo. Once accepted, KSeF gives it a KSeF number. The issue date in KSeF is the day of sending. - **PDF** - clicking the icon downloads a PDF prepared from the invoice stored in KSeF, with the KSeF number. - **Corrections** - you send them by hand. Automatic actions send only invoices and receipts. - **VAT rates** - KSeF accepts 23%, 8%, 5%, 0%, WDT (intra-EU supply), Zw. (exempt) and O.o (reverse charge) from us, as well as the former 22% and 7%. OSS rates are sent as OSS sales. An invoice with any other rate is not sent - you will see the **Tax rate not supported** error. ## Reconnection required This state shows up when KSeF stops accepting the certificate - for example after it expired or was revoked. Until then invoices will not reach KSeF. 1. Generate a new KSeF certificate - the same way as the first time. 2. On the integration page click **Update credentials**, add the new files, enter the password and confirm. A valid certificate refreshes the connection, and the history of sent invoices stays unchanged. > **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately. In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page. ![The Update credentials window of the KSeF integration with fields for the private key file, the key password and the certificate file](https://ritevo.com/docs/integrations/ksef/en-update.webp) ## Deleting the integration **Delete integration** turns the integration off in Ritevo. Documents sent earlier stay in KSeF. **Restore integration** turns it back on. ## What the integration does not do - It does not send receipts. - It does not send invoices in offline mode - online only. - It does not change invoices that are already in KSeF - you make changes with a correction. - It does not fetch purchase invoices or other documents from KSeF. ## The integration through the API This integration's endpoints are under `/integrations/accountings/ksef`, and the ones shared by the whole type (list, get one, delete, restore) under `/integrations/accountings`. You send a document with `POST /orders/billings/{billingId}/transfer-to-external-accounting/{integrationId}`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. --- All help in one file: https://ritevo.com/llms-full.txt. Help map with links to every page: https://ritevo.com/llms.txt.