Specifica JSON v1.1 | OB1 Connector HUB

1. Scopo e architettura

Il presente documento descrive il protocollo HTTP/JSON esposto dal Trading Partner e utilizzato da OB1 per lo scambio di dati contabili e anagrafici. La specifica è rivolta allo sviluppatore del sistema esterno e descrive esclusivamente il contratto di integrazione, senza dettagli implementativi interni di OB1.

Direzione	Metodo	Funzione
Trading Partner → OB1	GET	Dati da importare/elaborare in OB1
OB1 → Trading Partner	POST	Esito dell’elaborazione dei dati ricevuti
OB1 → Trading Partner	POST	Piano dei conti e Centri di costo
OB1 → Trading Partner	POST	Incassi clienti e Pagamenti fornitori

Il mandante viene identificato da id_ow. Per questa integrazione l’identificativo univoco esterno utilizzato negli esiti è id_teleutias. Il nome identifica l’ID del record nel sistema esterno e non modifica la struttura o il funzionamento del protocollo.

2. GET - richiesta dati a OB1

OB1 esegue una GET verso l’endpoint configurato del Trading Partner. La richiesta è incrementale e comprende il contesto del mandante e l’intervallo dei due esercizi aperti.

Parametro	Significato
last-sync-datetime	Data/ora dell’ultima sincronizzazione registrata da OB1.
first-date	Data iniziale dell’esercizio corrente.
last-date	Data finale dell’esercizio successivo.
id_ow	Identificativo del mandante presso il Trading Partner.

GET <base-url><token><get-url><last-sync-datetime>&first-date=<YYYY-MM-DD>&last-date=<YYYY-MM-DD>&id_ow=<ID> Nota: I nomi first-date, last-date e id_ow fanno parte del contratto corrente. L’endpoint, il token e la parte iniziale della URL sono configurabili.

2.1 Risposta GET

La risposta è un oggetto JSON. I metadati seguenti sono riconosciuti da OB1; le collection possono essere presenti solo quando contengono dati.

{
  "version": "1.0",
  "message": "",
  "sync-datetime": "01/10/2026@07:00:00",
  "debug": "",
  "ok": true,
  "login": true,
  "customers": [],
  "customers_deleted": [],
  "vendors": [],
  "vendors_deleted": [],
  "services": [],
  "services_deleted": [],
  "products": [],
  "products_deleted": [],
  "invoices": [],
  "invoices_deleted": [],
  "creditnotes": [],
  "creditnotes_deleted": [],
  "cinvoices": [],
  "cinvoices_deleted": [],
  "ccreditnotes": [],
  "ccreditnotes_deleted": [],
  "financial_transactions": [],
  "financial_transactions_deleted": [],
  "payments": [],
  "payments_deleted": []
}

Campo	Tipo	Uso
version	string	Versione del payload. Se assente OB1 usa 1.0.
message	string	Messaggio informativo del Trading Partner.
sync-datetime	string	Timestamp di sincronizzazione restituito dal TP; se assente OB1 assegna data/ora corrente.
debug	string	Informazione diagnostica opzionale.
ok	boolean	Esito generale della risposta.
login	boolean	Esito autenticazione/autorizzazione.

3. Anagrafiche GET

3.1 customers - Clienti

Campo	Tipo	Presenza	Descrizione
id_customer	string	Sì	ID esterno cliente
nr_customer	string	Sì	Numero cliente
name	string	Sì	Nome
company	string	Sì	Ragione sociale
surname	string	Sì	Cognome
adresse	string	Sì	Indirizzo
adresse2	string	Sì	Indirizzo 2
cap	string	Sì	CAP
location	string	Sì	Località
tel1	string	Sì	Telefono
tel2	string	Sì	Telefono 2
fax	string	Sì	Fax
email	string	Sì	E-mail
web	string	Sì	Sito web
cust_currency	string	Sì	Valuta
acct_code	string	Sì	Conto contabile
cust_title	string	Sì	Titolo
cust_status	string	Sì	Stato
cust_lang	string	Sì	Lingua
resp1	string	Sì	Contatto/responsabile
cust_exempt_iva	string	Sì	Indicatore esenzione IVA
email_invoice	array[string]	No	Indirizzi e-mail fattura
cust_country_code	string	No	Codice paese
vat_number	string	No	Numero IVA
tax_id	string	No	Identificativo fiscale

