MaceLoyalty — универсальное решение для работы с картами Apple Wallet и Google Pay. API MaceLoyalty построено на REST-принципах, работает с реальными объектами и обладает предсказуемым поведением. С помощью этого API вы можете отправлять запросы на выпуска карт, создавать пользователей, совершать операции по картам и многое другое. API в качестве основного протокола использует HTTP, а значит, подходит для разработки на любом языке программирования, который умеет работать с HTTP-библиотеками (cURL и другими).

API поддерживает POST и GET-запросы. POST-запросы используют JSON-аргументы, GET-запросы работают со строками запросов. API всегда возвращает ответ в формате JSON, независимо от типа запроса.

Для аутентификации запросов необходимо использовать HTTP Basic Auth. В заголовках запросов в качестве имени пользователя необходимо передать идентификатор вашей компании в MaceLoyalty, в качестве пароля — ваш секретный ключ (его нужно сгенерировать через менеджера). Секретный ключ отвечает за безопасность ваших данных. Храните его в защищенном месте и не публикуйте на сторонних ресурсах (например, вместе с примерами кода).

В контексте API идемпотентность означает, что многократные запросы обрабатываются так же, как однократные. Это значит, что получив повторный запрос с теми же параметрами, MaceLoyalty выдаст в ответе результат исходного запроса. Такое поведение помогает избежать нежелательного повторения операций. Например, если при проведении начисления возникли проблемы с сетью, и соединение прервалось, вы сможете безопасно повторить нужный запрос неограниченное количество раз. GET-запросы являются по умолчанию идемпотентными, так как не имеют нежелательных последствий. Для обеспечения идемпотентности POST-запросов используется заголовок Idempotence-Key (или ключ идемпотентности).

Если вы повторяете запрос с теми же данными и тем же ключом, API обрабатывает его как повторный. Если данные в запросе те же, а ключ идемпотентности отличается, запрос выполняется как новый. В заголовке Idempotence-Key можно передавать любое значение, уникальное для этой операции на вашей стороне. Мы рекомендуем использовать V4 UUID. MaceLoyalty обеспечивает идемпотентность в течение 24 часов после первого запроса, потом повторный запрос будет обработан как новый.

Некоторые запросы могут возвращать структуру, содержащую коллекцию объектов, а также nextCursor. С помощь него можно получить ссылку на следующую порцию данных, передав его в GET параметрах запроса. Также, можно передавать параметр limit для управления количеством объектов в ответе.