API integratora DurableQR
API dynamicznych kodów QR
API pozwala systemom serwerowym tworzyć kody, odczytywać ich wersje, zmieniać miejsca docelowe, przygotowywać parametry renderera, eksportować mapę routingu i odbierać podpisane zdarzenia zmian kodów.
Ta strona jest projekcją aktualnych przykładów OpenAPI tworzoną podczas budowy. Nie wykonuje żądań ani nie przyjmuje sekretów; przykłady są wyłącznie tekstem referencyjnym.
Routing po stronie serwera
Twórz i listuj kody, odczytuj kod i jego wersje, zmieniaj miejsce docelowe z expected_version, wykonuj przywracanie jako nową wersję i eksportuj mapę konta. Drukowany adres to adres kodu, a nie adres docelowy.
API jest przeznaczone do wywołań z Twoich serwerów. CORS dopuszcza origin panelu, a nie publiczną integrację w przeglądarce, i strona publiczna nigdy nie wysyła przykładowych żądań.
Uwierzytelnianie i nagłówki żądań
Utwórz klucz API w panelu konta. Wysyłaj jego wartość Bearer przy każdym żądaniu razem z niepustym User-Agent. Żądania tworzenia wymagają także Idempotency-Key; przy niepewnym wyniku ponów to samo żądanie z tym samym kluczem i ciałem.
Klucz jest pokazywany raz podczas tworzenia i należy do konta w panelu. W przykładach pozostaw zmienną środowiskową; nigdy nie wklejaj prawdziwego klucza na stronę publiczną.
Aktualne przykłady żądań i odpowiedzi
Poniższe przykłady są wybierane bezpośrednio z przypiętego dokumentu OpenAPI. Każdy blok pokazuje metodę, ścieżkę, status, żądanie JSON, odpowiedź JSON i niewykonywane polecenie curl.
create — POST /v1/int/codes → 201
{
"destination_url": "https://example.com/menu/spring",
"fallback_url": "https://example.com/menu",
"name": "Spring menu, table cards"
}{
"id": "7K4M9QXT2B",
"url": "https://qr.durableqr.com/7K4M9QXT2B"
}curl --request POST 'https://api.durableqr.com/v1/int/codes' --header 'Authorization: Bearer ${DURABLEQR_API_KEY}' --header 'User-Agent: durableqr-example/1.0' --header 'Idempotency-Key: menu-spring-202610' --header 'Content-Type: application/json' --data '{"destination_url":"https://example.com/menu/spring","fallback_url":"https://example.com/menu","name":"Spring menu, table cards"}'destination — PUT /v1/int/codes/{code_id}/destination → 200
{
"expected_version": 3,
"destination_url": "https://example.com/menu/summer"
}{
"id": "7K4M9QXT2B",
"version": 4,
"destination_url": "https://example.com/menu/summer",
"fallback_url": "https://example.com/menu"
}curl --request PUT 'https://api.durableqr.com/v1/int/codes/7K4M9QXT2B/destination' --header 'Authorization: Bearer ${DURABLEQR_API_KEY}' --header 'User-Agent: durableqr-example/1.0' --header 'Content-Type: application/json' --data '{"expected_version":3,"destination_url":"https://example.com/menu/summer"}'render-spec — POST /v1/int/codes/{code_id}/render-spec → 200
{}{
"id": "7K4M9QXT2B",
"params": {
"data": "https://qr.durableqr.com/7K4M9QXT2B",
"format": "png"
}
}curl --request POST 'https://api.durableqr.com/v1/int/codes/7K4M9QXT2B/render-spec' --header 'Authorization: Bearer ${DURABLEQR_API_KEY}' --header 'User-Agent: durableqr-example/1.0' --header 'Content-Type: application/json' --data '{}'pause — POST /v1/int/codes/{code_id}/pause → 200
{
"expected_version": 1
}{
"id": "AAAAAAAAAA",
"state": "paused",
"version": 2
}curl --request POST 'https://api.durableqr.com/v1/int/codes/AAAAAAAAAA/pause' --header 'Authorization: Bearer ${DURABLEQR_API_KEY}' --header 'User-Agent: durableqr-example/1.0' --header 'Content-Type: application/json' --data '{"expected_version":1}'resume — POST /v1/int/codes/{code_id}/resume → 200
{
"expected_version": 1
}{
"id": "AAAAAAAAAA",
"state": "active",
"version": 2
}curl --request POST 'https://api.durableqr.com/v1/int/codes/AAAAAAAAAA/resume' --header 'Authorization: Bearer ${DURABLEQR_API_KEY}' --header 'User-Agent: durableqr-example/1.0' --header 'Content-Type: application/json' --data '{"expected_version":1}'delete — DELETE /v1/int/codes/{code_id} → 200
{
"expected_version": 1
}{
"id": "AAAAAAAAAA",
"state": "deleted",
"version": 2
}curl --request DELETE 'https://api.durableqr.com/v1/int/codes/AAAAAAAAAA' --header 'Authorization: Bearer ${DURABLEQR_API_KEY}' --header 'User-Agent: durableqr-example/1.0' --header 'Content-Type: application/json' --data '{"expected_version":1}'Wstrzymanie, wznowienie i usunięcie
Pause zmienia active na paused; resume zmienia paused na active. DELETE zmienia active, paused, grace lub frozen na deleted. Udana zmiana tworzy jedną nową wspólną wersję. Każde polecenie wymaga JSON z samym expected_version, również DELETE.
DELETE pozostawia trwały tombstone: identyfikator nie jest używany ponownie, a resume ani rollback nie przywrócą deleted. Odpowiedź 503 może nadejść po zapisaniu tombstone. Cleanup można kontynuować z bieżącą wersją tombstone: sukces zwraca 200 z tą samą wersją, nieukończony cleanup 503, błędna wersja 409, a kolejny DELETE po cleanup 404.
Detail nie ujawnia wersji tombstone. Jeśli znasz oczekiwane n, n+1 jest tylko protokołem kontynuacji cleanup, a nie dowodem wyniku ani endpointem statusu. Odpowiedź 404 nie dowodzi, kto usunął kod ani czy cleanup się zakończył.
Kod paused przekierowuje do fallback przez 302, a bez niego pokazuje neutralne 200. Fallback równy destination nie blokuje dostępu. Resume respektuje health i fallback; deleted zwraca 404 bez Location. Silny odczyt META rozpoczęty po zapisie, bez nowszego writera, widzi nowy stan; dodatkowy cache META DurableQR wynosi 0 s. To nie jest globalne SLA czasu i nie cofa wydanego Location ani pobranego zasobu.
Konflikty i ponawianie lifecycle
Niedozwolone przejście zwraca 409, blocked zwraca 403, deleted, brak kodu lub inny właściciel zwraca 404, a nieznany lub uszkodzony stan 503. Niedozwolony stan jest sprawdzany przed nieaktualną wersją. Nieaktualne expected_version lub wyścig zapisu zwraca 409; powstaje najwyżej jedna nowa wersja. Powtórne pause lub resume zwraca 409, nie sukces bez zmiany.
Funkcja zwraca 403 z code feature_not_entitled i message feature is not included in the account plan albo 403 z message the code cannot be changed dla kodu blocked. Komunikaty 409: the code cannot make this transition; expected_version does not match the current version; the code changed before this request committed; the code is frozen: it keeps its last destination; editing requires a paid account. Błędy gateway mają własne treści.
Te polecenia nie mają Idempotency-Key, cache odpowiedzi ani automatycznego ponawiania. Po niepewnym timeout odczytaj detail i uzgodnij stan oraz wersję; nie ponawiaj ślepo z nową wersją. Limity trzech tras to wspólne cele best-effort 0.005 żądania/s, burst 1, nie na klucz i nie gwarancja czasu oczekiwania.
Dostęp i niezależna retencja
Utrata api_access blokuje wszystkie trzy polecenia, także DELETE i cleanup retencji, przed walidacją biznesową. Cache uprawnień do 30 s i cache autoryzatora klucza 300 s są osobne, nie sumują się. Podczas awarii lub utraty uprawnienia potrzebujesz własnej bramy dostępu i procesu retencji.
Wersje i równoczesne zmiany
Zmiany miejsca docelowego i przywrócenia zawierają expected_version. Po ponowieniu odczytaj kod, aby nie powtórzyć zapisu, który już się udał. Przywrócenie tworzy nową wersję i nie przepisuje historii.
Odpowiedź API identyfikuje kod i wynikową wersję. Limity konta i tras obowiązują niezależnie od nazwy klucza API.
Parametry renderowania, szablony i eksport
Render-spec jest tylko do odczytu: przygotowuje zapytanie do render.durableqr.com i nie zapisuje projektu. Szablony wyglądu konta i eksport mapy są osobnymi operacjami z własnymi kształtami odpowiedzi.
Przy budowaniu adresu renderera użyj całej mapy response.params. Nie odtwarzaj pól stylu ani nie podstawiaj adresu docelowego.
Podpisane webhooki
Webhooki niosą code.created, code.destination_updated i code.destination_rolled_back. Weryfikuj podpis HMAC-SHA256 na dokładnej surowej treści z otrzymanym timestampem, porównuj w stałym czasie i deduplikuj event id przed zwróceniem sukcesu.
Pełny algorytm odbiornika i kontrakt webhooka znajdują się w dokumentacji API. Dostarczenie może duplikować lub zmieniać kolejność zdarzeń; nie jest to obietnica exactly-once ani SLA liczonego w sekundach.
Limity i oferty konta
Każda trasa ma wspólny docelowy limit best-effort dla wszystkich integratorów; nie ma limitu przypisanego do pojedynczego klucza. Opublikowane oferty Pro i Business obejmują dostęp API. Oferta jest czymś innym niż stan autoryzacji konkretnego konta.
Dostęp API jest wymieniony w katalogu dla planów pro i business.