Dokumentacja API - ifirma.pl

Faktura OSS / Dowód sprzedaży OSS


 

Faktury i dowody sprzedaży w procedurze OSS, opodatkowane są stawkami podatku VAT odpowiednimi dla kraju dostawy towaru (lub kraju usługobiorcy, w przypadku sprzedaży usług).

Udostępniamy możliwość pobrania aktualnych stawek VAT – więcej na stronie Stawki VAT w krajach Unii Europejskiej

 

Wystawianie faktury OSS

Wystawienie faktury OSS możliwe jest poprzez przesłania żądania POST w formacie JSON na adres:

https://www.ifirma.pl/iapi/fakturaoss.json

Klucz autoryzacji: FAKTURA

Przesyłane żądanie powinno zawierać zestaw danych faktury w formacie przedstawionym poniżej:

Nazwa w JSON Typ danych Wartości Wymagane Opis
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
FormatDatySprzedazy String DZN (dzienny) T Format daty sprzedaży
DataWystawienia String Format: RRRR-MM-DD;
>= data sprzedaży;
>=data wystawienia faktury wcześniejszej w tej samej serii numeracji;
<= 15 dzień miesiąca następnego względem daty sprzedaży		 T Data wystawienia faktury
MiejsceWystawienia String <= 50 znaków N Miejsce wystawienia faktury
NazwaSeriiNumeracji String Jeśli nie zostanie podana, zostanie wybrana domyślna N Nazwa serii numeracji dla faktury
Numer Integer <= 10 znaków;
null (kolejny numer z podanej serii numeracji)		 N Numer wystawianej faktury
NazwaSzablonu String Jeśli nie zostanie podany, zostanie wybrany domyślny N Nazwa szablonu wystawianej faktury
Jezyk String en (angielski); de (niemiecki); bg (bułgarski); hr (chorwacki); cs (czeski); da (duński); nl (niderlandzki); es (hiszpański); et (estoński); fi (fiński); fr (francuski); gr (grecki); hu (węgierski); it (włoski); lv (łotewski); lt (litewski); ru (rosyjski); sk (słowacki); sl (słoweński); sv (szwedzki) T Język faktury
Waluta String PLN; EUR; GBP; USD; CHF; NOK; JPY; CZK; LTL; UAH; RUB; AUD; DKK; CAD; LVL; RON; SEK; HUF; THB; HKD; NZD; SGD; ISK; HRK; BGN; TRY; ILS; CLP; PHP; MXN; ZAR; BRL; MYR; IDR; INR; KRW; CNY; XDR T Waluta na fakturze
KursWalutyZDniaPoprzedzajacegoDzienWystawieniaFaktury Number >= 0.0000; <= 10 cyfr; < 100000000 T/N Kurs waluty obcej z dnia poprzedzającego dzień wystawienia faktury.
Pola nie podaje się, gdy walutą faktury jest PLN.
LiczOd String NET (netto);
BRT (brutto)		 T Sposób wystawienia faktury: od netto lub od brutto
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
WidocznyNumerBdo Boolean true; false T Widoczność numeru BDO/GIOŚ na fakturze
SprzedazUslug Boolean true; false T Wartość true, jeśli przedmiotem sprzedaży są usługi;
false, jeśli przedmmiotem sprzedaży są towary.
UstalenieMiejscaUslugi1 String T/N Rodzaj dowodu potwierdzającego kraj usługobiorcy.
Pole wymagane, jeśli przedmiotem sprzedaży są usługi
UstalenieMiejscaUslugi2 String T/N Rodzaj dowodu potwierdzającego kraj usługobiorcy.
Pole wymagane, jeśli przedmiotem sprzedaży są usługi
KrajDostawy String 2 znaki T Dwuliterowy kod państwa dostawy/usługobiorcy zgodny z normą ISO 3166-1 alfa-2
KrajWysylki String 2 znaki T Dwuliterowy kod państwa wysyłki/usługodawcy zgodny z normą ISO 3166-1 alfa-2
IdentyfikatorKontrahenta String <= 15 znaków N Identyfikator kontrahenta
PrefiksUEKontrahenta String <= 2 znaków N Prefiks UE kontrahenta
NIPKontrahenta String <= 13 znaków N Numer NIP kontrahenta
Pozycje
NazwaPelna String >= 1 znak; <= 300 znaków T Nazwa towaru lub usługi
NazwaPelnaObca String >= 1 znak; <= 300 znaków T Nazwa towaru lub usługi w języku obcym
Jednostka String >= 1 znak; <= 10 znaków T Jednostka towaru lub usługi
JednostkaObca String >= 1 znak; <= 10 znaków T Jednostka towaru lub usługi w języku obcym
CenaJednostkowa Number > 0.00;<= 10 cyfr; < 100000000 T Cena jednostkowa towaru lub usługi
Ilosc Number > 0.0000 ;<= 12 cyfr T Ilość towaru lub usługi
StawkaVat Number Właściwa dla kraju dostawy
Procentowa stawka w formie ułamka dziesiętnego		 T Stawka VAT pozycji faktury, zgodna z krajem dostawy
TypStawkiVat String POD (podstawowa);
PR1 (obniżona pierwsza);
PR2 (obniżona druga);
PR3 (obniżona trzecia);
ZW (zwolniona)		 T Typ stawki VAT
Kontrahent
Nazwa String >= 1 znak; <= 150 znaków T Nazwa firmy kontrahenta
Nazwa2 String >= 1 znak; <= 150 znaków N Nazwa firmy kontrahenta
Identyfikator String >= 1; <= 15 znaków; null (zostanie wygenerowany automatycznie) N Identyfikator 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 kontrahenta
KodPocztowy String >= 1 znak; <= 16 znaków T Kod pocztowy kontrahenta
Kraj String <= 70 znaków T Kraj siedziby 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

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

