Solavel Documenti
Italiano
Riferimento per sviluppatori

API Finance di SolaCount

Versione: v1 URL di base: https://solavel.com/api/v1 (sostituire con il proprio dominio) Formato: JSON 33 endpoint

L'API Finance di SolaCount consente di leggere e scrivere dati contabili in modo programmatico: clienti, fornitori, fatture, fatture passive, pagamenti, registrazioni contabili e report finanziari. Tutti gli endpoint restituiscono JSON. Crea una chiave API →

Autenticazione

Ogni endpoint protetto richiede tre intestazioni:

X-API-Key: solabooks_<prefix>.<secret>
X-Organization-Id: 1
X-Client-Id: 4
  • X-API-Key — la chiave completa mostrata una sola volta alla creazione in Impostazioni → Accesso API
  • X-Organization-Id — ID intero della tua organizzazione (visibile nella pagina Accesso API)
  • X-Client-Id — il tuo ID client (visibile nella pagina Accesso API)
Genera una chiave: Vai a Impostazioni → Accesso API in SolaCount. La chiave completa viene mostrata una sola volta. Ogni chiave ha ambiti: concedi solo quelli necessari.

L'endpoint GET /api/v1/health non richiede autenticazione e può essere usato per verificare la connettività.

Formato della risposta

Tutte le risposte usano un involucro JSON coerente.

Oggetto singolo

{
  "success": true,
  "data": { ... }
}

Elenco paginato

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 100,
    "last_page": 4
  }
}

Errore

{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Human readable message."
  }
}

Test rapido

Sostituisci your_key, 1 e 4 con la tua chiave API, l'ID dell'organizzazione e l'ID client effettivi.

Verifica dello stato (nessuna autenticazione richiesta)

curl https://solacount.com/api/v1/health

Elenca le fatture

curl https://solacount.com/api/v1/invoices \
  -H "X-API-Key: your_key" \
  -H "X-Organization-Id: 1" \
  -H "X-Client-Id: 4"

Creare un cliente

curl -X POST https://solacount.com/api/v1/customers \
  -H "X-API-Key: your_key" \
  -H "X-Organization-Id: 1" \
  -H "X-Client-Id: 4" \
  -H "Content-Type: application/json" \
  -d '{"name":"Demo Customer","email":"billing@example.com"}'

Creare una scrittura contabile

curl -X POST https://solacount.com/api/v1/journal-entries \
  -H "X-API-Key: your_key" \
  -H "X-Organization-Id: 1" \
  -H "X-Client-Id: 4" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-06-07",
    "reference": "JE-001",
    "description": "Manual accrual",
    "lines": [
      {"account_id": 101, "debit": 1000, "credit": 0},
      {"account_id": 202, "debit": 0, "credit": 1000}
    ]
  }'

Tutti gli endpoint

Fai clic su un endpoint per espanderne i dettagli. In totale, 33 endpoint suddivisi in 8 gruppi di risorse.

Salute

GET /api/v1/health nessuna autenticazione

Verifica che l'API sia online e risponda. Non è richiesta alcuna autenticazione.

Risposta HTTP 200

{"success":true,"data":{"service":"finance-api","status":"ok","timestamp":"2026-06-07T12:00:00+00:00"}}

Clienti

GET /api/v1/customers ambito: customers.get

Elenca tutti i clienti. Supporta ricerca e paginazione.

Parametri della query

ParametroTipoDescrizione
search string facoltativo Filtra per nome, email o telefono (corrispondenza parziale)
page integer facoltativo Numero di pagina (predefinito: 1)
per_page integer facoltativo Risultati per pagina (predefinito: 25, massimo: 100)

Risposta HTTP 200

{"success":true,"data":[{"id":1,"name":"Demo Customer","email":"billing@example.com","phone":"+1-555-0100","is_active":true}],"meta":{"current_page":1,"per_page":25,"total":3,"last_page":1}}
GET /api/v1/customers/{id} ambito: customers.get

Recupera un singolo cliente tramite ID.

