Per sviluppatori REST MCP Agent Skill

API e integrazioni

Integra la ricerca dei master, gli slot liberi e la prenotazione online nei tuoi servizi — oppure collega un assistente IA via MCP.

Scarica la specifica OpenAPI Agent Skill

Autenticazione

Registrazione e accesso restituiscono una coppia di token JWT: token + refresh_token. L'access token dura 24 ore, il refresh token — 90 giorni. Gli endpoint protetti accettano l'header Authorization: Bearer <token>.

AccessoPOST /api/v1/auth/login

curl -X POST https://minibi.pro/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"identifier": "user@example.com", "password": "Secret123"}'

Risposta200 · JSON

{
  "token": "<JWT access-токен — живёт 24 часа>",
  "refresh_token": "<refresh-токен — живёт 90 дней>",
  "expires_in": 86400,
  "user": {
    "id": "507f1f77bcf86cd799439111",
    "first_name": "Анна",
    "role": "master"
  }
}

Aggiorna la coppiaPOST /api/v1/auth/refresh-token

curl -X POST https://minibi.pro/api/v1/auth/refresh-token \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "<refresh_token из ответа login>"}'

Accesso con qualsiasi identificatore: email, telefono E.164 o username.
Rotazione del refresh: il vecchio refresh token smette di funzionare dopo lo scambio.
Limite: 2 richieste/sec sugli endpoint di auth (429 al superamento).

Inizio rapido

Tre richieste fino alla prima prenotazione

Tutti gli esempi sono codice funzionante sull'API di produzione https://minibi.pro. Senza registrazione e senza token.

Trova un master

Ricerca per query e raggio geografico: query, coordinate e raggio in chilometri.

RichiestaGET /api/v1/masters/search

curl "https://minibi.pro/api/v1/masters/search?query=маникюр&lat=55.7558&lng=37.6173&radius_km=10&limit=5"

Risposta200 · JSON

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439111",
      "first_name": "Анна",
      "last_name": "Смирнова",
      "username": "anna.nails",
      "rating": 4.9,
      "reviews_count": 128,
      "address": "Москва, ул. Тверская, 10",
      "avatar_url": "https://firsts3.ru/beauty-photos/avatars/507f1f77bcf86cd799439111.jpg"
    }
  ]
}

Nella scheda: id, nome, username, rating, reviews_count, indirizzo, avatar. Poi — GET /api/v1/masters/{id} per i servizi.

Prendi gli slot liberi

Slot per una data su un insieme di servizi: la durata della prenotazione = la somma delle durate dei servizi.

RichiestaGET /api/v1/masters/{id}/slots

curl "https://minibi.pro/api/v1/masters/<master_id>/slots?service_ids=<service_id>&date=2026-11-01"

Risposta200 · JSON

[
  {
    "start": "10:00",
    "end": "11:00",
    "is_booked": false,
    "workspace_name": "Основное"
  },
  {
    "start": "11:00",
    "end": "12:00",
    "is_booked": true,
    "workspace_name": "Основное"
  }
]

Parametri: service_ids (CSV, obbligatorio), date YYYY-MM-DD, tz — offset in minuti, workspace_id.

Prenota il cliente

Flusso ospite senza account: prima un codice di conferma via email, poi la prenotazione.

Passo 1 · codicePOST /api/v1/auth/send-code

curl -X POST https://minibi.pro/api/v1/auth/send-code \
  -H "Content-Type: application/json" \
  -d '{"identifier": "client@example.com"}'

Passo 2 · prenotazionePOST /api/v1/guest/appointments

curl -X POST https://minibi.pro/api/v1/guest/appointments \
  -H "Content-Type: application/json" \
  -d '{
    "master_id": "507f1f77bcf86cd799439111",
    "service_ids": ["507f1f77bcf86cd799439222"],
    "start_time": "2026-11-01T10:00:00Z",
    "client_name": "Анна",
    "client_email": "client@example.com",
    "password": "Str0ngPass",
    "password_confirmation": "Str0ngPass",
    "code": "123456"
  }'

Risposta del passo 1 — { "sent": true }. Rate limit: 2 richieste/sec per entrambi gli endpoint. La richiesta di creazione genera l'account del cliente (email + password) e una prenotazione confermata.

API REST

Catalogo, prenotazioni e attività via REST

Catalogo dei master, servizi, slot, recensioni, offerte, eventi, prenotazione ospite, oltre ad attività e progetti (via JWT) — JSON su HTTPS con paginazione a cursore, ETag/304 sui GET ed errori leggibili dalle macchine {code, error}. La maggior parte degli endpoint GET è pubblica — il token serve solo per gli scenari personalizzati e per la sezione attività e progetti.

