Accesso Bexio
per colleghi e agenti.
Usa la chiave emessa dalla console. Non fornire agli agenti il token personale Bexio.
Scarica la specifica OpenAPI 3.1 →
Autenticazione
Authorization: Bearer bxg_… Content-Type: application/json
La base URL è il dominio di questa console. I percorsi Bexio mantengono i nomi originali, con prefisso /bexio.
GET /v1/me GET /bexio/2.0/kb_order?limit=50&offset=0 GET /bexio/2.0/kb_order/123 POST /bexio/2.0/kb_order/search
Permessi distinti
| Permesso | Operazioni |
|---|---|
| orders.read | Elenco, ricerca, dettaglio, PDF e lettura posizioni degli ordini. |
| orders.create | Creazione ordini, incluse le posizioni iniziali. |
| orders.update | Modifica dei campi dell’ordine. Richiede orders.read. |
| positions.create / positions.update | Aggiunta o modifica di una singola posizione. Richiedono orders.read. |
| contacts.read / articles.read | Lettura e ricerca di contatti o articoli dell’azienda. |
| reference.read | Lettura utenti, lingue, paesi, valute, unità, imposte, tipi di pagamento. |
Creazione di un ordine
Ogni scrittura richiede Idempotency-Key (8–128 caratteri). Usa una nuova chiave per una nuova operazione, e la stessa chiave quando ripeti la medesima richiesta.
POST /bexio/2.0/kb_order
Idempotency-Key: order-your-unique-reference-001
{
"title": "Nuovo ordine",
"contact_id": 123,
"language_id": 1,
"currency_id": 1,
"positions": [{
"type": "KbPositionArticle",
"article_id": 456,
"amount": "2.000000",
"unit_price": "25.000000",
"unit_id": 1,
"tax_id": 1
}]
}Gli ID sono segnaposto da sostituire con valori dell’azienda. Bexio convalida campi e regole contabili. Il gateway imposta user_id al responsabile configurato nell’identità; una richiesta non può sceglierne un altro. Le modifiche preservano il responsabile esistente.
Modifica di ordine e posizioni
POST /bexio/2.0/kb_order/123
Idempotency-Key: order-123-title-update-001
{"title":"Titolo aggiornato"}
POST /bexio/2.0/kb_order/123/kb_position_article/456
Idempotency-Key: order-123-position-456-update-001
{"amount":"3.000000"}Non inviare l’array positions durante la modifica dell’ordine: usa gli endpoint della singola posizione. Tipi supportati: article, custom, text, subtotal, discount, pagebreak, subposition, sempre con prefisso kb_position_.
Limiti e comportamento
- Cancellazione, annullamento, invio email, conversione in fattura o consegna, contabilità, pagamenti e tutti gli altri endpoint sono bloccati.
- “Solo ordini del responsabile” filtra gli ordini per
user_id, anche in ricerca e sui PDF. La paginazione avviene in Bexio prima del filtro: una pagina vuota non indica necessariamente la fine dell’elenco. Questo ambito comprende anche ordini dello stesso responsabile creati fuori dal gateway. - Il filtro sugli ordini non limita i contatti e articoli: i relativi permessi danno lettura aziendale.
- Parametri query ammessi:
limit(1–500),offset(0–1.000.000),order_by. Nessun parametro permette di cambiare permessi o credenziali. - Corpo richiesta massimo 1 MiB. Ogni chiave ha un limite al minuto condiviso tra i processi.
- Le credenziali Bexio e le risposte delle scritture conservate per idempotenza sono cifrate nel database. Le chiavi gateway vengono conservate solo come hash.
- Ogni richiesta restituisce
X-Request-ID. Il registro include le richieste autenticate, gli esiti e le operazioni amministrative, senza token o contenuti dei documenti. - Le letture non riescono se non si può registrare l’audit. Una scrittura non parte senza audit e prenotazione di idempotenza persistenti.
- Un esito incerto restituisce 502; ripetere la stessa chiave restituisce 409. Verifica il documento in Bexio prima di decidere come procedere; non usare una nuova chiave per aggirare il blocco.
- Revoca e disabilitazione bloccano nuove richieste; una chiamata già inviata a Bexio può completarsi. Le modifiche effettuate contemporaneamente direttamente in Bexio non sono bloccate dal gateway.
Attribuzione dei documenti
Il gateway verifica il titolare del token tramite /3.0/users/me e lo imposta come responsabile dei nuovi ordini. user_id è il responsabile del documento, non una firma digitale. Per operare come Stefania collega un token creato dal suo account, il gateway rileva e fissa il suo ID utente e controlla l’attribuzione su un documento di prova concordato. Il registro del gateway conserva separatamente l’ID della chiave del collega o agente.
Errori
401 chiave non valida, scaduta o revocata; 403 operazione o permesso negato; 404 ordine non accessibile; 409 conflitto di idempotenza; 429 limite richieste; 502 errore Bexio; 503 audit, database o credenziale non disponibili. Le risposte di errore Bexio sono oscurate per non esporre dati interni.