Dokumentacja API - ifirma.pl

Pro forma do faktury eksportowej


Obsługiwane typy faktur

Poprzez API możliwe jest wystawienie pro formy do następujących typów faktur:

  • Eksport towarów
  • Wewnątrzunijna dostawa towarów
  • Świadczenie usług dla podatników VAT-UE w trybie art. 28b
  • Świadczenie usług poza terytorium kraju
  • Faktura z ceną określoną w walucie obcej

Rodzaj faktury wskazywany jest w przesyłanym żądaniu, w polu TypFaktury.
Wystawianie pro formy dla faktur krajowych zostało opisane na stronie Faktura pro forma

Wystawianie faktury pro forma

W celu wystawienia faktury pro forma należy skonstruować żądanie (POST) w formacie JSON na adres:

https://www.ifirma.pl/iapi/fakturaproformaeksport.json

Przesyłane żądanie powinno być zestawem danych faktury w formacie przedstawionym w poniższej tabeli.

Nazwa w JSON Typ danych Wartości Wymagane Opis
TypFaktury String prz_eksport_towarow (Eksport towarów);
prz_dostawa_ue_towarow (Wewnątrzunijna dostawa towarów);
prz_eksport_dost_uslug_ue (Świadczenie usług dla podatników VAT-UE w trybie art. 28b);
prz_eksport_dost_uslug_nie_ue (Świadczenie usług poza terytorium kraju);
prz_faktura_wys_ter_kraj (Faktura z ceną określoną w walucie obcej)		 T Rodzaj faktury, do której wystawiana jest pro forma
DataWystawienia String Format: RRRR-MM-DD;
data należąca do ustawionego miesiąca księgowego;
>= data wystawienia faktury wcześniejszej 		T Data wystawienia faktury
TerminPlatnosci String Format: RRRR-MM-DD;
>= data wystawienia		 N Termin płatności za towar lub usługę
MiejsceWystawienia String <= 50 znaków N Miejsce wystawienia faktury
Numer Integer <= 10 znaków;
null (kolejny numer z podanej serii numeracji)		 T Numer wystawianej faktury
NazwaSeriiNumeracji String Jeśli nie zostanie podana, zostanie wybrana domyślna N Nazwa serii numeracji dla faktury
Jezyk String en (angielski); de (niemiecki); bg (bułgarski); hr (chorwacki); cs (czeski); da (duński); nl (niderlandzki); es (hiszpański); et (estoński); fi (fiński); fr (francuski); gr (grecki); hu (węgierski); it (włoski); lv (łotewski); lt (litewski); ru (rosyjski); sk (słowacki); sl (słoweński); sv (szwedzki) T Język faktury
Waluta String PLN; EUR; GBP; USD; CHF; NOK; JPY; CZK; LTL; UAH; RUB; AUD; DKK; CAD; LVL; RON; SEK; HUF; THB; HKD; NZD; SGD; ISK; HRK; BGN; TRY; ILS; CLP; PHP; MXN; ZAR; BRL; MYR; IDR; INR; KRW; CNY; XDR T Waluta na fakturze
Uwagi String <= 1000 znaków N Uwagi na fakturze
SposobZaplaty String GTK – gotówka;
POB – za pobraniem;
PRZ – przelew;
KAR – karta;
PZA – polecenie zapłaty;
CZK – czek;
KOM – kompensata;
BAR – barter;
DOT – DotPay;
PAL – PayPal;
ALG – PayU;
P24 – Przelewy24;
TPA – tpay.com;
ELE – płatność elektroniczna;
 T Sposób zapłaty za towar lub usługę
