Rachunek krajowy

Wystawianie rachunku sprzedaży krajowej towarów i usług
Zmiany dla ryczałtowca
Wykorzystanie danych kontrahenta istniejącego w bazie
Pobieranie wystawionego rachunku sprzedaży krajowej towarów i usług
Pobieranie listy wystawionych rachunków sprzedaży krajowej towarów i usług

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

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

https://www.ifirma.pl/iapi/rachunekkraj.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 rachunku; <= 10 cyfr; < 100000000	T	Kwota wpłat za rachunek
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 rachunku wcześniejszego; <= data sprzedaży + 90 dni	T	Data wystawienia rachunku
MiejsceWystawienia	String	<= 50 znaków	N	Miejsce wystawienia rachunku
DataSprzedazy	String	Format: RRRR-MM-DD; jeśli bieżący miesiąc księgowy, to data bieżąca, 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ę
SposobZaplaty	String	GTK – gotówka; POB – za pobraniem; PRZ – przelew; KAR – karta; PZA – polecenie zapłaty; CZK – czek; KOM – kompensata; BAR – barter; DOT – DotPay; PAL – PayPal; ALG – PayU; P24 – Przelewy24; TPA – tpay.com; ELE – płatność elektroniczna;	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 rachunku
NazwaSzablonu	String	Jeśli nie zostanie podany, zostanie wybrany domyślny	N	Nazwa szablonu wystawianej rachunku
WpisDoKpir	String	NIE (brak wpisu); TOW (Wartość sprzredanych towarów i usług); POZ (Pozostałe przychody)	T	Określa czy i w jakiej kolumnie transakcja ma zostać zapisana w KPiR
PodpisOdbiorcy	String	<= 70 znaków	N	Podpis odbiorcy
PodpisWystawcy	String	<= 70 znaków	N	Podpis wystawcy
Uwagi	String	<= 1000 znaków	N	Uwagi na rachunku
Numer	Integer	<= 10 znaków; null (kolejny numer z podanej serii numeracji)	T	Numer wystawianego rachunku
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
Ilosc	Number	> 0.00; < 12 cyfr	T	Ilość towaru lub usługi
CenaJednostkowa	Number	> 0.00; <= 12 cyfr < 10000000	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
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 jest dostawcą (domyślnie: false)

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

{
    "Zaplacono": 78,
    "NumerKontaBankowego": null,
    "DataWystawienia": "2010-03-25",
    "MiejsceWystawienia": "Miasto",
    "DataSprzedazy": "2010-03-25",
    "FormatDatySprzedazy": "DZN",
    "TerminPlatnosci": null,
    "SposobZaplaty": "PRZ",
    "NazwaSeriiNumeracji": "default",
    "NazwaSzablonu": "logo",
    "WpisDoKpir": "TOW",
    "PodpisOdbiorcy": "Odbiorca",
    "PodpisWystawcy": "Wystawca",
    "Uwagi": "uwagi",
    "Numer": null,
    "Pozycje": [
        {
            "Ilosc": 1,
            "CenaJednostkowa": 78,
            "NazwaPelna": "cos",
            "Jednostka": "sztuk"
        }
    ],
    "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 = '{"Zaplacono": 78,"NumerKontaBankowego": null,"DataWystawienia": "2010-03-25","MiejsceWystawienia": "Miasto","DataSprzedazy": "2010-03-25","FormatDatySprzedazy": "DZN","TerminPlatnosci": null,"SposobZaplaty": "PRZ","NazwaSeriiNumeracji": "default","NazwaSzablonu": "logo","WpisDoKpir": "TOW","PodpisOdbiorcy": "Odbiorca","PodpisWystawcy": "Wystawca","Uwagi": "uwagi","Numer": null,"Pozycje":[{"Ilosc": 1,"CenaJednostkowa": 78,"NazwaPelna": "cos","Jednostka": "sztuk"}],"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 = "rachunek";
$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ść „rachunek”
requestContent – zawartość żądania

W rezultacie zwracany jest identyfikator rachunku oraz kod wiadomości mówiący o poprawności wykonania żadania:

{
	”response”: {
		”Kod”: 0,
		”Informacja”: ”Rachunek został pomyślnie dodany.”,
		”Identyfikator”: ”2861479”
	}
}

Zmiany dla ryczałtowca

W przypadku wystawiania rachunku przez ryczałtowca należy zmodyfikować przesyłane żądanie w następujący sposób:

pole WpisDoKpir powinno zawierać wartość NIE;
dodać pole WpisDoEwidencji do głównej struktury żądania;
dodać pole StawkaRyczaltu do każdej z pozycji na rachunku.

Nazwa w JSON	Typ danych	Wartości	Wymagane	Opis
WpisDoKpir	String	NIE	T	Określa czy i w jakiej kolumnie transakcja ma zostać zapisana w KPiR
WpisDoEwidencji	String	TAK; NIE	T	Określa czy transakcja ma zostać zapisana w Ewidencji Przychodów
Pozycje
StawkaRyczaltu	Number	0.03; 0.055; 0.85; 0.1; 0.125; 0.15; 0.17	T	Stawka ryczałtu pozycji rachunku

{
    "Zaplacono": 78,
    :
    "NazwaSzablonu": "logo",
    "WpisDoKpir": "NIE",
    "WpisDoEwidencji": "TAK",
    "PodpisOdbiorcy": "Odbiorca",
    :
    "Pozycje": [{
        "StawkaRyczaltu": 0.03,
        "Ilosc": 1,
        "CenaJednostkowa": 78.00,
        "NazwaPelna": "cos",
        "Jednostka": "sztuk",
    }],
    :
    }
}

Wykorzystanie danych kontrahenta istniejącego w bazie

Wystawiając rachunek sprzedaży krajowej towarów i usług można przypisać go 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 wystawionego rachunku sprzedaży krajowjej towarów i usług

Do pobrania wystawionego rachunku sprzedaży wysyłkowej towarów i usług wykorzystywany jest identyfikator rachunku, który jest zwracany w komunikacie potwierdzającym prawidłowe dodanie rachunku. Możliwe jest pobranie rachunku w wybranym formacie (PDF, JSON lub XML).
W celu pobrania rachunku należy skonstruować żądanie (GET) w formacie JSON na adres:
https://www.ifirma.pl/iapi/rachunekkraj/identyfikator_rachunku.format
gdzie:

identyfikator_rachunku – to identyfikator rachunku uzyskany w odpowiedzi po poprawnym wystawieniu rachunku, może zostać zastąpiony przez numer rachunku (w numerze rachunku 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/rachunekkraj/2861479.xml

Pobierając rachunek w formacie PDF, można pobrać jego duplikat poprzez wskazanie w żądaniu parametru typ jako dup.
Przykład:

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

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

Przykład żądania GET (PHP)

$klucz = "";
$url = "";
$nazwaUsera = "";
$nazwaKlucza = "rachunek";

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