Dokumentacja API - ifirma.pl

Faktura wysyłkowa z terytorium kraju / krajowa z ceną w walucie obcej


Wybór rodzaju faktury

Rodzaj faktury określa się poprzez wskazanie w przesyłanym żądaniu typu sprzedaży:

  • WYSYLKOWA – faktura sprzedaży wywyłkowej z terytorium kraju;
  • KRAJOWA – faktura sprzedaży krajowej towarów i usług

Struktura żądań służących do wystawienia faktur różni się w zależności od waluty, w której są określone ceny na fakturze.

Faktura z cenami określonymi w PLN

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

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

Przesyłane żądanie jest zestawem danych faktury w formacie przedstawionym poniżej:

Nazwa w JSON Typ danych Wartości Wymagane Opis
TypSprzedazy String WYSYLKOWA; KRAJOWA T Typ sprzedaży; określa rodzaj faktury
Zaplacono Number >= 0.00;
<= razem brutto faktury;
<= 10 cyfr;
< 100000000		 T Suma wpłat za fakturę
ZaplaconoNaDokumencie Number >= 0.00;
<= razem brutto faktury;
<= 10 cyfr;
< 100000000		 N Kwota zapłacono na dokumencie
LiczOd String NET (netto);
BRT (brutto)		 T Sposób wystawienia faktury: od netto lub od brutto
NumerKontaBankowego String <= 28 znaków;
BRAK (jeśli numer konta bankowego ma nie być wyświetlany)		 N Numer konta bankowego firmy
SplitPayment Boolean true; false N Dopisek Mechanizm Podzielonej Płatności
(domyślna wartość zgodna z ustawieniami na koncie)
DataWystawienia String Format: RRRR-MM-DD;
>= data sprzedaży;
>=data wystawienia faktury wcześniejszej;
<= 15 dzień miesiąca następnego względem daty sprzedaży		 T Data wystawienia faktury
MiejsceWystawienia String <= 50 znaków N Miejsce wystawienia faktury
DataSprzedazy String Format: RRRR-MM-DD T Data sprzedaży towaru
FormatDatySprzedazy String DZN (dzienny); MSC (miesięczny) T Format daty sprzedaży
TerminPlatnosci String Format: RRRR-MM-DD;
>= data sprzedaży		 N Termin płatności za towar
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
NazwaSeriiNumeracji String Jeśli nie zostanie podana, zostanie wybrana domyślna N Nazwa serii numeracji dla faktury
NazwaSzablonu String Jeśli nie zostanie podany, zostanie wybrany domyślny N Nazwa szablonu wystawianej 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 T Waluta na fakturze
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
Uwagi String <= 1000 znaków N Uwagi na fakturze
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
Numer Integer <= 10 znaków; null (daje kolejny numer z podanej serii numeracji) T Numer wystawianej faktury
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
StawkaVat Number Null; 0.00; 0.05; 0.08; 0.23 T Stawka VAT pozycji faktury
Ilosc Number > 0.0000 ;<= 12 cyfr T Ilość towaru
CenaJednostkowa Number > 0.00;<= 10 cyfr; < 100000000 T Cena jednostkowa towaru
NazwaPelna String >= 1 znak; <= 300 znaków T Nazwa towaru
NazwaPelnaObca String >= 1 znak; <= 300 znaków N Nazwa towaru w języku obcym
Jednostka String >= 1 znak; <= 10 znaków T Jednostka towaru
JednostkaObca String >= 1 znak; <= 10 znaków N Jednostka towaru w języku obcym
PKWiU String <= 30 znaków N (dla TypStawkiVat != ZW) Symbol PKWiU usługi lub CN towaru
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
Kontrahent
Nazwa String >= 1 znak; <= 150 znaków T Nazwa firmy kontrahenta
Nazwa2 String >= 1 znak; <= 150 znaków N Nazwa firmy kontrahenta
Identyfikator String >= 1; <= 15 znaków; null (zostanie wygenerowany automatycznie) N Identyfikator 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 kontrahenta
KodPocztowy String >= 1 znak; <= 16 znaków T Kod pocztowy kontrahenta
Kraj String <= 70 znaków T Kraj siedziby kontrahenta
KodKraju String 2 znaki N Kod 3166-1 alfa-2 kraju siedziby kontrahenta
Dla Grecji kod „EL”
Miejscowosc String >= 1 znak; <= 65 znaków T Miejscowość siedziby firmy kontrahenta
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 i sprzedawca są ze sobą powiązani.
domyślnie: false
PodmiotPowiazany Boolean true; false N Określa czy kontrahent jest podmiotem powiązanym ze sprzedawcą.
domyślnie: false
ProceduryJpk (obiekt opcjonalny)
SW Boolean true; false N Sprzedaż wysyłkowa z terytorium kraju (oznaczenie JPK).
domyślnie wg TypSprzedazy:

  • WYSYLKOWA: true
  • KRAJOWA: false
