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.

Utwórz statyczny kod QR z adresem

Załóż konto