Indik API — Integration Guide

Version v1 · Base URL: https://indik.app/api/v1 · Format: JSON · Message language: the store's (or the Accept-Language one)

A REST API that lets the merchant's ERP or POS run the referral program from inside its own system: validate, reserve and redeem coupons, sign up customers and read the metrics shown on the dashboard.

Formal reference (importable into Postman/Insomnia): openapi.yaml.

This guide is a translation of the Portuguese original. If the two ever disagree, the Portuguese version prevails.

Context

Without the API, validating a coupon means the cashier has to open /painel/validar on a second screen, next to the register. With it, the whole flow fits inside the ERP.

An important architectural point: the API and the dashboard share the same business-rule code (CouponRedemptionService, MetricsService, ReferralLinker). A coupon redeemed through the API has exactly the same effects as one redeemed on the dashboard — including confirming the referral and issuing the referrer's reward coupon.

1. Getting a key

On the dashboard, the store owner goes to Account → Integrations (/painel/integracoes), clicks New key, gives it a name (e.g. POS Downtown Store) and picks the permissions.

⚠️ The key is shown only once

The server stores only the SHA-256 hash of the secret. If you lose the key there is no way to recover it — you can only generate a new one and revoke the old one.

Create one key per integration, with the smallest set of permissions it needs. That way, if a system is decommissioned or its credential is exposed, you revoke just that key without taking the others down.

When creating it you can also set two optional restrictions:

On the same screen you can also follow the store's recent calls — route, result, key used and origin — to check that the integration is behaving as expected.

2. Authentication

Every request carries the token in the Authorization header:

Authorization: Bearer indk_live_8c17d1238ad36c3f.5ZqL1HQvNkonJ3UM9pIWxj4tXrZNyEn7zcjcsXMI

