Programowy dostęp do zasobów

API Wstęp | Klienci | Kontakty klienta | Oferty | Faktury | Płatności | Użytkownicy | Konta firmowe | Komentarze | Dodatkowe informacje


Historia zmian

3. grudnia 2012
Dodano faktury brutto.
14. marca 2012
Wprowadzono dostęp do płatności.
2. lutego 2012
Dodano możliwość dostępu do osób kontaktowych klientów.
17. czerwca 2011
Udostępniliśmy w API możliwość wysyłania dokumentów za pomocą poczty elektronicznej oraz poczty zwykłej za pośrednictwem Postivo.pl
24. lutego 2011
Pojawił się dostęp do kont firmowych
14. lutego 2011
Pojawiła się możliwość pobrania dokumentów zmienionych po określonym punkcie w czasie
24. stycznia 2011
API zaczęło obejmować również komentarze
10. stycznia 2011
Udostępniliśmy możliwość podania danych klienta bezpośrednio w treści faktury
29. grudnia 2010
W szczegółach faktury pojawiła się opcja sprzedaży ciągłej
7. czerwca 2010
Użytkownicy stali się dostępni z poziomu API
11. maja 2010
Dodaliśmy możliwość filtrowania dokumentów względem daty

Wstęp

Niniejszy dokument przeznaczony jest dla programistów i jego lektura wymaga znajomości zagadnień związanych z programowym dostępem do aplikacji internetowych. Jeśli nie jesteś programistą, a chciałbyś korzystać z Centrum Faktur we własnej aplikacji (np. wystawiać faktury lub oferty poprzez nasz serwis w swoim sklepie internetowym), przekaż niniejszy adres swojemu programiście albo napisz do nas.

Istniejące implementacje

Choć wiemy, jak fascynującym zajęciem jest pisanie klienta API, nie bylibyśmy programistami, gdybyśmy nie zaproponowali użycia jednego z istniejących rozwiązań:

Czegoś brakuje?

Jeśli znasz inne biblioteki umożliwiające dostęp do naszego API, daj nam znać za pomocą zgłoszenia na Burzy Mózgów.

REST

Interfejs CentrumFaktur jest typowym przykładem RESTful web API. Poszczególne zasoby mają przypisane własne adresy URI, zaś operacje na nich przeprowadza się wysyłając odpowiedni rodzaj zapytania HTTP. By nie pozostawać gołosłownym, zacznijmy od pobrania listy faktur:

$ curl -u login:haslo 'https://jakasfirma.centrumfaktur.pl/api/1.0/invoices/' -X GET
[
    {
        "status": "draft",
        "comments_uri": "/api/1.0/invoices/1/comments/",
        "language": "pl",
        "resource_uri": "/api/1.0/invoices/1/",
        "invoice_type": "regular",
        "invoice_id": "",
        "currency_symbol": "PLN",
        "summary": "Jedzenie z Mewy",
        "date_raised": "2010-03-09",
        "customer_address": "",
        "customer_uri": "/api/1.0/customers/1/",
        "items": [
            {
                "description": "Gulasz z serc z kaszą",
                "unit_price": "3.65",
                "amount": "1",
                "tax_rate": "22",
                "unit": "p",
                "product_id": ""
            }
        ],
        "date": "2010-03-09",
        "customer_tax_id": "",
        "paid_so_far": "0",
        "advance_amount": "0",
        "payment_due": 0,
        "pricing_model": "net",
        "customer_name": "",
        "customer_email": "",
    }
]

Powyższy przykład wykonuje zapytanie o listę faktur firmy jakasfirma.centrumfaktur.pl, uwierzytelniając się jako login z hasłem haslo. Śmiało, przetestuj na swoim koncie, szczegółami zajmiemy się za chwilę.

Logowanie i autoryzacja

Różne aplikacje mają różne potrzeby, dlatego udostępniamy dwa sposoby dostępu do API.

Pierwszy to użyty w powyższym przykładzie Basic Authentication. Wystarczy podać prawidłowy login i hasło, nie zapominając jednocześnie o użyciu właściwej domeny — w przykładzie była to jakasfirma.centrumfaktur.pl. Jeśli twoja aplikacja będzie uruchamiana na komputerze klienta to prawdopodobnie Basic Authentication jest rozwiązaniem dla ciebie.

Drugim protokołem jest OAuth. Jest on dedykowany przede wszystkim firmom trzecim, oferującym swoje usługi istniejącym klientom CentrumFaktur. Ze względu na bezpieczeństwo nie operuje on na loginach i hasłach. Aplikacje muszą zostać wcześniej zgłoszone i po weryfikacji przez nas otrzymują unikalny klucz API. Te z kolei umożliwiają poproszenie klienta CentrumFaktur o udzielenie zgody na dostęp.

