API

L’API di Gem Logic Le consente di integrarsi con sistemi esterni e automatizzare i flussi di lavoro. Può utilizzarla per gestire prodotti, vendite, contatti, riparazioni, inventari e stampe in modo programmatico.

Navighi in Impostazioni ‣ API per creare e gestire le Sue chiavi API.

Autenticazione

Tutte le richieste API devono includere una chiave API nell’header HTTP x-api-key. Può creare chiavi dalla pagina Impostazioni ‣ API. Le chiavi possono essere disattivate o eliminate in qualsiasi momento.

Esempio di richiesta:

curl -X GET https://your-instance.gem-logic.com/api/marketplaces/ \
  -H "x-api-key: YOUR_API_KEY"

Pericolo

Mantenga le Sue chiavi API segrete. Non le condivida mai in repository pubblici o nel codice lato client. Se una chiave viene compromessa, la disattivi immediatamente e ne crei una nuova.

URL di base

Tutti gli endpoint sono relativi all’URL della Sua istanza, sotto il prefisso /api/:

https://your-instance.gem-logic.com/api/

Formato di risposta

Tutte le risposte vengono restituite in formato JSON. Le richieste riuscite restituiscono un codice di stato 200 (per GET) o 201 (per POST). Gli errori restituiscono il codice di stato appropriato con un messaggio:

• 200 OK — richiesta GET riuscita

• 201 Created — richiesta POST riuscita

• 400 Bad Request — dati non validi o mancanti

• 401 Unauthorized — chiave API non valida o mancante

• 404 Not Found — la risorsa non esiste

Endpoint

Marketplace

Metodo	GET
URL	/api/marketplaces/
Descrizione	Restituisce un elenco di tutti i canali di vendita.

Campi di risposta:

Campo	Tipo	Descrizione
id	integer	Identificativo univoco
marketplace	string	Nome del marketplace

Prodotti

Elencare i prodotti

Metodo	GET
URL	/api/products/{marketplace_id}
Descrizione	Restituisce i prodotti filtrati per marketplace. Utilizzare l’ID del marketplace dal punto di accesso marketplaces.

Campi di risposta:

Campo	Tipo	Descrizione
id	integer	Identificativo univoco
item_sku	string	SKU del prodotto
created	datetime	Data di creazione
status	string	Stato del prodotto
images	array	Elenco delle immagini del prodotto (id, image)
item_weight	decimal	Peso
item_height	decimal	Altezza
item_length	decimal	Lunghezza
item_width	decimal	Larghezza

Creare un’immagine del prodotto

Metodo	POST
URL	/api/products/create/image/
Descrizione	Carica un’immagine del prodotto utilizzando la codifica base64. Se lo SKU del prodotto non esiste ancora, viene creato automaticamente un nuovo prodotto.

Campi della richiesta:

Campo	Tipo	Obbligatorio	Descrizione
item_sku	string	Sì	SKU del prodotto a cui allegare l’immagine
image	string (base64)	Sì	Dati immagine codificati in base64

Vendite

Elencare le vendite

Metodo	GET
URL	/api/sales/
Descrizione	Restituisce un elenco di tutti gli ordini di vendita.

Campi di risposta:

Campo	Tipo	Descrizione
order_id	string	Identificatore univoco dell’ordine

Creare una vendita

Metodo	POST
URL	/api/sales/create/
Descrizione	Crea un nuovo ordine di vendita.

Contatti

Metodo	GET
URL	/api/contacts/
Descrizione	Restituisce un elenco di tutti i contatti.

Campi di risposta:

Campo	Tipo	Descrizione
id	integer	Identificativo univoco
complete_name	string	Nome completo
contact_type	string	Tipo di contatto
email	string	Indirizzo email
phone	string	Numero di telefono
language	string	Lingua preferita

Riparazioni

Creare riparazione

Metodo	POST
URL	/api/repairs/create/
Descrizione	Crea un nuovo ordine di riparazione con un articolo di riparazione associato. Se il punto vendita o la divisione non viene fornito, viene utilizzato il primo disponibile.

Campi della richiesta:

