Apple Passbook Service
======================

The Apple Passbook Service provides an endpoint to allow for the
distribution of passes.

.. contents:: Topics

Endpoints
---------

Retrieve URL to Passbook Pass
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. http:get:: applepassbook/passbookUrl.json

   Returns a URL at which the user's Pass may be downloaded.

   The following authentication methods are allowed for this endpoint:

   * :ref:`b2b_auth`
   * :ref:`oauth_auth`

   :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in.
   :query String printedCardNumber: *(optional)*  Printed card number for which to acquire a pass
   :query Integer accountId: *(optional)*  The account ID to which the printed card number belongs 

   At least one of the optional parameters must be given.

.. http:response:: success

   :jsonparam String result: *(required)*  ``success``
   :jsonparam String url: *(required)*  The passbook URL at which the user's pass may be downloaded

.. http:response:: failure

   :jsonparam String result: *(required)*  ``failure``
   :jsonparam String errorCode: *(required)*  The error code of the failure.
   :jsonparam String errorMessage: *(required)*  The (human readable) error message of the failure.

Error Codes
-----------

The caller of the endpoint can use the returned message to display to
the end user or, if different wording is desired, can provide their own
mapping of code to message.

+--------------------------------+-------------------------------------------+
| Code                           | Message                                   |
+================================+===========================================+
| ``applepassbook.system_error`` | Unable to provide passbook download url   |
+--------------------------------+-------------------------------------------+