Brand Partner API¶

Mazs, paredzams REST API mintbot pasūtījumu izveidei, to statusa pārbaudei un dzīvescikla notikumu saņemšanai. JSON iekšā, JSON ārā. Bearer-token autentifikācija. Idempotenti rakstīšanas pieprasījumi. Parakstīti webhooks.

API piekļuves panelis Pāriet uz Webhooks

Īsumā¶


Bāzes URL	`https://mint.mintbot.ai/api/v1`
Autentifikācija	`Authorization: Bearer ***
Idempotence	`Idempotency-Key: <uuid>` katram `POST`
Satura tips	`application/json`
Ātruma limits	120 req / 60 s katram partnerim
Webhooks	Parakstīti ar HMAC-SHA256, atkārtoti mēģināti līdz 7 reizēm

Autentifikācija¶

Katrs pieprasījums nosūta partnera API key Authorization galvenē. Ģenerē vai rotē key panelī.

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

Rotācijai nav pārejas loga

Key rotēšana atomāri atsauc iepriekšējo key. Ieplāno vērtības nomaiņu savā konfigurācijā pirms klikšķini Rotate.

Idempotence¶

Katram POST ir nepieciešama Idempotency-Key galvene. Der jebkurš UUID katram atsevišķam pieprasījumam.

Mēs saglabājam atbildi kešā 24 stundas. Atkārtots mēģinājums ar to pašu key atskaņo sākotnējo atbildi ar Idempotent-Replay: true.
Tā paša key atkārtota izmantošana ar citu body atgriež 409 idempotency_key_mismatch.

Pasūtījumi¶

Izveidot pasūtījumu¶

POST /orders

Izveido pasūtījumu un atgriež Stripe Checkout URL. Kad maksājums ir apstiprināts, mintbot sagatavo aģentu un partnera daļas ieņēmumu notikums tiek ierakstīts automātiski.

Pieprasījums

{
  "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: Viens no trial, s1, s2, s4.
duration_months: Servera darbības laiks kalendārajos mēnešos. Jābūt vienam no 1, 3 vai 12.
credit_usd: Neobligāts. Iepriekš apmaksāts chat credit, kas iekļauts pasūtījumā.
language: Neobligāts. Ietekmē Stripe Checkout lokāli un sveiciena e-pasta valodu.
external_id: Neobligāts. Tiek atdots atpakaļ katrā webhook un pasūtījuma atbildē — izmanto to, lai sasaistītu mintbot pasūtījumus ar ierakstiem savā sistēmā.
success_url · cancel_url: Stripe Checkout atgriešanās URL. {ORDER_ID} tiek aizvietots servera pusē.
webhook_url: Neobligāts. Katram pasūtījumam paredzēta partnera līmeņa webhook URL pārrakstīšana.

Atbilde — 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
}

Piemērs

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"]

Iegūt pasūtījumu¶

GET /orders/{id}

Ielasa vienu pasūtījumu pēc tā mintbot id. Atgriež tādu pašu struktūru kā POST /orders.

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

Pasūtījumu saraksts¶

GET /orders

Ar kursoru lapots saraksts, jaunākie vispirms.

Vaicājuma parametri

status: Neobligāts. Filtrē pēc awaiting_payment, completed, deployed, deploy_failed vai expired.
cursor: Neobligāts. Padod next_cursor no iepriekšējās lapas, lai turpinātu.

Atbilde

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

next_cursor ir null, kad vairs nav nākamo lapu.

Atjaunot pasūtījumu¶

POST /orders/{id}/renew

Pagarina esošu aģentu par vēl vienu duration_months. Tikai infrastruktūra — netiek iekļauts jauns chat credit. Atgriež jaunu pasūtījuma id un jaunu Stripe Checkout URL.

Pieprasījums

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

Ieņēmumi¶

Lasīt ieņēmumus¶

GET /revenue

Kopsummas un jaunākie 200 ledger notikumi.

Vaicājuma parametri

include_paid: Neobligāts, noklusējums true. Iestati uz false, lai redzētu tikai notikumus, kas vēl nav izmaksāti.

Atbilde

{
  "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
    }
  ]
}

Partnera profils¶

Iegūt profilu¶

GET /partner

Atgriež tavu partnera profilu kopā ar neizmaksāto atlikumu — ērti, lai rādītu ieņēmumus savā admin UI bez to glabāšanas pie sevis.

Atbilde

{
  "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¶

Kad ar pasūtījumu kaut kas notiek, mēs nosūtām (POST) parakstītu JSON notikumu uz tavu konfigurēto webhook URL.

Notikumu tipi¶

Notikums	Kad tas tiek izsaukts
`order.created`	Stripe Checkout sesija izveidota, gaida maksājumu.
`order.paid`	Stripe apstiprināja maksājumu. Ieņēmumu notikums ierakstīts.
`order.cancelled`	Pasūtījumam beidzās termiņš vai tas tika skaidri atcelts.
`agent.provisioning_started`	Deploy pipeline sākās šim pasūtījumam.
`agent.ready`	Deploy izdevās. Payload satur `panel_url` un `expires_at`.
`agent.failed`	Deploy pipeline beidzās ar kļūdu. Pārbaudi `error` lauku, lai redzētu soli, kas salūza.
`agent.expired`	Aģenta TTL beidzies. Partneris var atjaunot ar `POST /orders/{id}/renew`.

Piegāde un atkārtoti mēģinājumi¶

Līdz 7 mēģinājumiem eksponenciālā grafikā: 0s, 30s, 2m, 10m, 1h, 6h, 24h.
Pēc pēdējā mēģinājuma piegāde tiek atzīmēta kā exhausted un atkārtota mēģināšana apstājas.
Atbildi ar 2xx statusu 10 sekunžu laikā, lai apstiprinātu.

Pieprasījuma galvenes¶

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

Parauga payload — `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"
}

