Dokumentacja API

Dokumentacja API serwisu BazaFirmCEIDG.pl

Oprócz standardowego sposobu tworzenia baz danych, składania zamówień i pobierania plików z danymi za pośrednictwem serwisu internetowego udostępniamy naszym użytkownikom również interfejs programistyczny (API) umożliwiający wykonywanie najczęściej używanych funkcji.

Dzięki API możesz w prosty sposób zintegrować swój system informatyczny z serwisem BazaFirmCEIDG.pl. Jeśli regularnie zamawiasz w naszym serwisie nowe dane i następnie importujesz je np. w systemie do wysyłki mailingów reklamowych, interfejs programistyczny pozwoli Ci w pełni zautomatyzować ten proces.

Jeśli chcesz skorzystać z tej możliwości pobierania danych, skontaktuj się z nami przy użyciu formularza kontaktowego.

Opłaty

Za 30-dniowy dostęp do API pobieramy z portfela użytkownika stałą opłatę w wysokości 50,00 zł netto. Opłata pobierana jest z góry po rozpoczęciu każdego kolejnego okresu abonamentowego i nie pokrywa kosztu zamawianych danych.

Wszystkie zamówienia złożone za pośrednictwem API wyceniane są według takich samych stawek cennikowych, jak zamówienia złożone w serwisie. Aktualny cennik dostępny jest na stronie z informacjami o naszej ofercie.

Ogólne informacje

API serwisu BazaFirmCEIDG.pl oparte jest na protokole HTTP, a treść wszystkich żądań i odpowiedzi, z wyjątkiem metod służących do autoryzacji, przekazywana jest w formie obiektów języka JavaScript (JSON).

W nagłówku HTTP Content-Type każdego żądania API przesyłanego metodą POST i zawierającego w treści obiekt JSON należy ustawić wartość application/json.

W treści żądań wszystkie wymienione parametry są obowiązkowe, o ile nie napisano inaczej. W treści odpowiedzi zawsze występują wszystkie wymienione parametry.

Każda metoda API może zwrócić jeden z kilku możliwych kodów odpowiedzi HTTP. Nagłówki i parametry odpowiedzi opisane poniżej dla każdej z metod zwracane są tylko dla kodów 200, 201 i 303.

W przypadku wystąpienia błędu w treści odpowiedzi zwracany jest obiekt ze szczegółową informacją, jak na poniższym przykładzie:

{
    "detail": "Expired funds. Cannot renew the API subscription."
}

Autoryzacja

Do uwierzytelniania użytkowników API wykorzystywany jest protokół OAuth 2.0. Pierwszą metodą, jaka musi być wykonana w trakcie każdej sesji, jest metoda POST /api/v1/token/.

Otrzymany w wyniku wykonania tej metody żeton dostępu (access token) musi być zawarty w nagłówku HTTP Authorization każdego kolejnego żądania API, jak na przykładzie poniżej:

GET /api/v1/app HTTP/1.1
Host: www.bazafirmceidg.pl
Authorization: Bearer 0b79bab50daca910b000d4f1a2b675d604257e42

Dostępne metody

Konto i autoryzacja
Bazy danych
Zestawienia
Pliki bazy

Autoryzacja użytkownika

POST /api/v1/token/

Pobiera żeton dostępu (access token) wykorzystywany do autoryzacji przy kolejnych żądaniach API.

Parametry żądania w metodzie POST /api/v1/token/ należy przekazać w formacie application/x-www-form-urlencoded.

Treść żądania:
client_id=[...]&client_secret=[...]&grant_type=client_credentials
Parametry żądania:
client_id

Identyfikator użytkownika API

Wartość:

Identyfikator widoczny w panelu API na stronie Konto.

client_secret

Hasło użytkownika API

Wartość:

Hasło widoczne w panelu API na stronie Konto.

grant_type

Rodzaj uprawnień

Wartość:

Jedyna możliwa wartość to "client_credentials".

Kody odpowiedzi:
200Prawidłowe wykonanie metody.
400Błędna treść żądania (brak wymaganych parametrów lub błędna wartość).
401Błąd autoryzacji.
Treść odpowiedzi:
{
    "access_token": "pShgf38bBqblNG3CfJavEHd2JJZQ14",
    "token_type": "Bearer",
    "expires_in": 36000,
    "scope": "read write"
}
Parametry odpowiedzi:
access_token

Żeton dostępu wykorzystywany do uwierzytelnienia przy kolejnych żądaniach API.

Wartość:

Łańcuch znaków.

token_type

Rodzaj żetonu

Wartość:

Jedyna możliwa wartość to "Bearer".

expires_in

Okres ważności żetonu

Wartość:

Liczba całkowita określająca czas w sekundach.

scope

Zakres uprawnień w ramach żetonu

Wartość:

Jedyna możliwa wartość to "read write".

Unieważnienie żetonu

POST /api/v1/revoke_token/

Unieważnia żeton dostępu (access token) wykorzystywany do autoryzacji przy kolejnych żądaniach API.

Parametry żądania w metodzie POST /api/v1/revoke_token/ należy przekazać w formacie application/x-www-form-urlencoded.

Treść żądania:

Patrz: POST /api/v1/token/

Parametry żądania:

Patrz: POST /api/v1/token/

Kody odpowiedzi:
200Prawidłowe wykonanie metody.
400Błędna treść żądania (brak wymaganych parametrów lub błędna wartość).
401Błąd autoryzacji.

Informacje o koncie

