API

Introduzione

In questa sezione vengono descritti tutti gli endpoint del package Cash Account Management. Di seguito il flusso via API:

GET Cash Accounts

L’endpoint GET Cash Accounts permette di recuperare l’elenco completo dei conti associati al soggetto autenticato. Di seguito un esempio di request:

GET /api/gbs/banking/v4.0/accounts

L’endpoint non richiede parametri di path o query.

e questo un esempio di risposta

{
  "list": [
    {
      "accountId": "14930637",
      "iban": "IT22D3706978430115706240270",
      "abiCode": "37069",
      "cabCode": "78430",
      "countryCode": "IT",
      "internationalCin": "22",
      "nationalCin": "D",
      "account": "115706240270",
      "alias": "Company main account",
      "productName": "Generic company cash account",
      "holderName": "ACME Inc.",
      "activatedDate": "2008-12-25",
      "currency": "EUR"
    }
  ]
}

dove

Campo	Tipo	Descrizione
accountId	String	Identificativo univoco del conto; necessario per gli altri endpoint.
iban	String	IBAN completo del conto.
abiCode	String	Codice ABI della banca.
cabCode	String	Codice CAB della filiale.
countryCode	String	Codice del Paese del conto (es. IT).
internationalCin	String	CIN internazionale dell’IBAN.
nationalCin	String	CIN nazionale dell’IBAN.
account	String	Numero di conto (sottostringa dell’IBAN).
alias	String	Alias del conto, se presente.
productName	String	Nome commerciale del prodotto collegato al conto.
holderName	String	Nome completo dell’intestatario o degli intestatari.
activatedDate	Date	Data di attivazione del conto.
currency	String	Valuta nativa del conto (es. EUR).

GET Cash Account

L’endpoint GET Cash Account restituisce i dettagli completi di un singolo conto, identificato tramite accountId.

GET /api/gbs/banking/v4.0/accounts/{accountId}

dove

Tipo	Nome	Req	Descrizione
Path	accountId	Sì	Identificativo univoco del conto ottenuto tramite GET Cash Accounts

La response è la stessa di quella vista nella precedente request, ma in quetso caso viene restituito un singolo elemento.

GET Cash Account Balance

L’endpoint GET Cash Account Balance consente di ottenere il saldo aggiornato del conto indicato, sia contabile che disponibile.
È fondamentale per funzioni di monitoraggio finanziario, dashboard conti e processi di riconciliazione.

DI seguito l'endpoint da invocare:

GET /api/gbs/banking/v4.0/accounts/{accountId}/balance

dove

Tipo	Nome	Req	Descrizione
Path	accountId	Sì	Identificativo univoco del conto

di seguito un esempi di response

{
  "balance": 15234.55,
  "availableBalance": 14980.10,
  "currency": "EUR",
  "date": "2024-01-15"
}

dove

Campo	Tipo	Descrizione
balance	Number	Saldo contabile del conto
availableBalance	Number	Saldo effettivamente disponibile
currency	String	Valuta
date	Date	Data di riferimento del saldo

---

GET Cash Account Transactions

Restituisce la lista delle transazioni relative al conto selezionato. Utilizzato per ricostruire la movimentazione, generare estratti conto, fare analisi o riconciliazione.

Di seguito la request

GET /api/gbs/banking/v4.0/accounts/{accountId}/transactions?fromAccountingDate=YYYY-MM-DD&toAccountingDate=YYYY-MM-DD

dove

Tipo	Nome	Req	Descrizione
Path	accountId	Sì	Identificativo univoco del conto
Query	fromAccountingDate	Sì	Data iniziale (inclusa) del periodo di ricerca
Query	toAccountingDate	Sì	Data finale (inclusa) del periodo di ricerca
Query	order	No	Ordinamento dei movimenti
Query	maxRecords	No	Numero massimo di movimenti da includere

---

di seguito un esempio di risposta

{
  "list": [
    {
      "transactionId": "123456789",
      "operationDate": "2024-02-01",
      "valueDate": "2024-02-01",
      "amount": -150.00,
      "currency": "EUR",
      "description": "Wire transfer outgoing",
      "type": "DEBIT"
    }
  ]
}

dove

Campo	Tipo	Descrizione
transactionId	String	ID univoco della transazione
operationDate	Date	Data operazione
valueDate	Date	Data valuta
amount	Number	Importo movimento
currency	String	Valuta
description	String	Descrizione movimento
type	String	Tipo movimento (DEBIT/CREDIT)

---

GET Cash Account Reserved Entries

Ritorna la lista delle voci riservate (reserved entries) del conto: importi contabilizzati ma non ancora disponibili, come addebiti futuri o autorizzazioni pendenti.

L'endpoint dovrà essere invocato come di seguito mostrato

GET /api/gbs/banking/v4.0/accounts/{accountId}/reserved-entries

dove

Tipo	Nome	Req	Descrizione
Path	accountId	Sì	Identificativo del conto

---

e di seguito un esempio di response

{
  "list": [
    {
      "reservedEntryId": "69451812",
      "creationDate": "2017-03-08",
      "dueDate": "2017-03-08",
      "amount": -10.01,
      "currency": "EUR",
      "description": "Mobile carrier phone charge."
    }
  ]
}

dove

Campo	Tipo	Descrizione
reservedEntryId	String	Identificatore della voce riservata
creationDate	Date	Data di creazione della voce
dueDate	Date	Data di scadenza prevista
amount	Number	Importo bloccato
currency	String	Valuta
description	String	Causale dell’importo bloccato