Dla przykładu aplikacja służąca do prowadzenia sklepu internetowego może zgłosić się do nas z prośbą o uzyskanie dostępu do API. Po jego uzyskaniu może zaoferować klientom automatyczne wystawianie faktur w systemie CentrumFaktur. Zainteresowani klienci zostaną przekierowywani do systemu CentrumFaktur z prośbą o zalogowanie i autoryzowanie dostępu. Od tego momentu sklep będzie mógł tworzyć dokumenty w imieniu użytkownika.

Każdy z użytkowników w zakładce Ustawienia otrzymuje wgląd w listę autoryzowanych aplikacji OAuth i ma możliwość odebrania uprawnień każdej z nich z osobna. W przypadku dostępu za pomocą loginu i hasła jedyna możliwość odebrania praw aplikacji, to zmiana hasła użytkownika.

OAuth

Dla protokołu OAuth przewidziano następujące adresy dla procedury wymiany tokenów:

Adres pozyskania niezautoryzowanego tokenu tymczasowego
/oauth/request/token/
Adres punktu autoryzacji, gdzie użytkownik potwierdza token tymczasowy
/oauth/authorize/
Adres wymiany zautoryzowanego tokenu na trwały token dostępowy
/oauth/access/token/

Każdy z nich powinien zostać wywołany w domenie należącej do firmy użytkownika. Po uzyskaniu tokenu dostępowego, dalsze operacje można przeprowadzać w domenie użytkownika, bądź w domenie secure.centrumfaktur.pl. W obu przypadkach wymagany jest protokół HTTPS.

Aby umożliwić ci przetestowanie API zanim zarejestrujesz własną aplikację, poniżej dostarczamy parę kluczy testowych. Za ich pomocą możesz sprawdzić swoją implementację bez potrzeby wcześniejszego uzyskania własnych kluczy. Nigdy nie używaj ich w gotowym produkcie.

Klucz aplikacji testowej
44jqZaCtZWxfeE7HvQ
Sekret aplikacji testowej
uBxbdqEVGWK7CgypgAQYDVZXtUQ8svXE
Czy wiesz, że…

Wykorzystując te klucze do uzyskiwania dostępu do ważnych danych, stwarzasz potencjalną lukę bezpieczeństwa i sprawiasz, że gdzieś tam umiera mały, słodki, puszysty kotek. Zastrzegamy sobie prawo do ostrzegania użytkowników przed autoryzacją kluczy testowych poprzez wyświetlanie ostrzeżeń, a nawet pisanie po francusku.

Operacje na danych

Zgodnie z przyjętą konwencją REST, metody GET, POST, PUTDELETE zapytań HTTP pozwalają odpowiednio na pobranie, utworzenie, aktualizację i usunięcie danych obiektu. Widzieliśmy już, jak pobrać listę faktur, spróbujmy zatem jedną z nich usunąć. Adres każdego obiektu znajdziesz w jego polu resource_uri. Dla przykładowej faktury było to /api/1.0/invoices/1/:

$ curl -u login:haslo 'https://jakasfirma.centrumfaktur.pl/api/1.0/invoices/1/' -X DELETE

I gotowe:

$ curl -u login:haslo 'https://jakasfirma.centrumfaktur.pl/api/1.0/invoices/' -X GET
[]

Faktura została usunięta i lista faktur jest pusta.

Czy wiesz, że…

Jeśli nie pozostały ci już żadne faktury, możesz przed dalszymi testami zalogować się do swojego CentrumFaktur i przywrócić usunięte obiekty z kosza.

Format danych

Niezależnie od sposobu uzyskania dostępu, dane pomiędzy aplikacją i API muszą być przesyłane w jakimś formacie. Być może zauważyłeś już, że w powyższych przykładach mieliśmy do czynienia z JSON, jednak nie jest to jedyny format, jaki system oferuje.

Obsługiwane formaty to JSON, YAML, XML, a także — w ograniczonym zakresie — pythonowy pickle oraz PDF. Format, w jakim API ma zwrócić dane określa się poprzez przesłanie w zapytaniu parametru format, zaś format wysyłanych do API treści reguluje nagłówek Content-Type. Odpowiednie wartości znajdziesz w zestawieniu poniżej:

Format danych Pobieranie (format) Wysyłanie (Content-Type)
JSON json application/json
YAML yaml application/x-yaml
XML xml text/xml
Python pickle pickle brak (ze względu na bezpieczeństwo)
PDF pdf (tylko szczegóły faktur i ofert) brak

Dla przykładu pobierzmy listę klientów w XML (dla czytelności odpowiedź API została złamana w zaznaczonych miejscach):

$ curl -u login:haslo 'https://jakasfirma.centrumfaktur.pl/api/1.0/customers/?format=xml' -X GET
<?xml version="1.0" encoding="utf-8"?>
<response><resource> ⤶
<name>Jan Kowalski</name> ⤶
<contact></contact> ⤶
<address>ul. Wyimaginowana 11</address> ⤶
<mailing_address>ul. Korespondencyjna 11</mailing_address> ⤶
<resource_uri>/api/1.0/customers/1/</resource_uri> ⤶
<email>foo@bar.com</email> ⤶
<tax_id>111-111-11-11</tax_id> ⤶
<notes>Notatki</notes> ⤶
</resource></response>

