forked from CGM_Public/pretix_original
8d6d885f6e
* API: Add various filtering options (#23158339) * fix query-param description * simplify payment provider qs-filter --------- Co-authored-by: Richard Schreiber <schreiber@rami.io>
345 lines
13 KiB
ReStructuredText
345 lines
13 KiB
ReStructuredText
.. _`rest-giftcards`:
|
|
|
|
Gift cards
|
|
==========
|
|
|
|
Resource description
|
|
--------------------
|
|
|
|
The gift card resource contains the following public fields:
|
|
|
|
.. rst-class:: rest-resource-table
|
|
|
|
===================================== ========================== =======================================================
|
|
Field Type Description
|
|
===================================== ========================== =======================================================
|
|
id integer Internal ID of the gift card
|
|
secret string Gift card code (can not be modified later)
|
|
value money (string) Current gift card value
|
|
currency string Currency of the value (can not be modified later)
|
|
testmode boolean Whether this is a test gift card
|
|
expires datetime Expiry date (or ``null``)
|
|
conditions string Special terms and conditions for this card (or ``null``)
|
|
owner_ticket integer Internal ID of an order position that is the "owner" of
|
|
this gift card and can view all transactions. When setting
|
|
this field, you can also give the ``secret`` of an order
|
|
position.
|
|
issuer string Organizer slug of the organizer who created this gift
|
|
card and is responsible for it.
|
|
===================================== ========================== =======================================================
|
|
|
|
The gift card transaction resource contains the following public fields:
|
|
|
|
.. rst-class:: rest-resource-table
|
|
|
|
===================================== ========================== =======================================================
|
|
Field Type Description
|
|
===================================== ========================== =======================================================
|
|
id integer Internal ID of the gift card transaction
|
|
datetime datetime Creation date of the transaction
|
|
value money (string) Transaction amount
|
|
event string Event slug, if the gift card was used in the web shop (or ``null``)
|
|
order string Order code, if the gift card was used in the web shop (or ``null``)
|
|
text string Custom text of the transaction (or ``null``)
|
|
info object Additional data about the transaction (or ``null``)
|
|
acceptor string Organizer slug of the organizer who created this transaction
|
|
(can be ``null`` for all transactions performed before
|
|
this field was added.)
|
|
===================================== ========================== =======================================================
|
|
|
|
.. versionchanged:: 4.20
|
|
|
|
The ``owner_ticket`` and ``issuer`` attributes of the gift card and the ``info`` and ``acceptor`` attributes of the
|
|
gift card transaction resource have been added.
|
|
|
|
Endpoints
|
|
---------
|
|
|
|
.. http:get:: /api/v1/organizers/(organizer)/giftcards/
|
|
|
|
Returns a list of all gift cards issued by a given organizer.
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /api/v1/organizers/bigevents/giftcards/ 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": "HLBYVELFRC77NCQY",
|
|
"currency": "EUR",
|
|
"testmode": false,
|
|
"expires": null,
|
|
"conditions": null,
|
|
"owner_ticket": null,
|
|
"issuer": "bigevents",
|
|
"value": "13.37"
|
|
}
|
|
]
|
|
}
|
|
|
|
:query integer page: The page number in case of a multi-page result set, default is 1
|
|
:query string secret: Only show gift cards with the given secret.
|
|
:query string value: Only show gift cards with the given value.
|
|
:query boolean expired: Filter for gift cards that are (not) expired.
|
|
:query boolean testmode: Filter for gift cards that are (not) in test mode.
|
|
:query boolean include_accepted: Also show gift cards issued by other organizers that are accepted by this organizer.
|
|
:query string expand: If you pass ``"owner_ticket"``, the respective field will be shown as a nested value instead of just an ID.
|
|
The nested objects are identical to the respective resources, except that the ``owner_ticket``
|
|
will have an attribute of the format ``"order": {"code": "ABCDE", "event": "eventslug"}`` to make
|
|
matching easier. The parameter can be given multiple times.
|
|
:param organizer: The ``slug`` field of the organizer to fetch
|
|
:statuscode 200: no error
|
|
:statuscode 401: Authentication failure
|
|
:statuscode 403: The requested organizer does not exist **or** you have no permission to view this resource.
|
|
|
|
.. http:get:: /api/v1/organizers/(organizer)/giftcards/(id)/
|
|
|
|
Returns information on one gift card, identified by its ID.
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /api/v1/organizers/bigevents/giftcards/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": "HLBYVELFRC77NCQY",
|
|
"currency": "EUR",
|
|
"testmode": false,
|
|
"expires": null,
|
|
"conditions": null,
|
|
"owner_ticket": null,
|
|
"issuer": "bigevents",
|
|
"value": "13.37"
|
|
}
|
|
|
|
:param organizer: The ``slug`` field of the organizer to fetch
|
|
:param id: The ``id`` field of the gift card to fetch
|
|
:query boolean include_accepted: Also show gift cards issued by other organizers that are accepted by this organizer.
|
|
:statuscode 200: no error
|
|
:statuscode 401: Authentication failure
|
|
:statuscode 403: The requested organizer does not exist **or** you have no permission to view this resource.
|
|
|
|
.. http:post:: /api/v1/organizers/(organizer)/giftcards/
|
|
|
|
Creates a new gift card
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
POST /api/v1/organizers/bigevents/giftcards/ HTTP/1.1
|
|
Host: pretix.eu
|
|
Accept: application/json, text/javascript
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"secret": "HLBYVELFRC77NCQY",
|
|
"currency": "EUR",
|
|
"value": "13.37"
|
|
}
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 201 Created
|
|
Vary: Accept
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"id": 1,
|
|
"secret": "HLBYVELFRC77NCQY",
|
|
"testmode": false,
|
|
"currency": "EUR",
|
|
"expires": null,
|
|
"conditions": null,
|
|
"owner_ticket": null,
|
|
"issuer": "bigevents",
|
|
"value": "13.37"
|
|
}
|
|
|
|
:param organizer: The ``slug`` field of the organizer to create a gift card for
|
|
:query string expand: If you pass ``"owner_ticket"``, the respective field will be shown as a nested value instead of just an ID.
|
|
The nested objects are identical to the respective resources, except that the ``owner_ticket``
|
|
will have an attribute of the format ``"order": {"code": "ABCDE", "event": "eventslug"}`` to make
|
|
matching easier. The parameter can be given multiple times.
|
|
:statuscode 201: no error
|
|
:statuscode 400: The gift card could not be created due to invalid submitted data.
|
|
:statuscode 401: Authentication failure
|
|
:statuscode 403: The requested organizer does not exist **or** you have no permission to create this resource.
|
|
|
|
.. http:patch:: /api/v1/organizers/(organizer)/giftcards/(id)/
|
|
|
|
Update a gift card. 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.
|
|
|
|
You can change all fields of the resource except the ``id``, ``secret``, ``testmode``, and ``currency`` fields. Be
|
|
careful when modifying the ``value`` field to avoid race conditions. We recommend to use the ``transact`` method
|
|
described below.
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
PATCH /api/v1/organizers/bigevents/giftcards/1/ HTTP/1.1
|
|
Host: pretix.eu
|
|
Accept: application/json, text/javascript
|
|
Content-Type: application/json
|
|
Content-Length: 94
|
|
|
|
{
|
|
"value": "14.00"
|
|
}
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
Vary: Accept
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"id": 1,
|
|
"secret": "HLBYVELFRC77NCQY",
|
|
"testmode": false,
|
|
"currency": "EUR",
|
|
"expires": null,
|
|
"conditions": null,
|
|
"owner_ticket": null,
|
|
"issuer": "bigevents",
|
|
"value": "14.00"
|
|
}
|
|
|
|
:param organizer: The ``slug`` field of the organizer to modify
|
|
:param id: The ``id`` field of the gift card to modify
|
|
:statuscode 200: no error
|
|
:statuscode 400: The gift card could not be modified due to invalid submitted data
|
|
:statuscode 401: Authentication failure
|
|
:statuscode 403: The requested organizer does not exist **or** you have no permission to change this resource.
|
|
|
|
.. http:post:: /api/v1/organizers/(organizer)/giftcards/(id)/transact/
|
|
|
|
Atomically change the value of a gift card. A positive amount will increase the value of the gift card,
|
|
a negative amount will decrease it.
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
POST /api/v1/organizers/bigevents/giftcards/1/transact/ HTTP/1.1
|
|
Host: pretix.eu
|
|
Accept: application/json, text/javascript
|
|
Content-Type: application/json
|
|
Content-Length: 79
|
|
|
|
{
|
|
"value": "2.00",
|
|
"text": "Optional value explaining the transaction"
|
|
}
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
Vary: Accept
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"id": 1,
|
|
"secret": "HLBYVELFRC77NCQY",
|
|
"currency": "EUR",
|
|
"testmode": false,
|
|
"expires": null,
|
|
"conditions": null,
|
|
"owner_ticket": null,
|
|
"issuer": "bigevents",
|
|
"value": "15.37"
|
|
}
|
|
|
|
:param organizer: The ``slug`` field of the organizer to modify
|
|
:param id: The ``id`` field of the gift card to modify
|
|
:query boolean include_accepted: Also show gift cards issued by other organizers that are accepted by this organizer.
|
|
:statuscode 200: no error
|
|
:statuscode 400: The gift card could not be modified due to invalid submitted data
|
|
:statuscode 401: Authentication failure
|
|
:statuscode 403: The requested organizer does not exist **or** you have no permission to change this resource.
|
|
:statuscode 409: There is not sufficient credit on the gift card.
|
|
|
|
.. http:get:: /api/v1/organizers/(organizer)/giftcards/(id)/transactions/
|
|
|
|
List all transactions of a gift card.
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /api/v1/organizers/bigevents/giftcards/1/transactions/ 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": 82,
|
|
"datetime": "2020-06-22T15:41:42.800534Z",
|
|
"value": "50.00",
|
|
"event": "democon",
|
|
"order": "FXQYW",
|
|
"text": null,
|
|
"acceptor": "bigevents",
|
|
"info": {
|
|
"created_by": "plugin1"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
|
|
:param organizer: The ``slug`` field of the organizer to view
|
|
:param id: The ``id`` field of the gift card to view
|
|
:statuscode 200: no error
|
|
:statuscode 401: Authentication failure
|
|
:statuscode 403: The requested organizer does not exist **or** you have no permission to view this resource.
|