EE Boolean true; false N Usługi telekomunikacyjne, nadawcze, elektroniczne (oznaczenie JPK).
domyślnie: false
TP Boolean true; false N Istnieją powiązania nabywcy ze sprzedawcą (oznaczenie JPK).
domyślnie: false
MPP Boolean true; false N Obowiązkowy mechanizm podzielonej płatności (oznaczenie JPK).
domyślnie: false
BSPV Boolean true; false N Transfer bonu jednego przeznaczenia we własnym imieniu (oznaczenie JPK).
domyślnie: false
BSPVDostawa Boolean true; false N Sprzedaż, której dotyczy bon jednego przeznaczenia na rzecz emitera (oznaczenie JPK).
domyślnie: false
BMPVProwizja Boolean true; false N Usługi pośrednictwa i inne dotyczące transferu bonu różnego przeznaczenia. (oznaczenie JPK).
domyślnie: false

Przykładowa zawartość żądania (JSON):

{
	"TypSprzedazy": "WYSYLKOWA",
        "Zaplacono": 141.42,
	"ZaplaconoNaDokumencie": 141.42,
	"LiczOd": "BRT",
	"NumerKontaBankowego": null,
	"DataWystawienia": "2014-10-21",
	"MiejsceWystawienia": "Kobierzyce",
	"DataSprzedazy": "2014-10-21",
	"FormatDatySprzedazy": "DZN",
	"TerminPlatnosci": null,
	"SposobZaplaty": "PRZ",
	"NazwaSeriiNumeracji": "default",
	"NazwaSzablonu": "logo",
	"Jezyk": "en",
	"Waluta": "PLN",
	"RodzajPodpisuOdbiorcy": "OUP",
	"PodpisOdbiorcy": "John Malkovich",
	"PodpisWystawcy": "Tomasz Markowski",
	"Uwagi": "Order No. 3141592653",
	"WidocznyNumerGios": true,
	"Numer": null,
	"Pozycje":
	[
		{
			"StawkaVat": 0.08,
			"Ilosc": 3,
			"CenaJednostkowa": 47.14,
			"NazwaPelna": "Neseser",
			"NazwaPelnaObca": "Briefcase",
			"Jednostka": "sztuk",
			"JednostkaObca": "pcs",
			"TypStawkiVat": "PRC"
		}
	],
	"Kontrahent": 
	{
		"Nazwa": "John Malkovich",
		"Identyfikator": null,
		"PrefiksUE": null,
		"NIP": null,
		"Ulica": "234 Laurier Avenue West",
		"KodPocztowy": "K1A 0G9",
		"Kraj": "Kanada",
		"Miejscowosc": "Ottawa",
		"Email": "john@malkovich.com",
		"Telefon": "18003031282",
		"OsobaFizyczna": true
	}
}

Przykład żądania POST (PHP):

$requestContent = '{"TypSprzedazy": "WYSYLKOWA","Zaplacono": 141.42,"ZaplaconoNaDokumencie": 141.42,"LiczOd": "BRT","NumerKontaBankowego": null,"DataWystawienia": "2014-10-21","MiejsceWystawienia": "Kobierzyce","DataSprzedazy": "2014-10-21","FormatDatySprzedazy": "DZN","TerminPlatnosci": null,"SposobZaplaty": "PRZ","NazwaSeriiNumeracji": "default","NazwaSzablonu": "logo","Jezyk": "en","Waluta": "PLN","RodzajPodpisuOdbiorcy": "OUP","PodpisOdbiorcy": "John Malkovich","PodpisWystawcy": "Tomasz Markowski","Uwagi": "Order No. 3141592653","WidocznyNumerGios": true,"Numer": null,"Pozycje":[{"StawkaVat": 0.08,"Ilosc": 3,"CenaJednostkowa": 47.14,"NazwaPelna": "Neseser","NazwaPelnaObca": "Briefcase","Jednostka": "sztuk","JednostkaObca": "pcs","TypStawkiVat": "PRC"}],"Kontrahent":{"Nazwa": "John Malkovic","Identyfikator": null,"PrefiksUE": null,"NIP": null,"Ulica": "234 Laurier Avenue West","KodPocztowy": "K1A 0G9","Kraj": "Kanada","Miejscowosc": "Ottawa","Email": "john@malkovich.com","Telefon": "18003031282","OsobaFizyczna": true}}';

