{"openapi":"3.1.0","info":{"title":"API Ephemeris","version":"1.1","description":"Dane produktów z kodów EAN i GTIN, tylko do odczytu. Domyślny dzienny limit konta: 1000 zapytań, najwyżej 10 zapytań na sekundę. Dane: Ephemeris (Coruls) — https://ephemeris.coruls.com"},"servers":[{"url":"https://api.ephemeris.coruls.com/v1"}],"security":[{"key":[]}],"paths":{"/products/{code}":{"get":{"operationId":"getProduct","summary":"Produkt po kodzie","description":"Pełna karta produktu. Kod może być w formacie EAN-13, EAN-8, UPC-A, UPC-E albo GTIN-14; dodatkowy kod po scaleniu duplikatów zwraca produkt główny z polem requestedCode.","parameters":[{"name":"code","in":"path","required":true,"description":"Kod EAN, UPC albo GTIN.","schema":{"type":"string"},"example":"5901234123457"}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Dzienny limit konta.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Ile zapytań zostało dziś.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Kiedy limit się odnowi: północ czasu polskiego w sekundach Unix.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"},"example":{"error":{"code":"not_found","message":"Nie ma produktu o kodzie 5901234123457."}}}}},"400":{"description":"Kod nie przechodzi walidacji.","headers":{"X-RateLimit-Limit":{"description":"Dzienny limit konta.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Ile zapytań zostało dziś.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Kiedy limit się odnowi: północ czasu polskiego w sekundach Unix.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_code","message":"Kod nie przechodzi walidacji."}}}}},"401":{"description":"Brak klucza API albo nieznany klucz.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Brak klucza API albo nieznany klucz."}}}}},"403":{"description":"Klucz zablokował administrator Ephemeris.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"key_blocked","message":"Klucz zablokował administrator Ephemeris."}}}}},"404":{"description":"Nie ma produktu o tym kodzie.","headers":{"X-RateLimit-Limit":{"description":"Dzienny limit konta.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Ile zapytań zostało dziś.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Kiedy limit się odnowi: północ czasu polskiego w sekundach Unix.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Nie ma produktu o tym kodzie."}}}}},"429":{"description":"Wykorzystano limit zapytań: dzienny konta, na sekundę albo zapytań bez ważnego klucza z jednego adresu.","headers":{"X-RateLimit-Limit":{"description":"Dzienny limit konta.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Ile zapytań zostało dziś.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Kiedy limit się odnowi: północ czasu polskiego w sekundach Unix.","schema":{"type":"integer"}},"Retry-After":{"description":"Za ile sekund ponowić zapytanie.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Wykorzystano limit zapytań: dzienny konta, na sekundę albo zapytań bez ważnego klucza z jednego adresu."}}}}},"503":{"description":"Prace serwisowe (maintenance) albo API chwilowo nie odpowiada (unavailable).","headers":{"Retry-After":{"description":"Za ile sekund ponowić zapytanie: do końca prac albo 60.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"maintenance","message":"Prace serwisowe (maintenance) albo API chwilowo nie odpowiada (unavailable)."}}}}}}}},"/products":{"get":{"operationId":"searchProducts","summary":"Wyszukiwanie produktów","description":"Po nazwie, marce i producencie bez względu na polskie znaki, ze stronicowaniem.","parameters":[{"name":"q","in":"query","required":false,"description":"Szukana fraza; bez niej wszystkie produkty.","schema":{"type":"string"},"example":"jogurt"},{"name":"category","in":"query","required":false,"description":"Identyfikator kategorii z /categories, razem z podkategoriami.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Numer strony, od 1; strony dalej niż 10 000 wyników są puste.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"perPage","in":"query","required":false,"description":"Liczba wyników na stronie.","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Dzienny limit konta.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Ile zapytań zostało dziś.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Kiedy limit się odnowi: północ czasu polskiego w sekundach Unix.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPage"},"example":{"query":"jogurt","category":null,"page":1,"perPage":2,"total":0,"items":[]}}}},"400":{"description":"Nie ma takiej kategorii.","headers":{"X-RateLimit-Limit":{"description":"Dzienny limit konta.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Ile zapytań zostało dziś.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Kiedy limit się odnowi: północ czasu polskiego w sekundach Unix.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_category","message":"Nie ma takiej kategorii."}}}}},"401":{"description":"Brak klucza API albo nieznany klucz.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Brak klucza API albo nieznany klucz."}}}}},"403":{"description":"Klucz zablokował administrator Ephemeris.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"key_blocked","message":"Klucz zablokował administrator Ephemeris."}}}}},"429":{"description":"Wykorzystano limit zapytań: dzienny konta, na sekundę albo zapytań bez ważnego klucza z jednego adresu.","headers":{"X-RateLimit-Limit":{"description":"Dzienny limit konta.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Ile zapytań zostało dziś.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Kiedy limit się odnowi: północ czasu polskiego w sekundach Unix.","schema":{"type":"integer"}},"Retry-After":{"description":"Za ile sekund ponowić zapytanie.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Wykorzystano limit zapytań: dzienny konta, na sekundę albo zapytań bez ważnego klucza z jednego adresu."}}}}},"503":{"description":"Prace serwisowe (maintenance) albo API chwilowo nie odpowiada (unavailable).","headers":{"Retry-After":{"description":"Za ile sekund ponowić zapytanie: do końca prac albo 60.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"maintenance","message":"Prace serwisowe (maintenance) albo API chwilowo nie odpowiada (unavailable)."}}}}}}}},"/categories":{"get":{"operationId":"listCategories","summary":"Drzewo kategorii","description":"Wszystkie kategorie z liczbą produktów i kodem GS1 GPC liści.","responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Dzienny limit konta.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Ile zapytań zostało dziś.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Kiedy limit się odnowi: północ czasu polskiego w sekundach Unix.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Categories"},"example":{"categories":[{"id":"zywnosc","name":"Żywność","parentId":null,"gpc":"50000000","products":0},{"id":"zywnosc/owoce","name":"Owoce","parentId":"zywnosc","gpc":"50000000","products":0},{"id":"zywnosc/owoce/jablka-i-gruszki","name":"Jabłka i gruszki","parentId":"zywnosc/owoce","gpc":"50250800","products":0}]}}}},"401":{"description":"Brak klucza API albo nieznany klucz.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Brak klucza API albo nieznany klucz."}}}}},"403":{"description":"Klucz zablokował administrator Ephemeris.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"key_blocked","message":"Klucz zablokował administrator Ephemeris."}}}}},"429":{"description":"Wykorzystano limit zapytań: dzienny konta, na sekundę albo zapytań bez ważnego klucza z jednego adresu.","headers":{"X-RateLimit-Limit":{"description":"Dzienny limit konta.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Ile zapytań zostało dziś.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Kiedy limit się odnowi: północ czasu polskiego w sekundach Unix.","schema":{"type":"integer"}},"Retry-After":{"description":"Za ile sekund ponowić zapytanie.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Wykorzystano limit zapytań: dzienny konta, na sekundę albo zapytań bez ważnego klucza z jednego adresu."}}}}},"503":{"description":"Prace serwisowe (maintenance) albo API chwilowo nie odpowiada (unavailable).","headers":{"Retry-After":{"description":"Za ile sekund ponowić zapytanie: do końca prac albo 60.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"maintenance","message":"Prace serwisowe (maintenance) albo API chwilowo nie odpowiada (unavailable)."}}}}}}}}},"components":{"securitySchemes":{"key":{"type":"http","scheme":"bearer","description":"Klucz API z Ephemeris (eph_…), w nagłówku Authorization: Bearer <klucz>."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Product":{"type":"object","required":["gtin","name","language","quantity","updatedOn","attribution"],"properties":{"gtin":{"type":"string"},"requestedCode":{"type":"string","description":"Kod z zapytania, gdy prowadzi do produktu głównego albo był w innym formacie."},"name":{"type":"string"},"brand":{"type":["string","null"]},"manufacturer":{"type":["string","null"]},"description":{"type":["string","null"]},"language":{"type":"string","const":"pl"},"category":{"type":["object","null"],"properties":{"id":{"type":"string"},"path":{"type":"array","items":{"type":"string"}},"gpc":{"type":["string","null"]}}},"quantity":{"type":"object","properties":{"amount":{"type":"string"},"unit":{"type":"string"},"text":{"type":"string"}}},"originCountry":{"type":["string","null"]},"gs1Country":{"type":"object","properties":{"kind":{"type":"string"},"name":{"type":["string","null"]},"note":{"type":"string"}}},"dimensionsCm":{"type":["object","null"]},"weightG":{"type":["string","null"]},"deposit":{"type":["object","null"],"properties":{"amount":{"type":"integer","description":"Grosze."},"currency":{"type":"string"}}},"food":{"type":["object","null"]},"variants":{"type":"array","items":{"type":"object"}},"multipacks":{"type":"array","items":{"type":"object"}},"contains":{"type":["object","null"]},"updatedOn":{"type":"string","format":"date"},"attribution":{"type":"string"}}},"SearchPage":{"type":"object","properties":{"query":{"type":"string"},"category":{"type":["string","null"]},"page":{"type":"integer"},"perPage":{"type":"integer"},"total":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"gtin":{"type":"string"},"name":{"type":"string"},"brand":{"type":["string","null"]},"quantity":{"type":"object"},"category":{"type":["string","null"]}}}}}},"Categories":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"parentId":{"type":["string","null"]},"gpc":{"type":["string","null"]},"products":{"type":"integer"}}}}}}}}}