Creazione Company (B2B)

🏢 Funzionalità di Creazione/Aggiornamento Company su Shopify

L'endpoint consente di creare o aggiornare una Company B2B su Shopify, inclusi contatti (company contact) e sedi (company location).

Logica di ricerca della company

Prima di creare o aggiornare, il sistema cerca la company già presente su Shopify:

Se è presente l'Id della company, viene effettuata una ricerca tramite Id Shopify (node(id: …)).
- Se la company esiste, il flusso prosegue con l'aggiornamento.
- Se non viene trovata, il flusso prosegue con la creazione.
Se l'Id non è valorizzato, la ricerca avviene tramite Reference (campo reference in input → externalId su Shopify).
- Filtro di ricerca: external_id:{reference}.
- Se la company esiste → aggiornamento; altrimenti → creazione.

💡 Nota: Il campo reference è obbligatorio in ogni richiesta (validazione ingress). Anche in presenza di id, reference deve essere valorizzato.

Validazione input

La validazione viene eseguita dall'adapter prima dell'invio a Shopify. In caso di errore il messaggio viene scartato con il relativo messaggio di validazione.

Campo	Regola
`reference`	Obbligatorio per ogni richiesta
`contacts[].email`	Obbligatorio per ogni contatto se la lista `contacts` è valorizzata
`contacts[].email`	Deve essere univoco all'interno della lista (confronto case-insensitive)
`contacts[].phone`	Se valorizzato, deve essere univoco all'interno della lista
`locations[].reference`	Obbligatorio per ogni location se la lista `locations` è valorizzata
`locations[].reference`	Deve essere univoco all'interno della lista (confronto case-insensitive)
`locations` (aggiornamento)	Se la lista è presente, non può essere un array vuoto (`[]`). Valori ammessi: `null` oppure uno o più oggetti

💡 Main contact: impostare isMainContact: true su un solo contatto della lista contacts.

Controlli sui contatti

Oltre alla validazione in ingresso, prima di creare o collegare un contatto il servizio verifica se esiste già un customer Shopify con la stessa email (o, se valorizzati entrambi, tramite id e email del contatto).

Situazione	Esito
Customer non presente su Shopify	Il contatto può essere creato
Customer esistente, non associato a nessuna company	Il contatto può essere collegato alla company
Customer già associato a un'altra company	Errore — sincronizzazione non consentita

Messaggio di errore:

The following contacts are already associated with another company: email1@example.com, email2@example.com.

Creazione e aggiornamento

L'endpoint crea o aggiorna la company, i contatti e le location in modalità upsert.

Company

Campi gestiti: reference, name, note. In aggiornamento, i campi omessi mantengono il valore già presente su Shopify.

Contatti

Corrispondenza con i contatti esistenti su Shopify (in ordine):

id del company contact (GID o valore numerico normalizzato)
email (confronto case-insensitive)

Esito	Azione
Non trovato	Creazione o collegamento del contatto
Trovato	Aggiornamento del contatto esistente
Presente su Shopify, assente in input	Eliminazione del contatto

Location

Corrispondenza con le location esistenti su Shopify (in ordine):

id della company location (GID o valore numerico normalizzato)
reference (mappata su externalId su Shopify)

Esito	Azione
Non trovata	Creazione della location
Trovata	Aggiornamento della location (dati anagrafici, configurazioni, esenzioni fiscali, indirizzi di spedizione e fatturazione)
Presente su Shopify, assente in input	Eliminazione della location

In aggiornamento location sono gestibili anche:

Esenzioni fiscali tramite configurations.taxExemptions
Indirizzi di spedizione (shippingAddress) e fatturazione (billingAddress)
Se isBillingSameAsShipping è true, l'indirizzo di fatturazione coincide con quello di spedizione

Configurazione destinazione

Configurare una destinazione Shopify e associarla al flusso, oltre alla configurazione base del flusso dati.