$klucz = ””;
$url = ””;
$nazwaUsera = ””;
$nazwaKlucza = ”faktura”;
$curlHandle = curl_init($url);

$hashWiadomosci = hmac($klucz, $url.$nazwaUsera.$nazwaKlucza.$requestContent);
$headers = array(
	'Accept: application/json',
	'Content-type: application/json; charset=UTF-8',
	'Authentication: IAPIS user='.$nazwaUsera.', hmac-sha1='.$hashWiadomosci
);

curl_setopt($curlHandle, CURLOPT_TIMEOUT, 300);
curl_setopt($curlHandle, CURLOPT_CONNECTTIMEOUT, 100);
curl_setopt($curlHandle, CURLOPT_URL, $url);
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curlHandle, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curlHandle, CURLOPT_HTTPGET, false);
curl_setopt($curlHandle, CURLOPT_POST, true);
curl_setopt($curlHandle, CURLOPT_POSTFIELDS, $requestContent);
curl_setopt($curlHandle, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($curlHandle, CURLOPT_SSL_VERIFYPEER, 0);

$rsp = curl_exec($curlHandle);

gdzie:

  • klucz – wygenerowany klucz dostępny w serwisie ifirma.pl;
  • url – url, pod który wysyłamy żądanie;
  • nazwaUsera – login do serwisu ifirma.pl;
  • nazwaKlucza – identyfiktorKlucza –  wartość  „faktura”;
  • requestContent – zawartość żądania;

W rezultacie 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”: ”1244512”
	}
}

Wystawianie faktury w walucie obcej

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

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

Przesyłane żądanie jest zestawem danych faktury w formacie przedstawionym poniżej:

