mirror of
https://github.com/pretix/pretix.git
synced 2026-05-18 17:24:03 +00:00
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 200: No error
|
||||||
:statuscode 401: Invalid authentication code
|
:statuscode 401: Invalid authentication code
|
||||||
:statuscode 403: Not permitted to access bulk data
|
: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