Site icon Pomoc serwisu ifirma.pl

Faktura proforma

dsankowski

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.

Nazwa w JSON Typ danych Wartości Wymagane Opis
LiczOd String NET (netto);
BRT (brutto)		 T Sposób wystawiania faktury: od brutto lub od netto
TypFakturyKrajowej String SPRZ (krajowa sprzedaż);
BUD (budowlana);
ZAL (zaliczkowa)		 T Typ faktury krajowej, do której wystawiana jest pro forma
DataWystawienia String Format: RRRR-MM-DD;
>= data sprzedaży;
>= data wystawienia faktury wcześniejszej gdy;
<= 7 dni + data sprzedaży; <= ostatni dzień mc księgowego		 T Data wystawienia faktury
MiejsceWystawienia String <= 50 znaków N Miejsce wystawienia faktury
TerminPlatnosci String Format: RRRR-MM-DD;
>= data sprzedaży		 N Termin płatności za towar lub usługę
SposobZaplaty String GTK (gotówka); PRZ (przelew); KOM (kompensata); POB (za pobraniem); CZK – czek; KAR – karta; PAL – PayPal; ALG -PayU; DOT – DotPay; ELE – elektronicznie T Sposób zapłaty za towar lub usługę
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
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 Integer <= 10 znaków; null (kolejny numer z podanej serii numeracji) T Numer wystawianej faktury
NumerZamowienia String <= 30 znaków T Numer powiazanego z pro formą zamówienia
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 Null; 0.00; 0,05; 0.08; 0.23 T Stawka VAT pozycji faktury
Ilosc Number > 0.0000
;<= 12 cyfr		 T Ilość towaru lub usługi
CenaJednostkowa Number > 0.00;
<= 10 cyfr; < 100000000		 T Cena jednostkowa towaru lub usługi
NazwaPelna String >= 1 znak;
<= 300 znaków		 T Nazwa towaru lub usługi
Jednostka String >= 1 znak;
<= 10 znaków		 T Jednostka towaru lub usługi
PKWiU String <= 30 znaków N (dla TypStawkiVat != ZW) Symbol PKWiU towaru lub usługi
TypStawkiVat String PRC (procentowa);
ZW (zwolniona)		 T Typ stawki VAT obowiązującej dla towaru lub usługi
Rabat Number >=0;
< 100		 N Wysokość rabatu podawana w procentach
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 Identyfikatora 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 firmy kontrahenta
KodPocztowy String >= 1 znak;
<= 16 znaków		 T Kod pocztowy kontrahenta
Kraj String <= 70 znaków N Kraj siedziby firmy kontrahenta
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: true)
JestDostawca Boolean true; false N Określa czy kontrahent jest dostawcą (domyślnie: true)

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:

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.

Nazwa w JSON Typ danych Wartości Wymagane Opis
StawkaRyczaltu Number 0.03; 0.055l 0.85; 0.17; 0.20 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",
			"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:

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:

Przykład:

https://www.ifirma.pl/iapi/fakturaproformakraj/3654778.xml

Pobierając dowolną fakturę w formacie PDF można dodatkowo wybrać typ:

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:

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:

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.

Exit mobile version