# wFirma

wFirma integration with Ritevo: connecting with API keys, sending invoices and receipts, VAT and contractor settings, reconnecting.

The wFirma integration sends invoices and receipts issued in Ritevo to wFirma. You connect it with API keys from the wFirma panel and pick the company the documents should go to.

> **Required integration:** You need a wFirma account and API keys generated in its panel: an access key (Access Key) and a secret key (Secret Key).

You can add as many wFirma 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 wFirma company ID. The companies available for the keys are returned by `POST /integrations/accountings/wfirma/companies`. You provide new keys with `PATCH /integrations/accountings/wfirma/{id}/credentials` - in any state of the integration. It checks that the keys see the `externalId` company and sets `authError=false` and `active=true`.

## Which documents it sends

- **VAT invoice** (API: "VAT invoice" = `INVOICE`; value in `billingType`) - goes to wFirma as a VAT invoice or an invoice without VAT, depending on the **Invoice with VAT** setting on the integration page.
- **Receipt** (API: "Receipt" = `RECEIPT`; value in `billingType`) - goes to wFirma as a receipt with or without VAT, depending on the **Receipt with VAT** setting on the integration page.
- **Invoice correction** (API: "Invoice correction" = `CORRECTION`; value in `billingType`) - not supported.

## How to generate the API key

You create API keys in the wFirma panel. wFirma shows the Secret Key only once, so copy both keys straight away - you will paste them into Ritevo when adding the integration.

1. Sign in to wFirma.
2. Go to **Ustawienia** → **Bezpieczeństwo** → **Aplikacje** → **Klucze API** (settings, security, applications, API keys) and click **Dodaj** (add).
3. Enter a name, for example "Ritevo", and confirm with your wFirma password.
4. Copy the **Access Key** and the **Secret Key**.

## 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 **wFirma** tile.
3. Paste the **Access key (Access Key)** and the **Secret key (Secret Key)** and click **Next step**. We check the keys in wFirma - if they are wrong, you will see the error returned by wFirma.
4. From the **Select company** list pick the company from your wFirma account and click **Create integration**. The new integration's settings open.

![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 wFirma tile framed in the Accounting section](https://ritevo.com/docs/integrations/wfirma/en-catalogue.webp)

![The wFirma add-integration screen with the Access key and Secret key fields and the Next step button](https://ritevo.com/docs/integrations/wfirma/en-add.webp)

## Integration settings

The integration is named after the company fetched from wFirma - you cannot change it. On the integration page you will find:

- **Integration settings** - fixed rules: we send gross amounts only, wFirma numbers the document with its own numbering, and wFirma accepts Polish VAT rates only - more below.
- **Create contractors** - once on, wFirma adds the buyer to its contractor list if they are not there yet. Off by default.
- **Invoice with VAT** / **Invoice without VAT** - the kind of invoice created in wFirma. With VAT by default.
- **Receipt with VAT** / **Receipt without VAT** - the kind of receipt created in wFirma. With VAT by default.
- **Update credentials** - you enter new API keys for the same company.

Creating: `accessKey`, `secretKey` and `externalId` - the company ID from `POST /integrations/accountings/wfirma/companies`, which returns `id:name` entries. You change settings with separate `PATCH` calls: `/{id}/invoice-with-vat` with `invoiceWithVat` (**Invoice with VAT** = `true`), `/{id}/receipt-with-vat` with `receiptWithVat` (**Receipt with VAT** = `true`) and `/{id}/auto-create-contractors` with `autoCreateContractors` (**Create contractors** = `true`).

> **Good to know:** The switches save right away and apply to documents sent from then on.

## 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 wFirma in two ways:

- **By hand** - in the document details, in the **External accounting systems** card, click the button with the wFirma 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 wFirma to confirm it.
- **Sent successfully** (API: "Sent successfully" = `SUCCESS`; value in `externalTransfers[].status`) - the document is in wFirma. Click the icon to download or open it.
- **Sending failed** (API: "Sending failed" = `FAILED`; value in `externalTransfers[].status`) - the document did not reach wFirma. 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 a document reaches wFirma

- **Right away** - wFirma answers straight away, so the document is **Sent successfully** or **Sending failed** right after sending.
- **Number and dates** - wFirma assigns the number. The issue date, sale date and payment due date come from the document in Ritevo.
- **PDF** - clicking the icon downloads the PDF generated by wFirma.
- **VAT rates** - wFirma accepts 23%, 8%, 5%, 0%, WDT (intra-EU supply), Zw. (exempt) and O.o (reverse charge) from us, and OSS rates are matched to the buyer's country. A document with any other rate is not sent - you will see the **Tax rate not supported** error.

## Reconnection required

This state shows up when wFirma stops accepting the API keys - for example after they were deleted in the wFirma panel. Until you enter new keys, documents will not reach wFirma.

1. Generate new API keys in the wFirma panel - the same way as the first time.
2. On the integration page click **Update credentials**, paste both keys and confirm. We check them in wFirma - the keys must have access to the same company. Correct ones refresh the connection, and the settings and the history of sent documents stay 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.

## Deleting the integration

**Delete integration** turns the integration off in Ritevo. Documents sent earlier stay in wFirma. **Restore integration** turns it back on.

## What the integration does not do

- It does not send invoice corrections.
- It does not change or delete documents that are already in wFirma.
- It does not fetch documents from wFirma into Ritevo.

## The integration through the API

This integration's endpoints are under `/integrations/accountings/wfirma`, 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.