Nazwa w JSON Typ danych Wartości Wymagane Opis
TypSprzedazy String WYSYLKOWA; KRAJOWA T Typ sprzedaży; określa rodzaj faktury
ZaplaconoNaDokumencie Number >= 0.00;
<= razem brutto faktury;
<= 10 cyfr;
< 100000000		 N Kwota zapłacono na dokumencie
LiczOd String NET (netto);
BRT (brutto)		 T Sposób wystawienia faktury: od netto lub od brutto
NumerKontaBankowego String <= 28 znaków;
BRAK (jeśli numer konta bankowego ma nie być wyświetlany)		 N Numer konta bankowego firmy
SplitPayment Boolean true; false N Dopisek Mechanizm Podzielonej Płatności
(domyślna wartość zgodna z ustawieniami na koncie)
DataWystawienia String Format: RRRR-MM-DD;
>= data sprzedaży;
>=data wystawienia faktury wcześniejszej;
<= 15 dzień miesiąca następnego względem daty sprzedaży		 T Data wystawienia faktury
MiejsceWystawienia String <= 50 znaków N Miejsce wystawienia faktury
DataSprzedazy String Format: RRRR-MM-DD T Data sprzedaży towaru
FormatDatySprzedazy String DZN (dzienny); MSC (miesięczny) T Format daty sprzedaży
TerminPlatnosci String Format: RRRR-MM-DD;
>= data sprzedaży		 N Termin płatności za towar
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
NazwaSeriiNumeracji String Jeśli nie zostanie podana, zostanie wybrana domyślna N Nazwa serii numeracji dla faktury
NazwaSzablonu String Jeśli nie zostanie podany, zostanie wybrany domyślny N Nazwa szablonu wystawianej 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 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
KursWalutyWidoczny Boolean true; false T Widoczność kursu waluty na fakturze
KursWalutyZDniaPoprzedzajacegoDzienWystawieniaFaktury Number >= 0.0000; <= 10 cyfr; < 100000000 T Kurs waluty obcej z dnia poprzedzającego dzień wystawienia faktury
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
Uwagi String <= 1000 znaków N Uwagi na fakturze
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
Numer Integer <= 10 znaków; null (daje kolejny numer z podanej serii numeracji) T Numer wystawianej faktury
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
StawkaVat Number Null; 0.00; 0.05; 0.08; 0.23 T Stawka VAT pozycji faktury
Ilosc Number > 0.0000 ;<= 12 cyfr T Ilość towaru
CenaJednostkowa Number > 0.00;<= 10 cyfr; < 100000000 T Cena jednostkowa towaru
NazwaPelna String >= 1 znak; <= 300 znaków T Nazwa towaru
NazwaPelnaObca String >= 1 znak; <= 300 znaków N Nazwa towaru w języku obcym
Jednostka String >= 1 znak; <= 10 znaków T Jednostka towaru
JednostkaObca String >= 1 znak; <= 10 znaków N Jednostka towaru w języku obcym
PKWiU String <= 30 znaków N (dla TypStawkiVat != ZW) Symbol PKWiU usługi lub CN towaru
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
Kontrahent
Nazwa String >= 1 znak; <= 150 znaków T Nazwa firmy kontrahenta
Nazwa2 String >= 1 znak; <= 150 znaków N Nazwa firmy kontrahenta
Identyfikator String >= 1; <= 15 znaków; null (zostanie wygenerowany automatycznie) N Identyfikator 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 kontrahenta
KodPocztowy String >= 1 znak; <= 16 znaków T Kod pocztowy kontrahenta
Kraj String <= 70 znaków T Kraj siedziby kontrahenta
KodKraju String 2 znaki N Kod 3166-1 alfa-2 kraju siedziby kontrahenta
Dla Grecji kod „EL”
Miejscowosc String >= 1 znak; <= 65 znaków T Miejscowość siedziby firmy kontrahenta
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 i sprzedawca są ze sobą powiązani.
domyślnie: false
PodmiotPowiazany Boolean true; false N Określa czy kontrahent jest podmiotem powiązanym ze sprzedawcą.
domyślnie: false
ProceduryJpk (obiekt opcjonalny)
SW Boolean true; false N Sprzedaż wysyłkowa z terytorium kraju (oznaczenie JPK).
domyślnie wg TypSprzedazy:

  • WYSYLKOWA: true
  • KRAJOWA: false
EE Boolean true; false N Usługi telekomunikacyjne, nadawcze, elektroniczne (oznaczenie JPK).
domyślnie: false
TP Boolean true; false N Istnieją powiązania nabywcy ze sprzedawcą (oznaczenie JPK).
domyślnie: false
MPP Boolean true; false N Obowiązkowy mechanizm podzielonej płatności (oznaczenie JPK).
domyślnie: false
BSPV Boolean true; false N Transfer bonu jednego przeznaczenia we własnym imieniu (oznaczenie JPK).
domyślnie: false
BSPVDostawa Boolean true; false N Sprzedaż, której dotyczy bon jednego przeznaczenia na rzecz emitera (oznaczenie JPK).
domyślnie: false
BMPVProwizja Boolean true; false N Usługi pośrednictwa i inne dotyczące transferu bonu różnego przeznaczenia. (oznaczenie JPK).
domyślnie: false

Przykładowa zawartość żądania (JSON):

{
	"TypSprzedazy": "WYSYLKOWA",
	"LiczOd": "BRT",
	"NumerKontaBankowego": null,
	"DataWystawienia": "2014-10-22",
	"MiejsceWystawienia": "Kobierzyce",
	"DataSprzedazy": "2014-10-22",
	"FormatDatySprzedazy": "DZN",
	"TerminPlatnosci": null,
	"SposobZaplaty": "PRZ",
	"NazwaSeriiNumeracji": "default",
	"NazwaSzablonu": "logo",
	"Jezyk": "en",
	"Waluta": "EUR",
	"KursWalutyWidoczny": true,
	"KursWalutyZDniaPoprzedzajacegoDzienWystawieniaFaktury": 4.0823,
	"RodzajPodpisuOdbiorcy": "OUP",
	"PodpisOdbiorcy": "John Malkovich",
	"PodpisWystawcy": "Andrzej Krzywy",
	"Uwagi": "Order No. 3141592653",
	"WidocznyNumerGios": true,
	"Numer": null,
	"Pozycje": 
	[
		{
			"StawkaVat": 0.05,
			"Ilosc": 3,
			"CenaJednostkowa": 47.14,
			"NazwaPelna": "Neseser",
			"NazwaPelnaObca": "Briefcase",
			"Jednostka": "sztuk",
			"JednostkaObca": "pcs",
			"TypStawkiVat": "PRC"
		}
	],
	"Kontrahent": 
	{
		"Nazwa": "John Malkovich",
		"Identyfikator": null,
		"PrefiksUE": null,
		"NIP": null,
		"Ulica": "234 Laurier Avenue West",
		"KodPocztowy": "K1A 0G9",
		"Kraj": "Kanada",
		"Miejscowosc": "Ottawa",
		"Email": "john@malkovich.com",
		"Telefon": "18003031282",
		"OsobaFizyczna": true
	}
}

