Integracja z API V-Desk — dokumentacja techniczna

1. Co robi integracja — przegląd

Aplikacja Intuiti Integrator V-Desk do Symfonii jest pośrednikiem między obiegiem dokumentów V-Desk a księgami Symfonii Finanse i Księgowość. Nie zapisuje niczego wprost do bazy Symfonii — po jednej stronie rozmawia z REST API V-Desk, po drugiej z obiektami integracji dostarczanymi przez producenta Symfonii.

1.1 Zakres funkcjonalny

1.2 Czego integracja nie robi

• Nie zapisuje do bazy Symfonii bezpośrednio. Wszystko idzie przez obiekty integracji producenta, więc obowiązują ich reguły walidacji i uprawnienia zalogowanego użytkownika FK.
• Nie księguje dokumentów. Dokumenty trafiają do bufora; zatwierdzenie zapisu pozostaje po stronie księgowego.
• Nie modyfikuje dokumentów w V-Desk. Jedyne, co wraca do obiegu, to numer nadany przez Symfonię.
• Nie obsługuje faktur sprzedaży. Integracja dotyczy dokumentów zakupu; strona sprzedażowa występuje wyłącznie jako domyślny schemat konta VAT należnego przy samonaliczeniu podatku.

2. Podstawy: adres, uwierzytelnianie, nagłówki

2.1 Adres bazowy

Każda instancja V-Desk ma własny adres bazowy. Aplikacja przechowuje go w ustawieniach jako bazowy endpoint i dokleja do niego ścieżkę końcówki. Adres bazowy podaje się bez ukośnika na końcu i bez ścieżki końcówki:

# poprawnie
https://firma-przykladowa.vdesk.przyklad.pl/api

# niepoprawnie — końcówka i ukośnik doklejane są przez aplikację
https://firma-przykladowa.vdesk.przyklad.pl/api/
https://firma-przykladowa.vdesk.przyklad.pl/api/invoice/export

Adres złożony wygląda więc tak: <bazowy endpoint> + <ścieżka końcówki> + ? + parametry zapytania.

2.2 Uwierzytelnianie

Uwierzytelnianie odbywa się kluczem API przekazywanym w query stringu jako parametr apikey. Nie jest używany nagłówek Authorization ani ciasteczka sesyjne — każde żądanie jest samodzielne i musi nieść klucz.

GET /invoice/export?apikey=a1b2c3d4e5f60718293a4b5c6d7e8f90&dateFrom=2026-08-01&dateTo=2026-08-31&showImported=0

2.3 Nagłówki żądania

3. Parametr company — kod firmy

Jedna instancja V-Desk może obsługiwać kilka firm. Parametr company zawęża operację do jednej z nich. Dopuszczalne wartości są zależne od instancji i podaje je dostawca V-Desk — nie jest to lista globalna.

Wartość jest kodowana procentowo przed doklejeniem do adresu, więc kody zawierające znaki specjalne są bezpieczne. Podanie wartości spoza listy dozwolonej kończy się odpowiedzią HTTP 400:

HTTP/1.1 400 Bad Request

Invalid company type [XYZ]. Allowed values: [FIRMA, ODDZIAL]

4. Formaty danych i konwencje

4.1 Standardowa odpowiedź operacji zapisu

Końcówki przyjmujące dane (POST) odpowiadają jednolitym obiektem statusu:

{
  "status": "ok",
  "msg": ""
}

5. Wykaz wykorzystywanych końcówek

6. GET /invoice/export — pobranie faktur

Zwraca listę faktur, których data zatwierdzenia mieści się w podanym zakresie. Jest to podstawowa operacja aplikacji.

Parametry zapytania

Przykładowe żądanie

GET /api/invoice/export?dateFrom=2026-08-01&dateTo=2026-08-31&showImported=0
        &apikey=a1b2c3d4e5f60718293a4b5c6d7e8f90&company=FIRMA HTTP/1.1
Host: firma-przykladowa.vdesk.przyklad.pl
Accept: application/json
User-Agent: C# App

