Dokumentacja API - ifirma.pl
Faktura pro forma
- Wystawianie faktur pro forma dla sprzedaży krajowej, usług budowlanych oraz zaliczek
- Zmiany dla ryczałtowca
- Wykorzystanie danych kontrahenta istniejącego w bazie
- Pobieranie wystawionej faktury pro forma
- Wystawianie faktury krajowej do faktury pro forma
- Wystawianie jednocześnie faktury pro forma oraz faktury z nią powiązanej
- Wyszukiwanie faktur po numerze zamówienia
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.jsonPrzesył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; 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ę |
| 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) |
| 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 |
| 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 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 |
| 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):
{
"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:
- 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”: ”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.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",
"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:
- 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 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.formatgdzie:
- 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/fakturaproformakraj/3654778.xmlPobierają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/fakturaproformakraj/1244521.pdf?typ=dupDuplikat 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);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ść „faktura”
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.jsongdzie:
- 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);
Przykład:
https://www.ifirma.pl/iapi/fakturaproformakraj/add/3654778.jsonWystawianie 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.jsonPrzykład:
https://www.ifirma.pl/iapi/fakturaproformakraj/find/32547965.jsonW 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.
Copyright 2001-2024 ifirma.pl