Oraz w YAML:

$ curl -u login:haslo 'https://jakasfirma.centrumfaktur.pl/api/1.0/customers/?format=yaml' -X GET
- {address: ul. Wyimaginowana 11, contact: '', email: foo@bar.com, name: Jan Kowalski,
  resource_uri: /api/1.0/customers/1/, tax_id: 111-111-11-11}

Odważni mogą również dokonywać bardziej szalonych wyczynów, na przykład wysłać dane w formacie YAML, a wynik odebrać w JSON. Poniższy przykład tworzy nowego klienta. Mamy nadzieję, że nigdy nie będziesz zmuszony użyć go w praktyce:

$ curl -u login:haslo 'https://jakasfirma.centrumfaktur.pl/api/1.0/customers/?format=json' -X POST \
-d "{name: Jan Testowy, address: plac Szeroki 1}" -H "Content-Type: application/x-yaml"
{
    "name": "Jan Testowy",
    "contact": "",
    "address": "plac Szeroki 1",
    "mailing_address": "ul. Korespondencyjna 11",
    "resource_uri": "/api/1.0/customers/2/",
    "email": "",
    "tax_id": "",
    "notes": "Notatki"
}

Powrót do spisu treści


Klienci

Skoro mamy za sobą podstawy, przebrnęliśmy przez wstęp i kilka dość chaotycznych przykładów użycia API, czas przejść do konkretów.

Adresem URI zasobu klientów jest /api/1.0/customers/ i jest to jedyny adres związany z klientami, jaki powinna znać aplikacja. Poszczególne obiekty posiadają następujące atrybuty:

Czy wiesz, że…

Uporczywe podkreślanie słowa jedyny nie jest przypadkowe i nie jest skutkiem stosowania metody Copiego-Paste'a. Żadna aplikacja nie powinna bowiem próbować programowo konstruować resource_uri poszczególnych obiektów. Adresy te mogą w przyszłości ulec zmianie z powodów technicznych.

Możemy również zmienić je z czystej złośliwości, jeśli przyłapiemy cię na ich budowaniu.

Nazwa atrybutu Typ Opis
resource_uri URI identyfikator obiektu (tylko do odczytu)
name ciąg znaków imię i nazwisko lub nazwa firmy
address pole tekstowe adres
mailing_address pole tekstowe adres korespondencyjny
tax_id VAT Tax ID identyfikator płatnika VAT (opcjonalny)
notes pole tekstowe uwagi
contact ciąg znaków osoba kontaktowa (opcjonalna, przestarzała, tylko do odczytu)
email email adres e-mail (opcjonalny, przestarzały, tylko do odczytu)
contacts_uri URI identyfikator zasobu listy osób kontaktowych (tylko do odczytu)

Pobranie listy klientów

Listę klientów możesz pobrać wysyłając zapytanie GET na adres URI zasobu. W odpowiedzi otrzymasz listę obiektów zserializowaną do wybranego formatu.

Utworzenie nowego klienta

Nowego klienta utworzysz przesyłając na adres URI zasobu zapytanie POST, zawierające co najmniej wszystkie wymagane pola z powyższej tabeli. Błędy zostaną zasygnalizowane kodami odpowiedzi 40x. Jeśli zaś dane okażą się poprawne, w odpowiedzi uzyskasz nowo utworzony obiekt, wraz z nadanym adresem resource_uri.

Aktualizacja danych klienta

W celu zmiany danych klienta, prześlij na resource_uri modyfikowanego obiektu zapytanie PUT, zawierające co najmniej wszystkie wymagane pola z powyższej tabeli. O błędach i ewentualnym sukcesie zostaniesz powiadomiony w taki sam sposób, jak w przypadku tworzenia nowego klienta.

Usuwanie klienta

Usunięcie klienta przeprowadzisz poprzez przesłanie zapytania DELETE na resource_uri usuwanego obiektu. Usunięcie jest sygnalizowane pustą odpowiedzią HTTP o kodzie 204.

Powrót do spisu treści


Kontakty klienta

Listę kontaktów danego klienta można pobierać poprzez atrybut contacts_uri zawarty w obiektach klientów. Poszczególne obiekty kontaktów posiadają następujące atrybuty:

Nazwa atrybutu Typ Opis
resource_uri URI identyfikator obiektu (tylko do odczytu)
name ciąg znaków nazwa kontaktu (opcjonalna)
email email adres e-mail
phone ciąg znaków numer telefonu (opcjonalny)
default_for_invoices wartość logiczna domyślny odbiorca wiadomości e-mail z fakturami (opcjonalny)
default_for_estimates wartość logiczna domyślny odbiorca wiadomości e-mail z ofertami (opcjonalny)

Pobranie listy kontaktów

Listę osób kontaktowych możesz pobrać wysyłając zapytanie GET na adres URI zasobu. W odpowiedzi otrzymasz listę obiektów zserializowaną do wybranego formatu.

