Source: http://api.ifirma.pl/swiadczenie-uslug-dla-podatnikow-vat-ue-w-trybie-art-28b/
Timestamp: 2019-10-14 15:31:52
Legal References Found: art. 28
 art. 28
 art. 28
 art. 28
 art. 28
 art. 28
 art. 28
 art. 28

Document Content:
Świadczenie usług dla podatników VAT-UE w trybie art. 28b - Dokumentacja API
Dokumentacja API - ifirma.pl
Świadczenie usług dla podatników VAT-UE w trybie art. 28b
Wystawianie faktury świadczenia usług dla podatników VAT-UE w trybie art. 28b – kwoty określone w PLN
Wystawianie faktury świadczenia usług dla podatników VAT-UE w trybie art. 28b – kwoty w walucie obcej
Zmiany dla ryczałtowca
Wykorzystanie danych kontrahenta istniejącego w bazie
Pobieranie wystawionej faktury świadczenia usług dla podatników VAT-UE w trybie art. 28b
Pobieranie listy wystawionych faktur świadczenia usług dla podatników VAT-UE w trybie art. 28b
W celu wystawienia faktury należy skonstruować żądanie (POST) w formacie JSON na adres:
https://www.ifirma.pl/iapi/fakturaeksportuslugue.json
Przesyłane żądanie jest zestawem danych faktury w formacie przedstawionym poniżej.
Nazwa w JSON
NazwaUslugi String <= 300 znaków T Nazwa usługi
Zaplacono Number >= 0.00;
<= razem brutto faktury;
<= 10 cyfr;
< 100000000 T Suma wpłat za fakturę
ZaplaconoNaDokumencie Number >= 0.00;
< 100000000 N Kwota zapłacono na dokumencie
NumerKontaBankowego String <= 28 znaków;
BRAK (jeśli numer konta bankowego ma nie być wyświetlany) N Numer konta bankowego firmy
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
DataObowiazkuPodatkowego String Format: RRRR-MM-DD T Moment powstania obowiązku podatkowego
TerminPlatnosci String Format: RRRR-MM-DD;
>= data sprzedaży N Termin płatności za towar
SposobZaplaty String GTK (gotówka); PRZ (przelew); KOM (kompensata); CZK (czek); KAR (karta); PAL (PayPal); ALG (PayU); DOT (DotPay); ELE (elektronicznie) T Sposób zapłaty
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 wysatwianej 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) 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 String <= 10 znaków;
null (kolejny numer z podanej serii numeracji) T Numer wystawianej faktury
IdentyfikatorKontrahenta String <= 15 znaków N Identyfikator kontrahenta
PrefiksUEKontrahenta String <= 2 znaki N Prefiks UE kontrahenta
NIPKontrahenta String <= 13 znaków N Numer NIP kontrahenta
StawkaVat Number 0.00 T Stawka VAT pozycji faktury
Ilosc Number > 0.0000;
<= 12 cyfr T Ilosc 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 T Nazwa towaru w języku obcym
Jednostka String >= 1 znak;
<= 10 znaków T Jednostka towaru
JednostkaObca String >= 1 znak;
<= 10 znaków T Jednostka towaru w języku obcym
TypStawkiVat String PRC (procentowa) T Typ stawki VAT
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 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 siedziby kontrahenta
Kraj String >= 1 znak
<= 70 znaków T Kraj siedziby kontrahenta
Miejscowosc String <= 70 znaków N Miejscowość siedziby 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)
Przykładowa zawartość żądania (JSON)
"NazwaUslugi": "Projekt strony internetowej",
"Zaplacono": 101.42,
"ZaplaconoNaDokumencie": 141.42,
"NumerKontaBankowego": null,
"DataWystawienia": "2014-10-21",
"MiejsceWystawienia": "Kobierzyce",
"DataSprzedazy": "2014-10-21",
"FormatDatySprzedazy": "DZN",
"DataObowiazkuPodatkowego": "2014-10-21",
"TerminPlatnosci": null,
"SposobZaplaty": "PRZ",
"NazwaSeriiNumeracji": "default",
"NazwaSzablonu": "logo",
"Jezyk": "en",
"Waluta": "PLN",
"RodzajPodpisuOdbiorcy": "OUP",
"PodpisOdbiorcy": "Sean Connery",
"PodpisWystawcy": "Tomasz Markowski",
"Uwagi": "Order No. 3141592653",
"WidocznyNumerGios": true,
"Numer": null,
"Pozycje":
"StawkaVat": 0.00,
"Ilosc": 3,
"CenaJednostkowa": 47.14,
"NazwaPelna": "Neseser",
"NazwaPelnaObca": "Briefcase",
"Jednostka": "sztuk",
"JednostkaObca": "pcs",
"TypStawkiVat": "PRC"
"Kontrahent":
"Nazwa": "Sean Connery",
"Identyfikator": null,
"PrefiksUE": "GB",
"NIP": "8526547913",
"Ulica": "16 Rutland Square",
"KodPocztowy": "EH1 2BB",
"Kraj": "Great Britain",
"Miejscowosc": "Edinburgh",
"Email": "sean@connery.com",
"Telefon": "441316298347",
"OsobaFizyczna": true
Przykład żądania POST (PHP)
$requestContent = '{"NazwaUslugi": "Projekt strony internetowej","Zaplacono": 101.42,"ZaplaconoNaDokumencie": 141.42,"NumerKontaBankowego": null,"DataWystawienia": "2014-10-21","MiejsceWystawienia": "Kobierzyce","DataSprzedazy": "2014-10-21","FormatDatySprzedazy": "DZN","DataObowiazkuPodatkowego": "2014-10-21","TerminPlatnosci": null,"SposobZaplaty": "PRZ","NazwaSeriiNumeracji": "default","NazwaSzablonu": "logo","Jezyk": "en","Waluta": "PLN","RodzajPodpisuOdbiorcy": "OUP","PodpisOdbiorcy": "Sean Connery","PodpisWystawcy": "Tomasz Markowski","Uwagi": "Order No. 3141592653","WidocznyNumerGios": true,"Numer": null,"Pozycje":[{"StawkaVat": 0.00,"Ilosc": 3,"CenaJednostkowa": 47.14,"NazwaPelna": "Neseser","NazwaPelnaObca": "Briefcase","Jednostka": "sztuk","JednostkaObca": "pcs","TypStawkiVat": "PRC"}],"Kontrahent":{"Nazwa": "Sean Connery","Identyfikator": null,"PrefiksUE": "GB","NIP": "8526547913","Ulica": "16 Rutland Square","KodPocztowy": "EH1 2BB","Kraj": "Great Britain","Miejscowosc": "Edinburgh","Email": "sean@connery.com","Telefon": "441316298347","OsobaFizyczna": true}}';
$klucz = ””;
$url = ””;
$nazwaUsera = ””;
$nazwaKlucza = ”faktura”;
$curlHandle = curl_init($url);
$hashWiadomosci = hmac($klucz, $url.$nazwaUsera.$nazwaKlucza.$requestContent);
'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_HTTPGET, false);
curl_setopt($curlHandle, CURLOPT_POSTFIELDS, $requestContent);
curl_setopt($curlHandle, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($curlHandle, CURLOPT_SSL_VERIFYPEER, 0);
$rsp = curl_exec($curlHandle);
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 żadania:
”response”: {
”Kod”: 0,
”Informacja”: ”Faktura została pomyślnie dodana.”,
”Identyfikator”: ”1244512”
DataSprzedazy String Format: RRRR-MM-DD T Data sprzedaży towaru
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
< 100000000 T Kurs waluty obcej z dnia poprzedzającego dzień wystawienia faktury
"Waluta": "EUR",
"KursWalutyWidoczny": true,
"KursWalutyZDniaPoprzedzajacegoDzienWystawieniaFaktury": 4.0843,
$requestContent = '{"NazwaUslugi": "Projekt strony internetowej","NumerKontaBankowego": null,"DataWystawienia": "2014-10-21","MiejsceWystawienia": "Kobierzyce","DataSprzedazy": "2014-10-21","FormatDatySprzedazy": "DZN","DataObowiazkuPodatkowego": "2014-10-21","TerminPlatnosci": null,"SposobZaplaty": "PRZ","NazwaSeriiNumeracji": "default","NazwaSzablonu": "logo","Jezyk": "en","Waluta": "EUR","KursWalutyWidoczny": true,"KursWalutyZDniaPoprzedzajacegoDzienWystawieniaFaktury": 4.0843,"RodzajPodpisuOdbiorcy": "OUP","PodpisOdbiorcy": "Sean Connery","PodpisWystawcy": "Tomasz Markowski","Uwagi": "Order No. 3141592653","WidocznyNumerGios": true,"Numer": null,"Pozycje": [{"StawkaVat": 0.00,"Ilosc": 3,"CenaJednostkowa": 47.14,"NazwaPelna": "Neseser","NazwaPelnaObca": "Briefcase","Jednostka": "sztuk","JednostkaObca": "pcs","TypStawkiVat": "PRC"}],"Kontrahent":{"Nazwa": "Sean Connery","Identyfikator": null,"PrefiksUE": "GB","NIP": "8526547913","Ulica": "16 Rutland Square","KodPocztowy": "EH1 2BB","Kraj": "Great Britain","Miejscowosc": "Edinburgh","Email": "sean@connery.com","Telefon": "441316298347","OsobaFizyczna": true}}';
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.
"StawkaVat": 0.23,
"StawkaRyczaltu": 0.03,
Wykorzystanie danych kontrahenta zapisanego w bazie użytkownika
Wystawianą fakturę można przypisać 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:
Wyszukiwanie w pierwszej kolejności odbywa się po identyfikatorze kontrahenta przekazanym w polu IdentyfikatorKontrahenta.
Nieodnalezienie pasującego kontrahenta po podanym identyfikatorze lub niepodanie pola IdentyfikatorKontrahenta powoduje wyszukanie kontrahenta po proefiksie UE i numerze NIP przekazanym w polach PrefiksUEKontrahenta i NIPKontrahenta
Brak dopasowania na podstawie powyższych pól powoduje utworzenie w bazie nowego kontrahenta na podstawie danych z obiektu Kontrahent.
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/fakturaeksportuslugue/identyfikator_faktury.format
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.
https://www.ifirma.pl/iapi/fakturaeksportuslugue/1244521.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/fakturaeksportuslugue/identyfikator_faktury.pdf.typ
https://www.ifirma.pl/iapi/fakturaeksportuslugue/1244521.pdf.single
Pobierając fakturę 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/fakturaeksportuslugue/1244521.pdf?jezykWydruku=polski
https://www.ifirma.pl/iapi/fakturaeksportuslugue/1244521.pdf?jezykWydruku=obcy
Przykład żądania GET (PHP)
$hashWiadomosci = hmac($klucz, $url.$nazwaUsera.$nazwaKlucza);
'Accept: application/pdf',
'Content-type: application/pdf; charset = UTF-8',
url – url, pod który przesyłane jest żądanie;
nazwaUsera – login do serwisu ifirma.pl
nazwaKlucza – identyfikator klucza – wartość „faktura”
Mozliwe jest również pobranie listy faktur świadczenia usług dla podatników VAT-UE w trybie art. 28b. W tym celu należy wysłać żądanie (GET) na adres:
https://www.ifirma.pl/iapi/fakturaeksportuslugue/list.json?parametry
gdzie jako parametry można zdefiniować, które faktury mają się znaleźć na liście. Możliwe jest:
Pobranie listy ze wskazaną liczbą ostatnich faktur świadczenia usług dla podatników VAT-UE w trybie art. 28b z użyciem parametru limit
Przykład dla pobrania listy ostatnich 10 faktur:
https://www.ifirma.pl/iapi/fakturaeksportuslugue/list.json?limit=10
Pobranie listy faktur wystawionych w określonym następujacymi parametrami przedziale czasu:
dzienOd
miesiacOd
dzienDo
miesiacDo
Przykład dla pobrania listy faktur wystawionych pomiędzy 10 kwietnia 2014 a 6 czerwca 2014:
https://www.ifirma.pl/iapi/fakturaeksportuslugue/list.json?dzienOd=10&miesiacOd=04&rokOd=2014&dzienDo=06&miesiacDo=06&rokDo=2014
Informacje ogólne o API
Aktywacja API
Sprawdzanie limitu API
Niezbędne informacje oraz wysyłanie żądania
Nagłówek autoryzacji
Pobranie i zmiana ustawionego miesiąca księgowego
Faktura krajowa
Faktura wysyłkowa
Faktura wysyłkowa z terytorium kraju / krajowa z ceną w walucie obcej
Faktura eksportu towarów
Świadczenie usług poza terytorium kraju
Pro forma do faktury eksportowej
Faktura krajowa (nievatowiec)
Rachunek krajowy
Rejestrowanie wpłat do faktur
Wysyłanie faktur pocztą tradycyjną oraz na adres e-mail kontrahenta
Kody i identyfikatory
Copyright 2001-2019 ifirma.pl