Riferimento API

Documentazione REST API completa per la piattaforma VynCo Swiss Corporate Intelligence

SDK ufficiali

VynCo pubblica librerie client proprietarie per Python, TypeScript, Rust e .NET. Tutti gli SDK sono open source (Apache-2.0 o MIT) e mantenuti sincronizzati con l'ultima versione dell'API.

pip install vynco

npm install @vynco/sdk

cargo add vynco

dotnet add package VynCo

Autenticazione

Gli endpoint di scrittura richiedono un token Bearer nell'header Authorization; la maggior parte degli endpoint di lettura funziona non autenticata sul piano Free. Sono supportati due tipi di token:

curl "https://vynco.ch/api/v1/companies?search=Nestl%C3%A9" \
  -H "Authorization: Bearer vc_live_abc123..."

Header di risposta

Ogni risposta API include header di limite di velocità per gruppo e un ID di richiesta per supporto e tracciamento. Il registro completo per gruppo è esposto tramite questi header — nel corpo della risposta non sono presenti informazioni di utilizzo.

Aziende

Cerchi e recuperi record aziendali svizzeri arricchiti dal registro. Il dataset copre oltre 790'000 aziende attive — 41 campi per record inclusi dati di registro, indirizzo, geolocalizzazione, classificazione NOGA, flag di sanzioni e traduzioni.

Modifiche

Tracci le mutazioni del registro — modifiche di indirizzo, cambi di revisore, aumenti di capitale, aggiornamenti dei membri del consiglio. Le letture consumano il gruppo standard_read; vedere la sezione Limiti di velocità per le quote per piano.

Persone

Consulti persone fisiche e i loro mandati nel consiglio attraverso il registro. Le letture consumano il gruppo standard_read.

Dossier

Generi dossier IA ancorati a citazioni. L'LLM emette tag [[obl:...]] risolti contro il knowledge graph metodologico, in modo che ogni affermazione rimandi a un obbligo registrato o a una riga di evidenza. Disponibile nel piano Professional (gruppo methodology_read).

Analytics

Esegua analisi di machine learning sull'intero registro delle aziende svizzere — clustering, rilevazione di anomalie, analisi di coorte. Tutti gli endpoint analytics richiedono il piano Starter o superiore (gruppo analytics_read).

Relazioni

Navighi le strutture societarie madre/figlia. Le letture consumano il gruppo standard_read.

Notizie e rapporti

Recuperi notizie aziendali da SIX e fonti pubbliche, oltre ai rapporti finanziari annuali analizzati. Le letture consumano il gruppo standard_read.

Note e tag

Annoti le aziende con note e tag a livello di team. Le note supportano tipi (Nota, Annotazione, Valutazione, Flag) e controlli di privacy. I tag consentono categorizzazione e filtri personalizzati.

Note

Tag

Classificazione e fingerprint

Recuperi classificazioni di settore (gerarchia in stile GICS) e fingerprint aziendali calcolati con metriche chiave, categoria dimensionale e riepilogo di profilo.

Confronto

Confronti due o più aziende affiancate in una singola richiesta (da 2 a 10 aziende).

Watches e notifiche

Monitori le aziende per ricevere notifiche quando vengono rilevate modifiche del registro. La gestione delle watches e il recupero delle notifiche fanno parte del gruppo account.

Preferenze di notifica

Screening

Effettui lo screening di entità rispetto alle sanzioni SECO, OpenSanctions (liste PEP) ed entità regolamentate FINMA in un'unica richiesta. Restituisce un livello di rischio e tutti i riscontri abbinati.

Auditor Intelligence

Interroghi i dati di durata dei mandati di revisione attraverso il registro di commercio svizzero. Identifichi le aziende con lunga durata del mandato di revisione per l'analisi di rotazione ISS, oppure recuperi la cronologia completa delle nomine del revisore per un'azienda specifica. Questi endpoint sono pubblici e non richiedono autenticazione.

Eventi aziendali

Recuperi gli eventi storici di modifica per un'azienda inclusi cambi di revisore, modifiche di capitale, cambi di membri del consiglio e altro ancora. Gli eventi seguono la specifica CloudEvents e includono metadati di severità e categoria. Endpoint di lettura pubblico.

Ricerche salvate

Salvi i filtri di ricerca per il riutilizzo rapido e li pianifichi per l'esecuzione automatica con cadenza giornaliera, settimanale o mensile. Le ricerche pianificate generano notifiche quando vengono trovati nuovi risultati.

Titolare effettivo

Tracci l'intera catena dei titolari effettivi per qualsiasi azienda svizzera. L'endpoint risolve ricorsivamente le entità madri e restituisce le percentuali di proprietà a ogni livello. Le strutture di proprietà circolari vengono rilevate e contrassegnate automaticamente. Disponibile nel piano Professional (gruppo methodology_read).

Risk v2

Punteggio di rischio del team metodologia: posteriori Beta-Bernoulli a 9 fattori con priori allineati al FATF. Ciascun fattore espone il proprio prior, posteriore, peso e l'evidenza a supporto; il punteggio composito è il log-odds ponderato. Disponibile nel piano Professional (gruppo methodology_read).

