To nie jest API katalogu spożywczego.To API do zapisu na jednym prawdziwym koncie.
Skieruj Grocey na swojego użytkownika. Loguje się raz, do własnego sklepu, w odizolowanej sesji przeglądarki. W zamian dostajesz jego prawdziwą historię zamówień, jego prawdziwe adresy dostawy i terminy, oraz koszyk, do którego możesz zapisywać: jedyną rzecz, której nigdy nie da Ci publiczny katalog ani scraper, bo odczytanie czyjegoś konta wymaga zalogowania się jako ta osoba.
GET https://api.grocey.shop/v1/connections/cxn_a1b2c3/profile Authorization: Bearer gro_live_… → 200 { "profile": { "status": "ready", "orders": { "supported": true, "value": [ {…} ] }, "addresses": { "supported": true, "value": [ {…} ] }, "favourites": { "supported": false } } }
Dwa poświadczenia, celowo
Jeden klucz dla Twojej aplikacji. Jeden cookie dla Twojego użytkownika.
Grocey odpowiada na dwa różne pytania i nigdy nie pozwala, by jedno poświadczenie odpowiadało na oba naraz.
Płaszczyzna deweloperska
api.grocey.shop/v1/*·POST /mcp
Authorization: Bearer gro_live_… (or gro_test_…)
Twój serwer, rozmawiający z Grocey jako Twoja aplikacja. Każde żądanie niesie Twój klucz, a na tej płaszczyźnie nie ma ani jednej anonimowej trasy, łącznie z katalogiem dostawców.
Płaszczyzna użytkownika końcowego
link.grocey.shop/c·/api/session*
a signed, single-use link nonce, plus the gr_owner cookie
Osoba, która dowodzi, że jest właścicielem konta, które za chwilę połączy. Jej przeglądarka nigdy nie widzi ani nie przechowuje Twojego klucza API, a Twój klucz nigdy nie musi opuszczać Twojego serwera, by do niej dotrzeć.
Ten podział nie jest przypadkowy. Publiczne API katalogu musi odpowiedzieć tylko na jedno pytanie: czy ta aplikacja ma prawo pytać. API integracji sklepu spożywczego, które czyta czyjeś prawdziwe zamówienia, musi odpowiedzieć też na drugie: czy ta osoba jest tym, za kogo się podaje, a odpowiedzieć na to może tylko jej własne logowanie. Połączenie obu w jedno poświadczenie oznaczałoby albo wysłanie sekretu Twojego serwera do przeglądarki, albo zmuszenie każdego z Twoich użytkowników do założenia konta Grocey tylko po to, by dwukrotnie udowodnić, kim jest.
Jak użytkownik faktycznie się łączy
Wygeneruj link. Użytkownik się loguje. Ty dostajesz z powrotem identyfikator.
Żadnego SDK do osadzenia i żadne z jego danych logowania nigdy nie przechodzą przez Twoje serwery.
WywołajPOST /v1/connect_linksz własnymredirect_urlorazend_user_id. Celhttpsjest rejestrowany w twojej aplikacji z wyprzedzeniem; własny schemat aplikacji, taki jakyourapp://returnjuż nie, bo wyniki wracają przez API i webhooka, a nie przez przekierowanie, więc pod tym adresem nie ma nic, co warto byłoby ukraść. Tak czy inaczej,redirect_urljest odczytywany z wywołania mint, nigdy ze strony, na którą trafia użytkownik, i właśnie dzięki temu link do połączenia nie staje się otwartym przekierowaniem w przepływie, gdzie miałoby to największe znaczenie.
Użytkownik otwiera link, widzi, o co prosisz, wybiera dostawcę (Delio, Frisco.pl or Woltdzisiaj) i loguje się dokładnie tak samo, jak zrobiłby to na stronie danego sklepu.
Dalej mogą się wydarzyć trzy rzeczy. Użytkownik łączy konto, a twoje przekierowanie dostajeconnection_id. Użytkownik zamyka okno, czyli nic nawet nie zostało podjęte, więc żaden webhook nie leci, a uznanie tego za błąd byłoby pomyłką. Albo pojawia się prawdziwy błąd, pokazany w oknie, z powrotem w formie przycisku, nigdy jako automatyczne przekierowanie, bo to jedyny moment, w którym wyjaśnienie naprawdę się liczy. Przeglądarkę, która nigdy nie wraca, traktuj tak samo jak anulowanie: przeglądarka, nad którą nie masz kontroli, po prostu może nie wrócić. To webhook faktycznie mówi ci, że połączenie istnieje.
POST https://api.grocey.shop/v1/connect_links { "end_user_id": "usr_42", "redirect_url": "https://your-app.example/return", "state": "whatever-you-need-back" } → { "connect_link_id": "cl_9f2k…", "url": "https://link.grocey.shop/c/…" } # the redirect, on success https://your-app.example/return?status=connected &connection_id=cxn_a1b2c3&state=whatever-you-need-back
Sygnał, na którym naprawdę można budować
Przekierowanie to udogodnienie interfejsu. Webhook to zapis zdarzenia.
Celowo zapożyczone od Plaid: przeglądarka, nad którą nie masz kontroli, może zniknąć w połowie procesu, więc to, czy połączenie istnieje, nie powinno zależeć od jej powrotu.
Deweloper, który czyta tylko przekierowanie, dowiaduje się jedynie o połączeniach, które kończą się bez zakłóceń, i o niczym więcej. Ktoś, kto zamknie kartę, zgubi kod SMS albo utknie na ekranie logowania sklepu, nie zostawia żadnego przekierowania, a to właśnie te konta musisz znać najbardziej. Webhook wysyła się z serwera Grocey w chwili, gdy coś się wydarzy, niezależnie od tego, czy przeglądarka jest jeszcze otwarta, by to usłyszeć.
Każdy ładunek jest podpisany:Grocey-Signature: t={timestamp},v1={hex}, HMAC-SHA256 liczony z{timestamp}.{raw body}, czyli schemat samego Stripe, bo to pod niego większość backendów ma już gotowy kod bibliotek. Dostarczanie działa w trybie at-least-once, więcevent_idto klucz idempotencji, a kolejność przy ponowieniach nie jest gwarantowana: do 8 prób z wykładniczym backoffem i jitterem, rozłożonych na mniej więcej 24 godziny, zanim dostarczenie zostanie oznaczone jako wyczerpane.GET /v1/eventspokazuje każde dostarczenie, więc pominięte ogarniasz sam, bez zgłoszenia do supportu, aPOST /v1/events/{id}/replaywysyła dokładnie ten sam ładunek ponownie, z nowym podpisem.
connection.created Działa już dziś Logowanie zostało zweryfikowane. Zawiera nowy connection_id.
connection.enriched Działa już dziś Pierwszy odczyt zamówień, adresów, ulubionych i wzorców wydatków na koncie się zakończył. Uruchamia się po connection.created, według własnego harmonogramu, nigdy przed nim.
connection.failed Działa już dziś Próba połączenia zakończyła się bez działającej sesji.
connection.deleted Działa już dziś Deweloper albo użytkownik końcowy usunął połączenie.
connection.stale Zadeklarowane, jeszcze nieuruchomione Jest w kontrakcie. Sesja, której nie da się odświeżyć, dziś oznacza połączenie wewnętrznie jako nieaktualne, więc odczyt odpowiada „połącz to konto ponownie” zamiast dziwnie zawodzić, ale ta zmiana stanu nie wysyła jeszcze webhooka.
connection.revoked Zadeklarowane, jeszcze nieuruchomione Jest w kontrakcie. Nic w dzisiejszym środowisku uruchomieniowym nie odróżnia dostawcy aktywnie cofającego dostęp od zwykłej wygasłej sesji, więc to zdarzenie nie ma jeszcze punktu wyzwalającego.
connection.staleiconnection.revokedto prawdziwe, zadeklarowane typy zdarzeń. Żaden z nich nie jest jeszcze wysyłany przez runtime i ta strona mówi to wprost, zamiast pozwalać, by kontrakt sugerował więcej, niż potrafi kod. Jeden kontrakt, 15 metod, 5 dostawców
Każdy dostawca odpowiada w tym samym kształcie.
getFulfilment,search,cart,orders,addToCarti więcej: te same metody, te same typy, niezależnie od tego, który sklep podłączysz. Lista poniżej to dane, po których przechodzi test zgodności, a nie obietnica na papierze.
getFulfilmentfulfilmentOptionssetFulfilmentstoressearchcategoriescatalogPageordersorderDetailscartaddToCartremoveFromCartclearCartsuggestReplacementscartUrl Plus 2 metody opcjonalne, których żaden dostawca jeszcze nie implementuje:paymentMethods,checkout(zobacz „Czego Grocey nie robi” poniżej).
API supermarketu, które tylko czyta katalog, nie potrzebuje takiej dyscypliny. Takie, które zapisuje do czyjegoś prawdziwego koszyka, już tak:GET /v1/providerszwraca dokładnie tę macierz, wyliczoną z tych samych deklaracji, które czyta samo API, więc ta strona nigdy nie obieca funkcji, której kod nie ma.
Collect&Go W budowie Zakupy z odbiorem w punkcie od Colruyt w Belgii i Luksemburgu. Zaloguj się e-mailem i hasłem do Collect&Go.
Delio Aktywne Polska dostawa artykułów spożywczych. Zaloguj się numerem telefonu i kodem SMS.
Frisco.pl W budowie Polski internetowy supermarket z dostawą samochodem. Zaloguj się e-mailem i hasłem.
Żabka Jush W budowie Ekspresowa dostawa zakupów od Żabki w Polsce. To samo konto i logowanie co w Delio.
Wolt W budowie Zakupy spożywcze i sklepy na Wolt. Zaloguj się linkiem, który Wolt wysyła na Twój adres e-mail.
Pełne zestawienie metoda po metodzie znajdziesz na własnej stronie każdego dostawcy w katalogu integracji.
Jedna czynność, której nie automatyzujemy
Nie ma narzędzia do składania zamówień.
Grocey celowo zatrzymuje swój zasięg przed miejscem, w którym poruszają się pieniądze. checkout istnieje w kontrakcie jako metoda opcjonalna, większość dostawców w ogóle jej nie ma, a złożenie zamówienia przez nią wymaga spełnienia naraz trzech niezależnych warunków: flagi środowiskowej, którą właściciel włącza osobno dla każdego wdrożenia, zapisanej metody płatności, którą sam właściciel konta wcześniej zapisał (dziś nie ma jej nikt, na żadnym połączonym koncie), oraz tokenu wygenerowanego przez serwer i związanego z dokładną zawartością potwierdzanego koszyka.
Model nie jest w stanie ominąć żadnego z tych trzech warunków samą rozmową. Otwarcie płatnego checkoutu dla zewnętrznych deweloperów na danych logowania, które przechowujemy, to osobna decyzja z własnym przeglądem, i nie zapada tutaj przez przeoczenie.
Tak wygląda uczciwie zbudowane agentowe API handlowe: prawdziwe konto, prawdziwe działania i jedno twarde ograniczenie, wokół którego zbudowany jest cały kontrakt.
Jak uzyskać dostęp
Wersja prywatna, imiennie zaproszeni deweloperzy.
Nie ma jeszcze samodzielnej rejestracji. Grocey jest dziś w wersji prywatnej, bo otwarcie jej publicznie wymaga dwóch rzeczy, które nie są jeszcze gotowe: prawnej analizy regulaminu każdego dostawcy oraz odpowiedzi na pytania RODO związane z prowadzeniem czyjegoś konta w jego imieniu. Dostęp przyznawany jest indywidualnie, imiennie zaproszonym deweloperom, dopóki obie sprawy się nie domkną.
Gdy cennik powstanie, opłata będzie naliczana za połączenie, nie za zapytanie: connect to żywa, odizolowana sesja przeglądarki wobec prawdziwego sklepu, a nie tanie wywołanie API, które można zbuforować i zapomnieć. Nie ma jeszcze żadnej liczby i nie będzie, dopóki nie zmierzymy realnego limitu równoległych połączeń, na którym się to opiera.
Najczęstsze pytania
Pytania, które naprawdę zadają deweloperzy.
Czy jest środowisko testowe (sandbox)?
Klucz gro_test_ trafi do jednego deterministycznego dostawcy testowego, dzięki czemu integrację można zbudować i przetestować, zanim potrzebny Ci kraj zostanie realnie obsłużony. To funkcja planowana, jeszcze nie wdrożona: nigdy nie pojawi się w tabeli pokrycia i nigdy nie posłuży jako dowód, że prawdziwy dostawca działa.
Którzy dostawcy naprawdę działają już dziś?
Delio ma za sobą prawdziwe połączenie. Collect&Go, Frisco.pl, Żabka Jush i Wolt są gotowe i przetestowane jednostkowo względem prawdziwego kontraktu, ale żadne z nich nie łączyło się jeszcze z aktywnym kontem, dlatego mają tu status Building, a nie Live.
Czy Grocey składa zamówienia w czyimś'w jego imieniu?
Nie. Na żywo działają wyszukiwanie, koszyk, realizacja dostawy i historia zamówień. checkout istnieje w kontrakcie jako metoda opcjonalna, domyślnie zablokowana, i nic w produkcji nigdy nie złożyło przez nią prawdziwego zamówienia.
Czy mogę wywołać to z Claude albo ChatGPT?
Tak. Grocey działa też jako serwer MCP dla zakupów spożywczych: POST /mcp mówi tym samym kontraktem co REST API, więc agent obsługujący MCP wywołuje bezpośrednio grocery_search, grocery_cart, grocery_add_to_cart i resztę, tym samym kluczem gro_*.
Czym różni się to od scrapowania albo publicznego katalogu produktów?
Grocey loguje się jako prawdziwe konto, w odizolowanej sesji przeglądarki, dokładnie tak, jak zrobiłby to właściciel konta ręcznie. Nie ma publicznego katalogu do scrapowania ani partnerskiego API supermarketu, na które trzeba czekać, dlatego też każdy odczyt jest ograniczony do konta jednej konkretnej osoby, a nie do wspólnego, ogólnego zbioru danych.
Co właściwie mógłbym z tym zbudować?
Agenta AI do zakupów spożywczych, który wypełnia koszyk na podstawie przepisu albo planu posiłków na tydzień. Asystenta ponownych zamówień, który obserwuje historię zamówień pod kątem kończących się produktów i pyta, zanim cokolwiek doda. Sprawdzenie ceny albo dostępności we wszystkich sklepach, które dana osoba połączyła, na jej własnym koncie, zamiast na publicznym katalogu, który jest nieaktualny w chwili, gdy tylko zmieni się stan magazynowy sklepu.
Jak uzyskać dostęp?
Nie ma jeszcze samodzielnej rejestracji. Poproś o dostęp, a my ręcznie utworzymy dla Ciebie klucz, dopasowany do tego, co budujesz.
Budujesz agenta AI do zakupów, który potrzebuje prawdziwego konta?
Grocey jest w wersji prywatnej. Powiedz nam, co budujesz, a przygotujemy dla Ciebie klucz.