3.2 vendors - Fornitori

Campo	Tipo	Presenza	Descrizione
id_customer	string	Sì	ID esterno fornitore
nr_customer	string	Sì	Numero fornitore
name	string	Sì	Nome
surname	string	Sì	Cognome
company	string	Sì	Ragione sociale
adresse	string	Sì	Indirizzo
adresse2	string	Sì	Indirizzo 2
cap	string	Sì	CAP
location	string	Sì	Località
tel1	string	Sì	Telefono
tel2	string	Sì	Telefono 2
fax	string	Sì	Fax
email	string	Sì	E-mail
web	string	Sì	Sito web
cust_currency	string	Sì	Valuta
acct_code	string	Sì	Conto contabile
cust_title	string	Sì	Titolo
cust_status	string	Sì	Stato
cust_lang	string	Sì	Lingua
resp1	string	Sì	Contatto/responsabile
cust_exempt_iva	string	Sì	Indicatore esenzione IVA
cust_country_code	string	No	Codice paese
vat_number	string	No	Numero IVA
tax_id	string	No	Identificativo fiscale

cf_acct_vendor_bank_name	string	No	Nome banca
cf_acct_vendor_bank_zip	string	No	CAP banca
cf_acct_vendor_bank_city	string	No	Località banca
cf_acct_vendor_bank_post_account	string	No	Conto postale
cf_acct_vendor_bank_pvbr_code	string	No	Codice PVBR
cf_acct_vendor_bank_iban	string	No	IBAN fornitore

{
  "vendors": [
    {
      "id_customer": "V250",
      "nr_customer": "250",
      "name": "",
      "surname": "",
      "company": "Fornitore SA",
      "adresse": "Via Esempio 20",
      "adresse2": "",
      "cap": "6900",
      "location": "Lugano",
      "tel1": "",
      "tel2": "",
      "fax": "",
      "email": "vendor@example.com",
      "web": "",
      "cust_currency": "CHF",
      "acct_code": "2000",
      "cust_title": "",
      "cust_status": "",
      "cust_lang": "IT",
      "resp1": "",
      "cust_exempt_iva": "0",
      "cust_country_code": "CH",
      "vat_number": "",
      "tax_id": "",
      "cf_acct_vendor_bank_name": "Banca Esempio",
      "cf_acct_vendor_bank_zip": "6900",
      "cf_acct_vendor_bank_city": "Lugano",
      "cf_acct_vendor_bank_post_account": "",
      "cf_acct_vendor_bank_pvbr_code": "",
      "cf_acct_vendor_bank_iban": ""
    }
  ]
}

3.3 services - Servizi

Campo	Tipo	Presenza	Descrizione
id_se	string	Sì	ID servizio
code	string	Sì	Codice
name	string	Sì	Descrizione
se_status	string	Sì	Stato
acct_code_sale	string	Sì	Conto vendita
acct_code_purchase	string	Sì	Conto acquisto
price	decimal/string	Sì	Prezzo vendita
price_buy	decimal/string	Sì	Prezzo acquisto
iva_perc_sell	decimal/string	Sì	Percentuale IVA vendita

3.4 products - Prodotti

Campo	Tipo	Presenza	Descrizione
id_pr	string	Sì	ID prodotto
code	string	Sì	Codice
name	string	Sì	Descrizione
pr_status	string	Sì	Stato
acct_code_sale	string	Sì	Conto vendita
acct_code_purchase	string	Sì	Conto acquisto
price_sell	decimal/string	Sì	Prezzo vendita
price_buy	decimal/string	Sì	Prezzo acquisto
iva_perc	decimal/string	Sì	Percentuale IVA

4. Documenti e partite aperte

Per l’integrazione contabile, invoices rappresenta i documenti/partite clienti e cinvoices i documenti/partite fornitori. Le rispettive note di credito sono creditnotes e ccreditnotes.

4.1 invoices - Partite/documenti clienti

