Brand Partner API¶

Väike ja ennustatav REST API mintboti tellimuste loomiseks, nende oleku pärimiseks ja elutsükli sündmuste vastuvõtmiseks. JSON sisse, JSON välja. Bearer-tokeniga autentimine. Idempotentsed kirjutused. Allkirjastatud webhookid.

API juurdepääsu töölaud Hüppa webhookide juurde

Kiirülevaade¶


Base URL	`https://mint.mintbot.ai/api/v1`
Auth	`Authorization: Bearer ***`
Idempotency	`Idempotency-Key: <uuid>` igal `POST` päringul
Content type	`application/json`
Rate limit	120 päringut / 60 s partneri kohta
Webhookid	Allkirjastatud HMAC-SHA256-ga, kuni 7 korduskatset

Autentimine¶

Iga päring saadab partneri API võtme Authorization päises. Võtme saab luua või roteerida töölaualt.

Authorization: Bearer mo_liv...xxxx
Content-Type: application/json

Roteerimisel armuaega ei ole

Võtme roteerimine tühistab eelmise võtme atomaarselt. Planeeri uue väärtuse vahetus oma konfiguratsioonis enne Rotate vajutamist.

Idempotentsus¶

Iga POST vajab Idempotency-Key päist. Sobib suvaline UUID iga eraldi päringu kohta.

Hoiame vastust puhvris 24 tundi. Sama võtmega korduskatse esitab algse vastuse uuesti, päisega Idempotent-Replay: true.
Sama võtme kasutamine teistsuguse päringu kerega tagastab 409 idempotency_key_mismatch.

Tellimused¶

Tellimuse loomine¶

POST /orders

Loob tellimuse ja tagastab Stripe Checkouti URL-i. Kui makse kinnitatakse, paigaldab mintbot agendi ja partneri tulusündmus salvestatakse automaatselt.

Päring

{
  "tier": "s1",
  "duration_months": 1,
  "credit_usd": 10,
  "language": "en",
  "external_id": "your-side-id",
  "success_url": "https://your.app/thanks?id={ORDER_ID}",
  "cancel_url":  "https://your.app/cart",
  "webhook_url": "https://your.app/mintbot-webhook"
}

tier: Üks väärtustest trial, s1, s2, s4.
duration_months: Kalendrikuud serveri elueaks. Üks väärtustest 1, 3 või 12.
credit_usd: Valikuline. Tellimusega kaasa pandud ette makstud vestluskrediit.
language: Valikuline. Mõjutab Stripe Checkouti keelevalikut ja tervituskirja keelt.
external_id: Valikuline. Kajastub igas webhookis ja tellimuse vastuses — kasuta seda mintboti tellimuste sidumiseks oma süsteemi ridadega.
success_url · cancel_url: Stripe Checkouti tagasisuuna URL-id. {ORDER_ID} asendatakse serveri poolel.
webhook_url: Valikuline. Tellimusepõhine ülekirjutus partneri taseme webhooki URL-ile.

Vastus — 201 Created

{
  "id": 42,
  "tier": "s1",
  "duration_months": 1,
  "credit_usd": 10,
  "amount_cents": 1200,
  "currency": "usd",
  "status": "awaiting_payment",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_…",
  "panel_url": null,
  "expires_at": null,
  "language": "en",
  "external_id": "your-side-id",
  "created_at": "2026-05-16 09:58:00",
  "paid_at": null
}

Näide

curlPython

curl -X POST https://mint.mintbot.ai/api/v1/orders \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "tier": "s1",
    "duration_months": 1,
    "credit_usd": 10,
    "success_url": "https://your.app/thanks?id={ORDER_ID}",
    "cancel_url":  "https://your.app/cart"
  }'

import os, uuid, requests

r = requests.post(
    "https://mint.mintbot.ai/api/v1/orders",
    headers={
        "Authorization": f"Bearer {os.environ['MINTBOT_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "tier": "s1",
        "duration_months": 1,
        "credit_usd": 10,
        "success_url": "https://your.app/thanks?id={ORDER_ID}",
        "cancel_url":  "https://your.app/cart",
    },
    timeout=10,
)
r.raise_for_status()
order = r.json()
redirect_to = order["checkout_url"]

Tellimuse pärimine¶

