Plik wsadowy do wykazu umów TFG: szablon CSV/JSON i przykład krok po kroku

Plik wsadowy to najszybszy sposób, by przekazać do TFG wiele umów naraz - bez ręcznego przeklikiwania formularza. Trzeba go tylko zbudować zgodnie ze ściśle określoną strukturą. W tym przewodniku pokazujemy, czym różni się plik CSV od JSON, jakie pola wypełnić, jak wygląda gotowy plik na konkretnym przykładzie i dlaczego wykaz bywa odrzucany przez UFG.

CSV czy JSON - który format wybrać

System TFG przyjmuje pliki w dwóch formatach. Możesz korzystać z obu zamiennie - różnią się głównie tym, jak złożone umowy potrafią pomieścić:

W skrócie: jeśli każda Twoja umowa to jeden wyjazd dla grupy podróżnych i dane masz w arkuszu - wybierz CSV. Jeśli w ramach jednej umowy występują różne warianty (np. część osób leci, część jedzie autokarem, albo są dwa różne terminy) - potrzebujesz JSON, bo CSV takiej umowy nie obsłuży.

Zanim zaczniesz: co przygotować

UFG udostępnia w Portalu TFG komplet materiałów, które warto pobrać przed pierwszą wysyłką:

• szablon i instrukcję przygotowania pliku CSV z Excela,
• przykładowe pliki wsadowe (wzorcowe CSV i JSON),
• słowniki kodów - kraje, lotniska (ICAO), zakres terytorialny, przedmiot umowy, sposób płatności, waluty,
• plik z regułami walidacji - lista warunków, które musi spełnić każda umowa.

Do tego potrzebujesz eksportu z własnego systemu rezerwacji lub arkusza, w którym prowadzisz umowy. To z niego przeniesiesz dane do struktury wymaganej przez TFG - i to właśnie tutaj pojawia się najwięcej pracy, bo część pól (kody ICAO, zakres terytorialny, przedmiot umowy) typowy system rezerwacyjny nigdy nie zapisywał.

Jakie pola musi zawierać każda umowa

Wykaz prowadzi się dla każdej umowy (nie dla każdego uczestnika). Dla nowej umowy (zasilenie typu „nowe dane”) plik musi zawierać co najmniej poniższe pola. Zwróć uwagę na wymagane formaty - to przez nie najczęściej „wykłada się” walidacja:

Opcjonalnie dodajesz tablice wplaty (terminy i kwoty faktycznych przedpłat) oraz zwroty (jeśli zwrot został dokonany) - każda do 286 pozycji.

Przykład: jedna umowa krok po kroku

Weźmy konkretną umowę: wycieczkę czarterową dla 2 osób na Kretę, zawartą 5 lipca 2026, z wylotem 10 września i powrotem 17 września. Cena 7400 zł, dwie wpłaty. Najpierw przenosimy dane do pól TFG:

1. 1Nagłówek umowy - numer rezerwacji, data zawarcia, przedmiot umowy (impreza turystyczna) i sposób przyjmowania wpłat.
2. 2Wariant podróży - liczba podróżnych i terminy realizacji „od/do”.
3. 3Miejsce realizacji - zakres terytorialny, kraj i miejscowość/trasa.
4. 4Transport - rodzaj środka transportu, a przy przelocie również kod lotniska ICAO.
5. 5Cena i wpłaty - łączna cena z walutą oraz faktycznie dokonane przedpłaty.

W formacie JSON ta sama umowa wygląda tak:

{
  "umowy": [
    {
      "nrUmowyRezerwacji": "REZ-2026-0042",
      "dataZawarciaUmowy": "2026-07-05",
      "przedmiotUmowy": "IMPREZA_TURYSTYCZNA",
      "sposobPrzyjmowaniaWplat": "PRZELEW",
      "warianty": [
        {
          "liczbaPodroznych": 2,
          "terminRealizacjiOd": "2026-09-10",
          "terminRealizacjiDo": "2026-09-17",
          "miejsceRealizacjiUmowy": [
            {
              "zakresTerytorialny": "EUROPA",
              "kraj": "GR",
              "miejscowoscTrasa": "Heraklion"
            }
          ],
          "rodzajeSrodkaTransportu": [
            {
              "rodzajSrodkaTransportu": "LOTNICZY_CZARTER",
              "kodLotniskaDocelowego": "LGIR"
            }
          ]
        }
      ],
      "cenyUslug": [
        { "lacznaCenaUslug": "7400.00", "walutaUslug": "PLN" }
      ],
      "wplaty": [
        { "dataWplaty": "2026-07-05", "kwotaWplaty": "2000.00", "walutaWplaty": "PLN" },
        { "dataWplaty": "2026-08-01", "kwotaWplaty": "5400.00", "walutaWplaty": "PLN" }
      ],
      "zwroty": []
    }
  ]
}