{
	"DataSprzedazy":"2021-12-01",
	"FormatDatySprzedazy":"DZN",
	"DataWystawienia":"2021-12-01",
	"MiejsceWystawienia":"Kobierzyce",
	"NazwaSeriiNumeracji":null,
	"Jezyk":"en",
	"Waluta":"PLN",
	"LiczOd":"BRT",
	"RodzajPodpisuOdbiorcy":"OUP",
	"PodpisOdbiorcy":"John Malkovich",
	"PodpisWystawcy":"Tomasz Markowski",
	"Uwagi":"Order No. 3141592653",
	"WidocznyNumerBdo":false,
	"KrajDostawy":"CY",
	"KrajWysylki":"PL",
	"SprzedazUslug":false,
	"Pozycje":[
		{
			"NazwaPelna":"Neseser z przedłużką",
			"NazwaPelnaObca":"Briefcase with an extension",
			"Jednostka":"sztuk",
			"JednostkaObca":"pcs",
			"CenaJednostkowa":"13.00",
			"Ilosc":"1",
			"StawkaVat":"0.19",
			"TypStawkiVat":"POD"
		}
	],
	"Kontrahent": {
        "Nazwa": "John Malkovich",
        "Identyfikator": null,
        "PrefiksUE": null,
        "NIP": "null",
        "Ulica": "Kibris Dedektif 2",
	"Kraj": "Cypr",
	"KodKraju": "CY",
	"KodPocztowy": "",
	"AdresZagraniczny": true,
	"Miejscowosc": "Nicosia",
	"Telefon": "111111111",
	"OsobaFizyczna": true
    }}

 

Wystawianie dowodu sprzedazy OSS

Wystawienie dowodu sprzedaży OSS możliwe jest poprzez przesłanie żądania POST w formacie JSON na adres:

https://www.ifirma.pl/iapi/fakturaoss.json

Klucz autoryzacji: FAKTURA

Struktura przesyłanego żądania jest analogiczna do struktury przesyłanej dla wystawienia faktury, ale pozbawione danych kontrahenta, czyli żądanie nie powinno zawierać:

  • Obiektu Kontrahent
  • Pola IdentyfikatorKontrahenta
  • Pola PrefiksUEKontrahenta
  • Pola NIPKontrahenta

 

Pobieranie wystawionej faktury lub dowodu sprzedaży OSS

Do pobrania wystawionej faktury/dowodu sprzedaży OSS wykorzystywany jest identyfikator faktury/dowodu sprzedaży, który jest zwracany w komunikacie potwierdzającym prawidłowe dodanie faktury.
Faktura może zostać pobrana w jednym z trzech formatów: PDF, JSON, XML.

W celu pobrania dokumentu należy skonstruować żądanie GET w formacie JSON na adres:

https://www.ifirma.pl/iapi/fakturaoss/identyfikator_faktury.format

gdzie:

  • identyfikator_faktury – to identyfikator faktury lub dowodu sprzedaży uzyskany w odpowiedzi po poprawnym wystawieniu dokumentu, może zostać zastąpiony przez numer dokumentu (w numerze dokumentu 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ć dokument, czyli: PDF, JSON lub XML.

Przykład:

https://www.ifirma.pl/iapi/fakturaoss/1244521.pdf

Pobierając fakturę/dowód sprzedaży w formacie PDF możliwy jest również wybór głównego języka faktury poprzez dodanie parametru jezykWydruku w żądaniu.
Parametr może przyjąć następujące wartości:

  • polski – głównym językiem dokumentu będzie język polski
  • obcy – głównym językiem dokumentu będzie język obcy

Przykłady żądań z parametrem:

https://www.ifirma.pl/iapi/fakturaoss/1244521.pdf?jezykWydruku=polski
https://www.ifirma.pl/iapi/fakturaoss/1244521.pdf?jezykWydruku=obcy

Copyright 2001-2024 ifirma.pl