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.

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.

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

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 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 dowolny rachunek w formacie PDF można dodatkowo wybrać typ:

• single – pojedynczy rachunek,
• double – podwójny rachunek,
• dup – duplikat rachunku.

Wyboru dokonuje się poprzez określenie typu w adresie, na który przesyłane jest żądanie:
https://www.ifirma.pl/iapi/rachunekkraj/identyfikator_rachunku.pdf.typ
Przykład:

https://www.ifirma.pl/iapi/rachunekkraj/2861479.pdf.single

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

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ść „rachunek”

Pobieranie listy wystawionych rachunków sprzedaży krajowej towarów i usług

Możliwe jest również pobranie listy rachunków krajowej sprzedaży towarów i usług. W tym celu należy wysłać żądanie (GET) na adres:
https://www.firma.pl/iapi/rachunekkraj/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 rachunków z użyciem parametru limit
      Przykład dla pobrania listy ostatnich 10 rachunków:

https://www.ifirma.pl/iapi/rachunekkraj/list.json?limit=10

1. 1. Pobranie listy rachunków wystawionych w określonym następujacymi parametrami przedziale czasu:
      • dzienOd
      • miesiacOd
      • rokOd
      • dzienDo
      • miesiacDo
      • rokDo

      Przykład dla pobrania listy rachunków wystawionych pomiędzy 10 kwietnia 2014 a 6 czerwca 2014:

https://www.ifirma.pl/iapi/rachunekkraj/list.json?dzienOd=10&miesiacOd=04&rokOd-2014&dzienDo=06&miesiacDo=06&rokDo=2014