REST API · OpenAPI 3.1

API Tier1.shop

Collega il tuo servizio o agente AI: registrazioni, tariffe, ordini, link e stato dei pagamenti tramite un'unica API. I dati dei clienti sono accessibili solo tramite la loro chiave revocabile.

Ottieni chiave API Avvio rapido OpenAPI JSON
URL Base API 
https://tier1.shop/wp-json/tier1-api/v1

Guida rapida

L'account esiste già

Crea una chiave

Apri «API e Connessioni» nella tua dashboard o richiedi un link per la creazione della chiave via email tramite POST /api-key-requests.

Nuovo Cliente

Conferma email

L'agente chiama POST /registration-intents. Segui il link nell'email per confermare il tuo indirizzo; solo allora l'account e la chiave verranno creati. Telegram può essere aggiunto in seguito.

Primo ordine — cinque passaggi

  1. Scegli un piano.GET /catalog/tariffs e GET /balances mostrerà i prezzi attuali e la disponibilità.
  2. Conferma i dettagli.Concorda la quantità, gli URL, i testi anchor e la valuta con l'agente prima di creare il checkout.
  3. Ottieni il link di pagamento.POST /checkout-intents restituirà un URL monouso; il pagamento viene elaborato solo sul sito web.
  4. Verifica pagamento.GET /checkout-intents/{id} mostrerà lo stato e il numero d'ordine WooCommerce.
  5. Apri i link.GET /orders/by-wc/{id} troverà gli ordini interni; placement_progress mostrerà lo stato di esecuzione.
Importante: il numero d'acquisto dell'email e l'ID ordine dell'account sono valori differenti. Per il numero email usa /orders/by-wc/{id}, per l'ID interno usa /orders/{id}.

Autorizzazione

Passa la chiave nell'intestazione HTTPS. Non inserirla nell'URL, in prompt pubblici o nei log. La chiave può essere revocata nell'account; il testo completo è mostrato solo durante la creazione.

Authorization: Bearer t1c_sk_YOUR_KEY
Permessi chiave (scope)8
profile:readStato del Profilo e della Connessione
balance:readSaldo Servizi e Portafoglio
orders:readVisualizza Ordini
links:readVisualizza Link
catalog:readCataloghi e Tariffe
orders:writeCompila e invia ordini in blocco
links:writeURL, Anchor, Testo circostante e Invio
checkout:createCrea Link di Pagamento Sicuri

La chiave non consente all'agente di detrarre fondi direttamente dal wallet. Per le richieste di mutazione, un valore casuale Idempotency-Key di 8–128 caratteri è richiesto. Se la risposta viene persa, ripeti la stessa richiesta con la stessa chiave; per una nuova azione, creane una nuova.

Metodi API

I metodi sono organizzati in 10 gruppi. Apri quello richiesto per i parametri e un esempio di risposta; il contratto macchina completo si trova in OpenAPI JSON.

23 metodi
Замены URL/анкораDiscoveryRegistratiAccountOrdiniLinkCatalogoBozzeInviaPagamento

Замены URL/анкора 3

GET/links/{id}/replacementУсловия платной замены размещённой ссылки: доступность, остаток замен, текущие данные и актуальные товары. Денежных списаний нет. При нехватке купите замены через checkout и дождитесь replacement_credits_fulfilled=true.
Accesso: BearerScope: links:read

Esempio di risposta

{
    "link_id": 456,
    "eligible": true,
    "credits_available": 1,
    "pending_replacement": false,
    "purchase_offers": []
}
POST/links/{id}/replacementПосле согласия клиента сохранить новые URL/анкор. Резервирует одну замену, но ещё не отправляет её в работу. expected_* берутся точно из свежих current_*; кошелёк не списывается.
Accesso: Bearer + Idempotency-KeyScope: links:write

Richiedi JSON

{
    "confirmed": true,
    "expected_url": "https://example.com/old",
    "expected_anchor": "старый анкор",
    "url": "https://example.com/new",
    "anchor": "новый анкор"
}

Esempio di risposta

{
    "saved": true,
    "link": {
        "id": 456
    },
    "wallet_was_charged": false
}
POST/links/{id}/replacement/submitОтправить только эту сохранённую замену. expected_* — уже новые данные. Проверяйте submission.submitted, submission.errors и статус; HTTP 200 сам по себе не означает принятия задачи. Это не замена донора.
Accesso: Bearer + Idempotency-KeyScope: links:write

Richiedi JSON

