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.

Nazwa w JSON	Typ danych	Wartości	Wymagane	Opis
Zaplacono	Number	>= 0.00; <= razem brutto faktury; <= 10 cyfr; < 100000000	T	Kwota wpłat za fakturę
LiczOd	String	NET (netto); BRT (brutto)	T	Sposób wystawiania faktury: od brutto lub od netto
NumerKontaBankowego	String	<= 28 znaków; BRAK (jeśli numer konta bankowego ma nie być wyświetlany)	N	Numer konta bankowego firmy
SplitPayment	Boolean	true; false	N	Dopisek Mechanizm Podzielonej Płatności (domyślna wartość zgodna z ustawieniami na koncie)
DataWystawienia	String	Format: RRRR-MM-DD; >= data sprzedaży; >= data wystawienia faktury wcześniejszej gdy; <= 15 dzień miesiąca następnego względem daty sprzedaży	T	Data wystawienia faktury
DataOtrzymaniaZaplaty	String	Format: RRRR-MM-DD; >= data sprzedaży	T	Data wystawienia faktury
MiejsceWystawienia	String	<= 50 znaków	N	Miejsce wystawienia faktury
DataSprzedazy	String	Format: RRRR-MM-DD; jeśli bieżący mc księgowy to bieżąca data, wpp ostatni dzień miesiąca	T	Data sprzedaży towaru lub usługi
FormatDatySprzedazy	String	DZN (dzienny); MSC (miesięczny)	T	Format daty sprzedaży
TerminPlatnosci	String	Format: RRRR-MM-DD; >= data sprzedaży	N	Termin płatności 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); BWO (bez podpisu odbiorcy i wystawcy)	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	Integer	<= 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	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 usługi lub CN towaru
GTU	String	BRAK, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13	N	Symbol GTU (grupy towarowo-usługowej)
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
KodKraju	String	2 znaki	N	Kod 3166-1 alfa-2 kraju siedziby kontrahenta Dla Grecji kod „EL”
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: false
JestDostawca	Boolean	true; false	N	Określa czy kontrahent i sprzedawca są ze sobą powiązani. domyślnie: false
PodmiotPowiazany	Boolean	true; false	N	Określa czy kontrahent jest podmiotem powiązanym ze sprzedawcą. domyślnie: false
ProceduryJpk (obiekt opcjonalny)
SW	Boolean	true; false	N	Sprzedaż wysyłkowa z terytorium kraju (oznaczenie JPK). domyślnie: false
EE	Boolean	true; false	N	Usługi telekomunikacyjne, nadawcze, elektroniczne (oznaczenie JPK). domyślnie: false
TP	Boolean	true; false	N	Istnieją powiązania nabywcy ze sprzedawcą (oznaczenie JPK). domyślnie: false
MPP	Boolean	true; false	N	Obowiązkowy mechanizm podzielonej płatności (oznaczenie JPK). domyślnie: false
BSPV	Boolean	true; false	N	Transfer bonu jednego przeznaczenia we własnym imieniu (oznaczenie JPK). domyślnie: false
BSPVDostawa	Boolean	true; false	N	Sprzedaż, której dotyczy bon jednego przeznaczenia na rzecz emitera (oznaczenie JPK). domyślnie: false
BMPVProwizja	Boolean	true; false	N	Usługi pośrednictwa i inne dotyczące transferu bonu różnego przeznaczenia. (oznaczenie JPK). domyślnie: false

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.

Nazwa w JSON	Typ danych	Wartości	Wymagane	Opis
StawkaRyczaltu	Number	0.03; 0.055; 0.85; 0.1; 0.125; 0.15; 0.17	T	Stawka ryczałtu pozycji faktury

{
	:
	"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:

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. 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”.
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 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 fakturę w formacie PDF, można pobrać jej duplikat poprzez wskazanie w żądaniu parametru typ jako dup.
Przykład:

https://www.ifirma.pl/iapi/fakturawysylka/1244521.pdf?typ=dup

Duplikat będzie zawierał datę wystawienia zgodną z datą jego pobrania.

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