GET /orders/{id}

Toob ühe tellimuse mintboti ID järgi. Vastuse kuju on sama mis POST /orders puhul.

curl https://mint.mintbot.ai/api/v1/orders/42 \
  -H "Authorization: Bearer ***"

Tellimuste nimekiri¶

GET /orders

Kursoripõhise lehitsemisega nimekiri, uusimad ees.

Päringu parameetrid

status: Valikuline. Filtreeri väärtuste awaiting_payment, completed, deployed, deploy_failed või expired järgi.
cursor: Valikuline. Jätkamiseks anna eelmise lehe next_cursor.

Vastus

{
  "items": [ /* OrderResponse … */ ],
  "next_cursor": "37"
}

next_cursor on null, kui rohkem lehekülgi pole.

Tellimuse pikendamine¶

POST /orders/{id}/renew

Pikendab olemasolevat agenti veel duration_months võrra. Ainult taristu — uut vestluskrediiti kaasa ei panda. Tagastab uue tellimuse ID ja värske Stripe Checkouti URL-i.

Päring

{
  "duration_months": 1,
  "external_id": "your-side-id",
  "success_url": "https://your.app/thanks?id={ORDER_ID}",
  "cancel_url":  "https://your.app/account"
}

Tulu¶

Tulu pärimine¶

GET /revenue

Kogusummad ja kuni 200 viimast pearaamatu sündmust.

Päringu parameetrid

include_paid: Valikuline, vaikimisi true. Sea false, et näha ainult veel välja maksmata sündmusi.

Vastus

{
  "currency": "usd",
  "gross_cents": 12000,
  "partner_cut_cents": 2000,
  "mintbot_cut_cents": 10000,
  "unpaid_cents": 800,
  "events": [
    {
      "id": 7,
      "order_id": 42,
      "kind": "order_paid",
      "gross_cents": 1200,
      "partner_cut_cents": 200,
      "mintbot_cut_cents": 1000,
      "currency": "usd",
      "created_at": "2026-05-16 09:58:00",
      "payout_id": null,
      "payout_at": null
    }
  ]
}

Partneri profiil¶

Profiili pärimine¶

GET /partner

Kajastab sinu partneriprofiili ja välja maksmata saldo — mugav viis kuvada oma tulu omaenda haldusliideses ilma seda ise salvestamata.

Vastus

{
  "id": 12,
  "email": "you@kliendifirma.com",
  "pricing_currency": "usd",
  "balance_unpaid_cents": 800,
  "webhook_url": "https://your.app/mintbot-webhook",
  "api_key_prefix": "mo_live_a12b"
}

Webhooks¶

Kui tellimusega midagi juhtub, saadame sinu seadistatud webhooki URL-ile allkirjastatud JSON-sündmuse POST päringuga.

Sündmuse tüübid¶

Sündmus	Millal käivitub
`order.created`	Stripe Checkouti sessioon loodi, makse ootab.
`order.paid`	Stripe kinnitas makse. Tulusündmus salvestati.
`order.cancelled`	Tellimus aegus või tühistati selgesõnaliselt.
`agent.provisioning_started`	Selle tellimuse paigaldusprotsess käivitus.
`agent.ready`	Paigaldus õnnestus. Päringukere sisaldab `panel_url` ja `expires_at`.
`agent.failed`	Paigaldusprotsess andis vea. Katkise sammu leiad `error` väljalt.
`agent.expired`	Agendi TTL sai täis. Partner saab pikendada `POST /orders/{id}/renew` kaudu.

Saatmine ja korduskatsed¶

Kuni 7 katset eksponentsiaalse vahega: 0s, 30s, 2m, 10m, 1h, 6h, 24h.
Pärast viimast katset märgitakse saatmine olekusse exhausted ja korduskatsed lõpevad.
Kinnitamiseks vasta 10 sekundi jooksul 2xx staatusekoodiga.

Päringu päised¶

Content-Type: application/json
User-Agent: mintbot-webhook/1.0
X-Mintbot-Signature: t=<unix_ts>,v1=<hex_hmac_sha256>
X-Mintbot-Event-Id: evt_42_order.paid_1747371234567
X-Mintbot-Event-Type: order.paid

Näidispäringukere — `order.paid`¶