{
    "confirmed": true,
    "expected_url": "https://example.com/new",
    "expected_anchor": "новый анкор"
}

Esempio di risposta

{
    "submission": {
        "submitted": 1,
        "errors": []
    },
    "link": {
        "id": 456,
        "status": "revision"
    }
}

Discovery 2

GET/capabilitiesFunzionalità API e link di connessione attuali.
Accesso: NoScope: —

Esempio di risposta

{
    "name": "Tier1.shop API",
    "api_enabled": true,
    "public_registration": true
}
GET/openapi.jsonSpecifica completa OpenAPI 3.1.
Accesso: NoScope: —

Esempio di risposta

{
    "openapi": "3.1.0",
    "info": {
        "title": "Tier1.shop Client API"
    }
}

Registrati 3

POST/registration-intentsAvvia la registrazione per un nuovo cliente con conferma email obbligatoria.
Accesso: NoScope: —

Richiedi JSON

{
    "email": "client@example.com",
    "telegram_username": "@client",
    "locale": "ru",
    "issue_api_key": true
}

Esempio di risposta

{
    "accepted": true,
    "request_id": "…",
    "status_token": "…",
    "status": "pending_email",
    "expires_in": 86400
}
GET/registration-intents/{id}?status_token={token}Verifica lo stato di una registrazione specifica.
Accesso: Status tokenScope: —

Esempio di risposta

{
    "status": "pending_email|email_verified|expired",
    "email_verified": false,
    "telegram_status": "not_requested|pending_bot_message|verified"
}
POST/api-key-requestsRichiedi un link di creazione chiave monouso per un account esistente.
Accesso: NoScope: —

Richiedi JSON

{
    "email": "client@example.com",
    "name": "Мой агент"
}

Esempio di risposta

{
    "accepted": true,
    "next_action": "…"
}

Account 2

GET/profileProfilo, conferma email e tutti i canali Telegram.
Accesso: BearerScope: profile:read

Esempio di risposta

{
    "account": {
        "email": "client@example.com",
        "email_verified": true,
        "telegram_username": "@client",
        "telegram_usernames": [
            "@client",
            "@manager"
        ]
    }
}
GET/balances?geo=allportafogli RUB/$ e servizi RU/internazionali non utilizzati.
Accesso: BearerScope: balance:read

Esempio di risposta

{
    "wallets": {
        "rub": {
            "currency": "RUB",
            "amount_minor": 0
        },
        "usd": {
            "currency": "USD",
            "amount_minor": 0
        }
    },
    "service_balances": []
}

Ordini 3

GET/orders?geo=all&page=1&per_page=20Elenco paginato degli ordini dell'account. per_page è limitato a 50: continua tramite next_page.
Accesso: BearerScope: orders:read

Esempio di risposta

{
    "orders": [
        {
            "cabinet_order_id": 123,
            "wc_order_id": 456,
            "placement_progress": {
                "completed": 2,
                "total": 3,
                "fully_placed": false
            }
        }
    ],
    "page": 1,
    "per_page": 20,
    "has_more": false,
    "next_page": null
}
GET/orders/{id}Un singolo ordine e i link per cabinet_order_id, non per il numero WooCommerce dell'email.
Accesso: BearerScope: orders:read

Esempio di risposta

{
    "order": {
        "cabinet_order_id": 123,
        "wc_order_id": 456,
        "geo": "ru"
    },
    "links": []
}
GET/orders/by-wc/{id}Tutti gli ordini interni e i link tramite il numero WooCommerce del cliente.
Accesso: BearerScope: orders:read

Esempio di risposta

{
    "wc_order_id": 456,
    "count": 2,
    "orders": [
        {
            "order": {
                "cabinet_order_id": 123
            },
            "links": []
        }
    ]
}

Link 1

GET/links?geo=all&page=1&per_page=20Link con filtri per geo, stato e link_type; continua tramite next_page.
Accesso: BearerScope: links:read

Esempio di risposta

{
    "links": [],
    "page": 1,
    "per_page": 20,
    "total": 0,
    "has_more": false,
    "next_page": null
}

Catalogo 2

GET/catalog/tariffs?geo=ruProdotti, prezzi, valute e composizione esatta degli slot attuali.
Accesso: BearerScope: catalog:read

Esempio di risposta

{
    "geo": "ru",
    "currency": "RUB",
    "tariffs": [
        {
            "product_id": 3708,
            "name": "…",
            "price": {
                "amount_minor": 200000
            }
        }
    ]
}
GET/catalog/burzh-igamingSiti donatori iGaming anonimizzati, metriche, prezzo e slot disponibili.
Accesso: BearerScope: catalog:read

