Site icon Pomoc serwisu ifirma.pl

Rachunek krajowy

dsankowski

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

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

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:

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.055l 0.85; 0.17; 0.20 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:

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:

Przykład:

https://www.ifirma.pl/iapi/rachunekkraj/2861479.xml

Pobierając dowolny rachunek 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/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:

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. 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. 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
Exit mobile version