Przykład żądania POST (PHP)

$requestContent = '{"TypSprzedazy": "WYSYLKOWA","LiczOd": "BRT","NumerKontaBankowego": null,"DataWystawienia": "2014-10-22","MiejsceWystawienia": "Kobierzyce","DataSprzedazy":"2014-10-22", "FormatDatySprzedazy":"DZN", "TerminPlatnosci":null,"SposobZaplaty":"PRZ","NazwaSeriiNumeracji":"default","NazwaSzablonu":"logo","Jezyk":"en","Waluta":"EUR","KursWalutyWidoczny":true,"KursWalutyZDniaPoprzedzajacegoDzienWystawieniaFaktury":4.0823,"RodzajPodpisuOdbiorcy": "OUP","PodpisOdbiorcy": "John Malkovich","PodpisWystawcy": "Andrzej Krzywy","Uwagi": "Order No. 3141592653","WidocznyNumerGios": true,"Numer": null,"Pozycje":[{"StawkaVat": 0.05,"Ilosc": 3,"CenaJednostkowa": 47.14,"NazwaPelna": "Neseser","NazwaPelnaObca": "Briefcase","Jednostka": "sztuk","JednostkaObca": "pcs","TypStawkiVat": "PRC"}],"Kontrahent":{"Nazwa": "John Malkovich","Identyfikator": null,"PrefiksUE": null,"NIP": null,"Ulica": "234 Laurier Avenue West","KodPocztowy": "K1A 0G9","Kraj": "Kanada","Miejscowosc": "Ottawa","Email": "john@malkovich.com","Telefon": "18003031282","OsobaFizyczna": true}}';

$klucz = ””;
$url = ””;
$nazwaUsera = ””;
$nazwaKlucza = ”faktura”;
$curlHandle = curl_init($url);

$hashWiadomosci = hmac($klucz, $url.$nazwaUsera.$nazwaKlucza.$requestContent);
$headers = array(
	'Accept: application/json',
	'Content-type: application/json; charset=UTF-8',
	'Authentication: IAPIS user='.$nazwaUsera.', hmac-sha1='.$hashWiadomosci
);

curl_setopt($curlHandle, CURLOPT_TIMEOUT, 300);
curl_setopt($curlHandle, CURLOPT_CONNECTTIMEOUT, 100);
curl_setopt($curlHandle, CURLOPT_URL, $url);
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curlHandle, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curlHandle, CURLOPT_HTTPGET, false);
curl_setopt($curlHandle, CURLOPT_POST, true);
curl_setopt($curlHandle, CURLOPT_POSTFIELDS, $requestContent);
curl_setopt($curlHandle, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($curlHandle, CURLOPT_SSL_VERIFYPEER, 0);

$rsp = curl_exec($curlHandle);

gdzie:

  • klucz – wygenerowany klucz dostępny w serwisie ifirma.pl;
  • url – url, pod który wysyłamy żądanie;
  • nazwaUsera – login do serwisu ifirma.pl;
  • nazwaKlucza – identyfiktorKlucza –  wartość  „faktura”;
  • requestContent – zawartość żądania;

W rezultacie 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”: ”1244512”
	}
}

Zmiany dla nievatowca

Zmiany w formacie żądania dla nievatowca (niezależnie od waluty):