Esempio di risposta

{
    "donors": [],
    "count": 0,
    "price": {
        "currency": "USD",
        "amount_minor": 9400
    }
}

Bozze 3

PATCH/links/{id}Cambia URL, anchor text, testo circostante o programmazione senza inviare il link per l'elaborazione.
Accesso: Bearer + Idempotency-KeyScope: links:write

Richiedi JSON

{
    "url": "https://example.com/page",
    "anchor": "пример",
    "context_text": "Окружающий текст с анкором пример.",
    "scheduled_at": "2026-09-01T09:00:00Z"
}

Esempio di risposta

{
    "link": {
        "id": 456,
        "status": "awaiting_confirmation"
    }
}
PUT/links/{id}Alias PATCH per i clienti che inviano un set parziale di campi modificabili.
Accesso: Bearer + Idempotency-KeyScope: links:write

Richiedi JSON

{
    "anchor": "новый анкор"
}

Esempio di risposta

{
    "link": {
        "id": 456,
        "status": "awaiting_confirmation"
    }
}
POST/orders/{id}/bulk-updateCompilazione massiva delle righe d'ordine senza invio in produzione.
Accesso: Bearer + Idempotency-KeyScope: orders:write

Richiedi JSON

{
    "links": [
        {
            "url": "https://example.com/a",
            "anchor": "ключ"
        },
        {
            "url": "https://example.com/b",
            "anchor": "другой ключ"
        }
    ]
}

Esempio di risposta

{
    "updated": 2,
    "errors": []
}

Invia 2

POST/links/{id}/submitInvia un singolo link pronto in produzione dopo la conferma del cliente.
Accesso: Bearer + Idempotency-KeyScope: links:write

Richiedi JSON

[]

Esempio di risposta

{
    "link": {
        "id": 456,
        "status": "in_progress"
    }
}
POST/orders/{id}/submit-allInvia tutte le righe degli ordini pronti dopo la conferma del cliente.
Accesso: Bearer + Idempotency-KeyScope: orders:write

Richiedi JSON

[]

Esempio di risposta

{
    "submitted": 2,
    "skipped": 0
}

Pagamento 2

POST/checkout-intentsCrea un link sicuro monouso per il checkout standard; non vengono addebitati fondi.
Accesso: Bearer + Idempotency-KeyScope: checkout:create

Richiedi JSON

{
    "geo": "ru",
    "items": [
        {
            "product_id": 3708,
            "quantity": 1
        }
    ],
    "links": [
        {
            "type": "yearly",
            "url": "https://example.com/page",
            "anchor": "пример"
        }
    ]
}

Esempio di risposta

{
    "intent_id": "32-символьный ID",
    "checkout_url": "https://tier1.shop/?t1c_agent_checkout=…",
    "expires_at": "…",
    "summary": {
        "currency": "RUB",
        "total_minor": 200000
    },
    "payment_preview": {
        "wallet_available_minor": 0,
        "nominal_wallet_gap_minor": 200000,
        "final_amount_at_checkout": true
    }
}
GET/checkout-intents/{id}Verifica la comparsa del pagamento e dell'ordine nell'account tramite intent_id senza riaprire il link monouso.
Accesso: BearerScope: checkout:create

Esempio di risposta

{
    "intent_id": "…",
    "state": "paid",
    "wc_order_id": 456,
    "cabinet_order_ids": [
        123
    ],
    "fulfilment_pending": false
}

Se la richiesta è fallita

400 / 422Correggi i parametri. Non ripetere la stessa richiesta non valida.
401 / 403Verifica la chiave e i relativi permessi; creane una nuova se necessario.
404Verifica il numero e il tipo di ID. Gli ordini di terzi non vengono divulgati.
409Aggiorna lo stato dell'ordine o usa una nuova chiave per una nuova azione.
429 / 5xxAttendi e riprova. Per una richiesta mutante, mantieni lo stesso Idempotency-Key e JSON.

Le liste restituiscono un massimo di 50 righe per pagina. Se has_more=true, vai a next_page. L'importo preliminare nell'API non sostituisce l'importo finale e i metodi di pagamento disponibili al checkout.

Hai bisogno di MCP invece di REST API?

La stessa chiave revocabile funziona per il client MCP con header HTTP. Puoi anche connetterti via OAuth se l'applicazione lo supporta.

Apri istruzioni MCP