Faktura proforma

• Wystawianie faktur pro forma dla sprzedaży krajowej, usług budowlanych oraz zaliczek
• Zmiany dla ryczałtowca
• Wykorzystanie danych kontrahenta istniejącego w bazie
• Pobieranie wystawionej faktury pro forma
• Wystawianie faktury krajowej do faktury pro forma
• Wystawianie jednocześnie faktury pro forma oraz faktury z nią powiązanej
• Wyszukiwanie faktur po numerze zamówienia

Wystawianie faktur pro forma dla sprzedaży krajowej, usług budowlanych oraz zaliczek

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

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

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

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

{
    "LiczOd": "BRT",
    "NumerKontaBankowego": null,
    "TypFakturyKrajowej": "sprz",
    "DataWystawienia": "2010-03-25",
    "MiejsceWystawienia": "Miasto",
    "TerminPlatnosci": null,
    "SposobZaplaty": "PRZ",
    "PodpisWystawcy": "Wystawca",
    "Uwagi": "uwagi",
    "WidocznyNumerGios": true,
    "RodzajPodpisuOdbiorcy": "BPO",
    "NumerZamowienia": "21/2011",
    "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": "Miejscowość",
        "Email": "em@il.pl",
        "Telefon": "111111111",
        "OsobaFizyczna": true
    }
}

Przykład żądania POST (PHP)

$requestContent ='{"LiczOd": "BRT","NumerKontaBankowego": null,"TypFakturyKrajowej": "sprz","DataWystawienia": "2010-03-25","MiejsceWystawienia": "Miasto","TerminPlatnosci": null,"SposobZaplaty": "PRZ","PodpisWystawcy": "Wystawca","Uwagi": "uwagi","WidocznyNumerGios": true,"RodzajPodpisuOdbiorcy": "BPO","NumerZamowienia": "21/2011","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": "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”: ”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.

{
	:
	"Pozycje":
	[
		{
			"StawkaVat": 0.23,
			"StawkaRyczaltu": 0.03,
			"Ilosc": 3,
			"CenaJednostkowa": 47.14,
			"NazwaPelna": "Neseser",
			"NazwaPelnaObca": "Briefcase",
			"Jednostka": "sztuk",
			"JednostkaObca": "pcs",
			"PKWiU": "",
			"TypStawkiVat": "PRC"
		}
	],
	:
}

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 faktury należy skonstruować żądanie (GET) w formacie JSON na adres:

https://www.ifirma.pl/iapi/fakturaproformakraj/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/fakturaproformakraj/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/fakturaproformakraj/identyfikator_faktury.pdf.typ

Przykład:

https://www.ifirma.pl/iapi/fakturaproformakraj/3654778.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”

Wystawianie faktury krajowej do faktury pro forma

W celu wystawienia faktury krajowej do wystawionej faktury pro forma należy wysłać żądanie GET na adres:

https://www.ifirma.pl/iapi/fakturaproformakraj/add/identyfikator_faktury.json

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);

Przykład:

https://www.ifirma.pl/iapi/fakturaproformakraj/add/3654778.json

Wystawianie jednocześnie faktury pro forma oraz faktury z nią powiązanej

Możliwe jest jednoczesne wystawienie faktury pro forma wraz z właściwą fakturą sprzedaży krajowej (dotyczy to jedynie faktury krajowej sprzedaży towarów i usług).
W tym celu należy wysłać żądanie (POST) analogiczne jak przy wystawianiu samodzielnej faktury pro forma pod adres:
https://www.ifirma.pl/iapi/fakturaproformakraj/add.json

Wyszukiwanie faktur po numerze zamówienia

Możliwe jest wyszukanie faktur po numerze zamówienia przekazanym przy wystawianiu faktury pro forma w polu NumerZamowienia*.
W tym celu należy przesłać żądanie GET na adres:

https://www.ifirma.pl/iapi/fakturaproformakraj/find/numer_zamowienia.json

Przykład:

https://www.ifirma.pl/iapi/fakturaproformakraj/find/32547965.json

W rezultacie jako odpowiedź zwracana jest lista w formacie JSON zawierająca znalezione typy faktur (np. „PROFORMA” lub „FAKTURA_KRAJ”) oraz ich numery. Jeżeli do pro formy nie została wystawiona faktura, to zostanie zwrócony jedynie informacja o znalezionej pro formie.

* – pole NumerZamowienia jest dostępne jedynie poprzez API, dlatego w ten sposób można odnaleźć jedynie pro formy oraz związane z nimi faktury, które zostały wystawione przy wykorzystaniu API.