API - INTERFEJS DLA PROGRAMISTÓW

Uwaga! Zalecamy korzystać z nowego API, którego dokumentacja znajduje się pod adresem https://doc.wfirma.pl.
Stare API nie jest już rozwijane od kilku lat i w przyszłości zostanie wyłączone.
API - INTERFEJS DLA PROGRAMISTÓW (NIEAKTUALNE)

Serwis wFirma.pl udostępnia swoje możliwości dla zewnętrznych programów, umożliwiając:

  • wystawienia faktury VAT (lub proforma) i automatyczne dodanie kontrahenta
  • możliwość wybrania serii faktur
  • pobranie gotowej faktury VAT (oryginał, kopia lub obie strony, druczek przelewu, duplikat faktury)
  • wysłanie gotowej faktury na e-mail
  • wysłanie wiadomości systemowej
  • automatyczne zalogowanie na konto

Komunikacja odbywa się za pośrednictwem XML (SOAP) z kodowaniem znaków w utf-8.

Każda metoda sprawdza ważność sesji przed wywołaniem, jeżeli otrzymają Państwo odpowiedź ERR_SESSION oznacza to że sesja wygasła lub id sesji ($sid) jest nieprawidłowy.

Ogólne uwagi dotyczące formatu danych

  • pola z cenami, rabatami z formatem oznaczonym jako NUMERIC(X,Y) mogą zawierać kropkę lub przecinek jako oznaczenie miejsca dziesiętnego

Obsługiwane metody API

login($username, $password)

Funkcja login() umożliwia uzyskanie identyfikatora sesji $sid umożliwiającego wywołanie pozostałych metod serwisu. Logowanie jest możliwe tylko na główne konto na wFirma.pl

Możliwe odpowiedzi:

  • $r['status'] == 'OK' - logowanie do serwisu przebiegło prawidłowo, $r['response'] zawiera przydzielony identyfikator sesji
  • $r['status'] == 'ERR_LOGIN' - w od komunikatu w $r['response'] oznacza błędne dane logowania
  • $r['status'] == 'ERR_PACKAGE' - używanie API wFirma.pl wymaga posiadania konta Premium (Faktura Premium lub Księgowość premium, może być to też bezpłatny okres testowy, patrz Cennik)