Catalogo dei master

GET /masters/search

Ricerca per testo, raggio geografico (lat/lng/radius_km), bounding box (sw/ne) e min_rating. Paginazione via page/limit o cursore after.

GET /masters/autocomplete

Suggerimenti durante la digitazione — nomi, username, postazioni di lavoro. Da 3 caratteri, fino a 20 risultati.

GET /masters/{id}

Scheda del master: profilo, servizi, postazioni. Un profilo nascosto dalle impostazioni di privacy restituisce 404.

GET /masters/{id}/services

Servizi attivi: durata in minuti, price_from/price_to, valuta del master.

GET /masters/{id}/schedule

Orario settimanale per giorno, inclusi gli orari delle postazioni.

GET /masters/{id}/available-days

Giorni con finestre libere in un intervallo from–to — per il calendario delle prenotazioni. Più next-slots — lo slot più vicino per ogni servizio.

Recensioni, offerte, eventi

Recensioni · /api/v1

GET /masters/{id}/reviews — recensioni con filtro per valutazione e paginazione limit/skip; …/reviews/distribution — numero di valutazioni 5…1 per l'istogramma delle stelline.

Offerte · /api/v2

GET /offers — feed delle offerte pubblicate con paginazione a cursore e filtri hashtags/category; GET /offers/{id} — scheda con le modalità di consegna; GET /masters/{id}/offers — vetrina del master. Le risposte sono in cache (ETag).

Eventi · /api/v2

GET /events/{id} — scheda dell'evento (prezzo, programma, posti, partecipanti); GET /masters/{id}/events — elenco (cursore). Con un Bearer token la scheda si arricchisce del tuo stato di partecipazione my_status.

Prenotazione online ospite