GET /api/v1/app

Pobiera informacje o koncie użytkownika.

Kody odpowiedzi:
200Prawidłowe wykonanie metody.
401Błąd autoryzacji (brak, błędna wartość lub przekroczony okres ważności żetonu dostępu).
Treść odpowiedzi:
{
    "credit": 10.00,
    "wallet_expiration_datetime": "2016-01-07 12:18:46",
    "api_expiration_datetime": "2016-01-07 12:18:46",
    "api_auto_renewal": true,
    "email": "mail@bazanowychfirm.pl",
    "api_notification_url": "http://www.example.com/notify_me"
}
Parametry odpowiedzi:
credit

Aktualny stan konta.

Wartość:

Liczba zmiennoprzecinkowa określająca kwotę netto w złotych.

wallet_expiration_datetime

Data i czas określające termin, do którego można wykorzystać środki zgromadzone w portfelu.

Wartość:

Data i czas w formacie YYYY-MM-DDThh:mm:ssZ.

api_expiration_datetime

Data i czas określające termin, do którego można korzystać z metod API.

Wartość:

Data i czas w formacie YYYY-MM-DDThh:mm:ssZ.

api_auto_renewal

Automatyczne przedłużanie dostępu do API.

Wartość:

true lub false.

Jeśli przyjmuje wartość true, stała opłata za dostęp do API będzie automatycznie pobierana z konta użytkownika na początku kolejnego okresu abonamentowego (po terminie określonym w parametrze api_expiration_datetime).

email

Adres e-mail przypisany do konta.

Wartość:

Łańcuch znaków.

api_notification_url

Adres URL strony odbierającej powiadomienia o możliwości zamówienia nowych rekordów (patrz: Mechanizm powiadomień).

Wartość:

Łańcuch znaków.

Zmiana ustawień API

PATCH /api/v1/app

Zmienia parametry związane z kontem użytkownika.

Treść żądania:
{
    "api_auto_renewal": true,
    "api_notification_url": "http://www.example.com/notify_me",
}
Parametry żądania:
api_auto_renewal
(opcjonalny)

Automatyczne przedłużanie dostępu do API.

Wartość:

true lub false.

Jeśli przyjmuje wartość true, stała opłata za dostęp do API będzie automatycznie pobierana z konta użytkownika na początku kolejnego okresu abonamentowego (po terminie określonym w parametrze api_expiration_datetime).

Po przekroczeniu terminu podanego w parametrze api_expiration_datetime (patrz: GET /api/v1/app) próba ustawienia wartości true spowoduje automatyczne pobranie opłaty za kolejny 30-dniowy okres korzystania z API.

api_notification_url
(opcjonalny)

Adres URL strony odbierającej powiadomienia o możliwości zamówienia nowych rekordów (patrz: Mechanizm powiadomień).

Wartość:

Łańcuch znaków.

Kody odpowiedzi:
200Prawidłowe wykonanie metody.
400Błędna treść żądania (brak wymaganych parametrów lub błędna wartość).
401Błąd autoryzacji (brak, błędna wartość lub przekroczony okres ważności żetonu dostępu).
Treść odpowiedzi:

Patrz: GET /api/v1/app

Parametry odpowiedzi:

Patrz: GET /api/v1/app

Wycena bazy danych

POST /api/v1/pricing

Pobiera wycenę bazy danych z rekordami spełniającymi podane kryteria.

Jeżeli któryś z opcjonalnych parametrów żądania w metodzie POST /api/v1/pricing nie jest ustawiony, oznacza to, że przy obliczaniu wyceny nie jest brany pod uwagę.

Przykład:

Pominięcie parametrów primary_business oraz secondary_business spowoduje uwzględnienie w wycenie rekordów z danymi wszystkich podmiotów, niezależnie od rodzaju wykonywanej przez nie działalności.

Treść żądania:
{
    "criteria": {
        "status": [1, 3],
        "primary_business": [
            "1101Z",
            "1102Z",
            "1103Z",
            "1104Z",
            "1105Z",
        ],
        "secondary_business": [
            "1101Z",
            "1102Z",
            "1103Z",
            "1104Z",
            "1105Z",
        ],
        "region": [
            "12",
            "14",
            "16",
            "1861",
            "2061"
        ],
        "area": [
            {
                "center_latitude": 52.412025,
                "center_longitude": 16.918945,
                "radius": 100000.0
            }
        ],
    },
    "from_date": "2000-01-01",
    "to_date": "2018-01-31"
}
Parametry żądania:
criteriaLista kryteriów doboru podmiotów w bazie.
status

Lista kodów statusu działalności.

Wartość:

Lista musi zawierać co najmniej jeden z niżej wymienionych kodów:

1Aktywny
2Wykreślony
3Zawieszony
primary_business
(opcjonalny)

Lista kodów rodzaju przeważającej działalności.

Wartość:

Maksymalnie 50 różnych kodów grupowań według Polskiej Klasyfikacji Działalności 2007 bez kropek oraz innych znaków niż cyfry i litery.

secondary_business
(opcjonalny)

Lista kodów rodzaju pobocznej działalności.

Wartość:

Maksymalnie 50 różnych kodów grupowań według Polskiej Klasyfikacji Działalności 2007 bez kropek oraz innych znaków niż cyfry i litery.

W serwisie BazaFirmCEIDG.pl lista kodów rodzaju pobocznej działalności, jeśli jest ustawiona, musi zawierać takie same kody jak lista kodów rodzaju przeważającej działalności.