Przykładowa odpowiedź

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 104821,
    "czyB2B": "TAK",
    "rodzajDokumentu": "FZ",
    "numerFaktury": "FZ/2026/08/017",

    "kontrahentNazwa": "Kontrahent A Sp. z o.o.",
    "kontrahentNip": "1111111111",
    "kontrahentMiasto": "Miasto Przykładowe",
    "kontrahentKodPocztowy": "00-001",
    "kontrahentUlica": "Przykładowa",
    "kontrahentUlicaNumer": "12/3",

    "dataWystawienia": "01.08.2026",
    "dataSprzedazy": "01.08.2026",
    "dataWplywu": "05.08.2026",
    "terminPlatnosci": "15.08.2026",
    "formaPlatnosci": "przelew",

    "opis": "Zakup materiałów biurowych",
    "pozycjaNetto": 10000.00,
    "pozycjaBrutto": 12300.00,
    "waluta": "PLN",
    "kurs": 1.0,

    "pozycjeVAT": [
      {
        "pozycjaNetto": 10000.00,
        "pozycjaVAT": "23",
        "pozycjaKwotaVat": 2300.00,
        "pozycjaBrutto": 12300.00
      }
    ],

    "dekret": [
      { "strona": "winien", "konto": "401-1", "kwota": 10000.00, "opis": "Materiały biurowe" },
      { "strona": "ma",     "konto": "202",   "kwota": 12300.00, "opis": "Materiały biurowe" },
      { "strona": "winien", "konto": "501-1", "kwota": 12300.00, "zapisRownolegly": 33 },
      { "strona": "ma",     "konto": "490",   "kwota": 12300.00, "zapisRownolegly": 33 }
    ],

    "nrKSEF": "1111111111-20260801-AB01CD23EF45-6A",
    "dataKSEF": "01.08.2026"
  }
]

Pola obiektu faktury

Obiekt pozycjeVAT[]

Obiekt dekret[]

Księgowanie równoległe — pełny przykład

Księgowanie równoległe to drugi, towarzyszący zapis tego samego zdarzenia — najczęściej przeksięgowanie kosztu z zespołu 4 (koszty rodzajowe) na zespół 5 (koszty według miejsc powstawania) przez konto 490. V-Desk przysyła je w tej samej tablicy dekret[], co zapisy podstawowe, odróżnione wyłącznie obecnością pola zapisRownolegly.

Dokument z jednym kosztem, rozdzielonym równolegle na dwa miejsca powstawania:

{
  "id": 40251,
  "rodzajDokumentu": "FZ",
  "numerFaktury": "FV/2026/08/0042",
  "kontrahentNazwa": "Kontrahent B Sp. z o.o.",
  "kontrahentNip": "2222222222",

  "dataWystawienia": "04.08.2026",
  "dataWplywu": "06.08.2026",
  "terminPlatnosci": "18.08.2026",

  "opis": "Energia elektryczna 07/2026",
  "pozycjaNetto": 8000.00,
  "pozycjaBrutto": 9840.00,
  "waluta": "PLN",
  "kurs": 1.0,

  "pozycjeVAT": [
    { "pozycjaNetto": 8000.00, "pozycjaVAT": "23", "pozycjaKwotaVat": 1840.00, "pozycjaBrutto": 9840.00 }
  ],

  "dekret": [
    // --- zapisy podstawowe: brak pola zapisRownolegly ---
    { "strona": "winien", "konto": "402-1", "kwota": 8000.00, "opis": "Energia elektryczna 07/2026" },
    { "strona": "ma",     "konto": "202",   "kwota": 9840.00, "opis": "Energia elektryczna 07/2026" },

    // --- zapisy równoległe: rozksięgowanie kosztu 4 -> 5 przez 490 ---
    { "strona": "ma",     "konto": "490",     "kwota": 8000.00, "zapisRownolegly": 33 },
    { "strona": "winien", "konto": "550-1",   "kwota": 5000.00, "zapisRownolegly": 33 },
    { "strona": "winien", "konto": "527-3",   "kwota": 3000.00, "zapisRownolegly": 33 }
  ],

  "nrKSEF": "2222222222-20260804-BC02DE34FG56-7B",
  "dataKSEF": "04.08.2026"
}

Jak aplikacja przenosi to do Symfonii FK

Odporność na błędne rekordy

Odpowiedź jest przetwarzana rekord po rekordzie: pojedyncza faktura o nieoczekiwanej strukturze jest raportowana użytkownikowi i pomijana, a pozostałe dokumenty z odpowiedzi zostają wczytane. Awaria jednego dokumentu nie przerywa całego pobrania.

7. POST /company/import — wysyłka kontrahentów

Przenosi kartotekę kontrahentów z bazy Symfonii FK do V-Desk. Aplikacja wysyła po jednym kontrahencie na żądanie (tablica jednoelementowa), dzięki czemu błąd jednego rekordu nie przerywa całej operacji — na końcu użytkownik dostaje zbiorczy raport.

Parametry zapytania

Przykładowe żądanie