Utworzenie nowego kontaktu

Aby utworzyć nowy kontakt należy przesłać na adres URI zasobu zapytanie POST, zawierające co najmniej wszystkie wymagane pola z powyższej tabeli. Błędy zostaną zasygnalizowane kodami odpowiedzi 40x. Jeśli zaś dane okażą się poprawne, w odpowiedzi uzyskasz nowo utworzony obiekt, wraz z nadanym adresem resource_uri.

Aktualizacja danych kontaktu

W celu zmiany danych osoby kontaktowej, prześlij na resource_uri modyfikowanego obiektu zapytanie PUT, zawierające co najmniej wszystkie wymagane pola z powyższej tabeli. O błędach i ewentualnym sukcesie zostaniesz powiadomiony w taki sam sposób, jak w przypadku tworzenia nowego kontaktu.

Usuwanie kontaktu

Usunięcie osoby kontaktowej przeprowadzisz poprzez przesłanie zapytania DELETE na resource_uri usuwanego obiektu. Usunięcie jest sygnalizowane pustą odpowiedzią HTTP o kodzie 204.

Powrót do spisu treści

Oferty

Istnieją dwa adresy URI związane z ofertami: /api/1.0/estimates/ oraz /api/1.0/estimates/updates/. Pierwszy z nich służy do pobierania listy ofert zaś drugi do monitorowania zmian w liście ofert.

Ostrożnie!

Obiekty jakie uzyskamy poprzez odwołania do wspomnianych dwóch adresów są różne.

Poszczególne obiekty zwracane z adresu /api/1.0/estimates/ posiadają następujące atrybuty:

Nazwa atrybutu Typ Opis
resource_uri URI identyfikator obiektu (tylko do odczytu)
summary ciąg znaków tytuł (opcjonalny)
status pole wyboru stan oferty:
  • draft — szkic
  • sent — wysłana
  • seen — obejrzana
  • rejected — odrzucona
  • accepted — zaakceptowana
  • invoiced — wystawiono fakturę
currency_symbol pole wyboru waluta:
  • EUR
  • GBP
  • PLN
  • USD
pricing_model pole wyboru sposób obliczania kwot na fakturze:
  • net — netto
  • gross — brutto
customer_uri URI identyfikator klienta
items lista pozycje oferty (opcjonalne)
comments_uri URI identyfikator zasobu komentarzy danej oferty
total liczba dziesiętna suma netto (tylko do odczytu)
total_gross liczba dziesiętna suma brutto (tylko do odczytu)
total_main_currency liczba dziesiętna suma netto przeliczona na PLN (tylko do odczytu)
total_gross_main_currency liczba dziesiętna suma brutto przeliczona n PLN (tylko do odczytu)
email_uri URI identyfikator zasobu wysyłki elektronicznej (tylko do odczytu)

Poszczególne zaś pozycje atrybutu items mają strukturę:

Nazwa atrybutu Typ Opis
description pole tekstowe nazwa i opis pozycji
unit_price liczba dziesiętna cena za sztukę (netto lub brutto, w zależności od wartości pola pricing_model oferty lub faktury)
unit pole wyboru jednostka:
  • a — zaliczka
  • d — dni
  • h — godziny
  • kg — kilogramy
  • km — kilometry
  • m — metry
  • p — sztuki
  • s — komplet
  • u — usługa
  • x — zniżka/upust
amount liczba dziesiętna ilość
tax_rate pole wyboru stawka VAT:
  • na — nie dotyczy
  • ex — zwolnione
  • 0 — 0%
  • 3 — 3%
  • 4 — 4%
  • 5 — 5%
  • 7 — 7%
  • 8 — 8%
  • 22 — 22%
  • 23 — 23%
product_id ciąg znaków PKWiU (opcjonalny)

Pobranie listy ofert

Listę ofert możesz pobrać wysyłając zapytanie GET na adres URI zasobu. W odpowiedzi otrzymasz listę obiektów zserializowaną do wybranego formatu.

Utworzenie nowej oferty

Nową ofertę utworzysz zaś przesyłając na adres URI zasobu zapytanie POST, zawierające co najmniej wszystkie wymagane pola z powyższej tabeli. W przypadku wystąpienia błędów zwrócona zostanie odpowiedź o kodzie 40x. W przeciwnym wypadku w odpowiedzi uzyskasz nowo utworzony obiekt, wraz z nadanym adresem resource_uri.

Aktualizacja danych oferty

Aby zmodyfikować ofertę, prześlij na resource_uri modyfikowanego obiektu zapytanie PUT, zawierające co najmniej wszystkie wymagane pola z powyższej tabeli. W przypadku pominięcia atrybutu items, pozycje oferty pozostaną niezmienione. W przypadku jego podania, istniejące pozycje zostaną zastąpione przesłanymi. Błędy i sukces zostaną zasygnalizowane identycznie, jak w przypadku tworzenia nowej oferty.

Usuwanie oferty