Campo	Tipo	Presenza	Descrizione
id_invoice	string	Sì	ID esterno documento
num_invoice	string	Sì	Numero documento
cf_acct_voucher	string	Sì	Voucher contabile
date_invoice	date	Sì	Data documento
currency	string	Sì	Valuta
inv_exch_rate	decimal/string	Sì	Cambio
nr_customer	string	Sì	Numero cliente
inv_pvbr_ref	string	Sì	Riferimento PVBR
acct_code	string	Sì	Conto collettivo/contabile
inv_title	string	Sì	Titolo/riferimento
action	string	Sì	Azione richiesta
id_bank	string	Sì	Identificativo banca
is_iva	string	Sì	Indicatore IVA
payment_condition_code	string	No	Condizione pagamento
due_date	date	No	Scadenza
date_expiration	date	No	Scadenza alternativa; se presente prevale
company/name/surname	string	No	Dati anagrafici cliente
adresse/cap/location	string	No	Indirizzo cliente
cust_country_code	string	No	Paese
tel1/tel2/email/web/resp1	string	No	Contatti
email_invoice	array[string]	No	E-mail fattura
doc_wiva	string	Sì	1 = importi IVA inclusa
inv_total	decimal/string	Sì	Totale documento
total_no_iva	decimal/string	Sì	Totale imponibile
iva_total	decimal/string	Sì	Totale IVA
inv_total_main_currency	decimal/string	Sì	Totale in valuta base
rows	array	Sì	Righe documento

Righe invoices.rows

Campo	Tipo	Presenza	Descrizione
id_invoice	string	Sì	ID documento
description	string	Sì	Descrizione riga
ordering	string	Sì	Ordinamento
qt_accounting	decimal/string	Sì	Quantità contabile
total_row	decimal/string	Sì	Totale riga
acct_code	string	Sì	Conto contabile
cc_code	string	Sì	Centro di costo
iva_row	decimal/string	Sì	Percentuale IVA numerica della riga (es. 8.1, 2.6, 0). Non inviare il codice IVA interno del sistema contabile; la relativa conversione è gestita da OB1.
discount_real	decimal/string	No	Sconto reale
discount_row	decimal/string	No	Sconto riga
id_pr	string	Sì	ID prodotto; usare 0 se non applicabile
id_se	string	Sì	ID servizio; usare 0 se non applicabile

{
  "invoices": [
    {
      "id_invoice": "100001",
      "num_invoice": "2026-00125",
      "cf_acct_voucher": "125",
      "date_invoice": "2026-09-15",
      "currency": "CHF",
      "inv_exch_rate": "1",
      "nr_customer": "1001",
      "inv_pvbr_ref": "",
      "acct_code": "1100",
      "inv_title": "Fattura 2026-00125",
      "action": "CU",
      "id_bank": "",
      "is_iva": "1",
      "payment_condition_code": "30",
      "due_date": "2026-10-15",
      "company": "Cliente SA",
      "name": "",
      "surname": "",
      "adresse": "Via Esempio 10",
      "cap": "6900",
      "location": "Lugano",
      "cust_country_code": "CH",
      "tel1": "",
      "tel2": "",
      "email": "billing@example.com",
      "web": "",
      "resp1": "",
      "email_invoice": [
        "billing@example.com"
      ],
      "doc_wiva": "1",
      "inv_total": "1081.00",
      "total_no_iva": "1000.00",
      "iva_total": "81.00",
      "inv_total_main_currency": "1081.00",
      "rows": [
        {
          "id_invoice": "100001",
          "description": "Prestazione",
          "ordering": "1",
          "qt_accounting": "1",
          "total_row": "1000.00",
          "acct_code": "3200",
          "cc_code": "",
          "iva_row": "8.1",
          "discount_real": "0",
          "discount_row": "0",
          "id_pr": "0",
          "id_se": "0"
        }
      ]
    }
  ]
}

4.2 cinvoices - Partite/documenti fornitori