region
(opcjonalny)

Lista kodów regionu siedziby.

Wartość:

Maksymalnie 50 różnych kodów województwa lub powiatu w Krajowym Rejestrze Urzędowym Podziału Terytorialnego Kraju (TERYT).

area
(opcjonalny)

Lista okręgów, wewnątrz których zlokalizowana jest siedziba.

Wartość:

Maksymalnie 5 różnych okręgów zdefiniowanych za pomocą wymienionych niżej parametrów.

center_latitude

Szerokość geograficzna środka okręgu.

Wartość:

Liczba zmiennoprzecinkowa określająca szerokość geograficzną środka okręgu w formacie dziesiętnym.

center_longitude

Długość geograficzna środka okręgu.

Wartość:

Liczba zmiennoprzecinkowa określająca długość geograficzną środka okręgu w formacie dziesiętnym.

radius

Długość promienia okręgu.

Wartość:

Liczba zmiennoprzecinkowa określająca długość w metrach.

from_date
(opcjonalny)

Początkowy zakres dla daty rozpoczęcia działalności.

Wartość:

Data w formacie YYYY-MM-DD.

to_date
(opcjonalny)

Końcowy zakres dla daty rozpoczęcia działalności.

Wartość:

Data w formacie YYYY-MM-DD.

Kody odpowiedzi:
200Prawidłowe wykonanie metody.
204Prawidłowe wykonanie metody. Baza danych o podanych kryteriach nie zawiera żadnych rekordów.
400Błędna treść żądania (brak wymaganych parametrów lub błędna wartość).
401Błąd autoryzacji (brak, błędna wartość lub przekroczony okres ważności żetonu dostępu).
402Zablokowany dostęp do API (brak środków na koncie, konto wygasło lub wyłączona opcja api_auto_renewal).
Nagłówki odpowiedzi:
Location

Adres URL, który można wykorzystać przy pobieraniu aktualnej wersji wyceny (patrz: GET /api/v1/pricing/id).

Treść odpowiedzi:
{
    "pricing": {
        "parts": [
            {
                "part": "info",
                "records_num": 8,
                "value": 0.08
            },
            {
                "part": "contact.email",
                "records_num": 8,
                "value": 0.16
            }
        ],
        "summary": {
            "records_num": 8,
            "value": 0.24
        }
    },
    "from_date": "2000-01-01",
    "to_date": "2015-08-12",
    "url": "https://www.bazafirmceidg.pl/api/v1/pricing/abcdefgh",
    "website_url": "https://www.bazafirmceidg.pl/nowa-baza/podglad/abcdefgh",
    "id": "abcdefgh"
}
Parametry odpowiedzi:
pricingSłownik z informacjami o wycenie bazy danych.
partsLista wycen dla poszczególnych grup informacji dostępnych w bazie danych.
part

Identyfikator grupy informacji.

Wartość:

Jeden z niżej wymienionych identyfikatorów:

infoPodstawowe dane o podmiocie
contact.emailOgólny adres e-mail
records_num

Liczba rekordów zawierających daną grupę informacji.

Wartość:

Liczba całkowita.

value

Koszt zamówienia danej grupy informacji dla wszystkich rekordów uwzględnionych bazie.

Wartość:

Liczba zmiennoprzecinkowa określająca kwotę netto w złotych.

summarySłownik z informacjami o łącznej wycenie (obejmującej wszystkie grupy informacji) bazy danych.
records_num

Liczba wszystkich rekordów w bazie danych.

Wartość:

Liczba całkowita.

value

Koszt zamówienia wszystkich grup informacji dla wszystkich rekordów uwzględnionych bazie.

Wartość:

Liczba zmiennoprzecinkowa określająca kwotę netto w złotych.

from_date

Początkowy zakres dla daty rozpoczęcia działalności.

Wartość:

Data w formacie YYYY-MM-DD.

Jeśli parametr from_date został przekazany w treści żądania, to w odpowiedzi będzie miał taką samą wartość.

Jeśli nie był ustawiony w żądaniu, to w odpowiedzi parametr ten będzie zawierał najwcześniejszą datę rozpoczęcia działalności wśród wszystkich rekordów uwzględnionych w bazie danych.

to_date

Końcowy zakres dla daty rozpoczęcia działalności.

Wartość:

Data w formacie YYYY-MM-DD.

Jeśli parametr to_date został przekazany w treści żądania, to w odpowiedzi będzie miał taką samą wartość.

Jeśli nie był ustawiony w żądaniu, to w odpowiedzi parametr ten będzie zawierał najpóźniejszą datę rozpoczęcia działalności wśród wszystkich rekordów uwzględnionych w bazie danych.

url

Adres URL, który można wykorzystać przy pobieraniu aktualnej wersji wyceny (patrz: GET /api/v1/pricing/id).

Wartość:

Łańcuch znaków.

website_url

Adres URL, który można wykorzystać do wyświetlenia wyceny bazy danych w serwisie BazaFirmCEIDG.pl.

Wartość:

Łańcuch znaków.

id

Unikalny identyfikator wyceny bazy.

Wartość:

Łańcuch znaków zawierający ośmioznakowy identyfikator wyceny.

Aktualizacja wyceny bazy danych

GET /api/v1/pricing/id

Pobiera aktualną wycenę bazy danych na podstawie id wyceny uzyskanego w wyniku wykonania metody POST /api/v1/pricing.

