Documentazione B2B

API B2B – Recupera automaticamente informazioni su ordini e prodotti

La nostra API REST è disponibile per ogni cliente con un account cliente e consente di recuperare automaticamente le informazioni su ordini e prodotti e di integrarle nei propri sistemi.

vpn_key Apri l'accesso API nell'account Pagina clienti business

Autenticazione

Tutte le richieste API richiedono un API-Key valido, inviato nell'header HTTP. L'accesso API è legato al tuo account cliente ed è generalmente disponibile per gli account cliente.

info Non hai bisogno di una richiesta B2B separata: accedi con il tuo account cliente, apri la scheda API e genera lì il tuo API-Key. All'accesso API →

Formato dell'header

HTTP Request Header

X-API-Key: YOUR_API_KEY_HERE
Content-Type: application/json
Accept: application/json

Esempio con cURL

cURL

curl -X GET "https://artumos.com/api/v1/orders" \
  -H "X-API-Key: YOUR_API_KEY_HERE" \
  -H "Accept: application/json"

Base URL

Tutti gli endpoint sono relativi alla seguente Base URL:

Base URL

https://artumos.com/api/v1

Tutte le risposte vengono restituite come JSON restituito (Content-Type: application/json).

Rate Limits

Plan	Richieste / minuto	Richieste / giorno
Account cliente	60	5.000
Limite esteso	su richiesta	su richiesta

In caso di superamento viene HTTP 429 Too Many Requests restituito. L'header Retry-After contiene il tempo di attesa in secondi.

Codici di errore

HTTP-Code	Significato
`200 OK`	Richiesta riuscita
`400 Bad Request`	Parametri non validi
`401 Unauthorized`	API-Key mancante o non valido
`403 Forbidden`	Nessuna autorizzazione per questa risorsa
`404 Not Found`	Risorsa non trovata
`429 Too Many Requests`	Rate Limit superato
`500 Internal Server Error`	Errore del server – contattare il supporto

Formato della risposta di errore

JSON

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key."
  }
}

Endpoint: Ordini

GET /api/v1/orders Tutti gli ordini dell'account

Parameter	Tipo	Descrizione
`page`	integer	Pagina (predefinito: 1)
`per_page`	integer	Voci per pagina (max. 100)
`status`	string	`paid` \| `pending` \| `all`

Beispiel-Response

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": "ORD-12345",
        "status": "paid",
        "total": 49.99,
        "currency": "EUR",
        "created_at": "2026-01-15T10:30:00Z",
        "items_count": 2
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 42
    }
  }
}

GET /api/v1/orders/{order_id} Recupera un singolo ordine

Endpoint: Informazioni su prodotti e ordini

GET /api/v1/orders/{order_id}/codes Tutte le informazioni sui prodotti di un ordine

Beispiel-Response

{
  "success": true,
  "data": {
    "order_id": "ORD-12345",
    "codes": [
      {
        "id": "CODE-789",
        "product_name": "Beispielprodukt vom Marktplatz",
        "product_sku": "ART-PRODUCT-001",
        "product_info": "Hinweise laut Verkäuferangaben",
        "delivery_url": "https://...",
        "delivered_at": "2026-01-15T10:31:00Z",
        "status": "active"
      }
    ]
  }
}

GET /api/v1/codes/{code_id} Recupera una singola informazione sul prodotto

warning Le informazioni su prodotti e ordini possono essere utilizzate solo nell'ambito del rispettivo ordine e delle indicazioni del venditore. Una divulgazione impropria può violare le condizioni d'uso.

Endpoint: Prodotti

GET /api/v1/products Recupera il catalogo prodotti

Parameter	Tipo	Descrizione
`category`	string	Filtra per slug della categoria
`in_stock`	boolean	Solo prodotti disponibili
`page`	integer	Pagina

Beispiel-Response

{
  "success": true,
  "data": {
    "products": [
      {
        "id": 42,
        "sku": "ART-PRODUCT-001",
        "name": "Beispielprodukt vom Marktplatz",
        "price": 49.99,
        "currency": "EUR",
        "in_stock": true,
        "category": "handmade"
      }
    ]
  }
}

Webhooks

I Webhook consentono di ricevere notifiche in tempo reale quando vengono forniti ordini o codici. Gli URL dei Webhook possono essere registrati nell'account cliente.

Eventi disponibili

Event	Descrizione
`order.paid`	L'ordine è stato pagato
`codes.delivered`	I codici sono stati forniti
`order.refunded`	L'ordine è stato rimborsato

Webhook Payload

POST – Il tuo endpoint Webhook

{
  "event": "codes.delivered",
  "timestamp": "2026-01-15T10:31:05Z",
  "data": {
    "order_id": "ORD-12345",
    "codes_count": 2
  },
  "signature": "sha256=..."
}

Verifica la firma con il tuo Webhook-Secret: HMAC-SHA256(payload, webhook_secret)

Domande frequenti

Chi può utilizzare l'API B2B?

Ogni cliente con un account cliente può utilizzare l'accesso API. Accedi al tuo account cliente e utilizza il relativo API-Key per le richieste autenticate.

Quale formato hanno le risposte?

Tutte le risposte vengono restituite come JSON. L'oggetto root contiene sempre success: true/false nonché data oppure error.

Posso effettuare ordini tramite API?

Nella prima versione l'API serve per recuperare ordini, informazioni su ordini e prodotti. Gli endpoint di scrittura per gli ordini verranno attivati separatamente non appena saranno disponibili.

Esiste un ambiente sandbox?

Sì. La sandbox può essere attivata nell'account cliente nella scheda „Accesso API“ ed è legata direttamente al rispettivo API-Key.