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

---

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ń:

• python-invoicible — napisana w Pythonie biblioteka na licencji LGPL
• js-invoicible — napisana w języku JavaScript biblioteka na licencji LGPL
• centrum_faktur — napisana w Rubym biblioteka na licencji MIT

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

Operacje na danych

Zgodnie z przyjętą konwencją REST, metody GET, POST, PUT i DELETE 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.

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:

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.

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.

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.

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.

Powrót do spisu treści