Kody odpowiedzi:
200Prawidłowe wykonanie metody.
401Błąd autoryzacji (brak, błędna wartość lub przekroczony okres ważności żetonu dostępu).
402Zablokowany dostęp do API (brak środków na koncie, konto wygasło lub wyłączona opcja api_auto_renewal).
404Brak wyceny o wskazanym id.
Treść odpowiedzi:

Patrz: POST /api/v1/pricing

Parametry odpowiedzi:

Patrz: POST /api/v1/pricing

Tworzenie bazy danych

POST /api/v1/bases

Tworzy nową bazę danych według podanych kryteriów.

Treść żądania:
{
    "criteria": {
        ...
    },
    "name": "Moja baza danych"
}
Parametry żądania:
criteria

Lista kryteriów doboru podmiotów w bazie.

Wartość:

Patrz: POST /api/v1/pricing

name

Nazwa bazy danych.

Wartość:

Łańcuch znaków.

Kody odpowiedzi:
200Prawidłowe wykonanie metody. Nowa baza danych nie została utworzona, ponieważ istnieje już baza o podanych kryteriach.
201Prawidłowe wykonanie metody. Baza danych została utworzona.
400Błędna treść żądania (brak wymaganych parametrów lub błędna wartość).
401Błąd autoryzacji (brak, błędna wartość lub przekroczony okres ważności żetonu dostępu).
402Zablokowany dostęp do API (brak środków na koncie, konto wygasło lub wyłączona opcja api_auto_renewal).
Nagłówki odpowiedzi:
Location

Adres URL, który można wykorzystać przy pobieraniu informacji o bazie danych (patrz: GET /api/v1/base/id).

Treść odpowiedzi:
{
    "creation_datetime": "2015-12-21 15:38:23",
    "name": "Moja baza danych",
    "api_notification_day": 0
    "email_notification_day": 1,
    "url": "https://www.bazafirmceidg.pl/api/v1/base/1",
    "id": 1
}
Parametry odpowiedzi:
creation_datetime

Data i czas utworzenia bazy danych.

Wartość:

Data i czas w formacie YYYY-MM-DDThh:mm:ssZ.

name

Nazwa bazy danych.

Wartość:

Łańcuch znaków.

api_notification_day

Dzień wysyłki powiadomień API o możliwości zamówienia nowych rekordów z bazy danych (patrz: Mechanizm powiadomień).

Wartość:

Jedna z niżej wymienionych wartości:

0Nigdy
1Codziennie
2Pierwszy dzień tygodnia
3Pierwszy dzień miesiąca
email_notification_day

Dzień wysyłki powiadomień e-mailowych o możliwości zamówienia nowych rekordów z bazy danych.

Wartość:

Jedna z niżej wymienionych wartości:

0Nigdy
1Codziennie
2Pierwszy dzień tygodnia
3Pierwszy dzień miesiąca
url

Adres URL, który można wykorzystać przy pobieraniu informacji o bazie danych (patrz: GET /api/v1/base/id).

Wartość:

Łańcuch znaków.

id

Unikalny identyfikator bazy danych.

Wartość:

Liczba całkowita.

Lista baz danych

GET /api/v1/bases

Pobiera listę utworzonych baz danych.

Kody odpowiedzi:
200Prawidłowe wykonanie metody.
401Błąd autoryzacji (brak, błędna wartość lub przekroczony okres ważności żetonu dostępu).
402Zablokowany dostęp do API (brak środków na koncie, konto wygasło lub wyłączona opcja api_auto_renewal).
Treść odpowiedzi:
[
    {
        "creation_datetime": "2015-12-21 15:38:23",
        "name": "Moja baza danych",
        "api_notification_day": 0,
        "email_notification_day": 1,
        "url": "https://www.bazafirmceidg.pl/api/v1/base/1",
        "id": 1
    },
    {
        "creation_datetime": "2015-12-21 17:40:18",
        "name": "Małopolskie",
        "api_notification_day": 0,
        "email_notification_day": 1,
        "url": "https://www.bazafirmceidg.pl/api/v1/base/2",
        "id": 2
    }
]
Parametry odpowiedzi:

Patrz: POST /api/v1/bases

Informacje o bazie danych

GET /api/v1/base/id

Pobiera informacje o bazie danych o wskazanym id.

Kody odpowiedzi:
200Prawidłowe wykonanie metody.
401Błąd autoryzacji (brak, błędna wartość lub przekroczony okres ważności żetonu dostępu).
402Zablokowany dostęp do API (brak środków na koncie, konto wygasło lub wyłączona opcja api_auto_renewal).
404Brak bazy danych o wskazanym id.
Treść odpowiedzi:

Patrz: POST /api/v1/bases

Parametry odpowiedzi:

Patrz: POST /api/v1/bases

Zmiana ustawień bazy danych

PATCH /api/v1/base/id

Zmienia ustawienia bazy danych o wskazanym id.

Treść żądania:
{
    "name": "Moja baza danych",
    "api_notification_day": 0,
    "email_notification_day": 1
}
Parametry żądania:
name

Nazwa bazy danych.

Wartość:

Łańcuch znaków.

api_notification_day

Dzień wysyłki powiadomień API o możliwości zamówienia nowych rekordów z bazy danych (patrz: Mechanizm powiadomień).

Wartość:

Jedna z niżej wymienionych wartości:

0Nigdy
1Codziennie
2Pierwszy dzień tygodnia
3Pierwszy dzień miesiąca
email_notification_day