POST /api/company/import?apikey=a1b2c3d4e5f60718293a4b5c6d7e8f90&company=FIRMA HTTP/1.1
Host: firma-przykladowa.vdesk.przyklad.pl
Content-Type: application/json
Accept: application/json
User-Agent: C# App

[
  {
    "id": 1042,
    "name": "Kontrahent A Sp. z o.o.",
    "nip": "1111111111",
    "city": "Miasto Przykładowe",
    "country": "PL",
    "postalCode": "00-001",
    "address": "Przykładowa 12/3",
    "postOffice": null,
    "phone": "+48 00 000 00 00",
    "email": "kontakt@przyklad.example",
    "description": "Kontrahent przeniesiony z Symfonia FK",
    "nrb": "PL00 0000 0000 0000 0000 0000 0000",
    "status": 1
  }
]

Pola obiektu kontrahenta

Odpowiedź

{ "status": "ok", "msg": "" }

Odpowiedź inna niż status: "ok", kod HTTP spoza zakresu sukcesu albo treść, która nie jest poprawnym JSON-em, kończą się dopisaniem kontrahenta do raportu błędów wraz z dosłowną treścią odpowiedzi serwera (przycinaną do 600 znaków).

8. POST /invoice/import/pk — zwrot numeru dokumentu Symfonii

Po zaksięgowaniu faktury w buforze Symfonii aplikacja może odesłać do V-Desk numer nadanego dokumentu (PK). Dzięki temu w V-Desk widać, że dokument został już przeniesiony do księgowości — i to właśnie na tej podstawie działa filtr showImported przy pobieraniu.

Przykładowe żądanie

POST /api/invoice/import/pk?apikey=a1b2c3d4e5f60718293a4b5c6d7e8f90 HTTP/1.1
Host: firma-przykladowa.vdesk.przyklad.pl
Content-Type: application/json
Accept: application/json
User-Agent: C# App

[
  {
    "id": 104821,
    "numerDokumnetuSymfonia": "3/2026"
  }
]

Pola

9. POST <słownik> — wysyłka słowników

V-Desk przyjmuje słowniki pomocnicze (rodzaje kosztów, marki, wymiary analityczne itp.). Ścieżka końcówki nie jest zaszyta w aplikacji — użytkownik definiuje ją samodzielnie razem z nazwą słownika, ponieważ zestaw słowników różni się między wdrożeniami. Przykładowe ścieżki spotykane we wdrożeniach: /import/costtype, /brand/import.

Przykładowe żądanie

POST /api/import/costtype?apikey=a1b2c3d4e5f60718293a4b5c6d7e8f90 HTTP/1.1
Host: firma-przykladowa.vdesk.przyklad.pl
Content-Type: application/json
Accept: application/json
User-Agent: C# App

[
  { "value": "MAT", "description": "Materiały",        "isActive": "1" },
  { "value": "USL", "description": "Usługi obce",      "isActive": "1" },
  { "value": "TRA", "description": "Transport",        "isActive": "0" }
]

Pola pozycji słownika

W jednym żądaniu wysyłane są wszystkie zaznaczone pozycje danego słownika. Odpowiedź ma standardowy format statusu (rozdział 4.1).

10. Obsługa błędów

11. Jak dane z V-Desk trafiają do Symfonii FK

Aplikacja nie zapisuje niczego wprost do bazy danych Symfonii — korzysta wyłącznie z obiektów integracji dostarczanych przez producenta systemu Symfonia. Poniżej skrót odwzorowania danych z API na dokument księgowy.

12. Bezpieczeństwo i dobre praktyki

• Wyłącznie HTTPS. Klucz API jest przekazywany w adresie URL, więc połączenie nieszyfrowane ujawnia go w całości.
• Nie logować pełnych adresów URL. Przed wklejeniem adresu do zgłoszenia serwisowego usuń z niego wartość apikey.
• Osobny klucz na instalację. Ułatwia to odcięcie pojedynczego stanowiska bez wpływu na pozostałe.
• Ograniczaj zakres dat. Końcówka pobierania nie ma stronicowania — miesięczne zakresy są bezpieczne, roczne potrafią zwrócić odpowiedź trudną do przetworzenia.
• Idempotencja po stronie klienta. API nie gwarantuje odrzucenia powtórnie wysłanego dokumentu; kontrola duplikatów musi odbywać się po stronie integratora — po numerze KSeF, a gdy go brak, po numerze dokumentu, kwocie brutto i NIP-ie.
• Traktuj odpowiedź jako niezaufaną. Pojedynczy rekord o nieoczekiwanej strukturze nie powinien przerywać przetwarzania całej paczki.