Ofertę usuniesz przesyłając zapytania DELETE na resource_uri usuwanego obiektu. Sukces jest sygnalizowany pustą odpowiedzią HTTP o kodzie 204.

Monitorowanie zmian

API udostępnia metodę pobrania listy ofert zmienionych od zadanej daty. Listę takich obiektów uzyskamy po wysłaniu żądania GET z parametrem (opcjonalnym) updated_since na adres /api/1.0/estimates/updates/.

Obiekt zwrócony w rezultacie takiego zapytania posiada następujące atrybuty:

Nazwa atrybutu Typ Opis
deleted lista resource_uri każdej z ofert usuniętych po zadanym terminie
updated lista resource_uri każdej z ofert zmodyfikowanych po zadanym terminie

Wraz z zapytaniem możliwe jest zadanie parametru GET, którego wartość określa początek okresu z jakiego mają być brane oferty (jeśli nie jest zadany przyjmowana jest bieżący dzień):

Nazwa parametru Typ Opis
updated_since data (YYYY-MM-DD) początek okresu w którym zmodyfikowano/usunięto oferty (włącznie)

Wysyłka

Ofertę można wysłać za pomocą poczty elektronicznej, wykorzystując do tego skojarzony z nią adres email_uri. Wysłanie na ten adres żądania GET spowoduje zwrócenie listy adresów, na jakie dokument został już wysłany. Żądanie POST spowoduje wysłanie dokumentu do wskazanych adresatów:

Nazwa atrybutu Typ Opis
body pole tekstowe treść
emails lista ciągów znaków adresy e-mail, na które ma zostać wysłany dokument

Powrót do spisu treści


Faktury

Z zasobem faktur są powiązane dwa adresy URI: /api/1.0/invoices/ oraz /api/1.0/invoices/updates/. Pierwszy z nich służy do pobierania listy faktur zaś drugi do monitorowania zmian w systemie.

Poszczególne obiekty zwracane poprzez /api/1.0/invoices/ posiadają następujące atrybuty:

Nazwa atrybutu Typ Opis
resource_uri URI identyfikator obiektu (tylko do odczytu)
invoice_id ciąg znaków numer faktury (opcjonalny)
auto_numbering wartość logiczna automatyczne nadanie numeru (tylko do zapisu)
summary ciąg znaków opis (opcjonalny)
invoice_type pole wyboru typ faktury:
  • advance — zaliczkowa
  • regular — zwykła
status pole wyboru stan faktury:
  • draft — szkic
  • raised — wystawiona
  • paid — spłacona
  • thanks — wysłano podziękowanie
currency_symbol pole wyboru waluta:
  • EUR
  • GBP
  • PLN
  • USD
pricing_model pole wyboru sposób obliczania kwot na fakturze:
  • net — netto
  • gross — brutto
language pole wyboru język faktury:
  • pl — polska
  • en — dwujęzyczna, polsko-angielska
company_name ciąg znaków nazwa sprzedawcy (przesłania aktualne dane firmy)
company_address pole tekstowe adres sprzedawcy (przesłania aktualne dane firmy)
company_tax_id VAT Tax ID identyfikator płatnika VAT sprzedawcy (przesłania aktualne dane firmy)
customer_uri URI identyfikator klienta
customer_name ciąg znaków nazwa nabywcy (przesłania aktualne dane klienta)
customer_address pole tekstowe adres nabywcy (przesłania aktualne dane klienta)
customer_tax_id VAT Tax ID identyfikator płatnika VAT nabywcy (przesłania aktualne dane klienta)
customer_email ciąg znaków adres email używany gdy faktura nie ma przypisanego klienta (nie przesłania danych klienta)
date data data sprzedaży
continuous_month prawda/fałsz sprzedaż ciągła w całym miesiącu
date_raised data data wystawienia
payment_due pole wyboru termin płatności:
  • 0 — w dniu sprzedaży
  • 7 — tydzień po sprzedaży
  • 15 — 15 dni po sprzedaży
  • 30 — 30 dni po sprzedaży
  • 45 — 45 dni po sprzedaży
  • 60 — 60 dni po sprzedaży
notes pole tekstowe uwagi do faktury
payments_uri URI identyfikator zasobu płatności faktury
items lista pozycje faktury (opcjonalne)
accounts lista informacja o formach płatności (opcjonalne)
total liczba dziesiętna suma netto (tylko do odczytu)
total_gross liczba dziesiętna suma brutto (tylko do odczytu)
total_main_currency liczba dziesiętna suma netto przeliczona na PLN (tylko do odczytu)
total_gross_main_currency liczba dziesiętna suma brutto przeliczona n PLN (tylko do odczytu)
comments_uri URI identyfikator zasobu komentarzy danej faktury
paid_so_far liczba dziesiętna spłacona kwota (tylko do odczytu)
advance_amount liczba dziesiętna kwota zaliczki (tylko dla faktur zaliczkowych)
previous_advance_uri URI identyfikator poprzedniej faktury (tylko dla faktur zaliczkowych)
corrected_invoice_uri URI identyfikator korygowanej faktury (tylko dla faktur korygujących)
email_uri URI identyfikator zasobu wysyłki elektronicznej (tylko do odczytu)
postivo_uri URI identyfikator zasobu wysyłki pocztowej (tylko do odczytu)