Dzień wysyłki powiadomień e-mailowych o możliwości zamówienia nowych rekordów z bazy danych.

Wartość:

Jedna z niżej wymienionych wartości:

0Nigdy
1Codziennie
2Pierwszy dzień tygodnia
3Pierwszy dzień miesiąca
Kody odpowiedzi:
200Prawidłowe wykonanie metody.
400Błędna treść żądania (brak wymaganych parametrów lub błędna wartość).
401Błąd autoryzacji (brak, błędna wartość lub przekroczony okres ważności żetonu dostępu).
402Zablokowany dostęp do API (brak środków na koncie, konto wygasło lub wyłączona opcja api_auto_renewal).
404Brak bazy danych o wskazanym id.
Treść odpowiedzi:

Patrz: POST /api/v1/bases

Parametry odpowiedzi:

Patrz: POST /api/v1/bases

Usuwanie bazy danych

DELETE /api/v1/base/id

Usuwa bazę danych o wskazanym id.

Kody odpowiedzi:
204Prawidłowe wykonanie metody.
401Błąd autoryzacji (brak, błędna wartość lub przekroczony okres ważności żetonu dostępu).
402Zablokowany dostęp do API (brak środków na koncie, konto wygasło lub wyłączona opcja api_auto_renewal).
404Brak bazy danych o wskazanym id.

Wycena zestawienia

POST /api/v1/base/id/pricing

Pobiera wycenę zestawienia z bazy danych o wskazanym id i podanych parametrach.

Treść żądania:
{
    "params": {
        "selected_parts": [
            "info",
            "contact.email"
        ],
        "obligatory_parts": [
            "contact.email"
        ],
        "from_date": "2015-01-08",
        "to_date": "2015-02-28"
    },
    "new_only": false
}
Parametry żądania:
paramsLista parametrów zestawienia.
selected_parts

Lista identyfikatorów grup informacji, które mogą się znaleźć w rekordach uwzględnionych w zestawieniu.

Wartość:

Lista musi zawierać co najmniej jeden z niżej wymienionych identyfikatorów:

infoPodstawowe dane o podmiocie
contact.emailOgólny adres e-mail

W serwisie BazaFirmCEIDG.pl lista musi obowiązkowo zawierać identyfikator "info".

obligatory_parts

Lista identyfikatorów grup informacji, które muszą się znaleźć w rekordach uwzględnionych w zestawieniu.

Wartość:

Lista musi zawierać co najmniej jeden z niżej wymienionych identyfikatorów:

infoPodstawowe dane o podmiocie
contact.emailOgólny adres e-mail
from_date

Początkowy zakres dla daty rozpoczęcia działalności przez podmioty uwzględnione w zestawieniu.

Wartość:

Data w formacie YYYY-MM-DD.

to_date

Końcowy zakres dla daty rozpoczęcia działalności przez podmioty uwzględnione w zestawieniu.

Wartość:

Data w formacie YYYY-MM-DD.

new_only
(opcjonalny)

Tylko rekordy dodane do bazy po ostanim zamówieniu.

Wartość:

true lub false

Jeśli przyjmie wartość true, w zestawieniu zostaną uwzględnione tylko takie rekordy, które pojawiły się w bazie po Twoim ostatnim zamówieniu.

Kody odpowiedzi:
200Prawidłowe wykonanie metody.
204Prawidłowe wykonanie metody. Zestawienie o podanych parametrach nie zawiera żadnych rekordów.
400Błędna treść żądania (brak wymaganych parametrów lub błędna wartość).
401Błąd autoryzacji (brak, błędna wartość lub przekroczony okres ważności żetonu dostępu).
402Zablokowany dostęp do API (brak środków na koncie, konto wygasło lub wyłączona opcja api_auto_renewal).
Treść odpowiedzi:
{
    "pricing": {
        "parts": [
            {
                "part": "info",
                "records_num": 961,
                "value": 9.61
            },
            {
                "part": "contact.email",
                "records_num": 961,
                "value": 19.22
            }
        ],
        "summary": {
            "records_num": 961,
            "value": 28.83
        }
    }
}
Parametry odpowiedzi:
pricingSłownik z informacjami o wycenie zestawienia.
partsLista wycen dla poszczególnych grup informacji uwzględnionych w zestawieniu.
part

Identyfikator grupy informacji.

Wartość:

Jeden z niżej wymienionych identyfikatorów:

infoPodstawowe informacje o przedsiębiorcy
contact.emailAdres e-mail przedsiębiorcy
records_num

Liczba rekordów zawierających daną grupę informacji.

Wartość:

Liczba całkowita.

value

Koszt zamówienia danej grupy informacji dla wszystkich rekordów uwzględnionych w zestawieniu.

Wartość:

Liczba zmiennoprzecinkowa określająca kwotę netto w złotych.

summarySłownik z informacjami o łącznej liczbie rekordów i wycenie zestawienia.
records_num

Liczba wszystkich rekordów w zestawieniu.

Wartość:

Liczba całkowita.

value

Łączny koszt zamówienia rekordów uwzględnionych w zestawieniu.

Wartość:

Liczba zmiennoprzecinkowa określająca kwotę netto w złotych.

Tworzenie zestawienia

POST /api/v1/base/id/orders

Tworzy nowe zestawienie według podanych parametrów dla bazy danych o wskazanym id.

Treść żądania:
{
    "params": {
        ...
    },
    "new_only": ...
}
Parametry żądania:

Patrz: POST /api/v1/base/id/pricing

