Faktura wysyłkowa

• Wystawianie faktury sprzedaży wysyłkowej towarów i usług
• Zmiany dla ryczałtowca
• Wykorzystanie danych kontrahenta istniejącego w bazie
• Pobieranie wystawionej faktury sprzedaży wysyłkowej towarów i usług
• Pobieranie listy wystawionych faktur sprzedaży wysyłkowej krajowej towarów i usług

Wystawianie faktury sprzedaży krajowej towarów i usług

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

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

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

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

{
    "Zaplacono": 78,
    "LiczOd": "BRT",
    "NumerKontaBankowego": null,
    "DataWystawienia": "2010-05-25",
    "MiejsceWystawienia": "Miasto",
    "DataSprzedazy": "2010-05-25",
    "DataOtrzymaniaZaplaty": "2010-06-01",
    "FormatDatySprzedazy": "DZN",
    "TerminPlatnosci": null,
    "NazwaSeriiNumeracji": "default",
    "NazwaSzablonu": "logo",
    "RodzajPodpisuOdbiorcy": "OUP",
    "PodpisOdbiorcy": "Odbiorca",
    "PodpisWystawcy": "Wystawca",
    "Uwagi": "uwagi",
    "WidocznyNumerGios": true,
    "Numer": null,
    "Pozycje": [{
        "StawkaVat": 0.23,
        "Ilosc": 1,
        "CenaJednostkowa": 78.00,
        "NazwaPelna": "cos",
        "Jednostka": "sztuk",
        "PKWiU": "",
        "TypStawkiVat": "PRC"
    }],
    "Kontrahent": {
        "Nazwa": "Imie Nazwisko",
        "Identyfikator": null,
        "PrefiksUE": null,
        "NIP": null,
        "Ulica": "Ulica",
        "KodPocztowy": "11-111",
        "Kraj": "Polska",
        "Miejscowosc": "Miejscowosc",
        "Email": "em@il.pl",
        "Telefon": "111111111",
        "OsobaFizyczna": true
    }
}

Przykład żądania POST (PHP)

$requestContent ='{"Zaplacono":78,"LiczOd":"BRT","NumerKontaBankowego":null,"DataWystawienia":"2010-03-25","MiejsceWystawienia":"Miasto","DataSprzedazy":"2010-03-25","FormatDatySprzedazy":"DZN","TerminPlatnosci":null,"NazwaSeriiNumeracji":"default","NazwaSzablonu":"logo","RodzajPodpisuOdbiorcy":"OUP","PodpisOdbiorcy":"Odbiorca","PodpisWystawcy":"Wystawca","Uwagi":"uwagi","WidocznyNumerGios":true,"Numer":null,"Pozycje":[{"StawkaVat":0.23,"Ilosc":1,"CenaJednostkowa":78.00,"NazwaPelna":"cos","Jednostka":"sztuk","PKWiU":"","TypStawkiVat":"PRC"}],"Kontrahent":{"Nazwa":"ImieNazwisko","Identyfikator":null,"PrefiksUE":null,"NIP":null,"Ulica":"Ulica","KodPocztowy":"11-111","Kraj":"Polska","Miejscowosc":"Miejscowość","Email":"em@il.pl","Telefon":"111111111","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",
			"Jednostka": "sztuk",
			"PKWiU": "",
			"TypStawkiVat": "PRC"
		}
	],
	:
}

Wykorzystanie danych kontrahenta zapisanego w bazie użytkownika

Wystawiając fakturę sprzedaży kwysyłkowej towarów i usług 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 sprzedaży wysyłkowej towarów i usług

Do pobrania wystawionej faktury sprzedaży wysyłkowej towarów i usług 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 faktury należy skonstruować żądanie (GET) w formacie JSON na adres:
https://www.ifirma.pl/iapi/fakturawysylka/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/fakturawysylka/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/fakturawysylka/identyfikator_faktury.pdf.typ
Przykład:

https://www.ifirma.pl/iapi/fakturawysylka/1244521.pdf.single

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łane jest żądanie
• nazwaUsera – login do serwisu ifirma.pl
• nazwaKlucza – identyfiktor klucza – wartość „faktura”

Pobieranie listy wystawionych faktur sprzedaży wysyłkowej towarów i usług

Możliwe jest również pobranie listy faktur krajowej sprzedaży towarów i usług. W tym celu należy wysłać żądanie (GET) na adres:
https://www.firma.pl/iapi/fakturawysylka/list.json?parametry
gdzie jako parametry można zdefiniować, które faktury mają się znaleźć na liście. Możliwe jest:

1. 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/fakturawysylka/list.json?limit=10

1. 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/fakturawysylka/list.json?dzienOd=10&miesiacOd=04&rokOd-2014&dzienDo=06&miesiacDo=06&rokDo=2014