diff --git a/doc/api/resources/index.rst b/doc/api/resources/index.rst index 70aec4d42..d9d11ccb8 100644 --- a/doc/api/resources/index.rst +++ b/doc/api/resources/index.rst @@ -1,6 +1,11 @@ Resources and endpoints ======================= +With a few exceptions, this only lists resources bundled in the pretix core modules. +Additional endpoints are provided by pretix plugins. Some of them are documented +at :ref:`plugin-docs`. + + .. toctree:: :maxdepth: 2 @@ -33,4 +38,4 @@ Resources and endpoints exporters sendmail_rules billing_invoices - billing_var + billing_var \ No newline at end of file diff --git a/doc/plugins/exhibitors.rst b/doc/plugins/exhibitors.rst new file mode 100644 index 000000000..e0f2c9634 --- /dev/null +++ b/doc/plugins/exhibitors.rst @@ -0,0 +1,363 @@ +Exhibitors +========== + +The exhibitors plugin allows to manage exhibitors at your trade show or conference. After signing up your exhibitors +in the system, you can assign vouchers to exhibitors and give them access to the data of these vouchers. The exhibitors +module is also the basis of the pretixLEAD lead scanning application. + +.. note:: On pretix Hosted, using the lead scanning feature of the exhibitors plugin can add additional costs + depending on your contract. + + +REST API Resource description +----------------------------- + +The exhibitors plugin provides a HTTP API that allows you to create new exhibitors. + +The exhibitors resource contains the following public fields: + +.. rst-class:: rest-resource-table + +===================================== ========================== ======================================================= +Field Type Description +===================================== ========================== ======================================================= +id integer Internal exhibitor ID in pretix +name string Exhibitor name +internal_id string Can be used for the ID in your exhibition system, your customer ID, etc. Can be ``null``. Maximum 255 characters. +contact_name string Contact person (or ``null``) +contact_name_parts object of strings Decomposition of contact name (i.e. given name, family name) +contact_email string Contact person email address (or ``null``) +booth string Booth number (or ``null``). Maximum 100 characters. +locale string Locale for communication with the exhibitor (or ``null``). +access_code string Access code for the exhibitor to access their data or use the lead scanning app (read-only). +allow_lead_scanning boolean Enables lead scanning app +allow_lead_access boolean Enables access to data gathered by the lead scanning app +allow_voucher_access boolean Enables access to data gathered by exhibitor vouchers +comment string Internal comment, not shown to exhibitor +===================================== ========================== ======================================================= + +You can also access the scanned leads through the API which contains the following public fields: + +.. rst-class:: rest-resource-table + +===================================== ========================== ======================================================= +Field Type Description +===================================== ========================== ======================================================= +attendee_order string Order code of the order the scanned attendee belongs to +attendee_positionid integer ``positionid`` if the attendee within the order specified by ``attendee_order`` +rating integer A rating of 0 to 5 stars (or ``null``) +notes string A note taken by the exhibitor after scanning +tags list of strings Additional tags selected by the exhibitor +first_upload datetime Date and time of the first upload of this lead +===================================== ========================== ======================================================= + +REST API Endpoints +------------------ + +.. http:get:: /api/v1/organizers/(organizer)/events/(event)/exhibitors/ + + Returns a list of all exhibitors configured for an event. + + **Example request**: + + .. sourcecode:: http + + GET /api/v1/organizers/bigevents/events/sampleconf/exhibitors/ 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, + "name": "Aperture Science", + "internal_id": null, + "contact_name": "Dr Cave Johnson", + "contact_name_parts": { + "_scheme": "salutation_title_given_family", + "family_name": "Johnson", + "given_name": "Cave", + "salutation": "", + "title": "Dr" + }, + "contact_email": "johnson@as.example.org", + "booth": "A2", + "locale": "de", + "access_code": "VKHZ2FU8", + "allow_lead_scanning": true, + "allow_lead_access": true, + "allow_voucher_access": true, + "comment": "" + } + ] + } + + :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)/exhibitors/(id)/ + + Returns information on one exhibitor, identified by its ID. + + **Example request**: + + .. sourcecode:: http + + GET /api/v1/organizers/bigevents/events/sampleconf/exhibitors/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, + "name": "Aperture Science", + "internal_id": null, + "contact_name": "Dr Cave Johnson", + "contact_name_parts": { + "_scheme": "salutation_title_given_family", + "family_name": "Johnson", + "given_name": "Cave", + "salutation": "", + "title": "Dr" + }, + "contact_email": "johnson@as.example.org", + "booth": "A2", + "locale": "de", + "access_code": "VKHZ2FU8", + "allow_lead_scanning": true, + "allow_lead_access": true, + "allow_voucher_access": true, + "comment": "" + } + + :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 exhibitor to fetch + :statuscode 200: no error + :statuscode 401: Authentication failure + :statuscode 403: The requested organizer/event/exhibitor does not exist **or** you have no permission to view it. + +.. http:get:: /api/v1/organizers/(organizer)/events/(event)/exhibitors/(id)/leads/ + + Returns a list of all scanned leads of an exhibitor. + + **Example request**: + + .. sourcecode:: http + + GET /api/v1/organizers/bigevents/events/sampleconf/exhibitors/1/leads/ 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": [ + { + "attendee_order": "T0E7E", + "attendee_positionid": 1, + "rating": 1, + "notes": "", + "tags": [], + "first_upload": "2021-07-06T11:03:31.414491+01:00" + } + ] + } + + :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 + :param id: The ``id`` field of the exhibitor to fetch + :statuscode 200: no error + :statuscode 401: Authentication failure + :statuscode 403: The requested organizer or event or exhibitor does not exist **or** you have no permission to view it. + +.. http:post:: /api/v1/organizers/(organizer)/events/(event)/exhibitors/ + + Create a new exhibitor. + + **Example request**: + + .. sourcecode:: http + + POST /api/v1/organizers/bigevents/events/sampleconf/exhibitors/ HTTP/1.1 + Host: pretix.eu + Accept: application/json, text/javascript + Content-Type: application/json + Content-Length: 166 + + { + "name": "Aperture Science", + "internal_id": null, + "contact_name_parts": { + "_scheme": "salutation_title_given_family", + "family_name": "Johnson", + "given_name": "Cave", + "salutation": "", + "title": "Dr" + }, + "contact_email": "johnson@as.example.org", + "booth": "A2", + "locale": "de", + "access_code": "VKHZ2FU8", + "allow_lead_scanning": true, + "allow_lead_access": true, + "allow_voucher_access": true, + "comment": "" + } + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 201 Created + Vary: Accept + Content-Type: application/json + + { + "id": 1, + "name": "Aperture Science", + "internal_id": null, + "contact_name": "Dr Cave Johnson", + "contact_name_parts": { + "_scheme": "salutation_title_given_family", + "family_name": "Johnson", + "given_name": "Cave", + "salutation": "", + "title": "Dr" + }, + "contact_email": "johnson@as.example.org", + "booth": "A2", + "locale": "de", + "access_code": "VKHZ2FU8", + "allow_lead_scanning": true, + "allow_lead_access": true, + "allow_voucher_access": true, + "comment": "" + } + + :param organizer: The ``slug`` field of the organizer to create new exhibitor for + :param event: The ``slug`` field of the event to create new exhibitor for + :statuscode 201: no error + :statuscode 400: The exhibitor 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 exhibitors. + + +.. http:patch:: /api/v1/organizers/(organizer)/events/(event)/exhibitors/(id)/ + + Update an exhibitor. 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/digitalcontents/1/ HTTP/1.1 + Host: pretix.eu + Accept: application/json, text/javascript + Content-Type: application/json + Content-Length: 34 + + { + "internal_id": "ABC" + } + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: text/javascript + + { + "id": 1, + "name": "Aperture Science", + "internal_id": "ABC", + "contact_name": "Dr Cave Johnson", + "contact_name_parts": { + "_scheme": "salutation_title_given_family", + "family_name": "Johnson", + "given_name": "Cave", + "salutation": "", + "title": "Dr" + }, + "contact_email": "johnson@as.example.org", + "booth": "A2", + "locale": "de", + "access_code": "VKHZ2FU8", + "allow_lead_scanning": true, + "allow_lead_access": true, + "allow_voucher_access": true, + "comment": "" + } + + :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 exhibitor to modify + :statuscode 200: no error + :statuscode 400: The exhibitor could not be modified due to invalid submitted data. + :statuscode 401: Authentication failure + :statuscode 403: The requested organizer/event/exhibitor does not exist **or** you have no permission to change it. + + +.. http:delete:: /api/v1/organizers/(organizer)/events/(event)/exhibitors/(id)/ + + Delete an exhibitor. + + .. warning:: This deletes all lead scan data and removes all connections to vouchers (the vouchers are not deleted). + + **Example request**: + + .. sourcecode:: http + + DELETE /api/v1/organizers/bigevents/events/sampleconf/exhibitors/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 exhibitor to delete + :statuscode 204: no error + :statuscode 401: Authentication failure + :statuscode 403: The requested organizer/event/exhibitor does not exist **or** you have no permission to change it diff --git a/doc/plugins/index.rst b/doc/plugins/index.rst index 1b441794d..04a4600aa 100644 --- a/doc/plugins/index.rst +++ b/doc/plugins/index.rst @@ -1,3 +1,5 @@ +.. _`plugin-docs`: + Plugin documentation ==================== @@ -10,13 +12,13 @@ If you want to **create** a plugin, please go to the :maxdepth: 2 list - pretixdroid banktransfer ticketoutputpdf badges campaigns certificates digital + exhibitors imported_secrets webinar presale-saml diff --git a/doc/plugins/list.rst b/doc/plugins/list.rst index b5790a3fd..89c6de87d 100644 --- a/doc/plugins/list.rst +++ b/doc/plugins/list.rst @@ -5,6 +5,6 @@ List of plugins =============== A detailed list of plugins that are available for pretix can be found on the -`project website`_. +`pretix Marketplace`_. -.. _project website: https://pretix.eu/about/en/plugins +.. _pretix Marketplace: https://marketplace.pretix.eu diff --git a/doc/plugins/pretixdroid.rst b/doc/plugins/pretixdroid.rst deleted file mode 100644 index a267f794b..000000000 --- a/doc/plugins/pretixdroid.rst +++ /dev/null @@ -1,368 +0,0 @@ -pretixdroid HTTP API -==================== - -The pretixdroid plugin provides a HTTP API that the `pretixdroid Android app`_ -uses to communicate with the pretix server. - -.. warning:: This API is **DEPRECATED** and will probably go away soon. It is used **only** to serve the pretixdroid - Android app. There are no backwards compatibility guarantees on this API. We will not add features that - are not required for the Android App. There is a general-purpose :ref:`rest-api` that provides all - features that you need to check in. - -.. versionchanged:: 1.12 - - Support for check-in-time questions has been added. The new API features are fully backwards-compatible and - negotiated live, so clients which do not need this feature can ignore the change. For this reason, the API version - has not been increased and is still set to 3. - -.. versionchanged:: 1.13 - - Support for checking in unpaid tickets has been added. - - -.. http:post:: /pretixdroid/api/(organizer)/(event)/redeem/ - - Redeems a ticket, i.e. checks the user in. - - **Example request**: - - .. sourcecode:: http - - POST /pretixdroid/api/demoorga/democon/redeem/?key=ABCDEF HTTP/1.1 - Host: demo.pretix.eu - Accept: application/json, text/javascript - Content-Type: application/x-www-form-urlencoded - - secret=az9u4mymhqktrbupmwkvv6xmgds5dk3&questions_supported=true - - You **must** set the parameter secret. - - You **must** set the parameter ``questions_supported`` to ``true`` **if** you support asking questions - back to the app operator. You **must not** set it if you do not support this feature. In that case, questions - will just be ignored. - - You **may** set the additional parameter ``datetime`` in the body containing an ISO8601-encoded - datetime of the entry attempt. If you don"t, the current date and time will be used. - - You **may** set the additional parameter ``force`` to indicate that the request should be logged - regardless of previous check-ins for the same ticket. This might be useful if you made the entry decision offline. - Questions will also always be ignored in this case (i.e. supplied answers will be saved, but no error will be - thrown if they are missing or invalid). - - You **may** set the additional parameter ``nonce`` with a globally unique random value to identify this - check-in. This is meant to be used to prevent duplicate check-ins when you are just retrying after a connection - failure. - - You **may** set the additional parameter ``ignore_unpaid`` to indicate that the check-in should be performed even - if the order is in pending state. - - If questions are supported and required, you will receive a dictionary ``questions`` containing details on the - particular questions to ask. To answer them, just re-send your redemption request with additional parameters of - the form ``answer_=``, e.g. ``answer_12=24``. - - **Example successful response**: - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: text/json - - { - "status": "ok" - "version": 3, - "data": { - "secret": "az9u4mymhqktrbupmwkvv6xmgds5dk3", - "order": "ABCDE", - "item": "Standard ticket", - "item_id": 1, - "variation": null, - "variation_id": null, - "attendee_name": "Peter Higgs", - "attention": false, - "redeemed": true, - "checkin_allowed": true, - "addons_text": "Parking spot", - "paid": true - } - } - - **Example response with required questions**: - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: text/json - - { - "status": "incomplete" - "version": 3 - "data": { - "secret": "az9u4mymhqktrbupmwkvv6xmgds5dk3", - "order": "ABCDE", - "item": "Standard ticket", - "item_id": 1, - "variation": null, - "variation_id": null, - "attendee_name": "Peter Higgs", - "attention": false, - "redeemed": true, - "checkin_allowed": true, - "addons_text": "Parking spot", - "paid": true - }, - "questions": [ - { - "id": 12, - "type": "C", - "question": "Choose a shirt size", - "required": true, - "position": 2, - "items": [1], - "options": [ - { - "id": 24, - "answer": "M" - }, - { - "id": 25, - "answer": "L" - } - ] - } - ] - } - - **Example error response with data**: - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: text/json - - { - "status": "error", - "reason": "already_redeemed", - "version": 3, - "data": { - "secret": "az9u4mymhqktrbupmwkvv6xmgds5dk3", - "order": "ABCDE", - "item": "Standard ticket", - "item_id": 1, - "variation": null, - "variation_id": null, - "attendee_name": "Peter Higgs", - "attention": false, - "redeemed": true, - "checkin_allowed": true, - "addons_text": "Parking spot", - "paid": true - } - } - - **Example error response without data**: - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: text/json - - { - "status": "error", - "reason": "unkown_ticket", - "version": 3 - } - - Possible error reasons: - - * ``unpaid`` - Ticket is not paid for or has been refunded - * ``already_redeemed`` - Ticket already has been redeemed - * ``product`` - Tickets with this product may not be scanned at this device - * ``unknown_ticket`` - Secret does not match a ticket in the database - - :query key: Secret API key - :statuscode 200: Valid request - :statuscode 404: Unknown organizer or event - :statuscode 403: Invalid authorization key - -.. http:get:: /pretixdroid/api/(organizer)/(event)/search/ - - Searches for a ticket. - At most 25 results will be returned. **Queries with less than 4 characters will always return an empty result set.** - - **Example request**: - - .. sourcecode:: http - - GET /pretixdroid/api/demoorga/democon/search/?key=ABCDEF&query=Peter HTTP/1.1 - Host: demo.pretix.eu - Accept: application/json, text/javascript - - **Example response**: - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: text/json - - { - "results": [ - { - "secret": "az9u4mymhqktrbupmwkvv6xmgds5dk3", - "order": "ABCE6", - "item": "Standard ticket", - "variation": null, - "attendee_name": "Peter Higgs", - "redeemed": false, - "attention": false, - "checkin_allowed": true, - "addons_text": "Parking spot", - "paid": true - }, - ... - ], - "version": 3 - } - - :query query: Search query - :query key: Secret API key - :statuscode 200: Valid request - :statuscode 404: Unknown organizer or event - :statuscode 403: Invalid authorization key - -.. http:get:: /pretixdroid/api/(organizer)/(event)/download/ - - Download data for all tickets. - - **Example request**: - - .. sourcecode:: http - - GET /pretixdroid/api/demoorga/democon/download/?key=ABCDEF HTTP/1.1 - Host: demo.pretix.eu - Accept: application/json, text/javascript - - **Example response**: - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: text/json - - { - "version": 3, - "results": [ - { - "secret": "az9u4mymhqktrbupmwkvv6xmgds5dk3", - "order": "ABCE6", - "item": "Standard ticket", - "variation": null, - "attendee_name": "Peter Higgs", - "redeemed": false, - "attention": false, - "checkin_allowed": true, - "paid": true - }, - ... - ], - "questions": [ - { - "id": 12, - "type": "C", - "question": "Choose a shirt size", - "required": true, - "position": 2, - "items": [1], - "options": [ - { - "id": 24, - "answer": "M" - }, - { - "id": 25, - "answer": "L" - } - ] - } - ] - } - - :query key: Secret API key - :statuscode 200: Valid request - :statuscode 404: Unknown organizer or event - :statuscode 403: Invalid authorization key - -.. http:get:: /pretixdroid/api/(organizer)/(event)/status/ - - Returns status information, such as the total number of tickets and the - number of performed check-ins. - - **Example request**: - - .. sourcecode:: http - - GET /pretixdroid/api/demoorga/democon/status/?key=ABCDEF HTTP/1.1 - Host: demo.pretix.eu - Accept: application/json, text/javascript - - **Example response**: - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: text/json - - { - "checkins": 17, - "total": 42, - "version": 3, - "event": { - "name": "Demo Conference", - "slug": "democon", - "date_from": "2016-12-27T17:00:00Z", - "date_to": "2016-12-30T18:00:00Z", - "timezone": "UTC", - "url": "https://demo.pretix.eu/demoorga/democon/", - "organizer": { - "name": "Demo Organizer", - "slug": "demoorga" - }, - }, - "items": [ - { - "name": "T-Shirt", - "id": 1, - "checkins": 1, - "admission": False, - "total": 1, - "variations": [ - { - "name": "Red", - "id": 1, - "checkins": 1, - "total": 12 - }, - { - "name": "Blue", - "id": 2, - "checkins": 4, - "total": 8 - } - ] - }, - { - "name": "Ticket", - "id": 2, - "checkins": 15, - "admission": True, - "total": 22, - "variations": [] - } - ] - } - - :query key: Secret API key - :statuscode 200: Valid request - :statuscode 404: Unknown organizer or event - :statuscode 403: Invalid authorization key - -.. _pretixdroid Android app: https://github.com/pretix/pretixdroid diff --git a/doc/spelling_wordlist.txt b/doc/spelling_wordlist.txt index 1edaa4076..b645083ae 100644 --- a/doc/spelling_wordlist.txt +++ b/doc/spelling_wordlist.txt @@ -103,6 +103,7 @@ prepending preprocessor presale pretix +pretixLEAD pretixSCAN pretixdroid pretixPOS