Paraksta pārbaude¶

Paraksts ir HMAC-SHA256(secret, "{timestamp}.{raw_body}"). Vienmēr pārbaudi raw pieprasījuma body — pārserializējot parsēto JSON, salīdzinājums vairs nesakritīs.

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"),
  );
}

Idempotenti saņēmēji

Izmanto X-Mintbot-Event-Id kā deduplikācijas key — atkārtotie mēģinājumi izmanto to pašu id, tāpēc row-level INSERT … ON CONFLICT DO NOTHING šajā kolonnā pasargā tavu handler.

Kļūdas¶

Katra kļūdas atbilde nes stabilu code, pēc kura vari programmatiski sazaroties. message lauks ir cilvēkam lasāms padoms un starp laidieniem var mainīties. request_id atspoguļo X-Request-Id atbildes galveni — iekļauj to atbalsta pieteikumos.

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

Kods	Nozīme
`unauthenticated`	Trūkst `Authorization` galvenes vai tā ir nepareizā formā.
`invalid_api_key`	API key nav zināms vai ir izrotēts.
`rate_limited`	Pārsniegts partnera vai IP rate limit — skati `Retry-After`.
`missing_idempotency_key`	`POST` pieprasījums bez `Idempotency-Key`.
`idempotency_key_mismatch`	Tas pats key izmantots atkārtoti ar citu pieprasījuma body.
`validation_error`	Pieprasījuma body neizturēja shēmas validāciju.
`not_found`	Resurss neeksistē vai nepieder tavam partnerim.
`payment_gateway_error`	Stripe noraidīja Checkout sesijas izveidi.

Ātruma ierobežojumi¶

120 pieprasījumi / 60 s slīdošais logs, katram partnerim. Burst un steady-state izmanto vienu bucket.
60 pieprasījumi / 60 s atsevišķs katra IP bucket neautentificētiem un neveiksmīgas autentifikācijas pieprasījumiem — tas neļauj bearer brute-force noēst partnera kvotu.
Pārmērīgi pieprasījumi atgriež 429 rate_limited ar Retry-After galveni (sekundes, cik ilgi atkāpties).

Vajadzīga palīdzība?¶

Šī dokumentācija ir rakstīta partneriem, kuri API patiešām lieto. Ja kaut kā trūkst, kaut kas ir neskaidrs vai novecojis, piemin to savam mintbot aģentam — viņš pārsūtīs atsauksmi, un mēs atjaunināsim lapu.

Brand Partner API¶

Īsumā¶

Autentifikācija¶

Idempotence¶

Pasūtījumi¶

Izveidot pasūtījumu¶

Iegūt pasūtījumu¶

Pasūtījumu saraksts¶

Atjaunot pasūtījumu¶

Ieņēmumi¶

Lasīt ieņēmumus¶

Partnera profils¶

Iegūt profilu¶

Webhooks¶

Notikumu tipi¶

Piegāde un atkārtoti mēģinājumi¶

Pieprasījuma galvenes¶

Parauga payload — order.paid¶

Paraksta pārbaude¶

Kļūdas¶

Ātruma ierobežojumi¶

Vajadzīga palīdzība?¶

Parauga payload — `order.paid`¶