Przykład (PHP):
$C = new SoapClient(null, array(      'uri' => "http://api.wfirma.pl/",      'location' => "http://api.wfirma.pl",      'trace' => 1,  ));    $r = $C->login('TWOJ_LOGIN','TWOJE_HASLO');  if ($r['status'] == 'OK') {      $sid = $r['response'];      // tutaj wywołanie innych metod ...  } else {      echo "Wystąpił błąd: {$r['status']}: {$r['response']}";  }  
addInvoice($sid, $invoiceHeader, $contactorDetails, $invoiceContents)Metoda ta możliwia wystawienie faktury VAT lub faktury pro forma. Mozliwe odpowiedzi:
  • $r['status'] == 'OK' - faktura została wystawiona, $r['response'] zawiera id faktury
  • $r['status'] == 'ERR_VALIDATION' - pola faktury zawierają błędy 
    $r['response']['invoice'] - zawiera opis błędnych danych nagłówka faktury, 
    $r['response']['invoiceContent'] zawiera informacje o błędnych pozycjach w fakturze, 
    $r['response']['contractorDetail'] zawiera informacje o błędnych danych kontrahenta.

Przykładowe parametry i ich opis (PHP)
// nagłówek faktury  $invoiceHeader = array(        'date' => '2009-01-01',             // data wystawienia,                                          // format (YYYY-MM-DD)        'disposaldate' => '2009-01-01',     // data sprzedaży,                                          // format (YYYY-MM-DD)        'paymentdate' => '2009-01-15',      // termin płatności,                                          // format (YYYY-MM-DD)        'paymentmethod' => 'transfer',      // metoda płatności                                          // możliwe wartości to                                          // cash, transfer i compensation        'paid' => 0,                        // opcjonalna flaga 0/1                                          // czy faktura została                                          // opłacona w całości,                                          // 0 jest wartością domyślną        'description' => 'Tutaj moje uwagi',// opcjonalne uwagi na fakturze,                                          // (max.320 znaków)        'auto_send' => '0',                 // opcjonalna flaga 0/1                                          // czy wysłać fakturę na                                          // adres e-mail kontrahenta,                                          // domyślna wartość to 0        'lump' => 'rate20',                 // opcjonalna stawka ryczałtu                                          // dla korzystających                                          // z pakietu Księgowości,                                          // możliwe wartości to: rate 20                                          // rate17, rate8_5, rate5_5, rate3,                                          // domyślna wartość,                                          // jeżeli nie zostanie                                          // podana, to rate20        'tax_evaluation_method' => 'netto', // określenie metody naliczania                                          // cen na fakturze,                                          // ceny w pozycjach faktury                                          // pozycji podawane                                          // netto lub brutto,                                          // domyślna wartość to netto        'series' => 'domyślna',  // opcjonalna nazwa serii faktur                               // w wybranym typie faktury (normal, proforma)        'type' => 'normal',   // opcjonalnie typ dokumentu, możliwe wartości:                            // normal - faktura VAT (wartość domyślna)                            // proforma - faktura proforma                            // bill - rachunek        'currency' => 'PLN',                // opcjonalnie waluta faktury,                                          // możliwe wartości:                                          // 'PLN' => 'złoty polski',                                          // 'EUR' => 'euro',                                          // 'USD' => 'dolar amerykański',                                          // 'GBP' => 'funt szterling',                                          // 'CHF' => 'frank szwajcarski',                                          // 'UAH' => 'hrywna (Ukraina)',                                          // 'CZK' => 'korona czeska',                                          // 'DKK' => 'korona duńska',                                          // 'EEK' => 'korona estońska',                                          // 'ISK' => 'korona islandzka',                                          // 'NOK' => 'korona norweska',                                          // 'SEK' => 'korona szwedzka',                                          // 'HRK' => 'kuna chorwacka',                                          // 'RON' => 'lej rumuński',                                          // 'BGN' => 'lew bułgarski',                                          // 'TRY' => 'lira turecka',                                          // 'LTL' => 'lit litewski',                                          // 'LVL' => 'łat łotewski',                                          // 'RUB' => 'rubel rosyjski'        'language' => 'pl',                 // opcjonalnie język faktury,                                          // możliwe wartości:                                          // 'pl' => 'polski',                                          // 'en' => 'pol-ang',                                          // 'de' => 'pol-niem',                                          // 'es' => 'pol-hisz',                                          // 'no' => 'pol-norw',        'account' => 'konto firmowe',   // opcjonalnie                                      // wybór konta bankowego                                      // wg nazwy konta                                      // konto musi być dodane                                      // w ustawieniach firmy        'schema' => 'normal',   // opcjonalnie                              // wybór schematu księgowego                              // możliwe wartości                              // 'normal' - zwykły (wartość domyślna)                              // 'fracht' - usługi transportowe i budowlane                              // 'small_taxpayer' - Faktura Małego Podatnika                              // 'assessor' - Faktura za opinię biegłego        'schema_bill' => 0,     // opcjonalnie                              // flaga 0/1 - faktura do paragonu        'template' => '3',   // opcjonalnie                              // wybór szablonu wydruku                              // jeżeli wartość nie jest podana                              // jest brana z ustawień konta                              // możliwe wartości:                              // 3 - Elegancki                              // 1 - Prosty                              // 4 - Gradient                              // 5 - Gradient II                              // 6 - Old school                              // 7 - Elegancki - mikro faktura                              // 9 - Elegancki - druk przelewu  );    // dane nabywcy  $contractorDetails = array(      'name' => 'Jan Kowalski',          // nazwa pełna kontrahenta        'tax_id_type' => 'nip',            // nip, vat, pesel, regon, custom, none        'nip' => '1871698429',             // NIP kontrahenta, bez spacji i kresek        'street' => 'Kwiatowa 5',          // Ulica, nr domu i lokalu        'zip' => '59-413',                 // kod pocztowy        'city' => 'Wrocław',               // miejscowość        'country' => 'PL',                 // opcjonalnie kod państwa        'email' => 'jan@kowalski-test.com',// opcjonalnie adres e-mail        'add' => 1                         // flaga 0/1 czy dopisać kontrahenta do katalogu                                         // (dopasowanie po NIP, jeśli taki kontrahent                                         // już jest to nie zostanie                                         // dodany ani zaktualizowany)  );    // pozycje towarów i usług na fakturze  $invoiceContents = array(      array(          'name' => 'Mysz komputerowa',  // nazwa towaru, max. 1024 znaki            'price' => '35,12',            // cenna netto lub brutto w zależności                                         // od ustawienia tax_evaluation_method w                                         // invoiceHeader, format NUMERIC(15,2)            'unit' => 'szt.',              // jednostka, max 64 znaki            'count' => '1',                // ilość towaru lub usługi, format NUMERIC(15,4)                                         // max. 15 cyfr i dwie cyfry po przecniku            'vatcode' => '23',             // opcjonalnie stawka VAT,                                         // możliwe wartości to                                         // 23, 8, 5, 0, WDT, EXP, NP, ZW                                         // domyślna wartość: 23            'classification' => '',        // opcjonalnie kod PKWiU dla obniżonych                                         // stawek VAT            'discount' => '25,00'          // opcjonalnie rabat w pozycji faktury,                                         // format NUMERIC(2,2)      )  );  

Przykład (PHP):
// zmienne $sid, $invoiceHeader i $contractorDetails i $invoiceContents z poprzednich przykładów    // wystawienie faktury  $r = $C->addInvoice($sid, $invoiceHeader, $contractorDetails, $invoiceContents);    if ($r['status']=='OK') {      $invoice_id = $r['response'];      $id_faktury = $r['object_id'];      // id faktury mozna wykorzystac np do wysyłania      // faktury na e-mail lub pobrania PDF z fakturą      // (patrz metody sendInvoice() i downloadInvoice())  } else {      // coś poszło nie tak      print_r($r['status']);      print_r($r['response']);  }  
downloadInvoice($sid, $invoice_id, $email, $options)

Funkcja służąca wygenerowania linku do pobrania wystawionej wcześniej faktury. Link po wygenerowaniu działa przez 10 minut!

Przykład i opis parametrów (PHP)
// $sid - id sesji zwrócony przez metodę login()  // $invoice_id - ID faktury zwrócony przez metodę addInvoice();    // dodatkowe ustawienia (opcjonalne)  $options = array(      'page' => 'invoice',            // którą stronę faktury załączyć, możliwe wartości to:                                      // invoice - oryginał                                      // invoicecopy - kopia                                      // all - wszystkie, wartość domyślna        'leaflet' => 0,                 // flaga 0/1 czy dołączyć druczek przelewu                                      // działa tylko dla metody płatności przelew,                                      // domyślnie 0        'duplicate' => 0,               // flaga 0/1 czy nadrukować słowo duplikat                                      // z aktualną datą,                                      // domyślnie 0  );      // generujemy plik PDF z wydrukiem  $response = $C->downloadInvoice($sid, $invoice_id, $options);    if ($response['status'] == 'OK') {      // w odpowiedzi przychodzi URL do pliku PDF, URL jest ważny przez 10 minut      $url_pliku_pdf = $response['response'];  } else {      // coś poszło nie tak      switch ($response['status']) {          case 'ERR':              echo "Nieprawidłowwy ID faktury";              break;          case 'FATAL_ERROR':              echo "Błąd usługi - skontaktuj się z administratorem";              break;      }  }  
logout($sid)

Funkcja logout() kończy sesję API i uniemożliwia wykonanie kolejnych metod z użyciem wcześniej pobranego identyfikatora sesji - $sid.

Przykład (PHP):
$C->logout($sid);  
sendInvoice($sid, $invoice_id, $email, $options)

Funkcja służąca do wysyłania faktury na e-mail, adres e-mail nie jest zapisywany w danych kontrahenta.

Przykład PHP i opis parametrów
// $sid - id sesji zwrócony przez metodę login()  // $invoice_id - ID faktury zwrócony przez metodę addInvoice();    // dodatkowe ustawienia (opcjonalne)  $options = array(      'subject' => 'Wystawiono fakturę',                                      // Temat wiadomości e-mail, domyślnie 'Faktura od NAZWA_FIRMY'        'page' => 'invoice',            // którą stronę faktury załączyć, możliwe wartości to:                                      // invoice - oryginał                                      // invoicecopy - kopia                                      // all - wszystkie, wartość domyślna        'leaflet' => 0,                 // flaga 0/1 czy dołączyć druczek przelewu                                      // działa tylko dla metody płatności przelew,                                      // domyślnie 0        'duplicate' => 0,               // flaga 0/1 czy nadrukować słowo duplikat                                      // z aktualną datą,                                      // domyślnie 0        'cc' => '',                     // opcjonalnie adres e-mail DW      'bcc' => '',                    // opcjonalnie adres e-mail UDW        'body' => 'Przesyłam fakturę. Pozdrowienia'                                      // treść wiadomości e-mail, jeśli nie będzie wpisana to                                      // zostanie użyta treść zdefiniowana w ustawieniach firmy  );    $response = $C->sendInvoice($sid, $invoice_id, 'spam@mediait.pl', $options);    switch ($response['response']) {      case 'OK':           // faktura wysłana          break;      case 'ERR':          // nie ma takiej faktury, sprawdź $invoice_id          break;      case 'FATAL_ERROR':  // coś poszło nie tak - skontaktuj się z nami          break;  }  
getLoginToken($sid)

Funkcja getLoginToken() pozwala na pobranie tokena umożliwiającego bezpieczne, automatyczne zalogowanie się do serwisu wFirma.pl. Po zalogowaniu token jest natychmiast unieważniany.

Przykład (PHP):
$r = $C->getLoginToken($sid);  $token = $r['response'];  header('Location: https://wfirma.pl/users/login/'.$token);  exit();  

Istnieje możliwość wybrania miejsca przekierowania po zalogowaniu poprzez podanie w adresie dodatkowego parametru:

  • https://wfirma.pl/users/login/$token/invoices - po zalogowaniu użytkownik jest przekierowany do zakładki Sprzedaż / Faktury VAT
  • https://wfirma.pl/users/login/$token - domyślne przekierowanie do zakładki Biuro
Uwaga! Zalecamy korzystać z nowego API, którego dokumentacja znajduje się pod adresem https://doc.wfirma.pl.
Stare API nie jest już rozwijane od kilku lat i w przyszłości zostanie wyłączone.