Guida
Changelog
XOX Group
Guida
Changelog
XOX Group

UPDATE/INSERT CLIENTI/UTENTI

Se è presente l'header AccessToken è possibile aggiornare soltanto l'anagrafica dell'utente loggato e soltanto l'utente loggato.

POST [baseUrl]/api/sync/v1/irs/update{?contactForm=true}

Il corpo della richiesta deve essere un array di oggetti in formato JSON, dove ogni oggetto rappresenta un'anagrafica (o evenetualmente un'attività CRM nel caso di chiamate API da moduli di contatto web)

Contact form WEB

Se nella chiamata viene passato il parametro contactForm con valore true, è prevista una gestione aggiuntiva per la gestione dei dati CRM e alcuni parametri sono dedicati solo a questa gestione o eventualmente ignorati (ved. colonne C.F. API - Only e C.F. API - Ignored)

I campi contrassegnati come C.F. API - Required sono obbligatori nelle chiamate API per i contact form Web

Per ogni modulo di contatto la configurazione dell'obbligatorietà dei campi può essere parametrizzata a livello applicativo su XOX, ma generalmente alcuni parametri sono sempre obbligatori (C.F. Required)

Clienti

Field Type Required C.F. API Default Description Notes
Ignored Only Required
ID int ✅ ❌ ❌ ❌ null ID del cliente Richiesto solo per gli update (non obbligatorio in caso di chiamate da contact form)
ExternalKey string ❌ ❌ ❌ ❌ null ID del cliente nella piattaforma esterna Per API contact form, la chiave esterna viene "costruita" dinamicamente secondo lo schema "EMail_Surname_Name"
FIDGroup int ✅ ✅ ❌ ❌ null Gruppo 1-Privati; 2-Azienda
TypologyIds int[] ✅ ✅ ❌ ❌ null Tipologia 1-Contatto; 2-Cliente; 3-Fornitore; 4-Commerciale; 5-Banca; 6-Corriere
Denomination string ❌ ❌ ❌ ❌ null Ragione sociale
Alias string ❌ ❌ ❌ ❌ null Alias
Vatnumber string ❌ ❌ ❌ ❌ null Partita IVA
Taxcode string ❌ ❌ ❌ ❌ null Codice fiscale
Surname string ❌ ❌ ❌ ✅ null Cognome
Name string ❌ ❌ ❌ ✅ null Nome
Address string ❌ ❌ ❌ ❌ null Indirizzo
City string ❌ ❌ ❌ ❌ null Città
Zip string ❌ ❌ ❌ ❌ null CAP
Province string ❌ ❌ ❌ ❌ null Provincia
Region string ❌ ❌ ❌ ❌ null Regione
Country string ❌ ❌ ❌ ❌ null Nazione
Destinations Destination[] ❌ ❌ ❌ ❌ null Destinazioni
Contacts Contact[] ❌ ❌ ❌ ❌ null Recapiti
Users User[] ✅ ❌ ❌ ❌ null Utenti Obbligatorio per gli update
SDICode string ❌ ❌ ❌ ❌ null Codice SDI per fatturazione elettronica
EMail string ❌ ❌ ✅ ✅ null E-mail cliente Gestita solo in chiamate contact form
CRMMessage string ❌ ❌ ✅ ❌ null Messaggio inviato dall'utente Gestita solo in chiamate contact form
WebReasonID int ❌ ❌ ✅ ✅ null ID Activity reason XOX Gestita solo in chiamate contact form - necessario per le configurazioni CRM di XOX
WebFormKey string ❌ ❌ ✅ ❌ null ID Contact form Gestita solo in chiamate contact form - da configurare su XOX - CONSIGLIATO
CRMTermsConditions bool ❌ ❌ ✅ ❌ null Consenso privacy (GDPR) Gestita solo in chiamate contact form - da configurare su XOX - CONSIGLIATO
CRMMarketingConsent bool ❌ ❌ ✅ ❌ null Consenso materiale marketing Gestita solo in chiamate contact form - da configurare su XOX - CONSIGLIATO
CRMPrivacyMarketing bool ❌ ❌ ✅ ❌ null Consenso privacy marketing Gestita solo in chiamate contact form - da configurare su XOX - CONSIGLIATO
BOPCode string ❌ ❌ ✅ ❌ null Referenza prodotto Gestita solo in chiamate contact form - tracciamento manifestazioni interesse su prodotti specifici (se contact form da pagina prodotto)
IdentityDocuments IdentityDocument[] ❌ ❌ ❌ ❌ null Documenti di identità

