# wFirma

Integracja wFirma z Ritevo: podłączenie kluczami API, przesyłanie faktur i paragonów, ustawienia VAT i kontrahentów, ponowne połączenie.

Integracja z wFirma przesyła do wFirma faktury i paragony wystawione w Ritevo. Podłączasz ją kluczami API z panelu wFirma i wybierasz firmę, do której mają trafiać dokumenty.

> **Wymagana integracja:** Potrzebujesz konta w wFirma i kluczy API wygenerowanych w jego panelu: klucza dostępu (Access Key) i klucza tajnego (Secret Key).

Integracji wFirma możesz dodać dowolnie wiele, także kilka dla tego samego konta - na przykład z innymi danymi albo innymi ustawieniami wystawiania dokumentów. Każda działa osobno.

Unikalność nie jest sprawdzana, celowo: każde utworzenie integracji tworzy nową, także dla tego samego `externalId`, żeby jedno konto mogło mieć kilka integracji z różnymi danymi albo ustawieniami.

`externalId` to ID firmy w wFirma. Listę firm dostępnych dla kluczy zwraca `POST /integrations/accountings/wfirma/companies`. Nowe klucze podasz przez `PATCH /integrations/accountings/wfirma/{id}/credentials` - w każdym stanie integracji. Sprawdza, czy klucze widzą firmę z `externalId`, i ustawia `authError=false` i `active=true`.

## Jakie dokumenty przesyła

- **Faktura VAT** (API: "Faktura VAT" = `INVOICE`; wartość w `billingType`) - trafia do wFirma jako faktura VAT albo faktura bez VAT, zależnie od ustawienia **Faktura z VAT** na stronie integracji.
- **Paragon** (API: "Paragon" = `RECEIPT`; wartość w `billingType`) - trafia do wFirma jako paragon z VAT albo bez VAT, zależnie od ustawienia **Paragon z VAT** na stronie integracji.
- **Korekta faktury** (API: "Korekta faktury" = `CORRECTION`; wartość w `billingType`) - nie jest obsługiwana.

## Jak wygenerować klucz API

Klucze API tworzysz w panelu wFirma. Secret Key wFirma pokazuje tylko raz, więc skopiuj oba klucze od razu - wkleisz je w Ritevo przy dodawaniu integracji.

1. Zaloguj się do wFirma.
2. Przejdź do **Ustawienia** → **Bezpieczeństwo** → **Aplikacje** → **Klucze API** i kliknij **Dodaj**.
3. Wpisz nazwę, na przykład „Ritevo", i potwierdź hasłem do wFirma.
4. Skopiuj **Access Key** i **Secret Key**.

## Podłączenie konta

Zacznij w Ritevo:

1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu.
2. W sekcji **Księgowość** wybierz kafelek **wFirma**.
3. Wklej **Klucz dostępu (Access Key)** i **Klucz tajny (Secret Key)** i kliknij **Kolejny krok**. Sprawdzamy klucze w wFirma - jeśli są błędne, zobaczysz błąd zwrócony przez wFirma.
4. Z listy **Wybierz firmę** wybierz firmę z Twojego konta wFirma i kliknij **Utwórz integrację**. Otworzą się ustawienia nowej integracji.

![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp)

