> ## Documentation Index > Fetch the complete documentation index at: https://docs.syrto.ai/llms.txt > Use this file to discover all available pages before exploring further. # Bundle aziende > Pura composizione dei cinque endpoint (45 crediti se separati). Prezzo: 25 crediti per record restituito; le voci notFound sono gratuite. Di sola lettura e idempotente: si usa POST solo perché la richiesta ha un corpo. Il metodo HTTP QUERY è il verbo preferito per questa operazione e verrà accettato sullo stesso percorso quando il supporto dei client sarà diffuso. ## OpenAPI ````yaml api-reference/openapi.standard.it.json POST /companies/bundle openapi: 3.1.0 info: title: Syrto API - endpoint standard version: 1.7.0 description: >- Dati finanziari, societari e di mercato sulle aziende italiane. Ogni chiamata risponde `200 { data, meta }`; `meta.usage.quantity` è quanto ha consumato la chiamata, in crediti, e `meta.warnings` elenca eventuali avvertenze non bloccanti (vuoto quando non ce ne sono). Ogni campo è sempre presente e i valori sconosciuti sono null. Le percentuali sono frazioni (0,15 = 15%). **Autenticazione.** Ogni chiamata richiede una chiave API, inviata come `Authorization: Bearer sk_...` su HTTPS - mai in un URL. Le chiavi sono legate alla tua organizzazione: gli admin le creano e le revocano nella dashboard Syrto (https://dashboard.syrto.ai/api-keys). Una chiave mancante o non riconosciuta è un 401 (`missing_api_key`, `invalid_api_key`); un 503 `auth_unavailable` significa che in questo momento non è stato possibile verificare la chiave, quindi riprova con backoff invece di ruotarla. **Base di addebito.** negativities, rna e structure addebitano una volta per persona giuridica: il record individuale e quello consolidato della stessa azienda contano una volta. Ogni altro endpoint addebita per record (o per chiamata), quindi individuale e consolidato contano separatamente. Un codice fiscale si risolve sempre in un solo record (`statementBasis`, individuale per impostazione predefinita): un'azienda viene addebitata due volte solo se vengono passati entrambi i suoi companyId. Una chiamata di mercato ha un prezzo per chiamata, qualunque sia la dimensione dell'insieme: omettere `filters` e `seedId`, o inviare `filters: {}`, significa tutta l'Italia, allo stesso prezzo. Le voci notFound non vengono mai addebitate, e nemmeno alcun errore. servers: - url: https://api.syrto.ai security: [] tags: - name: Company data description: Identità, indicatori di rischio, aiuti di Stato e sedi di aziende note. - name: Governance description: Proprietà, dirigenti, titolari effettivi e gruppo. - name: Financials description: Voci di bilancio, bilanci riclassificati, indici e grafico spider. - name: Composite description: Aziende comparabili. - name: Search description: Le aziende di un insieme filtrato, riga per riga. - name: Market description: Aggregati su un insieme filtrato. - name: Catalog description: Dati di riferimento gratuiti. paths: /companies/bundle: post: tags: - Company data summary: >- Panoramica, anagrafica, negatività, aiuti di Stato e sedi di fino a 20 aziende. description: >- Pura composizione dei cinque endpoint (45 crediti se separati). Prezzo: 25 crediti per record restituito; le voci notFound sono gratuite. Di sola lettura e idempotente: si usa POST solo perché la richiesta ha un corpo. Il metodo HTTP QUERY è il verbo preferito per questa operazione e verrà accettato sullo stesso percorso quando il supporto dei client sarà diffuso. operationId: company-bundle requestBody: required: true content: application/json: schema: type: object properties: ids: type: array items: type: string minLength: 1 maxLength: 100 minItems: 1 maxItems: 20 description: >- Da 1 a 20 riferimenti, ciascuno un companyId (id Syrto di un record di bilancio, inizia con `Zm86`) o un codice fiscale (partita IVA di 11 cifre o codice fiscale di 16 caratteri). Un codice fiscale si risolve nel record selezionato da `statementBasis`. I duplicati sono rifiutati. example: - '02579690039' - '03841740016' statementBasis: type: string enum: - individual - consolidated description: >- A quale bilancio si risolve un codice fiscale: `individual` (predefinito) è quello che l'azienda ha depositato per sé, `consolidated` quello del gruppo. I due possono differire di ordini di grandezza. Ignorato per un companyId, che indica già un record. year: type: integer minimum: 2015 maximum: 2100 description: >- Esercizio (2015-2100). Omesso: l'ultimo bilancio depositato. Gli anni previsionali non vengono mai restituiti. language: type: string enum: - it - en description: >- Lingua di nomi, etichette e descrizioni delle metriche (mai dei nomi dei campi o degli slug). Omessa: la lingua predefinita dell'account. required: - ids additionalProperties: false responses: '200': description: >- Panoramica, anagrafica, negatività, aiuti di Stato e sedi di fino a 20 aziende. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CompanyBundleBatch' meta: $ref: '#/components/schemas/ResponseMeta' required: - data - meta '401': description: missing_api_key | invalid_api_key content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: credits_exhausted | limit_reached content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: client_not_configured | not_entitled content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: unknown_endpoint | not_found content: application/json: schema: $ref: '#/components/schemas/Error' '413': description: payload_too_large content: application/json: schema: $ref: '#/components/schemas/Error' '415': description: unsupported_media_type content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: invalid_params content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: rate_limited headers: Retry-After: description: >- Secondi da attendere prima di riprovare. Né un 429 né un 504 vengono addebitati. Un 504 la cui query aveva raggiunto il servizio dati lo lascia in esecuzione, e la sua risposta viene messa in cache, quindi la stessa chiamata dopo questo intervallo è di solito veloce. schema: type: integer minimum: 0 content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: internal_error content: application/json: schema: $ref: '#/components/schemas/Error' '502': description: upstream_error content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: auth_unavailable | entitlement_unavailable content: application/json: schema: $ref: '#/components/schemas/Error' '504': description: upstream_timeout headers: Retry-After: description: >- Secondi da attendere prima di riprovare. Né un 429 né un 504 vengono addebitati. Un 504 la cui query aveva raggiunto il servizio dati lo lascia in esecuzione, e la sua risposta viene messa in cache, quindi la stessa chiamata dopo questo intervallo è di solito veloce. schema: type: integer minimum: 0 content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: CompanyBundleBatch: type: object properties: items: type: array items: $ref: '#/components/schemas/CompanyBundle' description: Voci risolte, nell'ordine di input. notFound: type: array items: $ref: '#/components/schemas/NotFoundEntry' required: - items - notFound ResponseMeta: type: object properties: requestId: type: string endpoint: type: string usage: $ref: '#/components/schemas/Usage' warnings: type: array items: $ref: '#/components/schemas/Warning' description: Vuoto quando non ce ne sono. required: - requestId - endpoint - usage - warnings Error: type: object properties: error: type: object properties: code: type: string enum: - missing_api_key - invalid_api_key - credits_exhausted - limit_reached - client_not_configured - not_entitled - unknown_endpoint - not_found - payload_too_large - unsupported_media_type - invalid_params - rate_limited - internal_error - upstream_error - auth_unavailable - entitlement_unavailable - upstream_timeout message: type: string requestId: type: string details: type: array items: type: object properties: path: type: string message: type: string required: - path - message required: - code - message - requestId required: - error CompanyBundle: type: object properties: overview: anyOf: - $ref: '#/components/schemas/CompanyOverview' - type: 'null' description: Null quando non c'è alcun bilancio depositato. anagraphic: $ref: '#/components/schemas/CompanyAnagraphic' negativities: $ref: '#/components/schemas/CompanyNegativities' rna: $ref: '#/components/schemas/CompanyRna' branches: $ref: '#/components/schemas/CompanyBranches' required: - overview - anagraphic - negativities - rna - branches description: >- I cinque endpoint sui dati aziendali per un record, senza campi aggiunti o rimossi. `branches` contiene le prime 100 sedi; `truncated` indica quando ce ne sono altre (l'endpoint delle sedi ne restituisce fino a 1000). NotFoundEntry: type: object properties: position: type: integer minimum: 0 description: Posizione nell'array `ids`. input: type: string reason: type: string enum: - not_found - no_filing_for_year - invalid_id required: - position - input - reason description: Un id che non è stato risolto. Mai addebitato. Usage: type: object properties: quantity: type: number unit: type: string required: - quantity - unit Warning: type: object properties: code: type: string message: type: string required: - code - message CompanyOverview: allOf: - $ref: '#/components/schemas/CompanyHeader' - type: object properties: year: type: integer description: Esercizio a cui si riferiscono i valori. financialStatementDate: type: - string - 'null' format: date description: >- Data del bilancio da cui provengono i valori: la data di chiusura dell'esercizio (31 dicembre per la maggior parte delle aziende, 30 giugno per un club con chiusura a giugno). Citala quando segnali una discrepanza. activityOverview: type: - string - 'null' description: Di cosa si occupa l'azienda. naceClass: type: - string - 'null' description: Classe NACE (4 cifre, es. 27.90). nuts3: type: - string - 'null' description: Provincia (NUTS 3) della sede legale. revenuesFromSalesAndServices: type: - number - 'null' description: Ricavi da vendite e prestazioni, EUR. ebitdaMargin: type: - number - 'null' description: 'EBITDA / ricavi. Frazione: 0,15 equivale al 15%.' ebitMargin: type: - number - 'null' description: 'EBIT / ricavi. Frazione: 0,15 equivale al 15%.' employeeCount: type: - integer - 'null' description: >- Spesso null, anche per le aziende grandi - non darlo mai per presente. revenueCagr3Years: type: - number - 'null' description: >- Tasso di crescita dei ricavi sugli ultimi tre esercizi depositati (due intervalli: radice quadrata di ricavi / ricavi di due anni prima - 1). Frazione: 0,15 equivale al 15%. required: - year - financialStatementDate - activityOverview - naceClass - nuts3 - revenuesFromSalesAndServices - ebitdaMargin - ebitMargin - employeeCount - revenueCagr3Years CompanyAnagraphic: allOf: - $ref: '#/components/schemas/CompanyHeader' - type: object properties: year: type: - integer - 'null' description: >- Esercizio a cui si riferiscono dimensione e dipendenti; null se non c'è alcun bilancio depositato. financialStatementDate: type: - string - 'null' format: date description: >- Data del bilancio da cui provengono i valori: la data di chiusura dell'esercizio (31 dicembre per la maggior parte delle aziende, 30 giugno per un club con chiusura a giugno). Citala quando segnali una discrepanza. vatNumber: type: - string - 'null' legalEntityType: type: - string - 'null' description: 'Forma giuridica: S.r.l., S.p.A., ...' naceSection: type: - string - 'null' description: Lettera A-U. naceDivision: type: - string - 'null' description: Due cifre. naceGroup: type: - string - 'null' description: es. 27.9 naceClass: type: - string - 'null' description: es. 27.90 naceSubclass: type: - string - 'null' description: Sottocategoria ATECO italiana, es. 27.90.01 activityOverview: type: - string - 'null' targetMarkets: type: array items: $ref: '#/components/schemas/TargetMarket' description: >- Ogni canale servito dall'azienda; un'azienda può servirne più di uno. targetMarketsDescription: type: - string - 'null' city: type: - string - 'null' nuts1: type: - string - 'null' nuts2: type: - string - 'null' nuts3: type: - string - 'null' lau: type: - string - 'null' description: Codice ISTAT del comune. countryCode: type: - string - 'null' description: ISO 3166-1 alpha-2. sizeClassification: anyOf: - $ref: '#/components/schemas/SizeBand' - type: 'null' description: >- Dimensione di QUESTO record di bilancio: una holding è di solito XS da sola e L consolidata. employeeCount: type: - integer - 'null' headcountEmployees: $ref: '#/components/schemas/Headcount' headcountContractors: $ref: '#/components/schemas/Headcount' foundingYear: type: - integer - 'null' incorporationDate: type: - string - 'null' format: date activityStartDate: type: - string - 'null' format: date websiteUrl: type: - string - 'null' contactEmails: type: array items: $ref: '#/components/schemas/TaggedContact' contactPhones: type: array items: $ref: '#/components/schemas/TaggedContact' socialMediaProfiles: type: array items: $ref: '#/components/schemas/SocialMediaProfile' pec: type: - string - 'null' description: >- Posta elettronica certificata (PEC) per le comunicazioni ufficiali. rea: type: - string - 'null' description: Numero di iscrizione al REA. cciaa: type: - string - 'null' description: Camera di commercio (CCIAA) di iscrizione. required: - year - financialStatementDate - vatNumber - legalEntityType - naceSection - naceDivision - naceGroup - naceClass - naceSubclass - activityOverview - targetMarkets - targetMarketsDescription - city - nuts1 - nuts2 - nuts3 - lau - countryCode - sizeClassification - employeeCount - headcountEmployees - headcountContractors - foundingYear - incorporationDate - activityStartDate - websiteUrl - contactEmails - contactPhones - socialMediaProfiles - pec - rea - cciaa CompanyNegativities: allOf: - $ref: '#/components/schemas/CompanyHeader' - type: object properties: protestsOfBill: type: - boolean - 'null' description: >- Protesti registrati. false significa che non risulta nulla, non che non ci sia rischio; null significa sconosciuto. insolvencyProceedings: type: - boolean - 'null' description: >- Procedure concorsuali in corso. false significa che non risulta nulla, non che non ci sia rischio; null significa sconosciuto. insolvencyApplications: type: - boolean - 'null' description: >- Istanze di fallimento presentate. false significa che non risulta nulla, non che non ci sia rischio; null significa sconosciuto. assetEncumbrances: type: - boolean - 'null' description: >- Gravami sui beni. false significa che non risulta nulla, non che non ci sia rischio; null significa sconosciuto. officersWithRiskIndicators: type: - boolean - 'null' description: >- Un esponente ha un indicatore di rischio registrato. false significa che non risulta nulla, non che non ci sia rischio; null significa sconosciuto. required: - protestsOfBill - insolvencyProceedings - insolvencyApplications - assetEncumbrances - officersWithRiskIndicators description: >- Solo booleani: date, importi e conteggi esistono solo nei documenti ufficiali a pagamento. CompanyRna: allOf: - $ref: '#/components/schemas/CompanyHeader' - type: object properties: count: type: - integer - 'null' description: Aiuti di Stato concessi registrati, di sempre, ogni regime. amount: type: - number - 'null' description: Aiuti di Stato ricevuti, di sempre, ogni regime. countLast36Months: type: - integer - 'null' amountLast36Months: type: - number - 'null' isAboveSectorMedianLast36Months: type: - boolean - 'null' sectorMedianAmount: type: - number - 'null' sectorMedianAmountLast36Months: type: - number - 'null' deMinimis: $ref: '#/components/schemas/DeMinimisSummary' required: - count - amount - countLast36Months - amountLast36Months - isAboveSectorMedianLast36Months - sectorMedianAmount - sectorMedianAmountLast36Months - deMinimis description: >- Aiuti di Stato (RNA). Cumulativi con una finestra mobile di 36 mesi, non per esercizio. CompanyBranches: type: object properties: companyId: type: string headquarters: anyOf: - $ref: '#/components/schemas/RegisteredAddress' - type: 'null' description: Sede legale. branches: type: array items: $ref: '#/components/schemas/RegisteredAddress' description: >- Sedi secondarie e unità locali ISCRITTE al Registro Imprese: la stessa persona giuridica a un altro indirizzo, mai le controllate. Vuoto significa nessuna iscritta, non una sede unica. branchesTotal: type: integer minimum: 0 truncated: type: boolean description: >- True quando `branches` si ferma prima di `branchesTotal` (più di 1000 sedi). required: - companyId - headquarters - branches - branchesTotal - truncated CompanyHeader: type: object properties: companyId: type: string description: >- Id Syrto di questo record di bilancio. Individuale e consolidato differiscono. legalName: type: - string - 'null' taxId: type: - string - 'null' description: Codice fiscale / partita IVA. consolidated: type: boolean description: >- Indica se questi valori provengono dal bilancio consolidato (di gruppo). required: - companyId - legalName - taxId - consolidated TargetMarket: type: string enum: - B2B - B2C - B2G - B2B2C - B2B2G - C2C - C2B - G2C - G2B SizeBand: type: string enum: - XS - S - M - L description: >- Classe dimensionale UE del record di bilancio (non del gruppo, salvo se consolidato). Headcount: type: object properties: value: type: - integer - 'null' updatedAt: type: - string - 'null' format: date required: - value - updatedAt TaggedContact: type: object properties: value: type: string tags: type: array items: type: string required: - value - tags SocialMediaProfile: type: object properties: platform: type: string url: type: string required: - platform - url DeMinimisSummary: type: object properties: amount: type: - number - 'null' description: Aiuti de minimis ricevuti, di sempre. amountLast36Months: type: - number - 'null' description: Aiuti de minimis negli ultimi 36 mesi (la finestra normativa). countLast36Months: type: - integer - 'null' ceiling: type: - number - 'null' description: >- Massimale normativo applicabile all'azienda (dipende dal suo settore). remaining: type: - number - 'null' description: Margine residuo prima del massimale. isAboveSectorMedian: type: - boolean - 'null' description: >- Importo de minimis degli ultimi 36 mesi sopra la mediana di settore (solo de minimis). sectorMedianAmountLast36Months: type: - number - 'null' required: - amount - amountLast36Months - countLast36Months - ceiling - remaining - isAboveSectorMedian - sectorMedianAmountLast36Months description: >- Capienza piena significa nessun de minimis ricevuto negli ultimi 36 mesi (amountLast36Months 0). RegisteredAddress: type: object properties: line1: type: - string - 'null' line2: type: - string - 'null' city: type: - string - 'null' postalCode: type: - string - 'null' countryCode: type: - string - 'null' nuts1: type: - string - 'null' nuts2: type: - string - 'null' nuts3: type: - string - 'null' lau: type: - string - 'null' required: - line1 - line2 - city - postalCode - countryCode - nuts1 - nuts2 - nuts3 - lau securitySchemes: bearerAuth: type: http scheme: bearer description: >- Chiave API di organizzazione WorkOS (sk_...), inviata come `Authorization: Bearer `. Gli admin creano e revocano le chiavi nella dashboard Syrto: https://dashboard.syrto.ai/api-keys ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.