Kody odpowiedzi:
200Prawidłowe wykonanie metody.
400Błędna treść żądania (brak wymaganych parametrów lub błędna wartość).
401Błąd autoryzacji (brak, błędna wartość lub przekroczony okres ważności żetonu dostępu).
402Niewystarczająca ilość środków w portfelu do opłacenia zamówienia lub Zablokowany dostęp do API (brak środków na koncie, konto wygasło lub wyłączona opcja api_auto_renewal).
404Brak bazy danych o wskazanym id.
Treść odpowiedzi:
{
    "creation_datetime": "2016-01-07 12:18:46",
    "expiration_datetime": "2015-12-21 17:40:18",
    "records_num": 15961,
    "value": 306.65,
    "url": "https://www.bazafirmceidg.pl/api/v1/order/1",
    "id": 1
}
Parametry odpowiedzi:
creation_datetime

Data i czas utworzenia zestawienia.

Wartość:

Data i czas w formacie YYYY-MM-DDThh:mm:ssZ.

expiration_datetime

Data i czas wygaśnięcia zestawienia. Po wygaśnięciu z zestawienia nie będzie można pobierać plików.

Wartość:

Data i czas w formacie YYYY-MM-DDThh:mm:ssZ.

records_num

Liczba wszystkich rekordów w utworzonym zestawieniu.

Wartość:

Liczba całkowita.

value

Łączny koszt utworzonego zestawienia.

Wartość:

Liczba zmiennoprzecinkowa określająca kwotę netto w złotych.

url

Adres URL, który można wykorzystać przy pobieraniu informacji o zestawieniu (patrz: GET /api/v1/order/id).

Wartość:

Łańcuch znaków.

id

Unikalny identyfikator utworzonego zestawienia.

Wartość:

Liczba całkowita.

Lista zestawień

GET /api/v1/base/id/orders

Pobiera listę utworzonych zestawień z bazy danych o wskazanym id.

Kody odpowiedzi:
200Prawidłowe wykonanie metody.
401Błąd autoryzacji (brak, błędna wartość lub przekroczony okres ważności żetonu dostępu).
402Zablokowany dostęp do API (brak środków na koncie, konto wygasło lub wyłączona opcja api_auto_renewal).
404Brak bazy danych o wskazanym id.
Parametry odpowiedzi:

Patrz: POST /api/v1/base/id/orders

Treść odpowiedzi:
[
    {
        "creation_datetime": "2016-01-07 12:18:46",
        "records_num": 16118,
        "value": 309.56,
        "url": "https://www.bazafirmceidg.pl/api/v1/order/1",
        "id": 1
    },
    {
        "creation_datetime": "2016-01-07 12:23:32",
        "records_num": 16118,
        "value": 309.56,
        "url": "https://www.bazafirmceidg.pl/api/v1/order/2",
        "id": 2
    }
]

Informacje o zestawieniu

GET /api/v1/order/id

Pobiera informacje o zestawieniu o wskazanym id.

Kody odpowiedzi:
200Prawidłowe wykonanie metody.
401Błąd autoryzacji (brak, błędna wartość lub przekroczony okres ważności żetonu dostępu).
402Zablokowany dostęp do API (brak środków na koncie, konto wygasło lub wyłączona opcja api_auto_renewal).
404Brak zestawienia o wskazanym id.
Treść odpowiedzi:

Patrz: POST /api/v1/base/id/orders

Parametry odpowiedzi:

Patrz: POST /api/v1/base/id/orders

Tworzenie pliku

POST /api/v1/order/id/files

Tworzy nowy plik z danymi pochodzącymi z zestawienia o podanym id.

Metoda POST /api/v1/order/id/files inicjuje proces generowania pliku. W zależności od liczby rekordów w zestawieniu oraz obciążenia naszych serwerów tworzenie pliku może zająć od kilku sekund do kilkunastu minut.

Po wywołaniu tej metody informację o postępie generowania pliku można uzyskać za pomocą metody GET /api/v1/file/id.

Treść żądania:
{
    "include_fields": [
        "name",
        "nip",
        "primary_business"
    ],
    "exclude_fields": [
        "secondary_business",
        "regon",
    ],
    "file_format": "csv"
}
Parametry żądania:
include_fields
(opcjonalny)

Lista pól z danymi, które powinny się znaleźć w tworzonym pliku.

Wartość:

Lista może zawierać jeden lub więcej z niżej wymienionych identyfikatorów pól:

nameFirma (nazwa)
first_nameImię
last_nameNazwisko
nipNumer NIP
regonNumer REGON
place_of_business_addressAdres głównego miejsca wykonywania działalności
correspondence_addressAdres do doręczeń
emailAdres e-mail
websiteAdres strony internetowej
status_nameStatus działalności gospodarczej
primary_business_codePrzeważająca działalność gospodarcza (kod PKD)
secondary_businesses_codesWykonywana działalność gospodarcza (kody PKD)
commencement_dateData rozpoczęcia działalności
suspension_start_dateData rozpoczęcia zawieszenia działalności
suspension_end_dateData zakończenia zawieszenia działalności
resumption_dateData wznowienia działalności
cessation_dateData zaprzestania wykonywania działalności
cancellation_dateData wykreślenia wpisu z rejestru

Jeśli parametr nie jest ustawiony, w pliku uwzględnione zostaną wszystkie pola z danymi dostępne w zestawieniu.

exclude_fields
(opcjonalny)