Poszczególne zaś pozycje atrybutu items mają strukturę identyczną jak w przypadku ofert:

Nazwa atrybutu Typ Opis
description pole tekstowe nazwa i opis pozycji
unit_price liczba dziesiętna cena za sztukę (netto lub brutto, w zależności od wartości pola pricing_model oferty lub faktury)
unit pole wyboru jednostka:
  • h — godziny
  • u — usługa
  • p — sztuki
  • d — dni
  • x — zniżka/upust
amount liczba dziesiętna ilość
tax_rate pole wyboru stawka VAT:
  • na — nie dotyczy
  • ex — zwolnione
  • 0 — 0%
  • 3 — 3%
  • 4 — 4%
  • 5 — 5%
  • 7 — 7%
  • 8 — 8%
  • 22 — 22%
  • 23 — 23%
product_id ciąg znaków PKWiU (opcjonalny)

Pozycje atrybutu accounts składają się jedynie z jednego pola:

Nazwa atrybutu Typ Opis
resource_uri URI identyfikator obiektu (tylko do odczytu)

W przypadku pobierania faktury w formacie PDF, możliwe jest przekazanie dodatkowych parametrów w celu wybrania rodzaju dokumentu:

Nazwa atrybutu Typ Opis
type pole wyboru rodzaj dokumentu:
  • draft — szkic
  • invoice — faktura
  • duplicate — duplikat
parts pole wielokrotnego wyboru części składowe:
  • original — oryginał
  • copy — kopia

Pobranie listy faktur

Aby faktur listę pobrać, w noc pełni udasz się na serwer i zapytanie GET na adres URI (/api/1.0/invoices/) zasobu wyślesz. Jeśli rytuał przeprowadzisz prawidłowo, w odpowiedzi listę obiektów zserializowaną do wybranego formatu otrzymasz.

Utworzenie nowej faktury

Choć atrybutów jest tu znacznie więcej, niż w przypadku klientów i ofert, podobnie jak tam, wystarczy przesłać na adres URI zasobu zapytanie POST, zawierające co najmniej wszystkie wymagane pola z tabeli atrybutów faktury. W przypadku wystąpienia błędów zwrócona zostanie odpowiedź o kodzie 40x. Gdy zaś serwer ukontentowany będzie, w odpowiedzi prześle nowo utworzony obiekt, wraz z nadanym adresem resource_uri.

Aktualizacja danych faktury

Aby zmodyfikować fakturę, prześlij na resource_uri modyfikowanego obiektu zapytanie PUT, zawierające co najmniej wszystkie wymagane pola z powyższej tabeli. W przypadku pominięcia atrybutu items, pozycje faktury pozostaną niezmienione. W przypadku jego podania, istniejące pozycje zostaną zastąpione przesłanymi. Błędy i sukces zostaną zasygnalizowane identycznie, jak w przypadku tworzenia nowej faktury.

Ostrożnie!

Za pomocą API możesz zmodyfikować więcej pól, niż jest to możliwe za pośrednictwem interfejsu użytkownika. Upewnij się, że nie naruszasz sensu i integralności danych (na przykład poprzez zmianę wartości atrybutu previous_advance_uri).

Usuwanie faktury

Ofertę usuniesz przesyłając zapytanie DELETE na resource_uri usuwanego obiektu. Sukces jest sygnalizowany pustą odpowiedzią HTTP o kodzie 204.

Monitorowanie zmian

Prócz listowania faktur opisanego powyżej istnieje możliwość pobrania listy faktur zmienionych od zadanej parametrem daty. Listę takich obiektów uzyskamy po wysłaniu żądania GET z parametrem updated_since na adres /api/1.0/invoices/updates/.

Obiekt utworzony w rezultacie takiego zapytania posiada następujące atrybuty:

Nazwa atrybutu Typ Opis
deleted lista resource_uri każdej z faktur usuniętych po zadanym terminie
updated lista resource_uri każdej z faktur zmodyfikowanych po zadanym terminie

Wraz z zapytaniem możliwe jest zadanie parametru GET, którego wartość określa początek okresu z jakiego mają być brane faktury:

Nazwa parametru Typ Opis
updated_since data (YYYY-MM-DD) początek okresu w którym zmodyfikowano/usunięto faktury (włącznie)

Wysyłka

Fakturę można wysłać za pomocą poczty elektronicznej, wykorzystując do tego skojarzony z nią adres email_uri. Wysłanie na ten adres żądania GET spowoduje zwrócenie listy adresów, na jakie dokument został już wysłany. Żądanie POST spowoduje wysłanie dokumentu do wskazanych adresatów:

Nazwa atrybutu Typ Opis
body pole tekstowe treść
emails lista ciągów znaków adresy e-mail, na które ma zostać wysłany dokument
type pole wyboru rodzaj dokumentu:
  • draft — szkic
  • invoice — faktura
  • duplicate — duplikat
parts pole wielokrotnego wyboru części składowe:
  • original — oryginał
  • copy — kopia
with_accounts_info prawda/fałsz dołączenie informacji o sposobach płatności (domyślnie włączone)

Istnieje również możliwość wysyłki faktury za pomocą tradycyjnej poczty, z pośrednictwem Postivo.pl. Do tego celu wykorzystać należy związany z konkretną fakturą adres postivo_uri. Wysłanie żądania GET spowoduje zwrócenie listy dostępnych w trakcie wysyłki konfiguracji.

Żądanie POST natomiast powoduje wysłanie dokumentu. Poniższa tabela przedstawia listę parametrów wysyłki:

Nazwa atrybutu Typ Opis
sender ciąg znaków identyfikator profilu nadawcy (nadawany przez Postivo.pl)
config_id ciąg znaków identyfikator profilu wysyłki (nadawany przez Postivo.pl)
type pole wyboru rodzaj dokumentu:
  • draft — szkic
  • invoice — faktura
  • duplicate — duplikat
parts pole wielokrotnego wyboru części składowe:
  • original — oryginał
  • copy — kopia
dry_run prawda/fałsz symulacja wysyłki bez podejmowania faktycznych czynności (domyślnie wyłączone)

Powrót do spisu treści


Płatności

Listę płatności danej faktury można pobierać poprzez atrybut payments_uri zawarty w obiektach faktur. Poszczególne obiekty płatności posiadają następujące atrybuty:

Nazwa atrybutu Typ Opis
resource_uri URI identyfikator obiektu (tylko do odczytu)
amount liczba dziesiętna kwota płatności
date data (YYYY-MM-DD) data płatności (opcjonalny, domyślnie: aktualna data)

Pobranie listy płatności

Listę dokonanych płatności możesz pobrać wysyłając zapytanie GET na adres URI zasobu. W odpowiedzi otrzymasz listę obiektów zserializowaną do wybranego formatu.

Dodanie nowej płatności

Aby dodać płatność należy przesłać na adres URI zasobu zapytanie POST, zawierające co najmniej wszystkie wymagane pola z powyższej tabeli. Błędy zostaną zasygnalizowane kodami odpowiedzi 40x. Jeśli zaś dane okażą się poprawne, w odpowiedzi uzyskasz nowo utworzony obiekt, wraz z nadanym adresem resource_uri.

Aktualizacja danych płatności

W celu zmiany danych płatności, prześlij na resource_uri modyfikowanego obiektu zapytanie PUT, zawierające co najmniej wszystkie wymagane pola z powyższej tabeli. O błędach i ewentualnym sukcesie zostaniesz powiadomiony w taki sam sposób, jak w przypadku dodawania nowej płatności.

Usuwanie płatności

Usunięcie płatności przeprowadzisz poprzez przesłanie zapytania DELETE na resource_uri usuwanego obiektu. Usunięcie jest sygnalizowane pustą odpowiedzią HTTP o kodzie 204.

Powrót do spisu treści


Użytkownicy

Adresem URI zasobu użytkowników jest /api/1.0/users/ i jest to jedyny adres związany z użytkownikami, jaki powinna znać aplikacja.

Poszczególne obiekty posiadają następujące atrybuty:

Nazwa atrybutu Typ Opis
resource_uri URI identyfikator obiektu (tylko do odczytu)
login ciąg znaków nazwa użytkownika używana do logowania
first_name ciąg znaków imię
last_name ciąg znaków nazwisko
e-mail adres e-mail lub puste adres e-mail

Pobranie listy użytkowników

Aby pobrać listę użytkowników, wyślij zapytanie GET na adres URI zasobu. Serwer zwróci listę obiektów zserializowaną do wybranego formatu.

Utworzenie nowego użytkownika

W tej chwili nie jest możliwe tworzenie nowych użytkowników za pomocą API.

Aktualizacja danych użytkownika

W tej chwili nie jest możliwe modyfikowanie użytkowników za pomocą API.

Usuwanie użytkownika

W tej chwili nie jest możliwe usuwanie użytkowników za pomocą API.

Powrót do spisu treści


Konta firmowe (formy płatności)

Listę istniejących form płatności można pobierać za pomocą adresu /api/1.0/accounts/. Dodatkowo wraz z informacjami o fakturze API udostępnia listę identyfikatorów form płatności, które są z danym dokumentem powiązane.

Pobranie listy kont

Listę wszystkich kont można uzyskać, wysyłając zapytanie GET na adres URI zasobu. Serwer odpowie listą obiektów zserializowaną do wybranego formatu.

Poszczególne obiekty posiadają następujące atrybuty:

Nazwa atrybutu Typ Opis
title ciąg znaków identyfikator danej formy płatności
description ciąg znaków opis formy płatności
resource_uri URI identyfikator obiektu

