Skip to main content
I documenti ufficiali sono i documenti che un registro pubblico rilascia per un’azienda: visure, bilanci depositati, statuti, certificazioni sui protesti. Sono PDF emessi dal registro, non dati elaborati da Syrto, e per questo costano crediti. Se ne occupano due strumenti:
Gli acquisti appartengono all’intera organizzazione, non a chi li ha effettuati. Un collega potrebbe aver già acquistato il documento che stai per comprare: syrto_list_official_documents è il modo per scoprirlo, e non costa crediti.

​
syrto_list_official_documents

Elenca i documenti camerali disponibili per un’azienda e recupera quelli già acquistati. Questo strumento non spende crediti documento ed è sicuro da chiamare ripetutamente. Risponde a tre domande in una volta sola: che cosa si può acquistare e a quanto, che cosa questa organizzazione ha già acquistato e quanti crediti restano. Usalo:
  • Prima di ogni acquisto. Fornisce lo slug, il costo da confermare con l’utente e gli eventuali dati aggiuntivi richiesti dal documento, come l’anno fiscale.
  • Per recuperare un documento già acquistato. I link di download scadono dopo circa 6 ore, e questo strumento li rigenera senza costo di crediti - quindi un link scaduto richiede questo strumento, mai un nuovo acquisto.
  • Per verificare se un collega lo ha già acquistato.

​
Argomenti

​
string
obbligatorio
L’ID aziendale da syrto_find_company. Funziona con entrambe le basi di bilancio - i documenti appartengono all’entità giuridica, quindi l’ID individuale e quello consolidato della stessa azienda restituiscono gli stessi documenti.
​
string
"en" per inglese (predefinito) o "it" per italiano.

​
Risposta

​
object
id (il company_id che hai passato), name, consolidated.
​
object[]
Ciascuno con:
  • slug - da passare a syrto_request_official_document
  • name - nome leggibile del documento
  • description
  • credit_cost - il prezzo da confermare con l’utente
  • inputs - i valori aggiuntivi richiesti da questo documento, ciascuno con key, label, required e kind (per esempio un YEAR per i bilanci depositati). Una lista vuota significa che non serve alcun dato aggiuntivo
​
object[]
Ciò che questa organizzazione ha già acquistato per questa azienda, dal più recente - slug, name, requested_at e un download_url valido per circa 6 ore da adesso.
​
object | null
Crediti available e reserved dell’organizzazione. available è ciò su cui attinge un acquisto ora; reserved è trattenuto da operazioni ancora in corso. Omesso quando la credenziale non ha un’organizzazione per cui l’API possa risolvere i crediti.
​
string
La regola di scadenza dei link, utile da riferire a chiunque riceva un link.

​
syrto_request_official_document

Acquista un documento camerale per un’azienda. Questo spende i crediti dell’organizzazione.

​
Prima di acquistare

  1. Chiama syrto_list_official_documents per lo slug, il credit_cost esatto e gli eventuali dati richiesti.
  2. Comunica all’utente il nome del documento e il suo costo in crediti, e ottieni il suo consenso esplicito a spenderli.
  3. Passa quel costo come expected_credit_cost. L’acquisto viene rifiutato se il prezzo corrente è diverso, il che intercetta un prezzo cambiato da quando hai letto il catalogo - non attesta che qualcuno lo abbia approvato, quindi il passo 2 resta indispensabile.
I controlli su duplicati e prezzo vengono eseguiti immediatamente prima dell’acquisto, non in modo atomico con esso. Intercettano un errore, non lo escludono: due acquisti dello stesso documento emessi nello stesso istante possono andare a buon fine entrambi.

​
Quando una ripetizione non costa nulla

Due meccanismi indipendenti determinano se una ripetizione viene addebitata:
  • L’API del registro deduplica un’intenzione di acquisto già inviata - stessa azienda, documento, anno e force_new - per 24 ore, restituendo il primo documento invece di addebitare di nuovo.
  • Separatamente, questo strumento rifiuta un documento che l’organizzazione possiede già, che quella finestra sia trascorsa o meno, a meno che force_new non sia true.
Quindi una ripetizione semplice resta protetta anche dopo 24 ore dalla seconda regola, mentre la ripetizione di un’intenzione che già portava force_new: true è protetta solo dalla prima, e acquista una seconda copia una volta trascorsa la finestra. Leggi il catalogo - che non costa nulla - prima di ripetere un acquisto forzato.

​
Timeout e ritentativi

La chiamata è sincrona e lenta: il registro produce il documento mentre la richiesta è aperta, cosa che di solito richiede secondi ma può richiedere diversi minuti. Se va in timeout o fallisce, richiamala con la stessa intenzione di acquisto - stessa azienda, documento, anno e force_new. La ripetizione restituisce il primo documento oppure segnala che l’organizzazione lo possiede già, con un link funzionante, e entro le 24 ore né l’una né l’altra è un secondo addebito. expected_credit_cost e language non fanno parte dell’intenzione, quindi se il prezzo è cambiato concorda la nuova cifra con l’utente e invia quella - resta lo stesso acquisto. Se la ripetizione segnala che la richiesta è ancora in elaborazione, attendi circa 30 secondi e richiama.

​
Argomenti

​
string
obbligatorio
L’azienda per cui acquistare il documento. Funziona con entrambe le basi di bilancio.
​
string
obbligatorio
Quale documento, da syrto_list_official_documents - per esempio "it.company.visura_ordinaria".
​
integer
obbligatorio
Il credit_cost di quel documento, come mostrato all’utente.
​
integer
L’anno fiscale, per i documenti i cui inputs lo richiedono - tipicamente i bilanci depositati.
​
boolean
Acquista un’altra copia di un documento già posseduto - incluso lo stesso documento per un anno diverso, l’unico caso che il controllo sui duplicati non riesce a distinguere. Addebita l’intero costo. Predefinito false.
​
string
"en" per inglese (predefinito) o "it" per italiano.

​
Risposta

​
object
id, name, consolidated.
​
object
slug, name, requested_at e download_url - valido per circa 6 ore. syrto_list_official_documents lo rigenera senza costo di crediti.
​
integer
Il prezzo di listino del documento al momento dell’acquisto. L’API del registro non riporta l’importo effettivamente addebitato, quindi questo è il prezzo quotato e non un addebito confermato.
​
boolean
true quando questa chiamata ha restituito un documento che l’organizzazione già possedeva, perché un acquisto identico nelle ultime 24 ore non viene addebitato due volte - questa chiamata non ha speso nulla.false non è la prova del contrario: è il valore normale di un acquisto reale, ed è anche ciò che producono due chiamate identiche simultanee.
​
string
La regola di scadenza dei link; riferiscila insieme al link.

​
Esempio

1. Leggere il catalogo (gratuito):
2. Acquistare quello concordato con l’utente: