# Zupy Partner API

## Docs

- [Request OTP for customer verification](https://docs.zupy.com/api-reference/authentication/request-otp-for-customer-verification.md): Send OTP code to customer's phone or email. Used when integration requires identity verification. Authentication via X-API-Key header (partner API key).
- [Verify OTP and return customer session](https://docs.zupy.com/api-reference/authentication/verify-otp-and-return-customer-session.md): Verify OTP code and return session token with customer data. Creates customer if new. Session token valid for 30 minutes. Authentication via X-API-Key header (partner API key).
- [Get company profile](https://docs.zupy.com/api-reference/companies/get-company-profile.md): Retrieve the company profile associated with the authenticated user's current context.
- [List companies](https://docs.zupy.com/api-reference/companies/list-companies.md): List all companies accessible to the authenticated user.
- [Add points to customer](https://docs.zupy.com/api-reference/customers/add-points-to-customer.md): Add loyalty points to a customer's balance. Delegates to LoyaltyUser.add_points(). All async side effects (Z$ distribution, RFM, wallet push) preserved.
- [Get customer points balance](https://docs.zupy.com/api-reference/customers/get-customer-points-balance.md): Get customer's current points balance summary.
- [Get customer points history](https://docs.zupy.com/api-reference/customers/get-customer-points-history.md): Get paginated points transaction history for a customer.
- [Get customer profile](https://docs.zupy.com/api-reference/customers/get-customer-profile.md): Retrieve a single customer's profile including contact details, loyalty tier, and segment.
- [Get customer Z$ token balance](https://docs.zupy.com/api-reference/customers/get-customer-z$-token-balance.md): Query on-chain Z$ compressed token balance via Photon API. Returns 200 with error field on timeout/failure (graceful degradation).
- [Redeem a reward for a customer](https://docs.zupy.com/api-reference/customers/redeem-a-reward-for-a-customer.md): Redeem a reward using points (default) or Z$ topping (use_z_tokens=true). Delegates to LoyaltyUserService or MultiPaymentRewardService. All async side effects (wallet card, Z$ split, notifications) preserved.
- [Search and list customers](https://docs.zupy.com/api-reference/customers/search-and-list-customers.md): Paginated customer list with filters for name, email, phone, card code, tier, and RFM segment.
- [Validate (use) a coupon](https://docs.zupy.com/api-reference/customers/validate-use-a-coupon.md): Atomically mark a coupon as used, creating an activity record. Prevents double-usage via select_for_update. Auto-expires coupons past valid_until.
- [Get loyalty program details](https://docs.zupy.com/api-reference/loyalty-programs/get-loyalty-program-details.md): Retrieve a loyalty program's configuration including tiers, points rules, and enrollment URL.
- [List loyalty programs](https://docs.zupy.com/api-reference/loyalty-programs/list-loyalty-programs.md): List all loyalty programs for the authenticated company.
- [Get reward details](https://docs.zupy.com/api-reference/rewards/get-reward-details.md): Retrieve a single reward from the catalog including points cost, redemption limits, and availability.
- [List coupon inventory](https://docs.zupy.com/api-reference/rewards/list-coupon-inventory.md): List active coupons with remaining usage counts and expiry dates.
- [List reward catalog](https://docs.zupy.com/api-reference/rewards/list-reward-catalog.md): List available rewards for the company. Optionally filter by redeemability for a specific customer.
- [Generate coupon wallet pass](https://docs.zupy.com/api-reference/wallet/generate-coupon-wallet-pass.md): Generate an Apple/Google wallet pass for a redeemed coupon.
- [Generate loyalty wallet pass](https://docs.zupy.com/api-reference/wallet/generate-loyalty-wallet-pass.md): Generate an Apple/Google wallet pass for a customer's loyalty card.
- [Get wallet pass status](https://docs.zupy.com/api-reference/wallet/get-wallet-pass-status.md): Check the current status of a wallet pass (active, expired, voided).
- [List wallet passes for customer](https://docs.zupy.com/api-reference/wallet/list-wallet-passes-for-customer.md): List all wallet passes (loyalty + coupon) issued to a specific customer.
- [Send push notification via wallet pass](https://docs.zupy.com/api-reference/wallet/send-push-notification-via-wallet-pass.md): Send a push notification to the customer's device via an active wallet pass.
- [Get webhook configuration](https://docs.zupy.com/api-reference/webhook-management/get-webhook-configuration.md): Retrieve current webhook configuration for the authenticated partner. Returns webhook_url, selected events, masked webhook_secret, and available events.
- [Test webhook delivery](https://docs.zupy.com/api-reference/webhook-management/test-webhook-delivery.md): Send a test ping event to the configured webhook URL. Returns the delivery status and any error message.
- [Update webhook configuration](https://docs.zupy.com/api-reference/webhook-management/update-webhook-configuration.md): Update webhook configuration for the authenticated partner. If webhook_signature_secret is not set, it will be auto-generated. Pass webhook_url as null/empty string to disable webhooks.
- [Receive integration partner webhook](https://docs.zupy.com/api-reference/webhooks/receive-integration-partner-webhook.md): Receives JSON data from integration partners (e.g. Repediu, Saipos). Authenticates via per-company API key (X-API-Key header), persists to WebhookEvent, and dispatches async processing. Idempotent — duplicate payloads return 200 with status 'duplicate'.
- [Authentication](https://docs.zupy.com/authentication.md): Authenticate with the Zupy Partner API using API key authentication via X-API-Key header
- [Coupon Lifecycle](https://docs.zupy.com/guides/coupon-lifecycle.md): Browse rewards, redeem coupons, list customer coupons, and validate (use) coupons via the Zupy API
- [Getting Started](https://docs.zupy.com/guides/getting-started.md): Get your first API call working in under 15 minutes with the Zupy Partner API
- [OTP Verification Flow](https://docs.zupy.com/guides/otp-flow.md): Verify customer identity using one-time passwords before sensitive operations like reward redemption and coupon usage
- [Outbound Webhooks](https://docs.zupy.com/guides/outbound-webhooks.md): Receive real-time notifications when loyalty events occur — customer enrollments, points earned, reward redemptions, and coupon lifecycle events
- [Partner Onboarding](https://docs.zupy.com/guides/partner-onboarding.md): Step-by-step guide for integration partners — what you receive, what you configure, and how to go live
- [Postman Collection](https://docs.zupy.com/guides/postman.md): Import the ready-made Postman collection to test all Zupy Partner API endpoints instantly
- [Webhook Setup](https://docs.zupy.com/guides/webhook-setup.md): Send order data to Zupy for automatic customer enrollment and points processing via webhooks
- [Z$ Tokens](https://docs.zupy.com/guides/z-dollar-tokens.md): Understand how Z$ (Zupy Dollar) blockchain tokens work — earning, checking balance, and using them in reward redemptions
- [Zupy Partner API](https://docs.zupy.com/index.md): Build loyalty integrations with the Zupy Partner API

## OpenAPI Specs

- [openapi](https://docs.zupy.com/api-reference/openapi.json)

## Optional

- [Support](mailto:webmaster@zupy.com.br)
- [GitHub](https://github.com/zupy-fmartinelli)