Campo	Tipo	Presenza	Descrizione
id_invoice	string	Sì	ID esterno documento
num_invoice	string	Sì	Numero documento
date_invoice	date	Sì	Data documento
currency	string	Sì	Valuta
inv_exch_rate	decimal/string	Sì	Cambio
nr_customer	string	Sì	Numero fornitore; può essere vuoto nel flusso di risoluzione/creazione fornitore
acct_code	string	Sì	Conto contabile
payment_condition_code	string	No	Condizione pagamento
due_date	date	No	Scadenza
date_expiration	date	No	Scadenza alternativa; se presente prevale
qrcode	string	Sì	Contenuto QR se disponibile

qr_iban	string	Sì	QR-IBAN se disponibile
company/name/surname	string	No	Dati anagrafici fornitore
adresse/cap/location/cust_country_code	string	No	Indirizzo e paese
vat_number	string	No	Numero IVA
tax_id	string	No	Identificativo fiscale
cf_acct_vendor_bank_name	string	No	Nome banca
cf_acct_vendor_bank_zip	string	No	CAP banca
cf_acct_vendor_bank_city	string	No	Località banca
cf_acct_vendor_bank_post_account	string	No	Conto postale
cf_acct_vendor_bank_pvbr_code	string	No	Codice PVBR
cf_acct_vendor_bank_iban	string	No	IBAN
cf_acct_vendor_bank_bic	string	No	BIC
vendor_num	string	Sì	Numero/riferimento fornitore
action	string	Sì	Azione richiesta
is_iva	string	Sì	Indicatore IVA
id_bank	string	Sì	Identificativo banca
doc_wiva	string	Sì	1 = importi IVA inclusa
inv_total	decimal/string	Sì	Totale documento
total_no_iva	decimal/string	Sì	Totale imponibile
iva_total	decimal/string	Sì	Totale IVA
inv_total_main_currency	decimal/string	Sì	Totale in valuta base
rows	array	Sì	Righe documento

Righe cinvoices.rows

Campo	Tipo	Presenza	Descrizione
id_invoice	string	Sì	ID documento
description	string	Sì	Descrizione
ordering	string	Sì	Ordinamento
qt_accounting	decimal/string	Sì	Quantità contabile
total_row	decimal/string	Sì	Totale riga
acct_code	string	Sì	Conto contabile
cc_code	string	Sì	Centro di costo
iva_row	decimal/string	Sì	Percentuale IVA numerica della riga (es. 8.1, 2.6, 0). Non inviare il codice IVA interno del sistema contabile; la relativa conversione è gestita da OB1.
only_vat	string	Sì	Indicatore sola IVA
id_pr	string	Sì	ID prodotto; 0 se non applicabile
id_se	string	Sì	ID servizio; 0 se non applicabile

{
  "cinvoices": [
    {
      "id_invoice": "200001",
      "num_invoice": "RE-2026-7845",
      "date_invoice": "2026-09-20",
      "due_date": "2026-10-20",
      "currency": "CHF",
      "inv_exch_rate": "1",
      "nr_customer": "250",
      "acct_code": "2000",
      "payment_condition_code": "30",
      "qrcode": "",
      "qr_iban": "",
      "company": "Fornitore SA",
      "name": "",
      "surname": "",
      "adresse": "Via Fornitore 20",
      "cap": "6900",
      "location": "Lugano",
      "cust_country_code": "CH",
      "vat_number": "",
      "tax_id": "",
      "cf_acct_vendor_bank_name": "Banca Esempio",
      "cf_acct_vendor_bank_zip": "6900",
      "cf_acct_vendor_bank_city": "Lugano",
      "cf_acct_vendor_bank_post_account": "",
      "cf_acct_vendor_bank_pvbr_code": "",
      "cf_acct_vendor_bank_iban": "",
      "cf_acct_vendor_bank_bic": "",
      "vendor_num": "",
      "action": "CU",
      "is_iva": "1",
      "id_bank": "",
      "doc_wiva": "1",
      "inv_total": "2162.00",
      "total_no_iva": "2000.00",
      "iva_total": "162.00",
      "inv_total_main_currency": "2162.00",
      "rows": [
        {
          "id_invoice": "200001",
          "description": "Acquisto materiale",
          "ordering": "1",
          "qt_accounting": "1",
          "total_row": "2000.00",
          "acct_code": "4200",
          "cc_code": "100",
          "iva_row": "8.1",
          "only_vat": "0",
          "id_pr": "0",
          "id_se": "0"
        }
      ]
    }
  ]
}