The token has two parts separated by a dot: the prefix (public, shown in the dashboard's key list so you can tell which key is which) and the secret.

Test the credential before anything else:

curl https://indik.app/api/v1/ping \
  -H "Authorization: Bearer $INDIK_TOKEN"

{
  "data": {
    "tenant": { "slug": "my-store", "name": "My Store", "status": "active" },
    "api_key": { "name": "POS Downtown Store", "prefix": "indk_live_8c17d1238ad36c3f", "scopes": ["coupons.read", "coupons.write"] },
    "server_time": "2026-08-13T19:36:44+00:00"
  }
}

Scopes

Each key carries a list of permissions. Grant only what the ERP actually uses.

3. Response envelope

Success — always inside data; paginated lists also include meta:

{ "data": { "...": "..." } }
{ "data": [ ... ], "meta": { "page": 1, "per_page": 25, "total": 87, "last_page": 4 } }

Error — always inside error:

{
  "error": {
    "code": "coupon_already_redeemed",
    "message": "This coupon has already been used.",
    "details": {}
  }
}

code is the stable contract — write your conditions against it. message is ready-to-display text for the cashier and may be reworded at any time without notice. It comes in the language of the store that owns the key (English, Spanish or Portuguese); to get another one, send the Accept-Language header (en, es or pt-BR).

Error codes

On validation_failed, details lists the fields and their messages:

{
  "error": {
    "code": "validation_failed",
    "message": "The data sent is invalid.",
    "details": { "accepted_terms": ["The customer's acceptance of the program terms must be recorded."] }
  }
}

4. Limits and idempotency

Rate limiting

The first two limits are per key, not per IP — several registers in the same store go out through the same address and must not eat into each other's quota. When you exceed them, the response is 429 with the Retry-After and X-RateLimit-* headers.

The third one protects against credential guessing and is counted per IP, because a rejected request has no key to count against. A successful authentication resets the counter, so getting the token wrong once and fixing it doesn't leave the register locked out.

⚠️ Treat 429 as a wait, not an error

Honor Retry-After before retrying. An immediate retry loop only pushes the window forward and keeps the integration stalled for longer.

Idempotency

Every POST accepts the optional (but strongly recommended) Idempotency-Key header:

Idempotency-Key: sale-2026-08-13-000123

• Resending the same key with the same body returns the original response, with the Idempotency-Replayed: true header. The coupon is not redeemed twice.
• Resending the same key with a different body returns 409 idempotency_conflict.
• The replay window is 24 hours.

Use an identifier of the sale itself in the ERP (receipt number, order ID). That turns your network layer's automatic retry into a safe operation.

⚠️ Concurrency

Every mutation runs in a transaction with a row lock. Two simultaneous calls to redeem the same coupon never result in two redemptions — the second one gets coupon_already_redeemed.

5. Recommended checkout flow

                    ┌──────────────┐
   customer         │  available   │◄──────────────┐
   shows            └──────┬───────┘               │
   the coupon              │                       │ POST /release
        │          POST /reserve                   │ (sale canceled)
        │                  ▼                       │
   GET /coupons/{code}  ┌──────────────┐───────────┘
   (validate, no        │  reserved    │
    side effects)       └──────┬───────┘
                               │ POST /redeem  { "sale_value": 150.00 }
                               ▼
                        ┌──────────────┐
                        │  redeemed    │  ← final state
                        └──────────────┘

Two steps (recommended for POS): reserve when the sale starts, redeem when it closes, release if the customer gives up. This keeps the same coupon from being used at two registers at the same time.

One step: call POST /redeem directly on an available coupon — the reservation happens implicitly. Good for simple or post-sale integrations.

⚠️ Always send sale_value

For percentage coupons, the sale amount determines the actual discount (prize_value = sale_value × value / 100). Without it, the coupon is redeemed but the average ticket, campaign cost and CAC metrics have nothing to be calculated from.

6. Endpoint reference

GET /ping

Checks connectivity and the credential. No scope required. See the example in section 2.

GET /coupons/{code} — look up a coupon

Scope: coupons.read. No side effects: this is the register's "validate". The code is case-insensitive.

curl https://indik.app/api/v1/coupons/ABC12345 \
  -H "Authorization: Bearer $INDIK_TOKEN"

{
  "data": {
    "code": "ABC12345",
    "status": "available",
    "type": "percent",
    "origin": "welcome",
    "value": 10,
    "value_label": "10% OFF",
    "product": null,
    "sale_value": null,
    "prize_value": null,
    "campaign_id": 1,
    "customer_id": 26,
    "referral_id": 23,
    "store_id": null,
    "seller_id": 6,
    "min_purchase": 50,
    "customer": { "id": 26, "name": "Anna", "phone": "+14155550102", "email": null },
    "expires_at": "2026-09-02T14:36:50+00:00",
    "reserved_at": null,
    "redeemed_at": null,
    "created_at": "2026-08-03T14:36:50+00:00"
  }
}

Errors: coupon_not_found (404), coupon_already_redeemed (409), coupon_expired (409).

POST /coupons/{code}/reserve — reserve

Scope: coupons.write. No body. Only works from available.

curl -X POST https://indik.app/api/v1/coupons/ABC12345/reserve \
  -H "Authorization: Bearer $INDIK_TOKEN" \
  -H "Idempotency-Key: sale-000123-reserve"

Returns the coupon with status: "reserved" and reserved_at filled in.

POST /coupons/{code}/redeem — redeem

Scope: coupons.write. Accepts a reserved or available coupon.

curl -X POST https://indik.app/api/v1/coupons/ABC12345/redeem \
  -H "Authorization: Bearer $INDIK_TOKEN" \
  -H "Idempotency-Key: sale-000123" \
  -H "Content-Type: application/json" \
  -d '{"sale_value": 150.00, "store_id": 3}'

{
  "data": {
    "code": "ABC12345",
    "status": "redeemed",
    "type": "percent",
    "value": 10,
    "sale_value": 150,
    "prize_value": 15,
    "redeemed_at": "2026-08-13T19:36:59+00:00"
  }
}

prize_value is the actual discount in the store's currency — for percent, calculated from sale_value; for the other types, equal to value.

⚠️ Important side effect

Redeeming a welcome coupon (origin: "welcome") confirms the referral that created it: the referral becomes used and the referrer automatically gets the reward coupon (and the milestone coupon, if they reached one). It's the same behavior as /painel/validar.

Errors: coupon_not_found (404), coupon_already_redeemed (409), coupon_expired (409), below_min_purchase (422, with details.min_purchase), validation_failed (422).

POST /coupons/{code}/release — release a reservation

Scope: coupons.write. No body. Returns a reserved coupon to available — use it when the sale is canceled, otherwise the coupon stays stuck.

Errors: coupon_not_reserved (409), coupon_already_redeemed (409).

GET /customers — list customers

Scope: customers.read.

curl "https://indik.app/api/v1/customers?phone=%2B14155550123" \
  -H "Authorization: Bearer $INDIK_TOKEN"

GET /customers/{id} — customer details

Scope: customers.read. Includes the customer's coupons.

{
  "data": {
    "id": 26,
    "name": "Anna",
    "phone": "+14155550102",
    "email": null,
    "cpf": null,
    "invite_token": "S17hEMaLzABq5vvRHePtE908d2nzXjTX",
    "invite_url": "https://indik.app/my-store/?invite=S17hEMaLzABq5vvRHePtE908d2nzXjTX",
    "referrer_id": 25,
    "store_id": null,
    "seller_id": null,
    "accepted_terms_at": "2026-07-27T20:26:36+00:00",
    "removed_at": null,
    "created_at": "2026-07-31T20:26:36+00:00",
    "coupons": [ ... ]
  }
}

invite_url is the ready-made link the customer shares to refer friends — print it on the receipt or send it by text or WhatsApp straight from the ERP.

POST /customers — sign up a customer

Scope: customers.write.

curl -X POST https://indik.app/api/v1/customers \
  -H "Authorization: Bearer $INDIK_TOKEN" \
  -H "Idempotency-Key: signup-phone-14155550123" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Joanna Smith",
        "phone": "+14155550123",
        "accepted_terms": true,
        "referrer_phone": "+14155550102"
      }'