Destination

Field Type Required Default Description Notes
ID int ✅ null ID del cliente
ExternalKey string ❌ null ID della destinazione nella piattaforma esterna
FIDGroup int ✅ null Gruppo 1-Privati; 2-Azienda
TypologyIds int[] ✅ null Tipologia 1-Contatto;2-Cliente;3-Fornitore;4-Commerciale;5-Banca;6-Corriere;9-Destinazione
Denomination string ✅ null Ragione sociale
Alias string ✅ null Ragione sociale
Vatnumber string ❌ null Partita IVA
Taxcode string ❌ null Codice fiscale
Surname string ❌ null Cognome
Name string ❌ null Nome
Address string ❌ null Indirizzo
City string ❌ null Città
Zip string ❌ null CAP
Province string ❌ null Provincia
Region string ❌ null Regione
Country string ❌ null Nazione

Contact

Field Type Required Default Description Notes
ID int ✅ null ID del recapito
ExternalKey string ❌ null ID del contatto nella piattaforma esterna
FIDContactTypology int ❌ null ID tipologia recapito
  1. Telefono
  2. Email
  3. Web
  4. Pec
  5. Fax
  6. Cellulare
Default bool ❌ null Recapito predefinito
Value string ❌ null Recapito (telefono, fax, email ecc)
Remarks string ❌ null Note

IdentityDocument

Field Type Required Default Description Notes
ID int ✅ null ID del documento
ExternalKey string ❌ null ID del documento nella piattaforma esterna
FIDDocumentTypology int ✅ null ID tipologia documento
  1. Passaporto
  2. Carta d'identità
  3. Patente
Number string ❌ null Numero documento
ReleaseDate Date ❌ null Data di rilascio del documento
ExpirationDate Date ❌ null Data di scadenza del documento
Files File[] ❌ null File allegati al documento

File

Field Type Required Default Description Notes
Extension string ✅ null Estensione del file
FileName string ✅ null Nome del file
FileBase64 string ✅ null Contenuto del file in base64

User

Field Type Required Default Description Notes
ID int ✅ null ID dell'utente Richiesto solo per aggiornamenti
Username string ✅ null Username Richiesto solo per gli inserimenti. Se viene passato mentre si fa un'aggiornamento non viene preso in considerazione
Email string ✅ null Email Richiesto solo per gli inserimenti. Se viene passato mentre si fa un'aggiornamento non viene preso in considerazione
Password string ✅ null
ConfirmPassword string ✅ null Note Il valore deve essere uguale al valore del campo Password

Tipo response

Field Type Description Notes
Item1 int Id dell'anagrafica in xtra
Item2 string Chiave della piattaforma esterna
Item3 bool Esito della chiamata
Item4 ErrorMessage Messaggio nel caso in cui la chiamata non sia andata a buon fine
Item5 Dictionary<string, int?> Gli id delle destinazioni La chiave è l'id della piattaforma esterna oppure l'indice della destinazione nell'array della chiamata nel caso in cui non sia specificata la chiave esterna. Il valore è l'id della destinazione in XTRA
Item6 Dictionary<string, int?> Gli id dei contatti La chiave è l'id della piattaforma esterna oppure l'indice del contatto nell'array della chiamata nel caso in cui non sia specificata la chiave esterna. Il valore è l'id del contatto in XTRA