4.3 creditnotes e ccreditnotes

Le note di credito seguono lo stesso principio delle fatture. Per i clienti la chiave documento è id_cn / num_cn e i totali sono cn_total e cn_total_main_currency. Per i fornitori ccreditnotes supporta inoltre i dati fiscali e bancari analoghi a cinvoices, compreso cf_acct_vendor_bank_bic. Le righe utilizzano la stessa struttura contabile di base.

4.4 Cancellazioni

Le collection *_deleted trasmettono la cancellazione di un oggetto già sincronizzato. Per anagrafiche e documenti il modello base è:

{
  "invoices_deleted": [
    {
      "id": "100001",
      "action": "D"
    }
  ]
}

Per financial_transactions_deleted sono presenti id, type e action. Per payments_deleted sono presenti id_invoice, id e action.

5. financial_transactions - Giornale Dare/Avere

Campo	Tipo	Presenza	Descrizione
id	string	Sì	ID esterno registrazione
type	string	Sì	Tipo registrazione
action	string	Sì	Azione
text	string	Sì	Testo registrazione
date	date	Sì	Data registrazione
currency_rate	decimal/string	No	Cambio generale; se assente può essere ricavato dalle righe
debits	array	Sì	Righe Dare
credits	array	Sì	Righe Avere

Righe debits[] / credits[]

Campo	Tipo	Presenza	Descrizione
date	date	Sì	Data riga
text	string	Sì	Testo riga
amount	decimal/string	Sì	Importo in valuta riga
acct_code	string	Sì	Conto contabile
currency	string	Sì	Valuta
vat_perc	decimal/string	Sì	Percentuale IVA numerica della riga contabile (es. 8.1, 2.6, 0). Non inviare il codice IVA interno del sistema contabile; la conversione è gestita da OB1.
amount_base	decimal/string	No	Importo in valuta base
doc_wiva	string	Sì	Indicatore IVA inclusa

{
  "financial_transactions": [
    {
      "id": "FT-2026-000125",
      "type": "GL",
      "action": "CU",
      "text": "Registrazione contabile",
      "date": "2026-09-30",
      "currency_rate": "1",
      "debits": [
        {
          "date": "2026-09-30",
          "text": "Costo materiale",
          "amount": "1000.00",
          "acct_code": "4200",
          "currency": "CHF",
          "vat_perc": "8.1",
          "amount_base": "1000.00",
          "doc_wiva": "0"
        }
      ],
      "credits": [
        {
          "date": "2026-09-30",
          "text": "Contropartita",
          "amount": "1000.00",
          "acct_code": "2000",
          "currency": "CHF",
          "vat_perc": "",
          "amount_base": "1000.00",
          "doc_wiva": "0"
        }
      ]
    }
  ]
}

6. payments - Incassi ricevuti tramite GET

Campo	Tipo	Presenza	Descrizione
VoucherNbr	string	Sì	Numero voucher
id_payment	string/integer	Sì	ID esterno pagamento; se 0 OB1 può assegnare una sequenza
VoucherDate	date	Sì	Data
ClientNbr	string	Sì	Numero cliente
Currency	string	Sì	Valuta
CurrencyRate	decimal/string	Sì	Cambio
TotalBc	decimal/string	Sì	Importo
TotalMc	decimal/string	Sì	Importo valuta principale
VoucherText	string	Sì	Testo
VoucherType	string	Sì	Tipo voucher
CounterAccountCode	string	Sì	Conto contropartita
PaymentType	string	No	Tipo pagamento
Company	string	No	Ragione sociale

7. POST - Esito elaborazione

Regola IVA. Nei campi iva_row e vat_perc il Trading Partner deve trasmettere la percentuale IVA numerica, ad esempio 8.1, 2.6 oppure 0. Non deve trasmettere i codici IVA interni di sistema contabile: la conversione verso tali codici è gestita dalla mappatura configurata in OB1. Dopo l’elaborazione, OB1 invia al Trading Partner un JSON di esito. In questa integrazione l’identificativo esterno è id_teleutias. La struttura data può contenere le stesse collection gestite dalla GET.

