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

Kasa fiskalna w firmie - co warto wiedzieć?
Podatnicy, którzy dokonują sprzedaży na rzecz osób fizycznych nieprowadzących działalności gospodarczej bądź na rzecz rolników ryczałtowych, są zobowiązani do rejestrowania sprzedaży na kasie fiskalnej. Sprawdź, kiedy kasa fiskalna nie będzie wymagana!
Czytaj dalej
Uwaga na fałszywe wezwania do rejestracji w GIODO
W związku z wiadomościami, jakie są rozsyłane do przedsiębiorców przez podmioty takie jak Bądźmy Legalni, Legalni z Prawem czy Kancelaria Liberty, pragniemy poinformować, że wiadomości tego rodzaju należy traktować z dużą ostrożnością. Dowiedz się więcej!
Czytaj dalej
Struktura JPK (Jednolitego Pliku Kontrolnego) - analiza
Jednolity plik kontrolny obejmuje nie tylko rejestry sprzedaży i zakupów VAT. Tworzeniu JPK podlegają również m.in. księgi rachunkowe, faktury sprzedaży VAT, wyciągi bankowe. Jak wygląda struktura JPK w poszczególnych obszarach? Dowiedz się więcej!
Czytaj dalej