RodzajPodpisuOdbiorcy String OUP (osoba upoważniona do otrzymania faktury VAT);
UPO (upoważnienie);
BPO (bez podpisu odbiorcy);
BWO (bez podpisu odbiorcy i wystawcy)		 T Rodzaj podpisu odbiorcy
PodpisOdbiorcy String <= 70 znaków N Podpis odbiorcy
PodpisWystawcy String <= 70 znaków N Podpis wystawcy
NazwaSzablonu String Jeśli nie zostanie podany, zostanie wybrany domyślny N Nazwa szablonu wystawianej faktury
WidocznyNumerGios Boolean true; false T* Widoczność numeru BDO/GIOŚ na fakturze
* Możliwe zamienne użycie pola WidocznyNumerBdo
WidocznyNumerBdo Boolean true; false T* Widoczność numeru BDO/GIOŚ na fakturze
* Pole zamiennie stosowane zamiast WidocznyNumerGios
IdentyfikatorKontrahenta String <= 15 znaków N Identyfikator kontrahenta
PrefiksUEKontrahenta String <= 2 znaków N Prefiks UE kontrahenta
NIPKontrahenta String <= 13 znaków N Numer NIP kontrahenta
Pozycje
NazwaPelna String >= 1 znak; <= 300 znaków T Nazwa towaru
NazwaPelnaObca String >= 1 znak; <= 300 znaków T Nazwa towaru w języku obcym
Ilosc Number > 0.0000 ;<= 12 cyfr T Ilość towaru
Jednostka String >= 1 znak; <= 10 znaków T Jednostka towaru
JednostkaObca String >= 1 znak; <= 10 znaków T Jednostka towaru w języku obcym
CenaJednostkowa Number > 0.00;
<= 10 cyfr;
< 100000000		 T Cena jednostkowa towaru lub usługi
StawkaVat Number Null; 0.00; 0,05; 0.08; 0.23 T Stawka VAT pozycji faktury
GTU String BRAK, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13 N Symbol GTU (grupy towarowo-usługowej)
TypStawkiVat String PRC (procentowa);
ZW (zwolniona) 		T Typ stawki VAT
Rabat Number >=0;
< 100		 N Wysokość rabatu podawana w procentach
Kontrahent
Nazwa String >= 1 znak;<= 150 znaków T Nazwa firmy kontrahenta
Nazwa2 String <= 150 znaków N Nazwa firmy kontrahenta
Identyfikator String <= 15 znaków;
null (zostanie wygenerowany automatycznie)		 N Identyfikatora kontrahenta
PrefiksUE String <= 2 znaki N Prefiks UE kontrahenta
NIP String <= 13 znaków N Numer NIP kontrahenta
Ulica String <= 65 znaków N Ulica siedziby firmy kontrahenta
KodPocztowy String >= 1 znak;
<= 16 znaków		 T Kod pocztowy kontrahenta
Miejscowosc String >= 1 znak;
<= 65 znaków		 T Miejscowość siedziby firmy kontrahenta
Kraj String <= 70 znaków N Kraj siedziby firmy kontrahenta
KodKraju String 2 znaki N Kod 3166-1 alfa-2 kraju siedziby kontrahenta
Dla Grecji kod „EL”
Email String <= 65 znaków N Adres e-mail kontrahenta
Telefon String <= 32 znaki N Numer telefonu kontrahenta
OsobaFizyczna Boolean true; false N Określa czy kontrahent jest osobą fizyczną (domyslnie: false))
JestOdbiorca Boolean true; false N Określa czy kontrahent jest odbiorcą (domyślnie: false)
JestDostawca Boolean true; false N Określa czy kontrahent jest dostawcą (domyślnie: false)

Przykładowa zawartość żądania:

{
	"TypFaktury": "prz_eksport_towarow",
	"DataWystawienia": "2017-10-18",
	"TerminPlatnosci": "2017-10-25",
	"MiejsceWystawienia": "Wrocław",
	"Numer": null,
	"NazwaSeriiNumeracji": null,
	"Jezyk": "en",
	"Waluta": "EUR",
	"Uwagi": "Order No. 589644125-17",
	"SposobZaplaty": "GTK",
	"NumerKontaBankowego": "brak",
	"RodzajPodpisuOdbiorcy": "BPO",
	"PodpisWystawcy": "Andrzej Majeranek",
	"WidocznyNumerGios": true,
	"Pozycje": 
	[
	    {
			"NazwaPelna": "Kanister",
		    "NazwaPelnaObca": "Canister",
		    "Ilosc": "2",
		    "Jednostka": "sztuk",
		    "JednostkaObca": "pcs",
		    "CenaJednostkowa": 28.99,
		    "StawkaVat": 0.00,
		    "TypStawkiVat": "PRC"
	    }
	],
	"Kontrahent": {
		"Nazwa": "John Malkovich",
		"Identyfikator": null,
		"PrefiksUE": null,
		"NIP": null,
		"Ulica": "234 Laurier Avenue West",
		"KodPocztowy": "K1A 0G9",
		"Miejscowosc": "Ottawa",
		"Kraj": "Kanada",
		"Email": "john@malkovich.com",
		"Telefon": "18003031282",
		"OsobaFizyczna" :true
	}	
}

Po przesłaniu żądania zwracany jest identyfikator faktury oraz kod wiadomości mówiący o poprawności wykonania żądania:

{
	”response”: {
		”Kod”: 0,
		”Informacja”: ”Faktura została pomyślnie dodana.”,
		”Identyfikator”: ”3654778”
	}
}

Zmiany dla ryczałtowca

W przypadku wystawiania faktury przez ryczałtowca należy zmodyfikować przesyłane żądanie i w pozycjach faktury należy dodać pole StawkaRyczaltu. W przeciwnym wypadku zostanie zastosowana stawka ryczałtu domyślnie ustawiona w konfiguracji konta.