Ta sama umowa (ma tylko jeden wariant, więc zmieści się w CSV) w formacie CSV to jeden wiersz danych pod wierszem nagłówków:

nrUmowyRezerwacji;dataZawarciaUmowy;przedmiotUmowy;sposobPrzyjmowaniaWplat;liczbaPodroznych;terminRealizacjiOd;terminRealizacjiDo;zakresTerytorialny;kraj;miejscowoscTrasa;rodzajSrodkaTransportu;kodLotniskaDocelowego;lacznaCenaUslug;walutaUslug
REZ-2026-0042;2026-07-05;IMPREZA_TURYSTYCZNA;PRZELEW;2;2026-09-10;2026-09-17;EUROPA;GR;Heraklion;LOTNICZY_CZARTER;LGIR;7400.00;PLN

Jeden plik = jeden typ zasilenia

Pliku nie da się „wymieszać”. Każdy plik wsadowy musi zawierać pozycje tylko jednego typu zasilenia. Dla różnych operacji przygotowujesz osobne pliki:

Obowiązuje też kolejność: korekta, rozwiązanie czy usunięcie zadziałają dopiero wtedy, gdy wcześniejsze zasilenie „nowe dane” dla tej umowy uzyskało status „Przyjęte”. Jeśli wyślesz korektę umowy, której system jeszcze nie przyjął, zostanie ona odrzucona.

Limity i wymagania pliku

Zanim plik trafi do dalszego przetwarzania, system sprawdza jego format i strukturę. Te limity musi spełnić każdy plik wsadowy:

Najczęstsze błędy, przez które plik zostaje odrzucony

System TFG waliduje zasilenie w dwóch etapach: synchronicznie (od razu - format i struktura pliku, puste lub powtórzone numery umów) oraz asynchronicznie (reguły biznesowe, których wynik sprawdzasz, odpytując o status). Oto pułapki, które najczęściej wywracają plik:

• data w złym formacie - wymagany jest zawsze RRRR-MM-DD (np. 2026-09-10, nie 10.09.2026),
• kwota jako tekst zamiast liczby albo bez formatu #.## (np. „7400 zł” zamiast 7400.00),
• kod spoza słownika - błędny kraj, lotnisko, waluta, sposób płatności czy przedmiot umowy,
• puste lub powtórzone numery umów w obrębie jednego pliku,
• przekroczone limity - więcej niż 50 wariantów, 286 wpłat/zwrotów albo 5000 umów,
• zła kolejność zasileń - korekta przed przyjęciem umowy pierwotnej,

Pełną listę przyczyn odrzucenia i sposób ich uniknięcia zebraliśmy w sekcji „Najczęstsze powody odrzucenia wykazu”. W praktyce bezpieczna wysyłka wymaga sprawdzenia danych zanim trafią do TFG.

Jak Prosty TFG przygotowuje plik za Ciebie

Ręczne budowanie pliku co miesiąc - przepisywanie kodów ze słowników, pilnowanie formatów dat i kwot, sprawdzanie limitów - to żmudna i ryzykowna robota. Prosty TFG robi to za Ciebie:

• Wczytuje eksport z Twojego systemu rezerwacji lub Excela - niezależnie od układu kolumn.
• Mapuje kolumny na strukturę TFG i zapamiętuje mapowanie jako profil Twojego biura.
• Uzupełnia kody słownikowe - kraj, zakres terytorialny, kody lotnisk ICAO i przedmiot umowy.
• Waliduje plik pod kątem wszystkich reguł TFG przed wysyłką, żeby nie został odrzucony.
• Generuje gotowy plik CSV/JSON albo wysyła wykaz przez API w Twoim imieniu, z właściwym typem i kolejnością zasileń.

Podsumowanie

Plik wsadowy oszczędza czas przy większej liczbie umów, ale wymaga precyzji: właściwy format (CSV dla prostych umów, JSON dla złożonych), poprawne formaty dat i kwot, kody zgodne ze słownikami i jeden typ zasilenia na plik. Co zrobić teraz:

1. 1Pobierz z Portalu TFG szablon CSV, przykładowe pliki, słowniki kodów i plik z walidacjami.
2. 2Sprawdź, których wymaganych pól (ICAO, zakres terytorialny, przedmiot umowy) brakuje w Twoim eksporcie.
3. 3Zdecyduj o formacie: CSV, gdy umowy mają jeden wariant, JSON - gdy wariantów jest więcej.
4. 4Zapisz się na listę oczekujących Prosty TFG, żeby przygotować i wysłać plik bez ręcznego mapowania kodów.

Masz pytania o przygotowanie pliku? Napisz do nas na kontakt@prostytfg.pl.