ERROR MESSAGE

Field Type Description Notes
Code string Codice dell'errore
  • ER.DOC.EXISTS - documento esistente
  • ER.DOC.RNOIMPORT - riga non importata
  • ER.DOC.UNERR - eccezione non gestita
  • ER.IR.INVAL - richiesta non valida
  • ER.IR.NOFOUND - anagrafica non trovata (se viene passato l'ID di xtra e non viene trovata nessuna anagrafica con l'id indicato)
  • ER.IR.EXISTS - anagrafica già trovata (se non viene passato l'id e viene passato il Code, ed esiste già un'anagrafica con il codice indicato)
  • ER.IR.INS - errore inserimento
  • ER.IR.UNERR - eccezione non gestita
Message string Messaggio dell'errore

Esempio richiesta (tramite doppia chiave)

sh
curl --location --request POST '[baseUrl]/api/sync/v1/irs/update?debug=true&contactForm=true' \
--header 'Content-Type: application/json' \
--header 'SyncPublicKey: {SyncPublicKey}' \
--header 'SyncSecretKey: {SyncSecretKey}' \
--data-raw '[{
    "EMail": "develop@art-soft.it",
    "Surname": "ArtsofT",
    "Name": "Test",
    "WebReasonID": 13,
    "Address": "Via Ariosto",
    "Country": "IT",
    "City": "VALENZA",
    "CRMMessage": "Richiesta informazioni per orologio Rolex Daytona",
    "CRMTermsConditions": true,
    "CRMMarketingConsent": true,
    "CRMPrivacyMarketing": true,
    "BOPCode": "M116680-0002"
}]'

Esempio richiesta inserimento documento di identità su anagrafica loggata

sh
curl --location --request POST '[baseUrl]/api/sync/v1/irs/update?debug=true' \
--header 'Content-Type: application/json' \
--header 'AccessToken: {{token}}' \
--data-raw '[{
    "ID": 59990,
    "IdentityDocuments": [
        {
            "Number": "1",
            "ExpirationDate": "2035-01-01",
            "ReleaseDate": "2024-05-12",
            "FIDDocumentTypology": 1,
            "Files": [
                {
                    "Extension": ".pdf",
                    "FileName": "ID.pdf",
                    "FileBase64": "base64file"
                }
            ]
        }
    ]
}]'

Esempio richiesta aggiornamento documento di identità su anagrafica loggata

sh
curl --location --request POST '[baseUrl]/api/sync/v1/irs/update?debug=true' \
--header 'Content-Type: application/json' \
--header 'AccessToken: {{token}}' \
--data-raw '[{
    "ID": 59990,
    "IdentityDocuments": [
        {
            "ID": 1,
            "Number": "1",
            "ExpirationDate": "2035-01-01",
            "ReleaseDate": "2024-05-12",
            "FIDDocumentTypology": 1,
            "Files": [
                {
                    "Extension": ".pdf",
                    "FileName": "ID.pdf",
                    "FileBase64": "base64file"
                }
            ]
        }
    ]
}]'

Esempio Risposta

JSON
{
    "statusCode": 200,
    "errorCode": null,
    "message": null,
    "result": {
        "totalCount": 1,
        "totalPages": 1,
        "page": 1,
        "count": 1,
        "records": [
            {
                "Item1": 33438,
                "Item2": "develop@artsoft.it_ArtsofT_Test",
                "Item3": true,
                "Item4": null,
                "Item5": {},
                "Item6": {
                    "0": 115209
                }
            }
        ],
        "record": null
    },
    "debug": {
        "requestTime": "2025-04-17 11:53:49",
        "responseTime": "2025-04-17 11:53:50",
        "duration": "00:00:00.7408426",
        "clientIP": "::1"
    }
}
IN QUESTA PAGINA