API - interfejs dla programistów (nieaktualne)

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.

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 email
  • 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 email 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 email
    
    '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 email 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 email, adres email 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 email, 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 email DW
    'bcc' => '',                    // opcjonalnie adres email UDW
    
    'body' => 'Przesyłam fakturę. Pozdrowienia'
                                    // treść wiadomości email, 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.

Współtworzymy Poradnik Przedsiębiorcy

Setki wartościowych artykułów, porady rynkowych ekspertów - wszystko w jednym miejscu

Konferencja Business Process Management już 28 września w Warszawie
Sprawnie działająca firma to właściwe zarządzanie i monitorowanie zachodzących w niej operacji. Na konferencji Business Process Management, dowiesz się jak właściwe modelować procesy biznesowe. Zapraszamy na wydarzenie już 28 września w Warszawie.
Czytaj dalej
Data Center Trends odbędzie się 28 września w Wraszawie
Aby firma funkcjonowała właściwie należy szczególnie dbać o bezpieczeństwo danych oraz stabilność systemów. Dowiedz się, jak to robić na konferencji Data Center Trends, która odbędzie się 28 września w Warszawie.
Czytaj dalej
Targi Outsourcing Expo już 21 września w Warszawie
Prowadzisz małą lub średnią firmę? Chcesz wiedzieć, w jaki sposób wprowadzać do niej nowoczesne rozwiązania, przy jednoczesnej optymalizacji kosztów? Przyjdź na Targi Outsourcing Expo już 21 września w Warszawie i posłuchaj ekspertów.
Czytaj dalej