{
  "data": {
    "invoices": [
      {
        "id_accounting": "F20260000125",
        "id_teleutias": "100001",
        "ok": true,
        "message": "",
        "total": "1081.00",
        "voucher_acct": "125"
      }
    ],
    "cinvoices": [
      {
        "id_accounting": "A20260000200",
        "id_teleutias": "200001",
        "ok": true,
        "message": "",
        "total": "2162.00",
        "voucher_acct": "200"
      }
    ],
    "financial_transactions": [
      {
        "id_accounting": "FT2026000125",
        "id_teleutias": "FT-2026-000125",
        "ok": true,
        "message": "",
        "total": "1000.00",
        "type": "GL",
        "voucher_acct": "300"
      }
    ]
  }
}

Campo	Descrizione
id_accounting	Identificativo assegnato/gestito dal sistema contabile.
id_teleutias	Identificativo univoco esterno dell’oggetto ricevuto. Viene restituito da OB1 per correlare l’esito al record originario.
ok	Esito elaborazione.
message	Messaggio di elaborazione/errore.
total	Totale, per gli oggetti che lo prevedono.
voucher_acct	Voucher contabile, per gli oggetti che lo prevedono.
type	Tipo, per financial_transactions.

8. POST - Piano dei conti e Centri di costo

OB1 invia il Piano dei conti completo e i Centri di costo. Questo flusso corrisponde all’AccountStructure richiesto dal Trading Partner.

{
  "data": {
    "accounts": [
      {
        "id_ow": "95",
        "AccCode": "1100",
        "DescrIt": "Debitori",
        "DescrEn": "Accounts receivable",
        "DescrDe": "Debitoren",
        "DescrFr": "Débiteurs",
        "Class": "1100",
        "Type": "0",
        "Currency": "CHF"
      }
    ],
    "costcenters": [
      {
        "id_ow": "95",
        "Code": "100",
        "DescrIt": "Amministrazione",
        "DescrEn": "Administration",
        "DescrDe": "Verwaltung",
        "DescrFr": "Administration",
        "Type": "1"
      }
    ]
  }
}

accounts[]

Campo	Descrizione
id_ow	ID mandante
AccCode	Codice conto
DescrIt	Descrizione italiana
DescrEn	Descrizione inglese
DescrDe	Descrizione tedesca
DescrFr	Descrizione francese
Class	Classe
Type	Tipo
Currency	Valuta

costcenters[]

Campo	Descrizione
id_ow	ID mandante
Code	Codice centro di costo
DescrIt	Descrizione italiana
DescrEn	Descrizione inglese
DescrDe	Descrizione tedesca
DescrFr	Descrizione francese
Type	Tipo

Nota: I nomi dei campi JSON sono case-sensitive. Le descrizioni multilingua utilizzano uniformemente DescrIt, DescrEn, DescrDe e DescrFr.

9. POST - Incassi clienti e Pagamenti fornitori

{
  "data": {
    "client_payments": [
      {
        "id_ow": "95",
        "VoucherNbr": "15025",
        "VoucherDate": "2026-09-30",
        "ClientNbr": "1001",
        "Currency": "CHF",
        "CurrencyRate": 1,
        "TotalBc": 1081.0,
        "TotalMc": 1081.0,
        "VoucherText": "Incasso fattura 2026-00125",
        "VoucherType": "Z",
        "CounterAccountCode": "1020",
        "HeaderId": "12345",
        "PaidHeaderId": "98765",
        "IdAdjustement": "0",
        "DocumentType": "I"
      }
    ],
    "vendor_payments": [
      {
        "id_ow": "95",
        "VoucherNbr": "16020",
        "VoucherDate": "2026-09-30",
        "supplierNbr": "250",
        "Currency": "CHF",
        "CurrencyRate": 1,
        "TotalBc": 2162.0,
        "TotalMc": 2162.0,
        "VoucherText": "Pagamento fattura RE-2026-7845",
        "VoucherType": "Z",
        "CounterAccountCode": "1020",
        "HeaderId": "22345",
        "PaidHeaderId": "88765",
        "IdAdjustement": "0",
        "DocumentType": "I"
      }
    ]
  }
}

