Skip to main content
This guide walks you through the complete onboarding process — from receiving your credentials to going live in production.

​
What Zupy Provides

When your partnership is activated, the Zupy team provides:
ItemFormatDescription
API Key(s)zupy_pk_*One key per restaurant (company) you integrate with
Integration Sluge.g., repediuYour unique identifier for webhook URLs
Webhook URLhttps://api.zupy.com/api/v2/webhooks/integrations/{slug}/Endpoint for sending order data
Company ID(s)KSUID stringsIDs for each restaurant in the Zupy system
OTP Policystrict / relaxed / trustedWhich actions require customer OTP verification
Rate Limit TierFree / Standard / EnterpriseYour request quota (60 / 300 / 3,000 req/min)
DocumentationThis portalFull API reference and integration guides
Credentials are shared via a secure channel (encrypted email or password manager). Never share API keys via plain text chat (Slack, WhatsApp, etc.).

​
What You Configure

After receiving your credentials, set up your integration:
1

Store API Keys Securely

Store your API keys as environment variables or in a secrets manager. Never hardcode keys in source code or expose them in client-side code.
# .env (add to .gitignore!)
ZUPY_API_KEY=zupy_pk_your_api_key_here
ZUPY_BASE_URL=https://api.zupy.com/api/v2
ZUPY_INTEGRATION_SLUG=your-partner-slug
2

Configure Webhook Sending

Set up your system to send order data to Zupy’s webhook endpoint. See the Webhook Setup guide for payload format and examples.Your webhook URL:
POST https://api.zupy.com/api/v2/webhooks/integrations/{your-slug}/
3

Implement Customer Lookup

Use the Customer Search API to look up customers by phone, email, or name:
GET /api/v2/customers/?phone=5511987654321
See the Getting Started guide for code examples.
4

Implement Points Flow

If your integration needs to display points or award them directly (beyond webhooks):
  • View balance: GET /api/v2/customers/{id}/points/
  • Award points: POST /api/v2/customers/{id}/points/add/
  • View history: GET /api/v2/customers/{id}/points/history/
5

Implement OTP Flow (If Required)

If your OTP policy requires verification for redemption or coupon usage, implement the OTP Flow in your customer-facing UI.
Trusted partners (e.g., Repediu) can skip this step — OTP is not required for any action.
6

Implement Error Handling

Handle RFC 7807 error responses from the API:
StatusAction
401Check your API key
403Complete OTP flow or check access level
429Wait for Retry-After header, then retry
400/422Fix request body based on detail field

​
Testing Checklist

Before going live, verify each integration point works correctly:
1

Verify API Key

Send a simple customer search to confirm your key is valid:
curl -s -o /dev/null -w "%{http_code}" \
  -X GET "https://api.zupy.com/api/v2/customers/?phone=0000000000" \
  -H "X-API-Key: zupy_pk_your_api_key_here"
# Expected: 200
2

Send Test Webhook

Send a test order payload and verify a 200 response. The payload format is partner-specific — the example below uses Repediu’s format. Replace the fields with your own payload structure:
curl -X POST "https://api.zupy.com/api/v2/webhooks/integrations/{your-slug}/" \
  -H "X-API-Key: zupy_pk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '[{"cliente":"Test Customer","Celular":"+5511999888777","Valor":"50.00","id_venda":999999,"DataVenda":"2026-03-23T12:00:00.000Z","loja_cnpj":"00.000.000/0001-00","loja_nome":"Test Store","Email":null,"CpfCnpj":null}]'
The webhook accepts any JSON payload. Zupy processes it using your partner-specific adapter. See the Webhook Setup guide for your payload format.
Expected response:
{"data": {"status": "received", "id": "..."}, "meta": {}}
3

Verify Customer Created

After the webhook processes (wait a few seconds), search for the test customer:
curl -X GET "https://api.zupy.com/api/v2/customers/?phone=5511999888777" \
  -H "X-API-Key: zupy_pk_your_api_key_here"
Verify the customer exists and has the expected points balance.
4

Verify Points Awarded

Check the customer’s points balance matches the order value:
curl -X GET "https://api.zupy.com/api/v2/customers/{customer_id}/points/" \
  -H "X-API-Key: zupy_pk_your_api_key_here"
5

Test OTP Flow (If Applicable)

If your policy requires OTP for redemption or coupon usage:
  1. Request OTP: POST /api/v2/auth/request-otp/
  2. Verify OTP: POST /api/v2/auth/verify-otp/
  3. Redeem with session: Include X-OTP-Session header
See the OTP Flow guide for full examples.
6

Test Error Handling

Verify your integration handles errors gracefully:
  • Send a request without X-API-Key → expect 401
  • Send invalid JSON → expect 400
  • Send the same webhook twice → expect 200 with "status": "duplicate"

​
Go-Live Checklist

Before declaring your integration production-ready:

​
Infrastructure

  • API key stored securely (environment variable or secrets manager)
  • All API calls use HTTPS (HTTP is rejected)
  • All API calls go through your backend server (never client-side)
  • Retry logic implemented for 429 rate limit responses
  • Error logging configured for API failures

​
Integration

  • Webhook sending configured with correct URL and API key
  • Customer lookup working for phone, email, and/or name search
  • Points display integrated (if showing points to customers)
  • OTP flow implemented (if required by your policy)
  • Idempotency tested — duplicate webhooks return "status": "duplicate"

​
Monitoring

  • API error rates tracked (401, 403, 429, 5xx)
  • Webhook delivery success rate monitored
  • Support contact established with Zupy team

​
Communication

  • Production API key received and deployed
  • Rate limit tier confirmed with Zupy
  • OTP policy confirmed with Zupy
  • Support escalation path established (both sides)
Do not go live without completing the testing checklist. Untested integrations risk awarding incorrect points, failing silently on errors, or creating duplicate customer records.

​
Rate Limit Tiers

TierRequests/minAssigned To
Free60Default for new integrations
Standard300Active partners (Repediu, Saipos)
Enterprise3,000High-volume partners
Your tier is assigned during onboarding. Contact Zupy to request a tier upgrade.
Webhook batching reduces API calls. A single webhook with 100 orders counts as 1 request. Batch your orders to stay well within limits.

​
Support

ChannelContact
Technical supportwebmaster@zupy.com.br
DocumentationThis portal

​
Next Steps

Getting Started

Make your first API call in under 15 minutes

Webhook Setup

Configure webhooks for automatic order processing

OTP Flow

Implement customer identity verification

API Reference

Browse all endpoints with request/response schemas