From 9be6ad4124fee803d61b448b2c320a8ef9ed9585 Mon Sep 17 00:00:00 2001 From: Raphael Michel Date: Mon, 31 Jan 2022 10:20:23 +0100 Subject: [PATCH] Add documentation on secrets import plugin --- doc/plugins/imported_secrets.rst | 301 +++++++++++++++++++++++++++++ doc/plugins/index.rst | 1 + doc/user/events/ticket_secrets.rst | 2 + 3 files changed, 304 insertions(+) create mode 100644 doc/plugins/imported_secrets.rst diff --git a/doc/plugins/imported_secrets.rst b/doc/plugins/imported_secrets.rst new file mode 100644 index 0000000000..75568bde47 --- /dev/null +++ b/doc/plugins/imported_secrets.rst @@ -0,0 +1,301 @@ +Secrets Import +============== + +Usually, pretix generates ticket secrets (i.e. the QR code used for scanning) itself. You can read more about this +process at :ref:`secret_generators`. + +With the "Secrets Import" plugin, you can upload your own list of secrets to be used instead. This is useful for +integrating with third-party check-in systems. + + +API Resource description +------------------------- + +The secrets import plugin provides a HTTP API that allows you to create new secrets. + +The imported secret resource contains the following public fields: + +.. rst-class:: rest-resource-table + +===================================== ========================== ======================================================= +Field Type Description +===================================== ========================== ======================================================= +id integer Internal ID of the secret +secret string Actual string content of the secret (QR code content) +used boolean Whether the secret was already used for a ticket. If ``true``, + the secret can no longer be deleted. Secrets are never used + twice, even if an order is canceled or deleted. +item integer Internal ID of a product, or ``null``. If set, the secret + will only be used for tickets of this product. +variation integer Internal ID of a product variation, or ``null``. If set, the secret + will only be used for tickets of this product variation. +subevent integer Internal ID of an event series date, or ``null``. If set, the secret + will only be used for tickets of this event series date. +===================================== ========================== ======================================================= + +API Endpoints +------------- + +.. http:get:: /api/v1/organizers/(organizer)/events/(event)/imported_secrets/ + + Returns a list of all secrets imported for an event. + + **Example request**: + + .. sourcecode:: http + + GET /api/v1/organizers/bigevents/events/sampleconf/imported_secrets/ HTTP/1.1 + Host: pretix.eu + Accept: application/json, text/javascript + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: application/json + + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "id": 1, + "secret": "foobar", + "used": false, + "item": null, + "variation": null, + "subevent": null + } + ] + } + + :query page: The page number in case of a multi-page result set, default is 1 + :param organizer: The ``slug`` field of a valid organizer + :param event: The ``slug`` field of the event to fetch + :statuscode 200: no error + :statuscode 401: Authentication failure + :statuscode 403: The requested organizer or event does not exist **or** you have no permission to view it. + +.. http:get:: /api/v1/organizers/(organizer)/events/(event)/imported_secrets/(id)/ + + Returns information on one secret, identified by its ID. + + **Example request**: + + .. sourcecode:: http + + GET /api/v1/organizers/bigevents/events/sampleconf/imported_secrets/1/ HTTP/1.1 + Host: pretix.eu + Accept: application/json, text/javascript + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: application/json + + { + "id": 1, + "secret": "foobar", + "used": false, + "item": null, + "variation": null, + "subevent": null + } + + :param organizer: The ``slug`` field of the organizer to fetch + :param event: The ``slug`` field of the event to fetch + :param id: The ``id`` field of the secret to fetch + :statuscode 200: no error + :statuscode 401: Authentication failure + :statuscode 403: The requested organizer/event/secret does not exist **or** you have no permission to view it. + +.. http:post:: /api/v1/organizers/(organizer)/events/(event)/imported_secrets/ + + Create a new secret. + + **Example request**: + + .. sourcecode:: http + + POST /api/v1/organizers/bigevents/events/sampleconf/imported_secrets/ HTTP/1.1 + Host: pretix.eu + Accept: application/json, text/javascript + Content-Type: application/json + Content-Length: 166 + + { + "secret": "foobar", + "used": false, + "item": null, + "variation": null, + "subevent": null + } + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 201 Created + Vary: Accept + Content-Type: application/json + + { + "id": 1, + "secret": "foobar", + "used": false, + "item": null, + "variation": null, + "subevent": null + } + + :param organizer: The ``slug`` field of the organizer to a create new secret for + :param event: The ``slug`` field of the event to create a new secret for + :statuscode 201: no error + :statuscode 400: The secret could not be created due to invalid submitted data. + :statuscode 401: Authentication failure + :statuscode 403: The requested organizer/event does not exist **or** you have no permission to create secrets. + +.. http:post:: /api/v1/organizers/(organizer)/events/(event)/imported_secrets/bulk_create/ + + Create new secrets in bulk (up to 500 per request). The request either succeeds or fails entirely. + + **Example request**: + + .. sourcecode:: http + + POST /api/v1/organizers/bigevents/events/sampleconf/imported_secrets/bulk_create/ HTTP/1.1 + Host: pretix.eu + Accept: application/json, text/javascript + Content-Type: application/json + Content-Length: 166 + + [ + { + "secret": "foobar", + "used": false, + "item": null, + "variation": null, + "subevent": null + }, + { + "secret": "baz", + "used": false, + "item": null, + "variation": null, + "subevent": null + } + ] + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: application/json + + [ + { + "id": 1, + "secret": "foobar", + "used": false, + "item": null, + "variation": null, + "subevent": null + }, + { + "id": 2, + "secret": "baz", + "used": false, + "item": null, + "variation": null, + "subevent": null + } + ] + + :param organizer: The ``slug`` field of the organizer to create new secrets for + :param event: The ``slug`` field of the event to create new secrets for + :statuscode 201: no error + :statuscode 400: The secrets could not be created due to invalid submitted data. + :statuscode 401: Authentication failure + :statuscode 403: The requested organizer/event does not exist **or** you have no permission to create secrets. + + +.. http:patch:: /api/v1/organizers/(organizer)/events/(event)/imported_secrets/(id)/ + + Update a secret. You can also use ``PUT`` instead of ``PATCH``. With ``PUT``, you have to provide all fields of + the resource, other fields will be reset to default. With ``PATCH``, you only need to provide the fields that you + want to change. + + **Example request**: + + .. sourcecode:: http + + PATCH /api/v1/organizers/bigevents/events/sampleconf/imported_secrets/1/ HTTP/1.1 + Host: pretix.eu + Accept: application/json, text/javascript + Content-Type: application/json + Content-Length: 34 + + { + "item": 2 + } + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: text/javascript + + { + "id": 1, + "secret": "foobar", + "used": false, + "item": 2, + "variation": null, + "subevent": null + } + + :param organizer: The ``slug`` field of the organizer to modify + :param event: The ``slug`` field of the event to modify + :param id: The ``id`` field of the secret to modify + :statuscode 200: no error + :statuscode 400: The secret could not be modified due to invalid submitted data. + :statuscode 401: Authentication failure + :statuscode 403: The requested organizer/event/secret does not exist **or** you have no permission to change it. + + +.. http:delete:: /api/v1/organizers/(organizer)/events/(event)/imported_secrets/(id)/ + + Delete a secret. You can only delete secrets that have not yet been used. + + **Example request**: + + .. sourcecode:: http + + DELETE /api/v1/organizers/bigevents/events/sampleconf/imported_secrets/1/ HTTP/1.1 + Host: pretix.eu + Accept: application/json, text/javascript + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 204 No Content + Vary: Accept + + :param organizer: The ``slug`` field of the organizer to modify + :param event: The ``slug`` field of the event to modify + :param id: The ``id`` field of the secret to delete + :statuscode 204: no error + :statuscode 401: Authentication failure + :statuscode 403: The requested organizer/event/secret does not exist **or** you have no permission to change it **or** the secret has already been used + diff --git a/doc/plugins/index.rst b/doc/plugins/index.rst index 36650f6111..70696d32fc 100644 --- a/doc/plugins/index.rst +++ b/doc/plugins/index.rst @@ -17,4 +17,5 @@ If you want to **create** a plugin, please go to the campaigns certificates digital + imported_secrets webinar diff --git a/doc/user/events/ticket_secrets.rst b/doc/user/events/ticket_secrets.rst index 49b4b8cbbb..e4c00ec8c9 100644 --- a/doc/user/events/ticket_secrets.rst +++ b/doc/user/events/ticket_secrets.rst @@ -1,3 +1,5 @@ +.. _secret_generators: + Ticket secret generators ========================