Utworzenie nowego konta

Nie jest możliwe tworzenie kont za pośrednictwem API.

Aktualizacja danych konta

Konta nie podlegają edycji.

Usuwanie konta

Konta nie można usuwać.

Powrót do spisu treści


Komentarze

Listę komentarzy można pobierać na dwa sposoby: za pomocą adresu /api/1.0/comments/ lub poprzez atrybut comments_uri zawarty ofertach i fakturach, który wskazuje na zasób związany z odpowiednim dokumentem.

Poszczególne obiekty posiadają następujące atrybuty:

Nazwa atrybutu Typ Opis
comment_type pole wyboru rodzaj komentarza: (tylko do odczytu)
  • user — komentarz użytkownika
  • created — informacja o utworzeniu dokumentu
  • customer — komentarz klienta
  • edited — informacja o edycji dokumentu
  • sent — informacja o wysłaniu dokumentu
  • thanks — informacja o wysłaniu podziękowania do klienta
  • reminder — informacja o wysłaniu przypomnienia o płatności
  • snailmail — informacja o wysłaniu dokumentu pocztą
  • seen — informacja o obejrzeniu dokumentu przez klienta
  • accepted — informacja o zaakceptowaniu dokumentu
  • rejected — informacja o odrzuceniu dokumentu
  • payment — informacja o płatności
  • invoiced — informacja o wystawieniu faktury
  • deleted — informacja o usunięciu dokumentu
  • undeleted — informacja o przywróceniu dokumentu
commented_object_type pole wyboru rodzaj komentowanego obiektu: (tylko do odczytu)
  • invoice — komentarz pod fakturą
  • estimate — komentarz związany z ofertą
commented_object_uri URI identyfikator zasobu, którego dotyczy komentarz
created data i czas czas utworzenia komentarza (tylko do odczytu)
summary ciąg znaków skrót (tylko do odczytu)
body pole tekstowe treść
is_public wartość logiczna widoczny dla klienta
user_uri URI lub puste identyfikator zasobu użytkownika, który jest autorem

Pobranie listy komentarzy

Aby pobrać listę komentarzy, wyślij zapytanie GET na adres URI zasobu. Serwer odpowie listą obiektów zserializowaną do wybranego formatu.

Utworzenie nowego komentarza

Aby dodać komentarz, wyślij na adres URI zasobu zapytanie POST, zawierające pola body oraz is_public. W przypadku wystąpienia błędów zwrócona zostanie odpowiedź o kodzie 40x. Gdy wszystko się powiedzie, w odpowiedzi otrzymasz nowo utworzony obiekt.

Aktualizacja danych komentarza

Komentarze nie podlegają edycji.

Usuwanie komentarza

Komentarzy nie można usuwać.

Powrót do spisu treści


Dodatkowe informacje

W przypadku pracy z aplikacjami przeznaczonymi na telefony komórkowe, pobieranie, a następnie parsowanie dużej ilości danych jednocześnie może okazać się problematyczne ze względu na ograniczoną pamięć. Dlatego udostępniamy możliwość dzielenia list obiektów na mniejsze fragmenty i pobierania ich po kawałku.

Aby skorzystać z tej opcji, prześlij w swoim zapytaniu dodatkowe parametry:

Nazwa parametru Typ Opis
offset liczba naturalna pomija pierwszych x obiektów listy
limit liczba naturalna ogranicza długość zwróconej listy

Dla przykładu pobranie trzeciej dziesiątki spośród faktur wyglądać będzie tak:

$ curl -u login:haslo 'https://jakasfirma.centrumfaktur.pl/api/1.0/invoices/?offset=20&limit=10' -X GET

Pełną listę złożyć można pytając o kolejne przedziały, aż zwrócona lista będzie krótsza niż przesłana wartość parametru limit.

Ostrożnie!

Przy składaniu listy w ten sposób należy zatroszczyć się o wykrywanie duplikatów. Jest bowiem możliwe, że pomiędzy poszczególnymi zapytaniami zostanie utworzona nowa faktura, tym samym przesuwając już istniejące o jedną pozycję. Zapytanie o kolejny przedział może więc zwrócić już widziane faktury.

Możliwe jest również ograniczenie listy ofert lub faktur do określonego przedziału dat. W przypadku ofert brany jest pod uwagę moment utworzenia dokumentu, w przypadku faktur jest to data wystawienia. Skorzystać z tej możliwości możesz przesyłając odpowiednie parametry:

Nazwa parametru Typ Opis
date_from data (YYYY-MM-DD) dolny zakres przedziału dat (włącznie)
date_to data (YYYY-MM-DD) górny zakres przedziału dat (włącznie)

Obie opcje zawężania listy wyników nie są rozłączne i mogą być stosowane jednocześnie.

Czy wiesz, że…

Jeśli twoim zdaniem w API brakuje istotnych funkcji, możesz nam o tym powiedzieć za pośrednictwem Burzy Mózgów.

Powrót do spisu treści