Nazwa w JSON Typ danych Wartości Wymagane Opis
StawkaRyczaltu Number 0.03; 0.055; 0.85; 0.1; 0.125; 0.15; 0.17 T Stawka ryczałtu pozycji faktury 
{
	:
	"Pozycje":
	[
		{
		    "NazwaPelna": "Kanister",
			"NazwaPelnaObca": "Canister",
			"Ilosc": 2,
			"Jednostka": "sztuk",
			"JednostkaObca": "pcs",
			"CenaJednostkowa": 28.99,
			"StawkaVat": 0.23,
			"TypStawkiVat": "PRC"
			"StawkaRyczaltu": 0.03,
		}
	],
	:
}

Wykorzystanie danych kontrahenta istniejącego w bazie

Wystawiając fakturę pro formę można przypisać ją do kontrahenta, który istnieje w bazie kontrahentów użytkownika. W tym celu należy wykorzystać następujące pola w żądaniu:

  • IdentyfikatorKontrahenta
  • PrefiksUEKontrahenta
  • NIPKontrahenta

Mechanizm działa następująco:

  1. Wyszukiwanie w pierwszej kolejności odbywa się po identyfikatorze kontrahenta przekazanym w polu IdentyfikatorKontrahenta.
  2. Nieodnalezienie pasującego kontrahenta po podanym identyfikatorze lub niepodanie pola IdentyfikatorKontrahenta powoduje wyszukanie kontrahenta po prefiksie UE i numerze NIP przekazanym w polach PrefiksUEKontrahenta i NIPKontrahenta. Jeśli nie podano prefiksu UE, to wyszukiwanie odbywa się po samym numerze NIP spośród kontrahentów, którzy nie mają zapisanego prefiksu Ue lub mają określony jako „PL”.
  3. Brak dopasowania na podstawie powyższych pól powoduje utworzenie w bazie nowego kontrahenta na podstawie danych z obiektu Kontrahent.
  4. W przypadku braku możliwości utworzenia nowego kontrahenta zwracany jest komunikat błędu.

Pobieranie wystawionej faktury pro forma

Do pobrania wystawionej faktury pro formy wykorzystywany jest identyfikator faktury, który jest zwracany w komunikacie potwierdzającym prawidłowe dodanie faktury. Możliwe jest pobranie faktury w wybranym formacie (PDF, JSON lub XML).
W celu pobrania pro formy należy skonstruować żądanie (GET) w formacie JSON na adres:

https://www.ifirma.pl/iapi/fakturaproformaeksport/identyfikator_faktury.format

gdzie:

  • identyfikator_faktury – to identyfikator faktury uzyskany w odpowiedzi po poprawnym wystawieniu faktury, może zostać zastąpiony przez numer faktury (w numerze faktury ukośniki „/” należy zastąpić podłogami „_”, czyli np. 314/2017/ProForma to 314_2017/ProForma);
  • format – to jeden z trzech formatów, w którym chcemy pobrać fakturę, czyli: PDF, JSON lub XML.

Przykład:

https://www.ifirma.pl/iapi/fakturaproformaeksport/3654778.xml

Pobierając dowolną fakturę w formacie PDF można dodatkowo wybrać typ:

  • single – pojedyncza faktura,
  • double – podwójna faktura,
  • dup – duplikat faktury.

Wyboru dokonuje się poprzez określenie typu w adresie, na który przesyłane jest żądanie:

https://www.ifirma.pl/iapi/fakturaproformaeksport/identyfikator_faktury.pdf.typ

Pobieranie listy wystawionych pro form eksportowych

Możliwe jest również pobranie listy pro form eksportowych. W tym celu należy wysłać żądanie (GET) na adres:

https://www.firma.pl/iapi/fakturaproformaeksport/list.json?parametry

gdzie jako parametry można zdefiniować, które faktury mają się znaleźć na liście. Możliwe jest:

    1. Pobranie listy ze wskazaną liczbą ostatnich pro form z użyciem parametru limit
      Przykład dla pobrania listy ostatnich 10 pro form:
https://www.ifirma.pl/iapi/fakturaproformaeksport/list.json?limit=10
    1. Pobranie listy pro form wystawionych w określonym następujacymi parametrami przedziale czasu:
      • dzienOd
      • miesiacOd
      • rokOd
      • dzienDo
      • miesiacDo
      • rokDo

      Przykład dla pobrania listy pro form wystawionych pomiędzy 10 kwietnia 2017 a 6 czerwca 2017:

https://www.ifirma.pl/iapi/fakturaproformaeksport/list.json?dzienOd=10&miesiacOd=04&rokOd-2017&dzienDo=06&miesiacDo=06&rokDo=2017

Copyright 2001-2024 ifirma.pl