- Wystawianie faktury świadczenia usług poza terytorium kraju – kwoty określone w PLN
- Wystawianie faktury świadczenia usług poza terytorium kraju – kwoty w walucie obcej
- Zmiany dla ryczałtowca
- Wykorzystanie danych kontrahenta istniejącego w bazie
- Pobieranie wystawionej faktury świadczenia usług poza terytorium kraju
- Pobieranie listy wystawionych faktur świadczenia usług poza terytorium kraju
Wystawianie faktury świadczenia usług poza terytorium kraju – kwoty określone w PLN
W celu wystawienia faktury należy skonstruować żądanie (POST) w formacie JSON na adres:
https://www.ifirma.pl/iapi/fakturaeksportuslug.json
Przesyłane żądanie jest zestawem danych faktury w formacie przedstawionym poniżej.
Nazwa w JSON | Typ danych | Wartości | Wymagane | Opis |
---|---|---|---|---|
NazwaUslugi | String | <= 300 znaków | T | Nazwa usługi |
UslugaSwiadczonaTrybArt28b | Boolean | true; false |
T | Oznaczenie usługi wykonywanej w trybie artykułu 28b ustawy |
ZaplaconoNaDokumencie | Number | >= 0.00; <= razem brutto faktury; <= 10 cyfr; < 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 GIOŚ na fakturze |
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 |
Pozycje | ||||
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 |
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 | 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 |
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",
"UslugaSwiadczonaTrybArt28b": true,
"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","UslugaSwiadczonaTrybArt28b": true,"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);
$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 żadania:
{
”response”: {
”Kod”: 0,
”Informacja”: ”Faktura została pomyślnie dodana.”,
”Identyfikator”: ”1244512”
}
}
Wystawianie faktury świadczenia usług poza terytorium kraju – kwoty w walucie obcej
W celu wystawienia faktury należy skonstruować żądanie (POST) w formacie JSON na adres:
https://www.ifirma.pl/iapi/fakturaeksportuslug.json
Przesyłane żądanie jest zestawem danych faktury w formacie przedstawionym poniżej.
Nazwa w JSON | Typ danych | Wartości | Wymagane | Opis |
---|---|---|---|---|
NazwaUslugi | String | <= 300 znaków | T | Nazwa usługi |
UslugaSwiadczonaTrybArt28b | Boolean | true; false |
T | Oznaczenie usługi wykonywanej w trybie artykułu 28b ustawy |
ZaplaconoNaDokumencie | Number | >= 0.00; <= razem brutto faktury; <= 10 cyfr; < 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 | 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) | 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 GIOŚ na fakturze |
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 |
Pozycje | ||||
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 |
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 | 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 |
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",
"UslugaSwiadczonaTrybArt28b": true,
"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
}
}
Przykład żądania POST (PHP)
$requestContent = '{"NazwaUslugi": "Projekt strony internetowej","UslugaSwiadczonaTrybArt28b": true,"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}}';
$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 żadania:
{
”response”: {
”Kod”: 0,
”Informacja”: ”Faktura została pomyślnie dodana.”,
”Identyfikator”: ”1244512”
}
}
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.
{
:
"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
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 prefiksie 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/fakturaeksportuslug/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/fakturaeksportuslug/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/fakturaeksportuslug/identyfikator_faktury.pdf.typ
Przykład:
https://www.ifirma.pl/iapi/fakturaeksportuslug/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/fakturaeksportuslug/1244521.pdf?jezykWydruku=polski
https://www.ifirma.pl/iapi/fakturaeksportuslug/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 przesyłane jest żądanie;
- nazwaUsera – login do serwisu ifirma.pl
- nazwaKlucza – identyfikator klucza – wartość „faktura”
Pobieranie listy wystawionych faktur świadczenia usług poza terytorium kraju
Mozliwe jest również pobranie listy faktur świadczenia usług poza terytorium kraju. W tym celu należy wysłać żądanie (GET) na adres:
https://www.ifirma.pl/iapi/fakturaeksportuslug/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 poza terytorium kraju z użyciem parametru limit
Przykład dla pobrania listy ostatnich 10 faktur:
- Pobranie listy ze wskazaną liczbą ostatnich faktur świadczenia usług poza terytorium kraju z użyciem parametru limit
https://www.ifirma.pl/iapi/fakturaeksportuslug/list.json?limit=10
-
- 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:
- Pobranie listy faktur wystawionych w określonym następujacymi parametrami przedziale czasu:
https://www.ifirma.pl/iapi/fakturaeksportuslug/list.json?dzienOd=10&miesiacOd=04&rokOd=2014&dzienDo=06&miesiacDo=06&rokDo=2014