Lista pól z danymi, które nie powinny się znaleźć w tworzonym pliku.

Wartość:

Lista może zawierać jeden lub więcej identyfikatorów pól (patrz: parametr include_fields).

Jeśli parametr nie jest ustawiony, w pliku uwzględnione zostaną wszystkie pola z danymi dostępne w zestawieniu.

file_format

Format pliku.

Wartość:

Jeden z niżej wymienionych formatów:

csvPlik tekstowy z polami rozdzielonymi przecinkiem, zgodny ze standardem RFC 4180 (przykładowy plik)
xlsxPlik w formacie programu Microsoft Excel 2007 (przykładowy plik)
xmlPlik tekstowy o strukturze umożliwiającej dalsze przetwarzanie (przykładowy plik)
jsonPlik tekstowy z listą obiektów języka JavaScript, zgodny ze standardem RFC 7159 (przykładowy plik)
Kody odpowiedzi:
200Prawidłowe wykonanie metody. Plik jest w trakcie generowania.
201Prawidłowe wykonanie metody. Rozpoczęto generowanie pliku.
303Prawidłowe wykonanie metody. Plik został wygenerowany i jest gotowy do pobrania.
400Błędna treść żądania (brak wymaganych parametrów lub błędna wartość).
401Błąd autoryzacji (brak, błędna wartość lub przekroczony okres ważności żetonu dostępu).
402Zablokowany dostęp do API (brak środków na koncie, konto wygasło lub wyłączona opcja api_auto_renewal).
404Brak zestawienia o wskazanym id.
Nagłówki odpowiedzi:
Location

Adres URL metody API umożliwiającej pobranie pliku (patrz: GET /api/v1/file/id/download).

Nagłówek jest ustawiony tylko przy kodzie odpowiedzi 303.

Treść odpowiedzi:
{
    "creation_datetime": "2016-01-22 16:07:30",
    "update_datetime": "2016-01-22 16:07:30",
    "fields": [
        "name",
        "nip",
        "primary_business"
    ],
    "file_format": "csv",
    "status": 1,
    "progress": 56,
    "url": "https://www.bazafirmceidg.pl/api/v1/file/1",
    "id": 1
}
Parametry odpowiedzi:
creation_datetime

Data i czas utworzenia pliku.

Wartość:

Data i czas w formacie YYYY-MM-DDThh:mm:ssZ.

update_datetime

Data i czas aktualizacji informacji o postępie tworzenia pliku.

Wartość:

Data i czas w formacie YYYY-MM-DDThh:mm:ssZ.

fields

Lista pól z danymi uwzględnionych w pliku.

Wartość:

Lista pól utworzona na podstawie listy wszystkich pól dostępnych w zestawieniu oraz wartości parametrów include_fields i exclude_fields w żądaniu.

file_format

Format pliku.

Wartość:

Taka sama jak w parametrach żądania.

status

Status pliku.

Wartość:

Jedna z niżej wymienionych wartości:

0Niedostępne
1W przygotowaniu
2Gotowe
progress

Postęp pracy przy tworzeniu pliku.

Wartość:

Liczba całkowita określająca postęp w procentach.

url

Adres URL, który można wykorzystać przy pobieraniu informacji o pliku (patrz: GET /api/v1/file/id).

Wartość:

Łańcuch znaków.

id

Unikalny identyfikator utworzonego pliku.

Wartość:

Liczba całkowita.

Lista plików

GET /api/v1/order/id/files

Pobiera listę plików z danymi utworzonymi dla zestawienia o wskazanym id.

Kody odpowiedzi:
200Prawidłowe wykonanie metody.
401Błąd autoryzacji (brak, błędna wartość lub przekroczony okres ważności żetonu dostępu).
402Zablokowany dostęp do API (brak środków na koncie, konto wygasło lub wyłączona opcja api_auto_renewal).
404Brak zestawienia o wskazanym id.
Treść odpowiedzi:
[
    {
        "creation_datetime": "2016-01-22 16:07:30",
        "update_datetime": "2016-01-22 16:07:30",
        "fields": [
            "name",
            "nip",
            "primary_business"
        ],
        "file_format": "csv",
        "status": 2,
        "progress": 100,
        "url": "https://www.bazafirmceidg.pl/api/v1/file/1",
        "id": 1
    },
    {
        "creation_datetime": "2016-02-22 16:07:30",
        "update_datetime": "2016-02-22 16:07:30",
        "fields": [
            "name",
            "website"
        ],
        "file_format": "csv",
        "status": 2,
        "progress": 100,
        "url": "https://www.bazafirmceidg.pl/api/v1/file/2",
        "id": 2
    },
]
Parametry odpowiedzi:

Patrz: POST /api/v1/order/id/files

Informacje o pliku

GET /api/v1/file/id

Pobiera informacje o pliku o wskazanym id.

Kody odpowiedzi:
200Prawidłowe wykonanie metody.
303Prawidłowe wykonanie metody. Plik został wygenerowany i jest gotowy do pobrania.
401Błąd autoryzacji (brak, błędna wartość lub przekroczony okres ważności żetonu dostępu).
402Zablokowany dostęp do API (brak środków na koncie, konto wygasło lub wyłączona opcja api_auto_renewal).
403Plik nie jest już dostępny do pobrania.
404Brak pliku o wskazanym id lub plik nie został jeszcze wygenerowany.
Nagłówki odpowiedzi:
Location

Adres URL metody API umożliwiającej pobranie pliku (patrz: GET /api/v1/file/id/download).

