forked from CGM_Public/pretix_original
Docs: Add Exhibitor API docs (Z#23225216) (#6184)
* Docs: Add Exhibitor API docs * Docs: Add Resource-table for Exhibitor vouchers
This commit is contained in:
Martin Gross
@@ -844,3 +844,187 @@ You can also fetch existing leads (if you are authorized to do so):
|
||||
:statuscode 200: No error
|
||||
:statuscode 401: Invalid authentication code
|
||||
:statuscode 403: Not permitted to access bulk data
|
||||
|
||||
Retrieving Vouchers
|
||||
"""""""""""""""""""
|
||||
|
||||
Vouchers returned by the App API use a different format than described in :ref:`rest-vouchers`.
|
||||
|
||||
.. rst-class:: rest-resource-table
|
||||
|
||||
===================================== ========================== =======================================================
|
||||
Field Type Description
|
||||
===================================== ========================== =======================================================
|
||||
id integer Internal ID of the voucher
|
||||
code string The voucher code that is required to redeem the voucher
|
||||
max_usages integer The maximum number of times this voucher can be
|
||||
redeemed (default: 1).
|
||||
redeemed integer The number of times this voucher already has been
|
||||
redeemed.
|
||||
valid_until datetime The voucher expiration date (or ``null``).
|
||||
subevent string Name of the date inside an event series this voucher belongs to (or ``null``).
|
||||
tag string A string that is used for grouping vouchers
|
||||
comment string An internal exhibitor comment on the voucher.
|
||||
items list of strings A list of items this voucher is restricted to (or ``null``).
|
||||
price_mode string Determines how this voucher affects product prices.
|
||||
Possible values:
|
||||
|
||||
* ``none`` – No effect on price
|
||||
* ``set`` – The product price is set to the given ``value``
|
||||
* ``subtract`` – The product price is determined by the original price *minus* the given ``value``
|
||||
* ``percent`` – The product price is determined by the original price reduced by the percentage given in ``value``
|
||||
value decimal (string) The value (see ``price_mode``)
|
||||
redemptions list of objects A list of objects, where each object represents an order position that has been purchased using the voucher.
|
||||
Each entry will contains the fields ``attendee_fields``, ``redemption_date`` and ``subevent``.
|
||||
|
||||
The attendee data in the ``attendee_fields`` that is shown is based on the event's configuration, and each entry
|
||||
contains the fields ``id``, ``label``, ``value``, and ``details``. ``details`` is usually empty
|
||||
except in a few cases where it contains an additional list of objects
|
||||
with ``value`` and ``label`` keys (e.g. splitting of names).
|
||||
===================================== ========================== =======================================================
|
||||
|
||||
|
||||
.. http:get:: /exhibitors/api/v1/vouchers/
|
||||
|
||||
Returns a list of all vouchers connected to the exhibitor.
|
||||
|
||||
Note that the ``attendee_fields`` array can contain any number of dynamic keys!
|
||||
Depending on the exhibitors permission and event configuration this might be empty, or contain lots of details.
|
||||
The app should dynamically show these values (read-only) with the labels sent by the server.
|
||||
|
||||
|
||||
**Example request**:
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
GET /exhibitors/api/v1/vouchers/ 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,
|
||||
"code": "43K6LKM37FBVR2YG",
|
||||
"max_usages": 1,
|
||||
"redeemed": 0,
|
||||
"valid_until": null,
|
||||
"subevent": null,
|
||||
"tag": "testvoucher",
|
||||
"comment": "",
|
||||
"items": [
|
||||
"All"
|
||||
],
|
||||
"price_mode": "set",
|
||||
"value": "12.00",
|
||||
"redemptions": [
|
||||
{
|
||||
"attendee_fields": [
|
||||
{
|
||||
"id": "attendee_name",
|
||||
"label": "Name",
|
||||
"value": "Jon Doe",
|
||||
"details": [
|
||||
{"label": "Given name", "value": "John"},
|
||||
{"label": "Family name", "value": "Doe"},
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "attendee_email",
|
||||
"label": "Email",
|
||||
"value": "test@example.com",
|
||||
"details": []
|
||||
}
|
||||
],
|
||||
"redemption_date": "2026-05-06",
|
||||
"subevent": null
|
||||
},
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
:statuscode 200: No error
|
||||
:statuscode 401: Invalid authentication code
|
||||
:statuscode 403: Not permitted to access bulk data
|
||||
|
||||
.. http:get:: /exhibitors/api/v1/vouchers/(id)/
|
||||
|
||||
Returns the details of a single, specific voucher connected to the exhibitor.
|
||||
|
||||
Note that the ``attendee_fields`` array can contain any number of dynamic keys!
|
||||
Depending on the exhibitors permission and event configuration this might be empty, or contain lots of details.
|
||||
The app should dynamically show these values (read-only) with the labels sent by the server.
|
||||
|
||||
|
||||
**Example request**:
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
GET /exhibitors/api/v1/vouchers/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,
|
||||
"code": "43K6LKM37FBVR2YG",
|
||||
"max_usages": 1,
|
||||
"redeemed": 0,
|
||||
"valid_until": null,
|
||||
"subevent": null,
|
||||
"tag": "testvoucher",
|
||||
"comment": "",
|
||||
"items": [
|
||||
"All"
|
||||
],
|
||||
"price_mode": "set",
|
||||
"value": "12.00",
|
||||
"redemptions": [
|
||||
{
|
||||
"attendee_fields": [
|
||||
{
|
||||
"id": "attendee_name",
|
||||
"label": "Name",
|
||||
"value": "Jon Doe",
|
||||
"details": [
|
||||
{"label": "Given name", "value": "John"},
|
||||
{"label": "Family name", "value": "Doe"},
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "attendee_email",
|
||||
"label": "Email",
|
||||
"value": "test@example.com",
|
||||
"details": []
|
||||
}
|
||||
],
|
||||
"redemption_date": "2026-05-06",
|
||||
"subevent": null
|
||||
},
|
||||
]
|
||||
}
|
||||
|
||||
:param id: The ``id`` field of the voucher to fetch
|
||||
:statuscode 200: No error
|
||||
:statuscode 401: Invalid authentication code
|
||||
:statuscode 403: Not permitted to access bulk data
|
||||
:statuscode 404: Voucher not found in system
|
||||
Reference in New Issue
Block a user