{
  "id": 42,
  "tier": "s1",
  "duration_months": 1,
  "credit_usd": 10,
  "amount_cents": 1200,
  "currency": "usd",
  "status": "completed",
  "external_id": "your-side-id",
  "paid_at": "2026-05-16 10:02:14"
}

Allkirja kontrollimine¶

Allkiri on HMAC-SHA256(secret, "{timestamp}.{raw_body}"). Kontrolli alati töötlemata päringukeret — parsitud JSON-i uuesti serialiseerimine rikub võrdluse.

PythonNode.js

import hmac, hashlib, time

def verify(secret: str, body: bytes, header: str, tolerance: int = 300) -> bool:
    try:
        ts_part, v1_part = header.split(",", 1)
        ts  = int(ts_part.split("=", 1)[1])
        sig = v1_part.split("=", 1)[1]
    except Exception:
        return False
    if abs(int(time.time()) - ts) > tolerance:
        return False
    expected = hmac.new(
        secret.encode(),
        f"{ts}.".encode() + body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, sig)

const crypto = require("crypto");

function verify(secret, rawBody, header, toleranceSec = 300) {
  const [tsPart, v1Part] = header.split(",");
  const ts  = Number(tsPart.split("=")[1]);
  const sig = v1Part.split("=")[1];
  if (Math.abs(Date.now() / 1000 - ts) > toleranceSec) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${ts}.`)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(sig, "hex"),
  );
}

Idempotentsed vastuvõtjad

Kasuta X-Mintbot-Event-Id väärtust dubleerimise vältimise võtmena — korduskatsed kasutavad sama ID-d, nii et INSERT … ON CONFLICT DO NOTHING selle veeru peal hoiab töötleja turvalisena.

Vead¶

Iga veavastus sisaldab stabiilset code väärtust, mille järgi saab koodis hargneda. message on inimesele mõeldud vihje ja võib versioonide vahel muutuda. request_id kajastab X-Request-Id vastuse päist — lisa see toepöördumisse.

{
  "error": {
    "code": "invalid_api_key",
    "message": "API key is unknown or revoked.",
    "request_id": "f0c2d6c4-…"
  }
}

Kood	Tähendus
`unauthenticated`	`Authorization` päis puudub või on vigane.
`invalid_api_key`	API võti on tundmatu või välja roteeritud.
`rate_limited`	Partneri- või IP-põhine päringukvoot on ületatud — vaata `Retry-After`.
`missing_idempotency_key`	`POST` päring ilma `Idempotency-Key` päiseta.
`idempotency_key_mismatch`	Sama võtit kasutati teistsuguse päringu kerega.
`validation_error`	Päringu keha ei läbinud skeemivalideerimist.
`not_found`	Ressurssi pole olemas või see ei kuulu sinu partnerile.
`payment_gateway_error`	Stripe lükkas Checkouti sessiooni loomise tagasi.

Päringukvoodid¶

120 päringut / 60 s libisev aken, partneri kohta. Lühiajalised tipud ja püsiv koormus kasutavad sama mahutit.
60 päringut / 60 s eraldi IP-põhine mahuti autentimata ja ebaõnnestunud autentimisega päringutele — see takistab bearer-tokeni murdekatseid partneri kvooti ammendamast.
Liigsed päringud tagastavad 429 rate_limited koos Retry-After päisega (mitu sekundit oodata enne uut katset).

Vajad abi?¶

Need juhendid on kirjutatud partneritele, kes API-t päriselt kasutavad. Kui midagi on puudu, segane või aegunud, ütle seda oma mintboti agendile — ta edastab tagasiside meile ja uuendame lehte.

Brand Partner API¶

Kiirülevaade¶

Autentimine¶

Idempotentsus¶

Tellimused¶

Tellimuse loomine¶

Tellimuse pärimine¶

Tellimuste nimekiri¶

Tellimuse pikendamine¶

Tulu¶

Tulu pärimine¶

Partneri profiil¶

Profiili pärimine¶

Webhooks¶

Sündmuse tüübid¶

Saatmine ja korduskatsed¶

Päringu päised¶

Näidispäringukere — order.paid¶

Allkirja kontrollimine¶

Vead¶

Päringukvoodid¶

Vajad abi?¶

Näidispäringukere — `order.paid`¶