Nagłówek jest ustawiony tylko przy kodzie odpowiedzi 303.

Treść odpowiedzi:

Patrz: POST /api/v1/order/id/files

Parametry odpowiedzi:

Patrz: POST /api/v1/order/id/files

Pobieranie pliku

GET /api/v1/file/id/download?compress=false&part=1

Pobiera plik z danymi pochodzącymi z zestawienia o podanym id.

Pliki z danymi mogą być pobierane w formacie wskazanym przy ich tworzeniu albo w postaci archiwum ZIP zawierającego właściwy plik (patrz parametr compress).

Pliki pochodzące z zestawień o liczbie rekordów przekraczającej 50 000 dzielone są na mniejsze części. Jeśli plik z takiego zestawienia pobierany jest w formie nieskompresowanej, opisywana metoda zwraca nagłówek HTTP Link, który zawiera adres URL z ustawionym parametrem part umożliwiającym pobranie kolejnej części pliku.

Parametry żądania:
compress
(opcjonalny)

Kompresja pliku.

Jeśli parametr jest ustawiony i ma wartość true, pobrane zostanie archiwum ZIP zawierające wygenerowany plik z danymi.

Wartość:

true lub false

part
(opcjonalny)

Numer części pliku, jeśli plik podzielony jest na mniejsze części.

Wartość:

Liczba całkowita.

Kody odpowiedzi:
200Prawidłowe wykonanie metody.
400Błędna treść żądania (brak wymaganych parametrów lub błędna wartość).
401Błąd autoryzacji (brak, błędna wartość lub przekroczony okres ważności żetonu dostępu).
402Zablokowany dostęp do API (brak środków na koncie, konto wygasło lub wyłączona opcja api_auto_renewal).
404Brak pliku o wskazanym id lub brak części pliku o podanym numerze (patrz: parametr part)
Nagłówki odpowiedzi:
Link

Adres URL umożliwiający pobranie następnej części pliku.

Nagłówek jest ustawiony tylko w przypadku gdy plik podzielony jest na mniejsze części, a część o numerze podanym w parametrze part nie jest częścią ostatnią.

Mechanizm powiadomień

Po każdej aktualizacji naszych zasobów w Twoich bazach danych (utworzonych w serwisie lub przez API) mogą się pojawić nowe rekordy. Interfejs programistyczny serwisu BazaFirmCEIDG.pl oferuje mechanizm automatycznego przekazywania do innego systemu informatycznego informacji o możliwości zamówienia nowych danych.

Aby skorzystać z tej funkcji, należy ustawić na stronie Konto albo za pomocą metody PATCH /api/v1/app adres URL strony odbierającej powiadomienia z naszego API (patrz: parametr api_notification_url).

Na wskazany adres będą wysyłane żądania HTTP metodą POST z informacjami o liczbie i zawartości nowych rekordów w Twoich bazach danych. Żądania te będą wysyłane tylko wtedy, gdy w co najmniej jednej z Twoich baz, dla których mechanizm powiadomień jest włączony (patrz: parametr api_notification_day), po ostatniej aktualizacji naszych zasobów pojawiły się nowe rekordy.

W odpowiedzi Twój system informatyczny powinien zwrócić kod odpowiedzi HTTP 200 OK. Jeśli zwrócony kod będzie inny albo wystąpią inne problemy przy próbie połączenia się z Twoim serwerem, żądania będą ponawiane z malejącą częstotliwością:

przez pierwszą minutęco 10 sekund
przez następną godzinęco 10 minut

Po upływie godziny od wysłania pierwszego powiadomienia API przestanie wysyłać kolejne żądania.

Poniżej prezentujemy przykładową treść żądania wysyłanego przez API oraz opis występujących w nim parametrów.

Treść żądania:
[
    {
        "parts": [
            {
                "part": "info",
                "records_num": 8
            },
            {
                "part": "contact.email",
                "records_num": 2
            }
        ],
        "summary": {
            "records_num": 8
        },
        "from_date": "1946-01-01",
        "to_date": "2016-01-27",
        "id": 1
    },

    {
        "parts": [
            {
                "part": "info",
                "records_num": 5
            },
            {
                "part": "contact.email",
                "records_num": 3
            }
        ],
        "summary": {
            "records_num": 8
        },
        "from_date": "1946-01-01",
        "to_date": "2016-01-27",
        "id": 2
    },
]
Parametry żądania:
partsLista wycen dla poszczególnych grup informacji dostępnych w nowych rekordach.
part

Identyfikator grupy informacji.

Wartość:

Jeden z niżej wymienionych identyfikatorów:

infoPodstawowe dane o podmiocie
contact.emailOgólny adres e-mail
records_num

Liczba rekordów zawierających daną grupę informacji.

Wartość:

Liczba całkowita.

summarySłownik z informacjami o łącznej wycenie (obejmującej wszystkie grupy informacji) nowych rekordów.
records_num

Liczba wszystkich rekordów w bazie danych.

Wartość:

Liczba całkowita.

from_date

Najwcześniejsza data rozpoczęcia działalności wśród wszystkich nowych rekordów.

Wartość:

Data w formacie YYYY-MM-DD.

to_date

Najpóźniejsza data rozpoczęcia działalności wśród wszystkich nowych rekordów.

Wartość:

Data w formacie YYYY-MM-DD.

id

Unikalny identyfikator bazy danych, której dotyczą informacje o liczbie nowych rekordów.

Wartość:

Liczba całkowita.