API: Expose history of check-ins (Z#23206049)

2026-05-03 14:54:04 +00:00 · 2025-10-10 17:47:05 +02:00
parent 7d5df2b69e
commit 9a69b76880
6 changed files with 215 additions and 3 deletions
--- a/doc/api/resources/checkin.rst
+++ b/doc/api/resources/checkin.rst
@@ -421,3 +421,94 @@ Annulment of a check-in
   :statuscode 401: Authentication failure
   :statuscode 403: The requested organizer/event does not exist **or** you have no permission to view this resource.
   :statuscode 404: The requested nonce does not exist.
+
+
+Check-in history
+----------------
+
+.. rst-class:: rest-resource-table
+
+===================================== ========================== =======================================================
+Field                                 Type                       Description
+===================================== ========================== =======================================================
+id                                    integer                    Internal ID of the check-in
+successful                            boolean                    Whether the check-in was successful
+error_reason                          string                     Category of reason why the check-in was unsuccessful. Currently
+                                                                 ``"canceled"``, ``"invalid"``, ``"unpaid"`` ``"product"``,
+                                                                 ``"rules"``, ``"revoked"``, ``"incomplete"``, ``"already_redeemed"``,
+                                                                 ``"ambiguous"``, ``"error"``, ``"blocked"``, ``"unapproved"``,
+                                                                 ``"invalid_time"``, ``"annulled"`` or ``null``
+error_explanation                     string                     Additional, human-readable reason for the check-in to be unsuccessful (or ``null``)
+position                              integer                    Internal ID of the order position (or ``null`` for unknown scans)
+datetime                              datetime                   Logical time when the check-in happened
+created                               datetime                   Time when the check-in appeared on the server
+list                                  integer                    Internal ID of the check-in list
+auto_checked_in                       boolean                    Whether the check-in was performed by the system automatically
+gate                                  integer                    Internal ID of the gate (or ``null``)
+device                                integer                    Internal ID of the device (or ``null``)
+device_id                             integer                    Organizer-internal ID of the device (or ``null``)
+type                                  string                     Type of check-in, currently ``"entry"`` or ``"exit"``
+===================================== ========================== =======================================================
+
+.. http:get:: /api/v1/organizers/(organizer)/events/(event)/checkins/
+
+   Returns a list of all check-in events within a given event.
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      GET /api/v1/organizers/bigevents/events/sampleconf/checkins/ 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,
+            "successful": true,
+            "error_reason": null,
+            "error_explanation": null,
+            "position": 1234,
+            "datetime": "2017-12-25T12:45:23Z",
+            "created": "2017-12-25T12:45:23Z",
+            "list": 2,
+            "auto_checked_in": false,
+            "gate": null,
+            "device": null,
+            "device_id": null,
+            "type": "entry",
+          }
+        ]
+      }
+
+   :query integer page: The page number in case of a multi-page result set, default is 1
+   :query datetime created_since: Only return check-ins that have been created since the given date (inclusive).
+   :query datetime created_before: Only return check-ins that have been created before the given date (exclusive).
+   :query datetime datetime_since: Only return check-ins that have happened since the given date (inclusive).
+   :query datetime datetime_before: Only return check-ins that have happened before the given date (exclusive).
+   :query boolean successful: Only return check-ins that have (not) been successful.
+   :query boolean error_reason: Only return check-ins with a specific error reason.
+   :query integer list: Only return check-ins from a specific list.
+   :query string type: Only return check-ins of a specific type.
+   :query integer gate: Only return check-ins from a specific gate.
+   :query integer device: Only return check-ins from a specific device.
+   :query boolean auto_checked_in: Only return check-ins that are (not) auto-checked in.
+   :query string ordering: Manually set the ordering of results. Valid fields to be used are ``datetime``, ``created``,
+                           and ``id``.
+   :param organizer: The ``slug`` field of the organizer to fetch
+   :param event: The ``slug`` field of the event to fetch
+   :statuscode 200: no error
+   :statuscode 401: Authentication failure
+   :statuscode 403: The requested organizer/event does not exist **or** you have no permission to view this resource.