Nazwa w JSON Typ danych Wartości Wymagane Opis
LiczOd String BRT T Określa fakturę jako wystawioną od brutto
SplitPayment pole niedostępne
Pozycje
StawkaVat Number Null T Wskazanie na zwolnienie z VAT
TypStawkiVat String ZW T Określenie typu stawki podatku VAT
PKWiU pole niedostępne
GTU pole niedostępne
PodstawaPrawna String Numer artykułu, uprawniającego do zwolnienia, np. dla zwolnienia podmiotowego: Art. 113 ust. 1 T Podstawa prawna zwolnienia
ProceduryJPK obiekt niedostępny

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":
	[
		{
			"StawkaVat": 0.23,
			"StawkaRyczaltu": 0.03,
			"Ilosc": 3,
			"CenaJednostkowa": 47.14,
			"NazwaPelna": "Neseser",
			"NazwaPelnaObca": "Briefcase",
			"Jednostka": "sztuk",
			"JednostkaObca": "pcs",
			"TypStawkiVat": "PRC"
		}
	],
	:
}

Wykorzystanie danych kontrahenta zapisanego w bazie użytkownika

Wystawiając fakturę 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 przekazanego w polu IdentyfikatorKontrahenta.
  2. Nieodnalezienie pasującego kontrahenta po podanym identyfikatorze lub niepodanie pola IdentyfikatorKontrahenta powoduje wyszukanie kontrahenta po prefiksie UE i numerze NIP podanymi w polach PrefiksUEKontrahenta i NIPKontrahenta.
  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

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

https://www.ifirma.pl/iapi/fakturawaluta/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/2014 to 314_2014);
  • 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/fakturawaluta/1244521.xml

Pobierając fakturę w formacie PDF, można pobrać jej duplikat poprzez wskazanie w żądaniu parametru typ jako dup.
Przykład:

https://www.ifirma.pl/iapi/fakturawaluta/1244521.pdf?typ=dup

Duplikat będzie zawierał datę wystawienia zgodną z datą jego pobrania.

Pobierając fakturę sprzedaży wysyłkowej z terytorium kraju w formacie PDF, możliwy jest również wybór głównego języka faktury poprzez dodanie parametru jezykWydruku w żądaniu.
Parametr może przyjąć następujące wartości:

  • polski – głównym językiem faktury będzie język polski
  • obcy – głównym językiem faktury będzie język obcy

Przykłady żądań z parametrem:

https://www.ifirma.pl/iapi/fakturawaluta/1244521.pdf?jezykWydruku=polski
https://www.ifirma.pl/iapi/fakturawaluta/1244521.pdf?jezykWydruku=obcy

Przykład żądania GET (PHP):

$klucz = ””;
$url = ””;
$nazwaUsera = ””;
$nazwaKlucza = ”faktura”;

$curlHandle = curl_init($url);

$hashWiadomosci = hmac($klucz, $url.$nazwaUsera.$nazwaKlucza);
$headers = array(
	'Accept: application/pdf',
	'Content-type: application/pdf; charset = UTF-8',
	'Authentication: IAPIS user='.$nazwaUsera.', hmac-sha1='.$hashWiadomosci
);
curl_setopt($curlHandle, CURLOPT_TIMEOUT, 300);
curl_setopt($curlHandle, CURLOPT_CONNECTTIMEOUT, 100);
curl_setopt($curlHandle, CURLOPT_URL, $url);
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curlHandle, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curlHandle, CURLOPT_HTTPGET, true);
curl_setopt($curlHandle, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($curlHandle, CURLOPT_SSL_VERIFYPEER, 0);

$rsp = curl_exec($curlHandle);

gdzie:

  • klucz – wygenerowany klucz dostępny w serwisie ifirma.pl;
  • url – url, pod który wysyłamy żądanie;
  • nazwaUsera – login do serwisu ifirma.pl;
  • nazwaKlucza – identyfiktorKlucza –  wartość  „faktura”;

Pobieranie listy wystawionych faktur

Możliwe jest również pobranie listy faktur sprzedaży wysyłkowej z terytorium kraju i sprzedaży krajowej. W tym celu należy wysłać żądanie (GET) na adres:
https://www.ifirma.pl/iapi/fakturawaluta/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 faktur z użyciem parametru limit
      Przykład dla pobrania listy ostatnich 10 faktur:
https://www.ifirma.pl/iapi/fakturawaluta/list.json?limit=10
    1. Pobranie listy faktur wystawionych w określonym następujacymi parametrami przedziale czasu:
      • dzienOd
      • miesiacOd
      • rokOd
      • dzienDo
      • miesiacDo
      • rokDo

      Przykład dla pobrania listy faktur wystawionych pomiędzy 10 kwietnia 2014 a 6 czerwca 2014:

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

Copyright 2001-2024 ifirma.pl