Risposta HTTP 200

{"success":true,"data":{"id":1,"name":"Demo Customer","email":"billing@example.com","phone":"+1-555-0100","is_active":true}}
POST /api/v1/customers ambito: customers.post

Crea un nuovo cliente.

Corpo della richiesta (JSON)

CampoTipoDescrizione
name string obbligatorio Nome cliente
email string facoltativo Indirizzo e-mail (deve essere un'e-mail valida)
phone string facoltativo Numero di telefono (massimo 50 caratteri)
is_active boolean facoltativo Stato attivo (predefinito: true)

Risposta HTTP 201

{"success":true,"data":{"id":42,"name":"Demo Customer","email":"billing@example.com","phone":null,"is_active":true}}

Fornitori

GET /api/v1/suppliers ambito: suppliers.get

Elenca tutti i fornitori. Supporta ricerca e paginazione.

Parametri della query

ParametroTipoDescrizione
search string facoltativo Filtra per nome (corrispondenza parziale)
page integer facoltativo Numero di pagina
per_page integer facoltativo Risultati per pagina (massimo 100)

Risposta HTTP 200

{"success":true,"data":[{"id":1,"name":"Demo Supplier","email":"ap@example.com","tax_id":"GB123456789","is_vat_registered":true}],"meta":{"current_page":1,"per_page":25,"total":1,"last_page":1}}
GET /api/v1/suppliers/{id} ambito: suppliers.get

Recupera un singolo fornitore tramite ID.

Risposta HTTP 200

{"success":true,"data":{"id":1,"name":"Demo Supplier","email":"ap@example.com","phone":null,"tax_id":"GB123456789","is_overseas":false,"is_vat_registered":true,"reverse_charge":false}}
POST /api/v1/suppliers ambito: suppliers.post

Crea un nuovo fornitore.

Corpo della richiesta (JSON)

CampoTipoDescrizione
name string obbligatorio Nome fornitore
email string facoltativo Indirizzo e-mail
phone string facoltativo Numero di telefono
tax_id string facoltativo Numero di registrazione IVA / fiscale
is_overseas boolean facoltativo Se il fornitore è estero (predefinito: false)
is_vat_registered boolean facoltativo IVA registrata (predefinito: true)
reverse_charge boolean facoltativo Si applica il reverse charge IVA (predefinito: false)

Risposta HTTP 201

{"success":true,"data":{"id":15,"name":"Demo Supplier","email":"ap@example.com","tax_id":"GB123456789","is_vat_registered":true}}

Fatture

GET /api/v1/invoices ambito: invoices.get

Elenca tutte le fatture con il relativo cliente. Supporta il filtro per stato e la paginazione.

Parametri della query

ParametroTipoDescrizione
status string facoltativo Filtro: draft | unpaid | paid | void | overdue
page integer facoltativo Numero di pagina
per_page integer facoltativo Risultati per pagina (massimo 100)

Risposta HTTP 200

{"success":true,"data":[{"id":101,"number":"INV-00101","date":"2026-06-01","due_date":"2026-07-01","status":"unpaid","total":5000.00,"customer":{"id":1,"name":"Demo Customer"}}],"meta":{"current_page":1,"per_page":25,"total":48,"last_page":2}}
GET /api/v1/invoices/{id} ambito: invoices.get

Recupera una singola fattura con cliente e righe.

Risposta HTTP 200

{"success":true,"data":{"id":101,"number":"INV-00101","date":"2026-06-01","due_date":"2026-07-01","status":"unpaid","subtotal":4347.83,"tax_total":652.17,"total":5000.00,"customer":{"id":1,"name":"Demo Customer"},"lines":[{"id":1,"description":"Consulting services","qty":10,"unit_price":434.78,"total":4347.83}]}}
POST /api/v1/invoices ambito: invoices.post

Crea una nuova fattura. Creata con stato=bozza e numero generato automaticamente.

Corpo della richiesta (JSON)

CampoTipoDescrizione
customer_id integer obbligatorio ID di un cliente esistente
date date obbligatorio Data fattura (AAAA-MM-GG)
due_date date facoltativo Data di scadenza del pagamento (AAAA-MM-GG)
notes string facoltativo Note interne o rivolte al cliente
subtotal decimal facoltativo Totale al netto delle imposte (predefinito: 0)
tax_total decimal facoltativo Importo dell'imposta (predefinito: 0)
discount_total decimal facoltativo Importo dello sconto (predefinito: 0)
total decimal facoltativo Totale generale (predefinito: 0)

Risposta HTTP 201

{"success":true,"data":{"id":102,"number":"INV-00102","status":"draft","date":"2026-06-07","due_date":"2026-07-07","total":5000.00,"customer_id":1}}
PUT /api/v1/invoices/{id} ambito: invoices.update

Aggiorna una fattura in bozza esistente. Tutti i campi sono facoltativi.

Corpo della richiesta (JSON)

CampoTipoDescrizione
customer_id integer facoltativo Nuovo ID cliente
date date facoltativo Data fattura (AAAA-MM-GG)
due_date date facoltativo Data di scadenza del pagamento
notes string facoltativo Note
subtotal decimal facoltativo Totale al netto delle imposte
tax_total decimal facoltativo Importo dell'imposta
total decimal facoltativo Totale generale

Risposta HTTP 200

{"success":true,"data":{"id":102,"status":"draft","total":6000.00,"customer":{"id":1,"name":"Demo Customer"},"lines":[]}}
POST /api/v1/invoices/{id}/post ambito: invoices.post

Registra una fattura in bozza nel libro mastro. Richiede totale > 0 e una data. Cambia lo stato in non pagata.

Risposta HTTP 200

{"success":true,"data":{"id":102,"status":"unpaid","posted_at":"2026-06-07T12:00:00Z","total":5000.00}}

Possibili errori: invoice_already_posted, invoice_total_required, invoice_date_required

POST /api/v1/invoices/{id}/void ambito: invoices.void

Annulla una fattura registrata. Storna tutte le scritture contabili e contrassegna la fattura come annullata.

Risposta HTTP 200

{"success":true,"data":{"id":102,"status":"void"}}
POST /api/v1/invoices/{id}/mark-sent ambito: invoices.send

Contrassegna una fattura in bozza come inviata al cliente (lo stato passa da bozza a non pagata). L'operazione è idempotente.

Risposta HTTP 200

{"success":true,"data":{"id":102,"status":"unpaid"}}
DELETE /api/v1/invoices/{id} ambito: invoices.delete

Elimina definitivamente una fattura in bozza e tutte le sue righe. Non è possibile eliminare fatture registrate o fatture con allocazioni di pagamento.

Risposta HTTP 200

{"success":true,"data":{"message":"Invoice deleted."}}

Possibili errori: posted_invoice_not_deletable, invoice_has_allocations

Fatture d'acquisto

GET /api/v1/bills ambito: bills.get

Elenca tutte le fatture dei fornitori. Supporta il filtro per stato e la paginazione.

Parametri della query

ParametroTipoDescrizione
status string facoltativo Filtro: draft | unpaid | paid | void
page integer facoltativo Numero di pagina
per_page integer facoltativo Risultati per pagina (massimo 100)

Risposta HTTP 200

{"success":true,"data":[{"id":55,"number":"BILL-00055","date":"2026-06-01","status":"draft","total":2000.00,"supplier":{"id":3,"name":"Demo Supplier"}}],"meta":{"current_page":1,"per_page":25,"total":12,"last_page":1}}
GET /api/v1/bills/{id} ambito: bills.get

Recupera una singola fattura con fornitore e righe.

Risposta HTTP 200

{"success":true,"data":{"id":55,"number":"BILL-00055","date":"2026-06-01","due_date":"2026-07-01","status":"draft","reference":"PO-001","total":2000.00,"supplier":{"id":3,"name":"Demo Supplier"},"lines":[]}}
POST /api/v1/bills ambito: bills.post

Crea una nuova fattura fornitore. Viene creata con status=draft e un numero BILL-XXXXX generato automaticamente.

Corpo della richiesta (JSON)

CampoTipoDescrizione
supplier_id integer obbligatorio ID di un fornitore esistente
date date obbligatorio Data fattura (AAAA-MM-GG)
due_date date facoltativo Data di scadenza del pagamento
reference string facoltativo Riferimento fornitore / numero ordine (max 120)
notes string facoltativo Note interne
subtotal decimal facoltativo Totale al netto delle imposte (predefinito: 0)
tax_total decimal facoltativo Importo dell'imposta (predefinito: 0)
discount_total decimal facoltativo Sconto (predefinito: 0)
total decimal facoltativo Totale generale (predefinito: 0)

Risposta HTTP 201

{"success":true,"data":{"id":56,"number":"BILL-00056","status":"draft","date":"2026-06-07","total":2000.00,"supplier_id":3}}
PUT /api/v1/bills/{id} ambito: bills.update

Aggiorna una fattura in bozza esistente. Tutti i campi sono facoltativi.

Corpo della richiesta (JSON)

CampoTipoDescrizione
supplier_id integer facoltativo Nuovo ID fornitore
date date facoltativo Data fattura
due_date date facoltativo Data di scadenza del pagamento
reference string facoltativo Riferimento fornitore
total decimal facoltativo Totale generale

Risposta HTTP 200

{"success":true,"data":{"id":56,"status":"draft","total":2500.00,"supplier":{"id":3,"name":"Demo Supplier"}}}
POST /api/v1/bills/{id}/post ambito: bills.post

Registra una fattura in bozza nel libro mastro generale, rilevando il debito.

Risposta HTTP 200

{"success":true,"data":{"id":56,"status":"unpaid","posted_at":"2026-06-07T12:00:00Z"}}

Possibili errori: bill_post_failed

DELETE /api/v1/bills/{id} ambito: bills.delete

Elimina definitivamente una fattura fornitore in bozza. La fattura deve essere in bozza senza assegnazioni di pagamenti.

Risposta HTTP 200

{"success":true,"data":{"message":"Bill deleted."}}

Possibili errori: posted_bill_not_deletable, bill_has_allocations

Pagamenti

GET /api/v1/payments ambito: payments.get

Elenca tutti i pagamenti (incassi ed esborsi).

Parametri della query

ParametroTipoDescrizione
type string facoltativo Filtro: receipt | disbursement
status string facoltativo Filtro: draft | posted
page integer facoltativo Numero di pagina
per_page integer facoltativo Risultati per pagina (massimo 100)

Risposta HTTP 200

{"success":true,"data":[{"id":20,"type":"receipt","payment_date":"2026-06-07","amount_total":5000.00,"status":"draft","customer_id":1}],"meta":{"current_page":1,"per_page":25,"total":8,"last_page":1}}
POST /api/v1/payments ambito: payments.post

Registra una ricevuta di pagamento (il cliente ha pagato) o un esborso (hai pagato il fornitore). Facoltativamente, assegna a una fattura o a un conto.

Corpo della richiesta (JSON)

CampoTipoDescrizione
type string obbligatorio receipt (pagamento del cliente) o disbursement (pagamento al fornitore)
payment_date date obbligatorio Data del pagamento (AAAA-MM-GG)
amount_total decimal obbligatorio Importo totale pagato (deve essere > 0)
method string facoltativo Metodo di pagamento, ad es. bank_transfer, cash, card
reference string facoltativo Riferimento bancario o numero di assegno (max 120)
description string facoltativo Descrizione o nota
customer_id integer cond. Obbligatorio per i pagamenti ricevuti (dedotto dalla fattura se document_type=ar_invoice)
supplier_id integer cond. Obbligatorio per i pagamenti effettuati (dedotto dalla fattura fornitore se document_type=ap_bill)
document_type string facoltativo "ar_invoice" o "ap_bill" — attivano l'allocazione automatica
document_id integer facoltativo ID della fattura cliente o fornitore a cui assegnare il pagamento (obbligatorio quando document_type è impostato)
allocated_amount decimal facoltativo Importo da allocare (predefinito amount_total)

Risposta HTTP 201

{"success":true,"data":{"id":21,"type":"receipt","payment_date":"2026-06-07","amount_total":5000.00,"status":"draft","allocations":[{"document_type":"ar_invoice","document_id":101,"allocated_amount":5000.00}]}}

Possibili errori: document_required, document_type_mismatch, invoice_not_found, bill_not_found, client_required, supplier_required

Registrazioni prima nota

GET /api/v1/journal-entries ambito: journal_entries.get

Elenca le scritture contabili con righe e conti. Supporta il filtro per intervallo di date.

Parametri della query

ParametroTipoDescrizione
status string facoltativo Filtro: draft | posted
from date facoltativo Data di inizio (YYYY-MM-DD)
to date facoltativo Data di fine (AAAA-MM-GG)
page integer facoltativo Numero di pagina
per_page integer facoltativo Risultati per pagina (massimo 100)

Risposta HTTP 200

{"success":true,"data":[{"id":5,"entry_date":"2026-06-07","reference":"JE-001","status":"posted","lines_count":2}],"meta":{"current_page":1,"per_page":25,"total":5,"last_page":1}}
POST /api/v1/journal-entries ambito: journal_entries.post

Crea e registra subito una scrittura contabile bilanciata. Il totale Dare deve uguagliare il totale Avere (tolleranza ±0,01).

Corpo della richiesta (JSON)

CampoTipoDescrizione
date date obbligatorio Data della voce (AAAA-MM-GG)
reference string facoltativo Codice di riferimento, ad es. JE-001 (max 120)
description string facoltativo Memo / descrizione (max 2000)
lines array obbligatorio Minimo 2 righe. Ogni riga: account_id (obbligatorio), debit (decimale), credit (decimale), description (stringa).

Risposta HTTP 201

{"success":true,"data":{"id":6,"entry_date":"2026-06-07","reference":"JE-001","status":"posted","posted_at":"2026-06-07T12:00:00Z","lines":[{"account_id":101,"account":{"code":"1100","name":"Cash"},"debit":1000,"credit":0},{"account_id":202,"account":{"code":"3000","name":"Equity"},"debit":0,"credit":1000}]}}

Possibili errori: journal_not_balanced

DELETE /api/v1/journal-entries/{id} ambito: journal_entries.delete

Elimina una scrittura contabile non contabilizzata. Le scritture contabilizzate non possono essere eliminate tramite API.

Risposta HTTP 200

{"success":true,"data":{"message":"Journal entry deleted."}}

Possibili errori: posted_journal_not_deletable

Rapporti

Tutti gli endpoint dei report accettano ?from=YYYY-MM-DD&to=YYYY-MM-DD. Bilancio, bilancio di verifica e report di scadenzario accettano anche ?as_of=YYYY-MM-DD (equivalente a to).

GET /api/v1/reports/income-statement ambito: reports.income_statement

Conto economico. Restituisce ricavi, spese e utile netto per il periodo specificato.

Parametri della query

ParametroTipoDescrizione
from date facoltativo Inizio periodo (AAAA-MM-GG)
to date facoltativo Fine periodo (AAAA-MM-GG)

Risposta HTTP 200

{"success":true,"data":{"revenue":150000,"expenses":85000,"net_income":65000}}
GET /api/v1/reports/balance-sheet ambito: reports.balance_sheet

Situazione patrimoniale. Restituisce attività, passività e patrimonio netto alla data specificata.

Parametri della query

ParametroTipoDescrizione
to date facoltativo Data di riferimento (AAAA-MM-GG). Accettata anche come ?as_of=

Risposta HTTP 200

{"success":true,"data":{"assets":{"total":250000},"liabilities":{"total":80000},"equity":{"total":170000}}}
GET /api/v1/reports/cash-flow ambito: reports.cash_flow

Rendiconto finanziario per il periodo indicato (metodo diretto).

Parametri della query

ParametroTipoDescrizione
from date facoltativo Inizio periodo
to date facoltativo Fine periodo

Risposta HTTP 200

{"success":true,"data":{"operating":45000,"investing":-12000,"financing":-8000,"net_change":25000}}
GET /api/v1/reports/trial-balance ambito: reports.trial_balance

Bilancio di verifica che mostra tutti i conti con i totali di dare e avere a una data.

Parametri della query

ParametroTipoDescrizione
to date facoltativo Data di riferimento (AAAA-MM-GG)

Risposta HTTP 200

{"success":true,"data":[{"account_code":"1100","account_name":"Cash","debit":50000,"credit":0},{"account_code":"2000","account_name":"Accounts Payable","debit":0,"credit":15000}]}
GET /api/v1/reports/ar-aging ambito: reports.ar_aging

Scadenzario dei crediti verso clienti. Fatture clienti insolute raggruppate secondo il ritardo di pagamento.

Parametri della query

ParametroTipoDescrizione
to date facoltativo Data di riferimento per l'anzianità (AAAA-MM-GG)

Risposta HTTP 200

{"success":true,"data":{"current":12000,"1_30":3500,"31_60":800,"61_90":0,"over_90":500,"total":16800}}
GET /api/v1/reports/ap-aging ambito: reports.ap_aging

Scadenzario dei debiti verso fornitori. Fatture fornitori insolute raggruppate secondo il ritardo di pagamento.

Parametri della query

ParametroTipoDescrizione
to date facoltativo Data di riferimento per l'anzianità (AAAA-MM-GG)

Risposta HTTP 200

{"success":true,"data":{"current":8000,"1_30":1200,"31_60":0,"61_90":0,"over_90":0,"total":9200}}
GET /api/v1/reports/tax ambito: reports.tax

Riepilogo IVA/imposte. Restituisce le imposte riscosse sulle vendite e quelle pagate sugli acquisti nel periodo.

Parametri della query

ParametroTipoDescrizione
from date facoltativo Inizio periodo
to date facoltativo Fine periodo

Risposta HTTP 200

{"success":true,"data":{"tax_collected":15000,"tax_paid":4200,"net_vat_payable":10800}}

Riferimento errori

Codice errore HTTP Significato
invoice_already_posted 422 La fattura è già registrata nel libro mastro
invoice_total_required 422 Impossibile registrare una fattura con totale zero o negativo
invoice_date_required 422 La data del documento è obbligatoria prima della registrazione
posted_invoice_not_deletable 422 Annulla o annulla la registrazione della fattura prima di eliminarla
invoice_has_allocations 422 Rimuovi le allocazioni di pagamento prima di eliminare
posted_bill_not_deletable 422 Impossibile eliminare una fattura registrata o non in bozza
bill_has_allocations 422 Rimuovi le allocazioni di pagamento prima di eliminare
bill_post_failed 422 La fattura non ha superato la convalida di registrazione interna
journal_not_balanced 422 Il totale dare non corrisponde al totale avere
posted_journal_not_deletable 422 Si possono eliminare solo le voci in bozza (non registrate)
document_required 422 document_id è obbligatorio quando è impostato document_type
document_type_mismatch 422 ar_invoice richiede receipt; ap_bill richiede disbursement
invoice_not_found 404 La fattura con questo ID non esiste
bill_not_found 404 La fattura con questo ID non esiste
client_required 422 customer_id è obbligatorio per i pagamenti receipt
supplier_required 422 supplier_id è obbligatorio per i pagamenti disbursement

Paginazione

Tutti gli endpoint di elenco restituiscono risultati suddivisi in pagine. Controlla la paginazione con i parametri di ricerca:

ParametroPredefinitoMassimoDescrizione
page1—Numero di pagina da recuperare
per_page25100Numero di risultati per pagina

L'oggetto meta in ogni risposta di elenco contiene current_page, per_page, total e last_page.