![Ekran Dodaj integrację z zaznaczonym kafelkiem wFirma w sekcji Księgowość](https://ritevo.com/docs/integrations/wfirma/pl-catalogue.webp)

![Ekran dodawania integracji wFirma z polami Klucz dostępu i Klucz tajny oraz przyciskiem Kolejny krok](https://ritevo.com/docs/integrations/wfirma/pl-add.webp)

## Ustawienia integracji

Nazwą integracji jest nazwa firmy pobrana z wFirma - nie da się jej zmienić. Na stronie integracji znajdziesz:

- **Ustawienia integracji** - stałe zasady: przesyłamy tylko kwoty brutto, numer dokumentu nadaje wFirma według swojej numeracji, a wFirma przyjmuje tylko polskie stawki VAT - więcej niżej.
- **Twórz kontrahentów** - po włączeniu wFirma dopisuje kupującego do listy kontrahentów, jeśli jeszcze go tam nie ma. Domyślnie wyłączone.
- **Faktura z VAT** / **Faktura bez VAT** - rodzaj faktury tworzonej w wFirma. Domyślnie z VAT.
- **Paragon z VAT** / **Paragon bez VAT** - rodzaj paragonu tworzonego w wFirma. Domyślnie z VAT.
- **Zaktualizuj dane logowania** - podajesz nowe klucze API tej samej firmy.

Tworzenie: `accessKey`, `secretKey` i `externalId` - ID firmy z listy `POST /integrations/accountings/wfirma/companies`, która zwraca pozycje `id:nazwa`. Ustawienia zmieniasz osobnymi `PATCH`: `/{id}/invoice-with-vat` z `invoiceWithVat` (**Faktura z VAT** = `true`), `/{id}/receipt-with-vat` z `receiptWithVat` (**Paragon z VAT** = `true`) i `/{id}/auto-create-contractors` z `autoCreateContractors` (**Twórz kontrahentów** = `true`).

> **Warto wiedzieć:** Przełączniki zapisują się od razu i działają dla dokumentów przesyłanych od tej chwili.

## Przesyłanie dokumentów

> **Warto wiedzieć:** Na jednym zamówieniu może być tylko jedna aktywna faktura i jeden aktywny paragon. Kolejny dokument tego typu wystawisz dopiero po usunięciu poprzedniego. Korekt do faktury możesz wystawić dowolnie wiele.

Dokumenty wystawiasz w zamówieniu. Do wFirma przesyłasz je na dwa sposoby:

- **Ręcznie** - w szczegółach dokumentu, w karcie **Zew. systemy księgowe**, kliknij przycisk z nazwą konta wFirma. Przycisk pojawia się tylko przy dokumentach, które ta integracja obsługuje.
- **Automatycznie** - krokiem **Prześlij fakturę do zew. systemu księgowego** albo **Prześlij paragon do zew. systemu księgowego** w [akcjach dla zamówień](https://ritevo.com/pl/docs/automations/order-actions).

Przesyłanie dokumentów najlepiej zaplanować po kolei - najpierw wystawienie, potem przesłanie:

- **Faktura** - pierwsza akcja kończy się krokiem **Wygeneruj fakturę**. Druga startuje wyzwalaczem **Faktura(dodanie/usunięcie)**, ma warunek **Posiada fakturę** i krok **Prześlij fakturę do zew. systemu księgowego**.
- **Paragon** - tak samo: pierwsza akcja kończy się krokiem **Wygeneruj paragon**, a druga startuje wyzwalaczem **Paragon(dodanie/usunięcie)**, ma warunek **Posiada paragon** i krok **Prześlij paragon do zew. systemu księgowego**.
- **Korekty** - do jednej faktury możesz wystawić wiele korekt. Każdą prześlij zaraz po wystawieniu, zanim wystawisz następną.

> **Warto wiedzieć:** Krok przesłania wysyła zawsze tylko jeden dokument - najnowszy nieusunięty danego typu. Jeśli najpierw wystawisz wszystkie dokumenty, a dopiero potem włączysz przesyłanie, trafi tylko ostatni, a pozostałe prześlesz ręcznie. Usuniętego dokumentu nie prześlesz.

W tej samej karcie każde przesłanie ma swoją ikonę. Po najechaniu na nią widzisz konto, stan i datę:

- **W trakcie przesyłania** (API: "W trakcie przesyłania" = `PENDING`; wartość w `externalTransfers[].status`) - dokument jest wysłany, czekamy na potwierdzenie od wFirma.
- **Przesłano pomyślnie** (API: "Przesłano pomyślnie" = `SUCCESS`; wartość w `externalTransfers[].status`) - dokument jest w wFirma. Kliknij ikonę, żeby go pobrać albo otworzyć.
- **Błąd podczas przesyłania** (API: "Błąd podczas przesyłania" = `FAILED`; wartość w `externalTransfers[].status`) - dokument nie trafił do wFirma. Pod stanem widzisz powód błędu.

> **Warto wiedzieć:** Jeden dokument ma do danej integracji tylko jedno przesłanie: prześlesz go tam raz. Jeśli przesłanie skończy się błędem, możesz je ponowić tym samym przyciskiem. Do innej integracji księgowej ten sam dokument prześlesz osobno.

Akcje dla zamówień: kroki **Prześlij fakturę do zew. systemu księgowego** i **Prześlij paragon do zew. systemu księgowego** to `TRANSFER_INVOICE_TO_EXTERNAL_ACCOUNTING` i `TRANSFER_RECEIPT_TO_EXTERNAL_ACCOUNTING` w `actionSteps[].action.type`, z `uuidValue` = id integracji księgowej (`GET /integrations/accountings`). Wyzwalacze **Przesłano fakturę w zew. systemie księgowym** i **Przesłano paragon w zew. systemie księgowym** to `triggerType` = `TRANSFERRED_INVOICE_TO_EXTERNAL_ACCOUNTING` i `TRANSFERRED_RECEIPT_TO_EXTERNAL_ACCOUNTING`. Warunki **Ma udany transfer faktury do zew. systemu księgowego** / **Nie ma udanego transferu faktury do zew. systemu księgowego** = `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING` / `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING_NOT`, a dla paragonu `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING` / `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING_NOT` (`uuidValues` = id integracji księgowych). Liczy się tylko przesłanie `SUCCESS`. Krok bierze ostatni dokument z `billings[]` zamówienia o danym `billingType` (`INVOICE` albo `RECEIPT`) z `deleted` = `false`. Na zamówieniu jest najwyżej jeden dokument danego `billingType` z `deleted` = `false` - próba wystawienia drugiego zwraca `BILLING_ALREADY_EXISTS`. Pełny opis: [Akcje dla zamówień](https://ritevo.com/pl/docs/automations/order-actions).

### Jak dokument trafia do wFirma

- **Od razu** - wFirma odpowiada od razu, więc dokument ma stan **Przesłano pomyślnie** albo **Błąd podczas przesyłania** zaraz po wysłaniu.
- **Numer i daty** - numer nadaje wFirma. Datę wystawienia, datę sprzedaży i termin płatności bierzemy z dokumentu w Ritevo.
- **PDF** - kliknięcie ikony pobiera PDF wygenerowany przez wFirma.
- **Stawki VAT** - wFirma przyjmuje od nas 23%, 8%, 5%, 0%, WDT, Zw. i O.o, a stawki OSS dobieramy według kraju kupującego. Dokument z inną stawką nie zostanie przesłany - zobaczysz błąd **Stawka podatku nie jest wspierana**.

## Wymaga ponownego połączenia

Ten stan pojawia się, gdy wFirma przestała akceptować klucze API - na przykład po ich usunięciu w panelu wFirma. Do czasu podania nowych kluczy dokumenty nie trafią do wFirma.

1. W panelu wFirma wygeneruj nowe klucze API - tak samo jak przy pierwszym podłączeniu.
2. Na stronie integracji kliknij **Zaktualizuj dane logowania**, wklej oba klucze i zatwierdź. Sprawdzamy je w wFirma - klucze muszą mieć dostęp do tej samej firmy. Poprawne odświeżą połączenie, a ustawienia i historia przesłanych dokumentów zostają bez zmian.

> **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać.

W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony.

## Usunięcie integracji

**Usuń integrację** wyłącza integrację w Ritevo. Dokumenty przesłane wcześniej zostają w wFirma. **Przywróć integrację** włącza ją z powrotem.

## Czego integracja nie robi

- Nie przesyła korekt faktur.
- Nie zmienia ani nie usuwa w wFirma dokumentów, które już tam trafiły.
- Nie pobiera dokumentów z wFirma do Ritevo.

## Integracja przez API

Endpointy tej integracji są pod `/integrations/accountings/wfirma`, a wspólne dla całego typu (lista, pobranie jednej, usunięcie, przywrócenie) pod `/integrations/accountings`. Dokument przesyłasz przez `POST /orders/billings/{billingId}/transfer-to-external-accounting/{integrationId}`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs.


---

Cała pomoc w jednym pliku: https://ritevo.com/llms-full.txt. Mapa pomocy z linkami do wszystkich stron: https://ritevo.com/llms.txt.