Gift cards
Public booking API · https://api.conciar.com/public/v1
Selling the restaurant's gift cards online. Separate limits: 60 reads and 6 purchases per minute per restaurant and IP. Here the restaurant is matched on its exact guid or current handle, and an unknown restaurant or token is a plain 404 without a code.
INFO
API 參考文件以英文撰寫。
Gift card settings
Whether gift cards are on sale (reason when not: NO_RESTAURANT, DISABLED or NO_ONLINE_PAYMENTS), the preset amounts, the custom amount range and how long cards stay valid.
速率限制: 60/min per restaurant and IP
路徑參數
organization_guidstring必填The restaurant's guid or its current handle, matched exactly (no @, no former handles).
查詢參數
langstringen, nl, de, fr or es. Falls back to Accept-Language, then the restaurant's language, then en.
狀態碼
404Unknown restaurant (plain {message}).
注意事項
- A restaurant that does not sell gift cards online still answers 200, with available: false, the reason and presets: [].
curl "https://api.conciar.com/public/v1/restaurants/bistro-example/gift-cards" \
-H "Accept: application/json"{
"status": true,
"available": true,
"reason": null,
"locale": "en",
"locales": [
"en",
"nl",
"de",
"fr",
"es"
],
"restaurant": {
"name": "Bistro Example",
"guid": "00000000000000000",
"handle": "bistro-example",
"logo": null,
"accent": "#1f6f5c",
"email": "hello@example.com",
"website": null
},
"page_url": "https://r.conciar.com/bistro-example/gift-card",
"currency": "EUR",
"presets": [
{
"amount": "25.00",
"minor": 2500,
"currency": "EUR"
},
{
"amount": "50.00",
"minor": 5000,
"currency": "EUR"
}
],
"allow_custom_amount": true,
"min_amount": {
"amount": "10.00",
"minor": 1000,
"currency": "EUR"
},
"max_amount": {
"amount": "500.00",
"minor": 50000,
"currency": "EUR"
},
"validity_months": 24,
"validity_text": "…"
}Buy a gift card
Returns the payment page. After paying, the buyer lands on status_url in the Conciar guest app; the card is emailed to the buyer or the recipient.
速率限制: 6/min per restaurant and IP
路徑參數
organization_guidstring必填The restaurant's guid or its current handle, matched exactly (no @, no former handles).
請求內容
request_idstring必填Your idempotency id, 8–64 letters, digits or dashes.
amountnumber必填1–100000; a preset, or within the custom range when allowed.
purchaser_namestring必填Max 160.
purchaser_emailstring必填Max 190.
deliver_tostring必填recipient or buyer.
recipient_namestringMax 160.
recipient_emailstringAn email address, max 190. Required when deliver_to is recipient.
messagestringMax 500.
marketing_opt_inbooleanConsent to marketing.
langstringen, nl, de, fr or es.
狀態碼
404UNAVAILABLE — unknown restaurant, or it does not sell gift cards online.409UNAVAILABLE — online payments are not available.422INVALID (with errors) or INVALID_AMOUNT.502PAYMENT_FAILED.503BUSY.
curl -X POST "https://api.conciar.com/public/v1/restaurants/bistro-example/gift-cards/purchase" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"request_id": "3a9e5f20-0000-4000-8000-000000000000",
"amount": 50,
"purchaser_name": "Alex Example",
"purchaser_email": "alex@example.com",
"deliver_to": "buyer"
}'{
"status": true,
"replayed": false,
"payment_url": "https://payment-provider.example/checkout/…",
"token": "ExampleGiftCardToken0000000000000000000000000000",
"status_url": "https://r.conciar.com/bistro-example/gift-card/order/ExampleGiftCardToken0000000000000000000000000000"
}Purchase status
paid, pending or failed (a payment still pending after two hours counts as failed). card_url when paid, payment_url while pending.
速率限制: 60/min per restaurant and IP
路徑參數
organization_guidstring必填The restaurant's guid or its current handle, matched exactly (no @, no former handles).
tokenstring必填The 48-character token from the purchase (32–64 accepted).
狀態碼
404Unknown restaurant or token (plain {message}).
curl "https://api.conciar.com/public/v1/restaurants/bistro-example/gift-cards/purchase/ExampleGiftCardToken0000000000000000000000000000" \
-H "Accept: application/json"{
"status": true,
"state": "paid",
"locale": "en",
"restaurant": {
"…": "…"
},
"amount": {
"amount": "50.00",
"minor": 5000,
"currency": "EUR"
},
"to_recipient": false,
"sent_to": "alex@example.com",
"card_url": "https://r.conciar.com/bistro-example/gift-card/card/ExampleGiftCardToken0000000000000000000000000000?sig=…",
"payment_url": null,
"page_url": "https://r.conciar.com/bistro-example/gift-card"
}Get the gift card
The paid card itself, for the printable card page: its code, amount, balance and expiry. Needs the signature from card_url. The answer contains the card's redeemable code.
速率限制: 60/min per restaurant and IP
路徑參數
organization_guidstring必填The restaurant's guid or its current handle, matched exactly (no @, no former handles).
tokenstring必填The 48-character token from the purchase or card_url (32–64 accepted).
查詢參數
sigstring必填The signature from card_url. It does not expire.
langstringen, nl, de, fr or es: show the card in that language. Otherwise the card's own language.
狀態碼
403INVALID_LINK — missing or wrong sig, or the card is not paid yet.404Unknown restaurant or token (plain {message}).
注意事項
- gift_card.status is active, redeemed, expired or void.
curl "https://api.conciar.com/public/v1/restaurants/bistro-example/gift-cards/card/ExampleGiftCardToken0000000000000000000000000000?sig=signature_from_card_url" \
-H "Accept: application/json"{
"status": true,
"locale": "en",
"restaurant": {
"name": "Bistro Example",
"guid": "00000000000000000",
"handle": "bistro-example",
"logo": null,
"accent": "#1f6f5c",
"email": "hello@example.com",
"website": null
},
"gift_card": {
"code": "…",
"status": "active",
"amount": {
"amount": "50.00",
"minor": 5000,
"currency": "EUR"
},
"balance": {
"amount": "50.00",
"minor": 5000,
"currency": "EUR"
},
"amount_text": "€50.00",
"balance_text": "€50.00",
"expires_at": "2028-10-28",
"expires_text": "28 October 2028",
"recipient_name": null,
"purchaser_name": "Alex Example",
"message": null
},
"t": {
"…": "…"
}
}