Campo	Descrizione
id_ow	ID mandante
VoucherNbr	Numero voucher
VoucherDate	Data voucher
ClientNbr / supplierNbr	Cliente o fornitore
Currency	Valuta
CurrencyRate	Cambio
TotalBc	Importo BC
TotalMc	Importo MC
VoucherText	Testo voucher
VoucherType	Tipo voucher
CounterAccountCode	Conto contropartita
HeaderId	ID testata
PaidHeaderId	ID documento pagato
IdAdjustement	ID rettifica/compensazione
DocumentType	Tipo documento collegato; I = invoice, C = credit note

10. Regole HTTP e sincronizzazione

• La GET è eseguita da OB1 verso il servizio del Trading Partner; il Trading Partner non deve chiamare OB1 per ottenere i dati della GET.

• Il token è gestito dalla configurazione dell’integrazione. Nel profilo corrente viene trasmesso nella URL secondo l’endpoint concordato. Per installazioni che lo prevedono può essere concordato l’invio tramite intestazione HTTP dedicata, evitando l’esposizione del token nella query string. La modalità effettiva viene definita nella configurazione del collegamento.

• OB1 invia Accept: application/json.

• I POST standard inviano un body JSON. Nel connettore corrente il Content-Type dei POST standard è application/x-www-form-urlencoded (per incassi/pagamenti: application/x-www-form-urlencoded;charset=UTF-8). Il servizio del Trading Partner deve quindi accettare il body JSON con questo Content-Type.

• Per le date JSON si raccomanda il formato ISO YYYY-MM-DD, compatibile con il parser data utilizzato da OB1.

• I valori monetari/cambi possono essere trasmessi come rappresentazione numerica testuale con punto decimale; OB1 ne valida la convertibilità.

• Le collection non interessate possono essere omesse; quando presenti, devono essere array JSON.

• last-sync-datetime consente la sincronizzazione incrementale. Il valore sync-datetime restituito dal Trading Partner viene memorizzato da OB1 per la sincronizzazione successiva. Le date documento utilizzano il formato YYYY-MM-DD; sync-datetime è invece un timestamp tecnico del protocollo e utilizza il formato DD/MM/YYYY@HH:MM:SS.

11. Corrispondenza con i dati richiesti

Informazione	Contratto
Giornale completo Dare/Avere	financial_transactions
Partite aperte clienti	invoices
Partite aperte fornitori	cinvoices
Piano dei conti / AccountStructure	POST data.accounts
Centri di costo	POST data.costcenters
Incassi clienti	POST data.client_payments; GET payments se previsto dal flusso
Pagamenti fornitori	POST data.vendor_payments
Codici IVA	Non è richiesto un export dell’anagrafica IVA. Nei dati si trasmette la percentuale IVA numerica; la mappatura verso i codici IVA del sistema contabile è gestita in OB1.
Mandante	id_ow
Esercizi	first-date e last-date nella GET
Dati bancari fornitori	vendors e cinvoices: IBAN e altri dati banca; cinvoices supporta anche BIC e QR-IBAN.

12. Punto da confermare: “conti bancari”

Le strutture vendors e cinvoices coprono le coordinate bancarie del fornitore/documento (IBAN e dati banca; cinvoices anche BIC e QR-IBAN). Qualora per “conti bancari” si intendano invece i conti bancari propri del mandante, con relativo IBAN, valuta e conto contabile, tale informazione va definita separatamente.

13. Riepilogo implementativo per il Trading Partner

• Esporre l’endpoint GET configurato e filtrare i dati tramite id_ow, first-date, last-date e last-sync-datetime.

• Restituire JSON con ok/login e le collection pertinenti.

• Esporre l’endpoint POST configurato per ricevere gli esiti di elaborazione con id_teleutias.

• Accettare il POST del Piano dei conti/Centri di costo.

• Accettare il POST di incassi clienti/pagamenti fornitori.

• Mantenere i nomi dei campi e il case esattamente come specificato.

• Gestire gli array *_deleted per le cancellazioni quando utilizzati.