Campo	Valore	Note
`Destination Type`	Shopify
`Operation`	Sync company	`POST /egress/sync-company-to-shopify`
`GraphQL endpoint URL`	https://SHOPIFYURL.myshopify.com/	URL dell'endpoint GraphQL Admin API dello shop Shopify
`Admin API access token`	shpat_CODICEALFANUMERICO	Oppure `Client ID (API key)` + `Client secret` — vedi Autenticazione
`Client ID (API key)`	IL_TUO_CLIENT_ID
`Client secret`	IL_TUO_CLIENT_SECRET
`x-parallel-processes-number`	`1` (default)	Numero di worker paralleli per l'elaborazione bulk (minimo `1`)

Deprecato — configurazione precedente (HTTP Adapter)

Deprecato

La configurazione tramite HTTP Adapter con Base Url, Resource Path e header x-api-key nei Settings Override è deprecata. Utilizzare la destinazione Shopify descritta sopra.

Oltre alla configurazione base del flusso dati era necessario impostare nei Settings Override:

Campo	Valore	Note
`Base Url`	https://adapter.flowlyze.io	url degli adapter
`Resource Path`	api/adp/shopify/egress/sync-company-to-shopify	path dell'adapter per il flusso di sync company
`Headers` :: `x-api-key`	**********	api key di verifica per l'interazione con l'endpoint
`Headers` :: `x-shopify-access-token`	shpat_CODICEALFANUMERICO	secret della custom app creata per l'integrazione
`Headers` :: `x-shopify-graphql-url`	https://SHOPIFYURL.myshopify.com/	url dello shopify con cui connettersi
`Headers` :: `x-parallel-processes-number`	`1`	parallelismo elaborazione messaggi

Esempi messaggi di input

1. Creazione / aggiornamento company completa

{
  "reference": "ACME-001",
  "name": "Acme Corporation",
  "note": "Cliente B2B principale",
  "contacts": [
    {
      "isMainContact": true,
      "email": "mario.rossi@acme.com",
      "firstName": "Mario",
      "lastName": "Rossi",
      "phone": "+393401234567",
      "title": "Purchasing Manager"
    },
    {
      "email": "luisa.bianchi@acme.com",
      "firstName": "Luisa",
      "lastName": "Bianchi",
      "title": "Accounting"
    }
  ],
  "locations": [
    {
      "reference": "ACME-HQ-MILANO",
      "name": "Sede Milano",
      "phone": "+390212345678",
      "isBillingSameAsShipping": true,
      "shippingAddress": {
        "firstName": "Mario",
        "lastName": "Rossi",
        "street1": "Via Roma 1",
        "city": "Milano",
        "zip": "20100",
        "countryCode": "IT",
        "phone": "+393401234567"
      },
      "configurations": {
        "checkoutToDraft": false,
        "editableShippingAddress": true,
        "paymentTermsTemplateId": "gid://shopify/PaymentTermsTemplate/2",
        "taxExemptions": []
      }
    },
    {
      "reference": "ACME-WH-ROMA",
      "name": "Magazzino Roma",
      "isBillingSameAsShipping": false,
      "shippingAddress": {
        "street1": "Via Appia 100",
        "city": "Roma",
        "zip": "00100",
        "countryCode": "IT"
      },
      "billingAddress": {
        "street1": "Via del Corso 50",
        "city": "Roma",
        "zip": "00186",
        "countryCode": "IT"
      },
      "configurations": {
        "checkoutToDraft": false,
        "editableShippingAddress": true,
        "depositPercentage": 50,
        "paymentTermsTemplate": "Net 30",
        "taxExemptions": ["CA_BC_COMMERCIAL_FISHERY_EXEMPTION"]
      }
    }
  ]
}

Logica di ricerca della company​

Validazione input​

Controlli sui contatti​

Creazione e aggiornamento​

Company​

Contatti​

Location​

Configurazione destinazione​

Deprecato — configurazione precedente (HTTP Adapter)​

Esempi messaggi di input​

1. Creazione / aggiornamento company completa​