Returns 201 when the customer is created and 200 when they were already in the program — meta.created tells the two apart, and meta.referral_id holds the referral that was opened (or null).

If there is a valid referrer and an active campaign, the response already includes the welcome coupon inside data.coupons:

{
  "data": {
    "id": 31,
    "name": "Joanna Smith",
    "coupons": [
      { "code": "RZSY2428", "status": "available", "type": "percent", "origin": "welcome", "value": 15, "value_label": "15% OFF" }
    ]
  },
  "meta": { "created": true, "referral_id": 23 }
}

⚠️ No OTP, so it's on you

Unlike the customer app, signing up through the API doesn't go through text-message verification — the ERP is a trusted channel. In exchange, accepted_terms is required: you are stating that you collected the customer's consent to the program terms. The person's global identifier is still the phone number (or the email), so the same customer signed up at two Indik stores is recognized as the same person.

GET /customers/{id}/coupons — a customer's coupons

Scope: coupons.read. Accepts status (available · reserved · redeemed · expired) and pagination.

GET /referrals — list referrals

Scope: referrals.read.

{
  "data": [
    {
      "id": 23,
      "status": "used",
      "campaign_id": 1,
      "referrer": { "id": 26, "name": "Anna", "phone": "+14155550102" },
      "referred": { "id": 31, "name": "Joanna Smith", "phone": "+14155550123" },
      "referred_contact": { "name": null, "phone": null, "email": null },
      "coupon": { "code": "UQFHBGPO", "value": 50, "origin": "referral", "status": "available" },
      "created_at": "2026-08-13T19:37:26+00:00"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 1, "last_page": 1 }
}

referred is the customer who already signed up; referred_contact holds the loose details of a direct invite (text/email) that hasn't turned into a sign-up yet.

GET /campaigns — list campaigns

Scope: campaigns.read. The active_only=1 parameter limits the result to the current campaign.

Use this endpoint to read min_purchase and block the sale in the ERP before you even call the redemption.

GET /stores — list stores

Scope: campaigns.read. Returns id, name, address, phone, is_active — the source of the store_id values you send when redeeming and signing up.

GET /metrics — metrics

Scope: metrics.read. The same numbers as /painel/dashboard, in raw form.

Each metric includes the value for the period, the value for the period immediately before and the change:

{
  "data": {
    "period": {
      "start": "2026-07-15T00:00:00+00:00",
      "end": "2026-08-13T23:59:59+00:00",
      "previous_start": "2026-06-15T00:00:00+00:00",
      "previous_end": "2026-07-14T23:59:59+00:00",
      "days": 30
    },
    "metrics": {
      "referrals": { "current": 2, "previous": 0, "delta": 100, "up": true },
      "conversion_rate": { "current": 50, "previous": 0, "delta": 100, "up": true }
    },
    "series": { "referrals_daily": [0, 1, 0, ...] },
    "active_campaign": { "id": 1, "name": "Demo Campaign", "progress": 12, "goal": 100 },
    "usage": [ { "key": "coupons_included", "label": "Coupons this month", "used": 12, "limit": 500, "state": "ok" } ]
  }
}

The series in series have one point per day of the period, in chronological order: referrals_daily, converted_daily, pending_daily, redeemed_daily.

7. Common integration errors

8. Go-live checklist

1. GET /ping returns 200 with the store's correct slug.
2. GET /coupons/{code} for a real coupon returns status: "available".
3. POST /reserve → POST /release puts the coupon back to available.
4. POST /redeem with sale_value stores prize_value correctly.
5. Repeating the redeem with the same Idempotency-Key returns Idempotency-Replayed: true and doesn't redeem again.
6. POST /customers with referrer_phone creates the customer and the welcome coupon.
7. Redeeming that welcome coupon confirms the referral on the dashboard and rewards the referrer.
8. GET /metrics?period=30d matches /painel/dashboard for the same period.
9. A key revoked on the dashboard starts returning 401 immediately.