Strainovic IT

API Zefix: interrogare i dati del registro di commercio

Zefix è l’indice centrale delle ditte della Svizzera, gestito dall’Ufficio federale del registro di commercio (UFRC) presso l’Ufficio federale di giustizia. Oltre alla ricerca nel browser, Zefix esiste come interfaccia REST, la «Zefix PublicREST API». Con essa un’applicazione ottiene direttamente dal registro di commercio ditta, sede, forma giuridica, stato e scopo. Questa guida mostra accesso, interrogazioni e risposta, e quando il registro IDI è la scelta più semplice.

Svolgimento di un’interrogazione Zefix: la vostra applicazione chiede a Zefix PublicREST con nome utente e password un IDI o un nome e riceve i dati dal registro di commercioLa vostraapplicazioneIDI o nomedella dittaZefix PublicRESTAccesso connome utente epasswordRegistro dicommercioNome, sede,formagiuridica,stato, scopoLa vostraapplicazioneCompilare ilmodulo overificare ilclienteSvolgimento di un’interrogazione Zefix: la vostra applicazione chiede a Zefix PublicREST con nome utente e password un IDI o un nome e riceve i dati dal registro di commercioLa vostra applicazioneIDI o nome della dittaZefix PublicRESTAccesso con nome utente e passwordRegistro di commercioNome, sede, forma giuridica, stato,scopoLa vostra applicazioneCompilare il modulo o verificare ilcliente

Cosa fornisce l’API Zefix

L’interfaccia si trova sotto https://www.zefix.admin.ch/ZefixPublicREST. La descrizione degli endpoint è nell’interfaccia Swagger, leggibile da macchina come OpenAPI sotto /v3/api-docs. Gli endpoint principali:

  • GET /api/v1/company/uid/{id}: impresa per IDI
  • POST /api/v1/company/search: ricerca per nome, forma giuridica, sede o cantone
  • GET /api/v1/sogc/bydate/{date}: pubblicazioni di un giorno nel Foglio ufficiale svizzero di commercio (FUSC)
  • GET /api/v1/legalForm e GET /api/v1/community: elenchi delle forme giuridiche e dei comuni

I dati sono soggetti alla condizione «Open use», con l’obbligo di indicare la fonte.

Passo 1: richiedere l’accesso

Le interrogazioni sono gratuite ma richiedono un account. L’UFRC concede l’accesso su richiesta per e-mail a zefix@bj.admin.ch; come nome utente serve un indirizzo e-mail. L’autenticazione avviene con HTTP Basic Auth, cioè con nome utente e password a ogni richiesta. Ottenere le credenziali può richiedere alcuni giorni, quindi conviene chiederle per tempo.

Passo 2: cercare un’impresa per IDI

L’IDI va nel percorso senza punti né trattino:

curl -u "utente@example.ch:password" \
  https://www.zefix.admin.ch/ZefixPublicREST/api/v1/company/uid/CHE107721785

La risposta è un elenco, non un singolo oggetto. Se l’IDI non è nel registro di commercio, Zefix risponde 404.

Passo 3: cercare un’impresa per nome

La ricerca si aspetta l’inizio del nome della ditta, almeno tre caratteri, con * come carattere jolly:

{
  "name": "Esempio*",
  "canton": "TI",
  "activeOnly": true
}

Si comporta come la ricerca esatta sul sito di Zefix. activeOnly nasconde le imprese cancellate. I risultati arrivano in forma breve; i dati completi si ottengono poi con un’interrogazione per IDI.

Cosa contiene la risposta

  • name, uid, legalSeat (comune di sede) e canton
  • legalForm con il codice secondo eCH-0097
  • status: ACTIVE attiva, BEING_CANCELLED in liquidazione, CANCELLED cancellata, con deletionDate
  • purpose, lo scopo iscritto nel registro di commercio
  • address con via, numero civico, codice postale e località
  • capitalNominal e capitalCurrency per le società di capitali
  • sogcPub con le pubblicazioni FUSC e oldNames con i nomi precedenti
  • cantonalExcerptWeb, il link all’estratto del registro di commercio cantonale

Zefix o registro IDI?

Zefix conosce solo le imprese iscritte nel registro di commercio. Il registro IDI dell’Ufficio federale di statistica conosce ogni impresa con un IDI, anche ditte individuali e associazioni non iscritte, e mostra l’iscrizione nel registro IVA. La sua interrogazione pubblica non richiede un account.

Per sapere se un IDI inserito nel checkout è valido e l’impresa attiva basta quindi il registro IDI. Zefix conviene quando servono scopo, capitale, nomi precedenti o pubblicazioni. Come funziona la verifica tramite il registro IDI è spiegato nella guida verificare il numero IDI.

Insidie

  • Grafia dell’IDI: nel percorso senza separatori (CHE107721785), nella visualizzazione con (CHE-107.721.785). Normalizzare prima dell’interrogazione.
  • Elenco invece di oggetto: anche l’interrogazione per IDI restituisce un elenco.
  • Liquidazione: BEING_CANCELLED non è ancora cancellata, ma non è più un normale partner commerciale. La vostra applicazione deve decidere come trattarla.
  • Credenziali: nome utente e password restano sul server. Una chiamata dal browser le mostrerebbe a ogni visitatore.
  • Memorizzazione temporanea: i dati delle imprese cambiano di rado. Conservare le risposte per un po’ invece di interrogare a ogni pagina.

Pronto per il negozio

Per verificare gli IDI nel checkout WooCommerce non serve codice proprio: il mio plugin Controllo IDI verifica formato, cifra di controllo e stato nel registro IDI, senza account e senza chiave.

Tutte le guide