# Documentazione API e integrazioni OpenAPI | MerchandAise

- slug: developers-api-integrations
- locale: it-CH
- localeResolved: it-CH
- canonical: https://www.merchandaise.com/it-ch/developers/api-integrations

Esplora la documentazione API e le specifiche OpenAPI MerchandAise per merchandising personalizzato, community incorporate, fornitori e identità aziendale.

## Scegli la connessione adatta al progetto
Usa i riferimenti qui sotto per valutare endpoint, formati delle richieste e requisiti di autorizzazione. Le specifiche pubbliche servono alla pianificazione e alla generazione di client; l’accesso operativo dipende da API, account e ambiente.
Quando MerchandAise gestisce la transazione dell’acquirente, Hutter Products GmbH è il venditore contraente e Merchant of Record sotto il marchio MerchandAise. Identità e contatti dei fornitori restano privati salvo gli obblighi di comunicazione. La produzione richiede comunque l’approvazione della prova digitale, la conferma della producibilità, i controlli tecnici obbligatori e le approvazioni dei campioni applicabili all’ordine esatto accettato.

## API e superfici di integrazione
- **Documentazione API e OpenAPI:** Trova il riferimento API per gli strumenti degli assistenti e le sessioni di design, poi scegli il contratto per community, fornitori o aziende adatto al tuo processo. Human guide: Apri la documentazione degli strumenti dell'assistente (/api/docs). Machine-readable contract: OpenAPI JSON degli strumenti per assistenti (/api/docs/openapi.json). Accesso: Pubblico. Riferimento pubblico per le API degli assistenti e degli strumenti. L’accesso in produzione e le operazioni che influiscono sugli ordini richiedono comunque l’autorizzazione applicabile. Canonical page: /it-ch/developers/api-integrations. Canonical section: /it-ch/developers/api-integrations#api-docs.
- **API Community:** Collega il sito di un club o di una community alle informazioni pubbliche della community, all’invio dei design, ai voti e ai passaggi per l’approvazione degli ordini. Cosa comprende il contratto: Informazioni pubbliche della community, pubblicazioni di design e voti, pubblicazione delle inserzioni, ordini in attesa e approvazione o rifiuto da parte del responsabile della community. Un punto di partenza pratico: Leggi le informazioni pubbliche della community per il sito di un club. Individua poi le azioni che richiedono l’accesso di un membro o i permessi del responsabile prima di aggiungere l’invio dei design o passaggi al checkout. Accesso: La specifica è pubblica. Letture pubbliche, azioni dei membri e operazioni riservate al responsabile hanno requisiti di autorizzazione diversi; segui le regole di sicurezza di ciascun endpoint. Human guide: Esplora l’API Community (/it-ch/developers/api-integrations#community-integrations). Machine-readable contract: OpenAPI JSON della Community (/api/v1/community/public/openapi/v1). Accesso: Pubblico. Contratto pubblico con versione per negozi incorporati, ricerca di community e passaggi tra pagine che rispettano la lingua scelta. Canonical page: /it-ch/developers/api-integrations. Canonical section: /it-ch/developers/api-integrations#community-integrations.
- **API Fornitori:** Collega i sistemi dei fornitori approvati ai pacchetti di produzione rilasciati, allo stato di onboarding e ai processi con webhook ERP o PLM. Cosa comprende il contratto: Stato di onboarding dei fornitori, pacchetti di produzione rilasciati, download tracciati dei file, analisi, iscrizioni ai webhook e punti di sincronizzazione. Un punto di partenza pratico: Pianifica una connessione tra il tuo ERP o sistema di gestione del ciclo di vita del prodotto e il Centro fornitori. Verifica payload dei webhook, nuovi tentativi e stato di sincronizzazione prima di gestire un ordine assegnato. Accesso: Leggi la specifica OpenAPI senza accedere. Le richieste operative richiedono l’account fornitore e i permessi appropriati; la documentazione pubblica non iscrive un fornitore e non concede accesso ai dati di altri fornitori. Human guide: Esplora l’API Fornitori (/it-ch/developers/api-integrations#supplier-integrations). Machine-readable contract: OpenAPI JSON dei fornitori (/api/v1/supplier/openapi/v1). Accesso: Pubblico. Contratto pubblico per la pianificazione e la generazione di client. L’accesso operativo dei fornitori resta soggetto ad autorizzazione. Canonical page: /it-ch/developers/api-integrations. Canonical section: /it-ch/developers/api-integrations#supplier-integrations.
- **API Identità aziendale:** Collega gli spazi di lavoro aziendali approvati all’accesso unico, alla gestione di utenti e gruppi e ai registri di controllo dell’identità. Cosa comprende il contratto: Accesso unico OpenID Connect (OIDC), gestione del ciclo di vita di utenti e gruppi SCIM, rotazione dei token SCIM ed eventi di controllo del provisioning. Un punto di partenza pratico: Collega il tuo provider di identità allo spazio di lavoro approvato. Pianifica accesso, attivazione e disattivazione degli utenti, poi verifica associazioni dei gruppi e registri di controllo nell’ambiente di test concordato. Accesso: La specifica dell’identità aziendale è protetta. Contatta il team delle integrazioni per verificare spazio di lavoro e requisiti di accesso prima dell’implementazione. L’identità aziendale è facoltativa per i normali acquisti di prodotti. Human guide: Esplora l’identità aziendale (/it-ch/developers/api-integrations#enterprise-integrations). Machine-readable contract: OpenAPI JSON dell’identità aziendale (/api/v1/enterprise/identity/openapi/v1). Accesso: Protetto. Contratto protetto per spazi di lavoro aziendali approvati. Richiedi l’accesso prima di usare questo endpoint. Canonical page: /it-ch/developers/api-integrations. Canonical section: /it-ch/developers/api-integrations#enterprise-integrations.

## Scegli il contratto prima del codice
- **Step 1: Mappa il journey dell’utente:** Decidi chi entra nel processo e dove: un acquirente in uno storefront embedded, un fornitore approvato, un utente enterprise o un assistente che opera con autorizzazione esplicita.
- **Step 2: Conferma il confine di accesso:** Usa i contratti pubblici per valutazione e generazione client, quindi conferma credenziali, scope, ambienti, callback ed endpoint protetti prima dell’implementazione.
- **Step 3: Dimostra la continuità di stato:** Verifica che design, preventivi, approvazioni, errori e passaggi d’ordine rimangano aggiornati alla versione corrente attraverso l’integrazione, inclusi nuovi tentativi e percorsi di rollback.

## Cosa ogni integrazione deve preservare
- **Uno stato versionato:** Design, intento commerciale, preventivo supportato dal fornitore, approvazione e stato ordine restano connessi. Modifiche obsolete devono attivare un re-quote visibile o uno stato di revisione.
- **Riservatezza commerciale e del fornitore:** MerchandAise resta il referente commerciale verso l’acquirente e il referente supporto. Identità, contatti e dati interni del fornitore non sono esposti tramite integrazioni pubbliche.
- **Approvazione prima della produzione:** Una vista 3D non costituisce una prova fisica. Il preventivo confermato spiega le opzioni di campionatura disponibili, i costi, i limiti e i tempi. Prima della produzione in serie, approva la prova digitale esatta e completa i controlli tecnici obbligatori e le approvazioni dei campioni richiesti o scelti. I requisiti degli ordini già accettati restano vincolanti.

## Prima del traffico di produzione
Un file OpenAPI pubblicato è una base di pianificazione, non una promessa di accesso di produzione anonimo. Revisioniamo ambienti, credenziali, gestione dei guasti e responsabileship operativa prima del go-live.
- **Accesso e ambienti:** Conferma la versione del contratto, lo spazio di lavoro approvato, gli scope di autenticazione, sandbox, credenziali di produzione e le destinazioni di callback.
- **Guasto e ripristino:** Definisci nuovi tentativi, idempotenza, timeout, errori visibili al cliente, osservabilità, responsabileship del supporto e rollback prima del rilascio.
- **Evidenza end-to-end:** Verifica il percorso previsto in staging dall’entry e la mutazione dello stato fino a preventivo, approvazione, handoff e comportamento di recovery.

## Domande frequenti
- **Da quale API per il merchandising dovrei iniziare?:** Parti dalla persona e dal cambiamento di stato. Usa le community incorporate per i percorsi di acquisto di club e community, le operazioni dei fornitori per i processi dei fornitori approvati, l’identità aziendale per SSO e SCIM e gli strumenti per assistenti solo per processi IA esplicitamente autorizzati.
- **Un contratto pubblico concede accesso pubblico alla produzione?:** No. Un contratto OpenAPI pubblico serve alla ricerca, alla verifica dell’architettura e alla generazione di client. Credenziali di produzione, operazioni di scrittura, processi dei fornitori, identità aziendale ed esecuzione degli assistenti possono richiedere uno spazio di lavoro approvato e autorizzazioni limitate all’ambito previsto.
- **Un’integrazione può esporre i fornitori o saltare le approvazioni?:** No. Identità e contatti dei fornitori restano privati salvo gli obblighi di comunicazione. MerchandAise gestisce la relazione con l’acquirente; le azioni che influiscono sugli ordini devono mantenere i requisiti configurati di approvazione della prova digitale, dei controlli tecnici e dei campioni specifici dell’ordine.

## Portaci il processo, non un’architettura finita.
Dicci chi userà l’integrazione, quale stato deve leggere o modificare e dove vivrà l’esperienza. Mappiamo insieme contratto, modello di accesso e percorso di rollout più sicuro.
- **Pianifica un’integrazione:** /it-ch/contact?intent=api-integration-review
- **Scopri AI agents e MCP:** /it-ch/developers/ai-agents-mcp