Intelligenza IA

Endpoint con IA per la generazione di dossier di due diligence, la ricerca aziendale in linguaggio naturale e la valutazione del rischio multi-segnale. Gli endpoint di dossier e ricerca utilizzano inferenza LLM; il punteggio di rischio algoritmico è multi-fattoriale. La generazione IA è misurata contro il gruppo expensive_ai.

IA comparativa

Generi analisi comparative multi-azienda con IA con rilevazione di sovrapposizioni di consigli di amministrazione, punteggio di governance e posizionamento competitivo. Confronti fino a 10 aziende in un'unica richiesta. Misurato contro il gruppo expensive_ai.

Operazioni in blocco

Esegua operazioni su più entità contemporaneamente. Lo screening in blocco verifica più entità rispetto alle liste di sanzioni in un'unica richiesta. L'import CSV della watchlist consente di aggiungere aziende in blocco. L'export con selezione di campi consente di scegliere esattamente quali colonne includere nel download. Misurato contro il gruppo bulk (piano Enterprise).

Export in blocco

Invii job di export in blocco asincroni in formato NDJSON o CSV. Interroghi l'endpoint di stato del job fino al completamento dell'export, quindi recuperi i dati inline (fino a 10 MB). Supporta il filtraggio per cantone, stato e limiti di righe. Misurato contro il gruppo bulk.

PDF aziendale

Generi un profilo PDF scaricabile per qualsiasi azienda svizzera. Il documento include una panoramica del registro, la cronologia delle modifiche, la composizione del consiglio, i dettagli del revisore e gli indicatori di rischio. Selezioni quali sezioni includere tramite parametro di query.

Widget incorporabile

Incorpori schede di riepilogo aziendale in tempo reale su siti partner. Sono supportati due metodi di integrazione: un auto-loader JavaScript che esamina la pagina alla ricerca di attributi data-vynco-uid, oppure un'incorporazione iframe diretta. Entrambe le opzioni supportano i temi chiaro e scuro. Nessuna autenticazione richiesta per i widget pubblici.

<script src="https://vynco.ch/api/v1/widget/embed.js"></script>
<div data-vynco-uid="CHE-105.962.875"></div>

<iframe src="https://vynco.ch/api/v1/widget/company/CHE-105.962.875?theme=light&fields=name,canton,capital,status"
        width="400" height="200" frameborder="0"></iframe>

Rapporti di settore

Accedi a rapporti di intelligence di settore generati con IA con narrazione LLM, statistiche chiave, aziende di punta e analisi delle tendenze. I rapporti coprono i settori basati su GICS attraverso il registro svizzero. Elenchi i settori disponibili o recuperi un rapporto dettagliato per uno specifico settore. Misurato contro il gruppo expensive_ai.

Blog

Endpoint del blog pubblico per elencare e recuperare i post pubblicati. Nessuna autenticazione richiesta. Filtri per tag o recuperi un singolo post tramite slug.

Export

Esporti i dati aziendali come fogli Excel. Supporta export filtrati con selezione di campi personalizzabile. Disponibile nel piano Professional (gruppo bulk).

Specifica OpenAPI

La specifica OpenAPI 3.0 completa (oltre 140 endpoint) è disponibile per l'auto-scoperta, la generazione di SDK e l'integrazione con strumenti come Postman, Insomnia o Swagger UI. Per recuperare la specifica non è richiesta alcuna autenticazione.

curl "https://api.vynco.ch/api/v1/openapi.json"

Gestione

Endpoint per la gestione di team, chiavi API e utilizzo. Queste letture fanno parte del gruppo account e dispongono di un limite generoso per piano.

Team

Chiavi API

Utilizzo

Riferimento agli errori

Tutte le risposte di errore seguono il formato RFC 7807 Problem Details con struttura coerente su tutti gli endpoint. L'esempio sottostante mostra una risposta 429 Too Many Requests — la modalità di errore più comune nel modello di limite di velocità per gruppo.

HTTP/1.1 429 Too Many Requests
Retry-After: 3540
x-ratelimit-group: methodology_read
x-ratelimit-window: 1h
x-ratelimit-limit: 600
x-ratelimit-remaining: 0
x-ratelimit-reset: 3540
{
  "type": "https://api.vynco.ch/errors/rate-limit-exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded for the methodology_read group on the Professional tier (600/h). Honour the Retry-After header.",
  "instance": "/v1/dossiers/CHE-109.322.551",
  "group": "methodology_read",
  "window": "1h",
  "limit": 600,
  "retryAfterSeconds": 3540
}

Limiti di velocità

Le richieste API sono limitate in velocità per gruppo di endpoint, per piano. I limiti sono esposti tramite gli header di risposta x-ratelimit-* e si reimpostano alla fine di ogni finestra. Quando una richiesta supera il proprio bucket, l'API restituisce 429 Too Many Requests con un header Retry-After.

Related Articles