Campo	Tipo	Obbligatorio	Descrizione
client_id	integer	No	ID del cliente/contatto
marketplace	string / integer	No	ID o nome del punto vendita
division_id	integer	No	ID della divisione aziendale
title	string	No	Titolo o descrizione dell’articolo di riparazione
repair_info_1	string	No	Commento di riparazione aggiuntivo
repair_info_2	string	No	Commento di riparazione aggiuntivo
repair_info_3	string	No	Commento di riparazione aggiuntivo
quantity	decimal	No	Quantità (predefinito: 1)
weight	decimal	No	Peso dell’articolo
weight_unit	string	No	Unità di misura del peso
size	string	No	Misura dell’articolo
color	string	No	Colore dell’articolo
engravement	string	No	Testo incisione
client_reference | string		No	Numero di riferimento del cliente

Esempio di risposta:

{"message": "Repair created successfully.", "order_id": "R-0001"}

Aggiungere articolo a riparazione

Metodo	POST
URL	/api/repairs/add-item/
Descrizione	Aggiunge un nuovo articolo a una scheda di riparazione esistente.

Campi della richiesta:

Campo	Tipo	Obbligatorio	Descrizione
order_id	string	Sì	ID scheda di riparazione a cui aggiungere l’articolo
item_sku	string	No	SKU prodotto da collegare all’articolo
title	string	No	Titolo o descrizione
repair_info_1	string	No	Commento di riparazione aggiuntivo
repair_info_2	string	No	Commento di riparazione aggiuntivo
repair_info_3	string	No	Commento di riparazione aggiuntivo
quantity	decimal	No	Quantità (predefinito: 1)
weight	decimal	No	Peso dell’articolo
weight_unit	string	No	Unità di misura del peso
size	string	No	Misura dell’articolo
color	string	No	Colore dell’articolo
engravement	string	No	Testo incisione
client_reference | string		No	Numero di riferimento del cliente
cost	decimal	No	Costo dell’articolo

Conteggi inventario

Creare conteggio inventario

Metodo	POST
URL	/api/inventory-counts/
Descrizione	Crea una nuova sessione di conteggio inventario.

Campi di risposta:

Campo	Tipo	Descrizione
id	string	ID conteggio inventario
created_at	datetime	Timestamp di creazione
status	string	Sempre active
tag_count	integer	Numero di prodotti conteggiati

Elencare prodotti conteggio inventario

Metodo	GET
URL	/api/inventory-counts/{inventory_count_id}/products/
Descrizione	Restituisce tutti i prodotti conteggiati in un conteggio inventario specifico.

Campi di risposta:

Campo	Tipo	Descrizione
id	string	Identificativo univoco
created_at	datetime	Quando il prodotto è stato conteggiato
product_sku	string	SKU del prodotto
product_name	string	Nome prodotto
quantity	integer	Quantità contata

Lavori di stampa

Metodo	POST
URL	/api/print-pdf/
Descrizione	Caricare un file PDF nella coda di stampa per una stampante specifica. Il file viene validato per formato e sicurezza. Dimensione massima del file: 20 MB. Utilizzare il tipo di contenuto multipart/form-data.

Campi della richiesta:

Campo	Tipo	Obbligatorio	Descrizione
pdf	file	Sì	File PDF da stampare (max 20 MB)
printer_uuid	UUID	Sì	UUID della stampante di destinazione
landscape	boolean	No	Stampa in modalità orizzontale (predefinito: false)

Esempio di richiesta:

curl -X POST https://your-instance.gem-logic.com/api/print-pdf/ \
  -H "x-api-key: YOUR_API_KEY" \
  -F "pdf=@document.pdf" \
  -F "printer_uuid=YOUR_PRINTER_UUID"

Esempio di risposta:

{"status": "queued", "print_job_id": 42}

Esploratore API interattivo

Gem Logic include un esploratore API interattivo integrato basato su Swagger UI. È possibile accedervi tramite il collegamento Documentazione API nella pagina Impostazioni ‣ API. L’esploratore consente di testare ciascun endpoint direttamente dal browser.

Vedi anche

• Integrazioni