Lo scenario di integrazione principale: prenotare un cliente da un master senza account. Due richieste — un codice di conferma via email (passo 1 dell'inizio rapido), poi la creazione della prenotazione. L'account del cliente con password viene creato automaticamente; per un utente esistente la prenotazione viene collegata al suo account dopo la verifica del codice. Se l'email appartiene già a un altro account — 409 user_already_exists, una prenotazione ospite non finisce mai nell'account di qualcun altro.

Campo	Obbligatorio	Descrizione
master_id	sì	ID del master (hex24)
service_ids	sì	Array di ID dei servizi — la durata della prenotazione è pari alla somma dei servizi
start_time	sì	Ora di inizio, ISO 8601 UTC
client_name	sì	Nome del cliente
code	sì	Codice di conferma del passo 1 (valido 15 minuti)
password, password_confirmation	sì	Password dell'account in creazione: 8+ caratteri, una maiuscola + una minuscola + una cifra
client_email o client_phone	uno tra	Contatto dell'ospite: email (percorso principale) o telefono E.164 (legacy)
workspace_id	no	Postazione di lavoro, se il master ne ha più di una
note, source, utm_*	no	Nota per il master, marcatura della fonte, UTM
terms_acceptance, personal_data_consent	no*	Consensi legali; versioni — da GET /api/v1/legal/manifest

* Consigliamo di inviare sempre i consensi: le versioni dei documenti si prendono da GET /api/v1/legal/manifest.

Regole e limiti

Formato degli errori

Ogni errore è un JSON con un codice macchina e un messaggio:

ErroreHTTP ≠ 2xx

{ "code": "time_slot_not_available", "error": "Выбранное время уже занято" }

HTTP	code	Quando
400	code_invalid	Codice di conferma non valido o scaduto
400	legal_consent_required	Consensi legali obbligatori non inviati
401	invalid_credentials	Identificatore o password errati
404	—	Risorsa non trovata o nascosta dalle impostazioni di privacy
409	email_taken	Email già registrata
409	user_already_exists	L'email dell'ospite è occupata da un account esistente
409	time_slot_not_available	L'orario scelto è stato appena occupato
429	too_many_attempts	Rate limit superato (2 richieste/sec, burst 5)

Rate limits

Mutazioni di auth e ospiti — 2 richieste/sec, burst 5, poi 429. Invio dei codici — attesa di 60 sec e 3 codici ogni 5 minuti per identificatore.

CORS

Le integrazioni lato server funzionano senza restrizioni. Per quelle browser aggiungiamo il tuo origin su richiesta — scrivi a minibils2026@gmail.com.

Cache

Le risposte GET restituiscono ETag / Last-Modified e supportano le richieste condizionali — If-None-Match restituisce 304 senza corpo.

Paginazione

Gli elenchi usano la paginazione a cursore: cursor.after + has_more; limiti puntuali via parametro limit.

Tutti gli endpoint

Tutti i 52 endpoint della piattaforma: catalogo pubblico e prenotazione ospite + attività e progetti tramite token JWT. Schemi completi di richieste e risposte — in openapi.yaml.

Metodo	Percorso	Scopo
Master — /api/v1
GET	/api/v1/masters/search	Ricerca dei master: testo, raggio geografico o bbox, min_rating, paginazione
GET	/api/v1/masters/autocomplete	Suggerimenti di ricerca da 3 caratteri
GET	/api/v1/masters/{master_id}	Scheda del master: profilo, servizi, postazioni
GET	/api/v1/masters/{master_id}/services	Servizi attivi di un master
GET	/api/v1/masters/{master_id}/schedule	Orario di lavoro settimanale
GET	/api/v1/masters/{master_id}/slots	Slot liberi per una data su un insieme di servizi
GET	/api/v1/masters/{master_id}/next-slots	Slot libero più vicino per ogni servizio
GET	/api/v1/masters/{master_id}/available-days	Giorni con finestre libere in un intervallo di date
GET	/api/v1/masters/{master_id}/reviews	Recensioni del master (limit, skip, rating)
GET	/api/v1/masters/{master_id}/reviews/distribution	Distribuzione delle valutazioni 5…1
Landing e prenotazione web — /api/public
GET	/api/public/masters	Elenco paginato dei master pubblici
GET	/api/public/masters/popular	Master popolari (fino a 8)
GET	/api/public/masters/{id}	Scheda pubblica del master (context=booking)
GET	/api/public/masters/{id}/workspaces	Postazioni per la pagina di prenotazione
GET	/api/public/masters/{id}/posts	Post di riferimento del master (cursore)
GET	/api/public/masters/{id}/reviews	Ultime recensioni (fino a 10)
Offerte ed eventi — /api/v2
GET	/api/v2/offers	Feed delle offerte pubblicate (cursor, hashtags)
GET	/api/v2/offers/{id}	Scheda offerta con modalità di consegna
GET	/api/v2/masters/{master_id}/offers	Offerte del master
GET	/api/v2/events/{id}	Scheda evento (con token — my_status)
GET	/api/v2/masters/{master_id}/events	Eventi attivi del master
Prenotazione ospite
POST	/api/v1/guest/appointments	Prenotazione online ospite da un master (due passi)
POST	/api/v2/events/{id}/join-guest	Partecipazione ospite a un evento
Autenticazione
POST	/api/v1/auth/register	Registrazione (email + password + consensi)
POST	/api/v1/auth/login	Accesso con identificatore e password
POST	/api/v1/auth/refresh-token	Scambio del refresh token con una nuova coppia
POST	/api/v1/auth/send-code	Codice di conferma via email
Attività e progetti — /api/v2 (JWT; creare un progetto è una funzione del piano Pro)
GET/POST	/api/v2/projects	Progetti: elenco dei miei (proprietario/partecipante) / creare (Pro)
GET/PATCH/DELETE	/api/v2/projects/{id}	Progetto: scheda / aggiornare / eliminare
PUT	/api/v2/projects/{id}/statuses	Riscrivere l'insieme di colonne-stato del progetto
POST	/api/v2/projects/{id}/members	Aggiungere un partecipante al progetto
DELETE	/api/v2/projects/{id}/members/{user_id}	Rimuovere un partecipante al progetto
POST	/api/v2/projects/{id}/invites	Invitare via email / telefono / username
GET	/api/v2/projects/{id}/report	Report sulle attività (from/to, piano contro reale)
POST	/api/v2/project_invites/{invite_id}/accept	Accettare un invito al progetto
POST	/api/v2/project_invites/{invite_id}/decline	Rifiutare un invito al progetto
GET	/api/v2/my/project_invites	I miei inviti attivi
GET/POST	/api/v2/tasks	Attività: elenco (project_id, filtri) / creare
GET	/api/v2/my/tasks	Le mie attività aperte
GET/PATCH/DELETE	/api/v2/tasks/{id}	Attività: scheda / aggiornare / eliminare
GET	/api/v2/tasks/{id}/history	Cronologia dei cambi di stato di un'attività
POST	/api/v2/tasks/{id}/attachments	Allegare un file a un'attività
DELETE	/api/v2/tasks/{id}/attachments/{attachment_id}	Rimuovere un allegato di un'attività
GET/POST	/api/v2/tasks/{id}/links	Collegamenti di un'attività: elenco / collegare (relates/blocks)
DELETE	/api/v2/tasks/{id}/links/{linked_task_id}	Rimuovere un collegamento tra attività
GET/POST	/api/v2/tasks/{id}/comments	Commenti di un'attività: elenco / aggiungere
PUT/DELETE	/api/v2/tasks/task_comments/{id}	Commento: modificare / eliminare
GET	/api/v2/tasks/task_comments/{id}/replies	Risposte a un commento
POST	/api/v2/tasks/media	Caricare una foto per un allegato (multipart, fino a 50 MB)
Servizio
GET	/api/v1/subscriptions/plans	Piani di abbonamento
GET	/api/v1/legal/manifest	Versioni dei documenti legali
GET	/api/v1/app/version	Versioni minime e attuali delle app

MCP per gli assistenti IA

Tutta la piattaforma come strumento di un agente IA

Il server MCP della piattaforma: set di base di 35 strumenti — ricerca dei master, prenotazioni, attività, chat, offerte ed eventi, eventi personali e gestione della prenotazione online. Set completo (294 strumenti) — su richiesta. L'agente lavora con gli stessi diritti e limiti dell'app.

Token

Connessione in un minuto

1 Crea un token: apri la bacheca web minibi.pro/cabinet → Impostazioni → Token di integrazione → Crea. Il token viene mostrato una sola volta — copialo.
2 Aggiungi il server al client MCP (Cursor, ZCode, Claude e altri):

Config del client MCPmcp.json

{
  "mcpServers": {
    "minibi": {
      "url": "https://minibi.pro/mcp",
      "headers": { "Authorization": "Bearer <ваш токен>" }
    }
  }
}

3 Fatto: gli strumenti lavorano per conto tuo con gli stessi diritti dell'app.

Il token inizia con mbk_… — puoi tenerne fino a 5 attivi. Eliminare un token nella bacheca revoca l'accesso all'istante.

Esempio di sessione

Lavoro con il calendario delle prenotazioni subito dopo la connessione:

Sessione MCPtools/list → appointments_list

# 1. Сразу после подключения клиент получает список инструментов
tools/list
→ { "tools": [ … ] }   # базовый набор — 35 инструментов

# 2. Токен уже идентифицирует вас — auth_login не нужен:
#    любой инструмент сразу работает от вашего имени
appointments_list(date: "2026-11-01", tz: 180)
→ {
  "appointments": [
    {
      "start_time": "10:00",
      "end_time": "11:30",
      "client_name": "Мария Иванова",
      "service_name": "Маникюр с покрытием",
      "status": "confirmed"
    }
  ]
}

Stack dev: http://localhost:8085/mcp.

Artefatti pronti

Scarica e inizia a lavorare

OpenAPI 3.0 — openapi.yaml

La specifica dell'API in OpenAPI 3.0 — catalogo, prenotazione online, attività e progetti: parametri, schemi delle risposte, codici di errore. Si importa in Postman, Insomnia e GPT Actions senza modifiche.

Agent Skill — minibi-api

Skill pronta per gli agenti IA: ricerca dei master e prenotazione ospite.

Scarica l'archivio zip
Collegalo al tuo agente IA (in Claude: Settings → Capabilities → Skills)
Carica l'archivio

FAQ

Domande frequenti

Serve un token per la ricerca dei master?

No. Tutti gli endpoint GET di catalogo, recensioni, offerte ed eventi sono pubblici e funzionano senza autorizzazione. Il Bearer token serve solo a personalizzare i risultati: la ricerca considera gli interessi dell'utente e gli eventi ricevono il campo my_status.

Quali sono i limiti dell'API?

Autenticazione e mutazioni ospite (send-code, guest/appointments, join-guest) — 2 richieste/sec con burst 5, 429 al superamento. I GET pubblici non sono limitati in modo così aggressivo, ma consigliamo di mettere in cache le risposte (ETag / Cache-Control vengono già serviti).

Come ottengo un Bearer token per MCP?

Crealo tu stesso nella bacheca web (minibi.pro/cabinet): Impostazioni → Token di integrazione → Crea. Il token mbk_… viene mostrato una sola volta — copialo. Il limite è di 5 token attivi; eliminare un token revoca l'accesso.

Come funziona il versionamento?

La versione è nel percorso: /api/v1 e /api/v2. Le modifiche retrocompatibili (nuovi campi, nuovi endpoint) avvengono senza aumentare la versione; le modifiche breaking — solo in una nuova versione, annunciate in anticipo.

Dove scrivere se qualcosa non funziona?

minibils2026@gmail.com — esaminiamo la richiesta, ti aiutiamo con gli endpoint e aggiungiamo il tuo origin al CORS per le integrazioni browser.