{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"31df0733-cf51-46b5-8189-326f69b365dc","name":"OTP Service Public IT API v1.1","description":"**OTP service** è un software SaaS rivolto a privati e aziende che devono proporre un documento da firmare a persone fisiche: clienti, collaboratori etc.\n\n## Compatibilità e URL\n\nL'API v1.1 è retrocompatibile con l'API v1 e pertanto le URL sono immutate.\n\nIl loro prefisso rimane `/api/v1/`\n\nQuando nella documentazione si fa riferimento ad una \"API deprecata\" si intende l'API v1 con i suoi parametri, che continuano a funzionare e sono automaticamente convertiti in parametri dell'API nuova.\n\n## Soggetti\n\nI soggetti coinvolti sono:\n\n- il _Proponente_: (il soggetto che vuole sottoporre a firma un documento, in genere è il cliente di OTP Service)\n    \n- uno o più firmatari (i clienti, collaboratori ecc. del proponente)\n    \n- OTP service come terzo soggetto in quanto fornitore dello strumento di firma.\n    \n\nNella sezione `Definizioni` si possono trovare maggiori dettagli.\n\n## Tipologie di firma\n\nGestiamo la firma elettronica semplice (FS) e la firma elettronica avanzata (FEA).\n\n### Firma elettronica semplice (FS)\n\nLa FS è adatta per gli scopi in cui la parte legale non è critica: quando si desidera sapere se e quando il firmatario riceve, legge e approva il documento. E' un processo molto veloce sia per il _Proponente_ che per il firmatario.\n\n### Firma elettronica avanzata (FEA)\n\nLa nostra soluzione soddisfa tutti i punti della normativa vigente (DPCM 22/02/2013 dall'articolo 55 al 63). Rispetto alla FS la FEA richiede di identificare ogni firmatario tramite il riconoscimento, richiedendo lo scatto delle foto, oppure di persona. Per fare questo è richiesto un quantitativo di dati maggiore (rispetto la FS) e nel caso si scelga il riconoscimento da remoto il processo si può concludere solo dopo che l'operatore del _Proponente_, tramite nostra interfaccia, validi i dati. Le pratiche successive alla prima sono veloci quanto la FS, fintanto che non si varia qualche dato anagrafico. In tal caso viene innescato una nuova sessione di riconoscimento, di persona o da remoto in base a chi ha modificato i dati, se il proponente o il firmatario.\n\n## Definizioni\n\nLa `pratica` è l'insieme delle informazioni per portare alla firma un documento.\n\nI `firmatari` sono le persone, inserite nella rubrica (viene fatto in automatico dopo la creazione della prima pratica). Questi dati possono essere modificati in qualsiasi momento e le modifiche saranno attive dalla successiva pratica.\n\nI `destinatari` della pratica sono firmatari ai quali verrà sottoposto il documento da firmare. In altre parole, sono \"cloni\" dei firmatari e sono immutabili nel tempo.\n\nIl `documento da firmare` è ciò che viene inviato ai destinatari ed è caricato dal _Proponente_.\n\nI `punti firma` definiscono le posizioni nel documento in cui i destinatari potranno apporre la firma. Per un dato destinatario un punto firma potrà essere obbligatorio, facoltativo o non dovrà poter essere firmato in quanto riservato ad altri destinatari.\n\nIl `documento firmato` è generato da otpservice.io alla conclusione del processo di firma. Sostanzialmente è il documento da firmare con in aggiunta il riepilogo del processo e l'apposizione del _sigillo elettronico_ di OTP service.\n\nVedi anche la sezione `Entità principali` nella quale viene data una descrizione più dettagliata.\n\n# Il processo\n\nIl processo cambia in base alla tipologia di firma e alle opzioni scelte.  \nLa tipologia di firma è stata già descritta, le opzioni verranno descritte nel paragrafo \"Configurazione del processo\". L'utilizzo via API nel rispettivo paragrafo. Di seguito descriviamo in modo sintetico gli step del processo.\n\n## Step 1 - Proponente\n\n1.A Il _Proponente_ prepara i requisiti per creare la pratica:\n\n- prepara in autonomia il documento che intende proporre ai firmatari, nel formato pdf (ad esempio: un documento word salvato in pdf)\n    \n- raccoglie i dati dei o del firmatario, la quantità varia in base alla tipologia di firma scelta: se FS sono pochi, se FEA sono molti di più e si può scegliere se anticiparli o lasciare che sia il firmatario ad inserirli e poi verranno verificati nella fase conclusiva durante il riconoscimento della persona.\n    \n\n1.B Il _Proponente_ crea la pratica con i dati dei/l firmatari/o e a seconda delle opzioni scelte, OTP Service avviserà ogni destinatario tramite email o tramite SMS.\n\nL'email conterrà:\n\n- presentazione del proponente (logo e colori) e istruzioni\n    \n- l'allegato col file pdf e l'hash con l'impronta (per poter verificare che si tratta dello stesso file prodotto)\n    \n- il link web alla pratica in modo che ogni firmatario possa procedere con la firma\n    \n\nIl SMS conterrà solo il link alla pagina di firma del documento che è comunque possibile leggere e scaricare prima della firma.\n\n## Step 2 - Firmatario\n\nIl firmatario riceve l'email con un evidente bottone per procedere oppure un SMS e cliccando sul link visualizzerà una landing page di presentazione e l'invito a proseguire.\n\nLa UI guida nel processo in base alla tipologia di firma scelta.\n\n## Step 3 - OTP Service\n\nOTP Service genera il pdf firmato, se l'opzione per la generazione è attiva altrimenti aspetta che sia il proponente a caricarlo con l'endpoint specifico.  \nIl documento firmato è solo un normale file pdf con una indicazione grafica e testuale dell'avvenuto processo e l'apposizione del sigillo elettronico di OTP Service. OTP service utilizza la sua impronta per calcolare l'hash che garantisce l'immutabilità del processo, in particolare:\n\n- il pdf originale prima di essere firmato\n    \n- il pdf firmato\n    \n- le azioni di ogni firmatario e i dati/recapiti utilizzati nel processo di firma\n    \n\nQuesto hash lo abbiamo chiamato \"Codice verifica firma\" che può essere inserito nella nostra UI (accessibile dalla pagina pubblica [https://app.otpservice.io/signature](https://app.otpservice.io/signature)) per consentire solo agli interessati di verificare il processo di firma ed eventualmente di scaricare il documento.\n\n# Configurazione del processo\n\nIl _Proponente_ che si è già registrato in OTP Service deve:\n\n1. Tramite UI entrare nel profilo -> organizzazione e verificare che il nome sia quello corretto (verificare che non sia rimasto quello di default).\n    \n2. Personalizzare con logo e colori per dare alle comunicazioni la propria impronta.\n    \n\nFacoltativamente, è possibile modificare le opzioni avanzate tramite UI. Le stesse è possibile sovrascriverle ad ogni creazione pratica (tranne sms_allowed) usando l'etichetta indicata:\n\n- `send_unsigned_document` Invio email iniziale con documento da firmare, se false potrà inviarla il _Proponente_ in autonomia. Lo stato della pratica rimane in \"just_created\". Se true, invece, lo stato della pratica assume \"notified\".\n    \n- `send_signed_document_by_email` Invio del documento firmato attraverso la email.\n    \n- `send_signed_document_by_sms` Invio del link per scaricare il documento firmato via SMS.\n    \n- ~~send_signed_document~~ Invio dell'email finale col documento firmato. Se false potrà occuparsene il _Proponente._ _**Deprecato.**_ _Usare gli attributi specifici per ogni modalità di invio._\n    \n- `duplicate_documents_allowed` Se true consente di caricare documenti con la stessa impronta, nel caso il proponente utilizzasse documenti generici. In caso contrario è meglio evitarlo per non commettere l'errore di inviare un documento già utilizzato.\n    \n- `sms_allowed` Di default è true in quanto la FEA lo richiede ma se interessa solo la FS ed è impostato a false, consente di bloccare l'utilizzo degli sms e ridurre così i costi per pratica.\n    \n\n# Interfaccia firmatario ed UUID destinatario\n\nQuando la pratica passa in stato \"Notificato\" (vedi la sezione degli stati) viene inviata un'email ai firmatari con istruzioni e link per iniziare il processo di firma. Quando il firmatario apre il link verrà avviata una sessione auto-autenticata dal token, un uuid con un periodo di validità legato alla pratica.\n\nIl link ha un path di questo tipo:\n\n```\napi.otpservice.io/sign/recipient/{{uuidRecipient}}\n\n ```\n\nIl parametro uuidRecipient presente nell'URL non è normalmente contenuto nelle risposte alle chiamate all'API in quanto i link alla pagina di firma vengono inviate direttamente da OTP Service al firmatario e pertanto il parametro non è rilevante per il proponente. Tuttavia, se un proponente volesse mandare in prima persona le mail o gli SMS con quei link, dovrà poter comporre l'URL. Per ricevere uuidRecipient nelle risposte JSON si deve farne richiesta all'assistenza (link Contattaci nel footer della web app). Con la funzionalità abilitata tutte le risposte dell'API aggiungeranno il parametro \"uuid\" ai dati dei recipient.\n\n# Modalità Embedded\n\nE' possibile includere la UI del firmatario all'interno del proprio gestionale o in una UI rivolta ai propri clienti. Per farlo è sufficiente passare il parametro `embedded`\n\n```\nhttps://app.otpservice.io/sign/recipient/{{uuidRecipient}}?embedded=true\n\n ```\n\nIl parametro uuidRecipient presente nell'URL va ricavato secondo le modalità descritte nella sezione precedente.\n\nLa modalità di inclusione è a discrezione dell'utilizzatore. Si può utilizzare un iframe o proporre il link a schermo pieno. In ogni caso è probabile che l'utilizzatore vorrà disabilitare le comunicazioni via SMS e via mail al firmatario, che conterrebbero i link privi di `?embedded=true` e che inoltre porterebbero alla pagina di firma standard e non a quella che include l'URL dell'embedded mode. Una pratica che non viene notificata ai firmatari resta in stato Nuovo / just_created ma è possibile firmarla.\n\nLa modalità embedded apporta delle variazioni al processo di navigazione, per adattarlo alle esigenze che tipicamente si hanno con l'inclusione nel proprio gestionale:\n\n- La landing della firma mostrata al firmatario viene omessa. E' una pagina di presentazione che non ha senso mostrare in un processo già avviato\n    \n- Per le pratiche di tipo \"Firma elettronica avanzata\" non mostriamo lo stepper in alto che riassume le tre sessioni di raccolta dati (condizioni FEA, form dati, scatto delle foto). Inoltre, lo step che mostra il form dati viene omesso nel caso tutti i dati siano presenti in quanto, tipicamente, sono raccolti dal sistema del proponente ed in questo modo evitiamo di essere ripetitivi.\n    \n- I messaggi conclusivi sono specifici per questa modalità\n    \n\nQuindi, come descritto, è possibile gestire anche le pratiche FEA. Ma come viene gestito l'esito negativo del riconoscimento? Premesso che nella sezione che descrive il riconoscimento si possono trovare maggiori dettagli, l'anomalia viene segnalata al firmatario che riceverà un link per tornare sulla pratica. Non è in modalità embedded per cui visualizzerà la UI completa e potrà quindi modificare i dati segnalati. Il proponente potrà ricevere le variazioni se attiverà le callback (vedi sezione callback del recipient).\n\nIn modalità embedded è disponibile un'ulteriore configurazione. Passando anche il parametro `sign_point_navigation`si può visualizzare il pulsante “Vai al prossimo punto di firma” presente nello stepper in modalità classica. La sintassi è\n\n```\nhttps://app.otpservice.io/sign/recipient/{{uuidRecipient}}?embedded=true&sign_point_navigation=true\n\n ```\n\nPer default nella modalità embedded quel pulsante è nascosto.\n\n# Entità principali\n\nL'entità principale è il `Customer`, la tua organizzazione, cliente di OTP Service.  \nIl `Dossier` è la pratica nella quale vengono \"congelati\" i dati anagrafici del `Signer` (firmatario) creando un clone, il `Recipient` (signer -> recipient) il quale rimane immutato nel tempo.\n\nQuando si crea un dossier, OTP Service verifica la presenza del signer e lo aggiorna o lo crea se è nuovo (ricercato da numero di telefono e/o email). Poi lo clona dando origine al recipient. Quindi, se l'anagrafica è nuova viene creato signer+recipient, altrimenti viene aggiornata (dipende dai parametri usati in fase di creazione) e creato il recipient.\n\n- Customer\n    \n    - Signers (rubrica dei firmatari)\n        \n    - Dossiers\n        \n        - Recipients (firmatari destinatari del documento della pratica)\n            \n        - Documents (unsigned_document o signed_document)\n            \n        - Emails (tutte le email inviate ai firmatari)\n            \n        - Sms (tutti gli SMS inviati)\n            \n\n# Processo tramite API\n\nIl processo può essere gestito da un sistema esterno tramite le API descritte in questa documentazione.  \nPotrebbe essere necessario l'accesso alla UI per poter modificare alcune configurazioni.  \nQuesti sono gli step tipici per svolgere la creazione di una pratica:\n\n1. Il customer (proponente) esegue l'autenticazione e ottiene il token da includere nel header per utilizzare gli endpoints\n    \n2. Chiama l'endpoint per la creazione del dossier\n    \n    1. Allega i dati di ogni firmatario\n        \n        - OTP service lo inserisce o lo modifica se esistente\n            \n        - Poi crea il destinatario dai dati del firmatario\n            \n    2. Allega il file del documento da firmare e l'elenco dei punti firma che possono avere valori assoluti o dinamici.\n        \n        - OTP Service verifica che il file del documento sia un pdf valido e non firmato precedentemente.\n            \n        - Verifica anche che i dati dei punti firma abbiano coordinate corrette, sia di forma che di integrità, ad esempio: che il numero della pagina indicato per il punto firma sia presente nel documento (si rimanda al paragrafo \"Come ottenere le coordinate dei punti firma\" della CREATE)\n            \n    3. Può specificare alcune opzioni facoltative (altrimenti verranno utilizzate quelle di default definite con la UI)\n        \n        - Per l'invio dell'email col documento da firmare a tutti i firmatari. In genere se ne occupa OTP Service ma il _Proponente_ può scegliere di farlo in autonomia.\n            \n        - Token per la gestione esterna della firma. In pratica è un link che viene costruito e proposto al firmatario al posto di quello normalmente previsto da OTP Service nei casi in cui il _Proponente_ desiderasse curare personalmente il processo anche per la parte visuale e appoggiarsi alle API di livello più basso per l'invio e la verifica dell'OTP.\n            \n        - Per la creazione del documento firmato, anche questo può crearlo il _Proponente_ e caricarlo via API (vedi endpoint \"Dossiers/ADD DOCUMENT\")\n            \n        - Per l'invio via email del documento _firmato_ a tutti i firmatari\n            \n3. Il processo prosegue fino alla conclusione in diverse modalità, relativamente alle opzioni scelte dal _Proponente_ e descritte nei precedenti punti.\n    \n\n**Firmatari interni ed esterni -** _**Deprecato**_\n\nOTP Service faceva distinzione tra firmatari interni ed esterni, rispettivamente quelli che fanno parte dell'organizzazione del proponente e tutti gli altri che tipicamente firmano i documenti nel ruolo di cliente. Questa distinzione è stata deprecata e non è più disponibile nell'interfaccia web per il proponente. Viene gestita tramite la possibilità o il divieto di firmare in un dato punto firma. La distinzione è ancora supportata dalle API in modo da non dover modificare i software di integrazione esistenti. Per le nuove implementazioni si raccomanda di usare il nuovo meccanismo dei permessi dei punti firma.\n\n# Callbacks (Webhooks)\n\nUna callback è una richiesta asincrona che OTP Service esegue in risposta ad un evento, per aggiornare un sistema esterno.\n\nGli eventi che eseguono una callback sono gli aggiornamenti allo stato della pratica e/o di ogni singolo destinatario. L'elenco completo degli degli stati è riportato nella tabella \"Stato del processo\" al termine di questa sezione.\n\nOTP Service effettua una chiamata con metodo `PUT` a un endpoint definito dal proponente. Per impostare l'UR dell'endpoint è necessario utilizzare la UI per gli admin (il campo \"Url callback cambio stato\" in modifica organizzazione) o scrivere al supporto. L'URL di callback sarà qualcosa del tipo\n\n`https://proponente.com/otpservice/callback`\n\nDopo aver impostato l'URL, le callback vanno richieste esplicitamente nelle richieste all'API valorizzando il parametro `callbacks` nel JSON dell'oggetto dossier e/o recipient. La sezione Dossiers CREATE contiene numerosi esempi in tal senso.\n\nPer associare la pratica di OTP Service al proprio sistema, il proponente può utilizzare due soluzioni\n\n1. Assegnare un proprio riferimento usando i seguenti campi:\n    \n    1. `customer_dossier_id`\n        \n    2. `customer_contract_hash`\n        \n2. Utilizzare l'uuid assegnato da OTP Service\n    \n\nQuando il proponente crea la pratica può inserire tra i parametri un proprio identificativo, scegliendo tra i due campi indicati sopra. In ogni caso, otpservice.io assegna un uuid univoco sia alla pratica che a ogni destinatario. Il proponente può tenere traccia di questi uuid per associare le callback alla pratica o al singolo destinatario. Anche in questo caso si suggerisce di far riferimento a Dossiers CREATE per gli esempi d'uso.\n\nLa callback eseguita da otpservice.io per i dossier avrà i seguenti parametri\n\n- `callback_object` -> `\"dossier\"`\n    \n- `callback_state` -> lo stato al momento dell'invocazione della chiamata\n    \n- `customer_dossier_id` -> l'eventuale id fornito dal proponente alla creazione della pratica\n    \n- `customer_contract_hash` -> l'eventuale hash (o uuid) fornito dal proponente alla creazione della pratica\n    \n- `uuid` -> l'uuid assegnato in automatico da OTP Service alla creazione della pratica\n    \n- `current_state` -> lo stato della pratica\n    \n\nLa callback per i recipient avrà i seguenti parametri\n\n- `callback_object` -> `\"recipient\"`\n    \n- `recipient_callback_state` -> lo stato al momento dell'invocazione della chiamata\n    \n- `recipient_uuid` -> uuid del destinatario che ha cambiato stato\n    \n- `recipient_current_state` -> lo stato del recipient\n    \n- `customer_dossier_id` -> l'eventuale id fornito dal proponente alla creazione della pratica\n    \n- `customer_contract_hash` -> l'eventuale hash (o uuid) fornito dal proponente alla creazione della pratica\n    \n- `dossier_uuid` -> uuid della pratica\n    \n- `dossier_current_state` -> lo stato della pratica\n    \n\nL'attributo `callback_state` indica lo stato della pratica (o del recipient) che ha fatto scattare la callback. L'attributo `current_state` invece indica lo stato corrente. Se la callback dovesse impiegare diversi secondi prima di essere eseguita, i due stati potrebbero non concidere. Mostrandoli entrambi si dà la facoltà di scegliere quale considerare.\n\nInoltre, a questi parametri ne verranno aggiunti altri in base allo stato o al tipo di evento (stato pratica o destinatario). Ad esempio: se una pratica è stata firmata il processo può fornire anche l'url del documento firmato, il codice per la verifica della firma ecc.\n\nNel dettaglio:\n\nDossier\n\n- `signed_document_url` -> L'url del documento firmato (presente a partire dallo stato `signed_document_loaded` del dossier in poi)\n    \n- `final_checksum` -> Il valore del \"Codice di verifica firma\".\n    \n\nRecipient\n\n- se di tipo \"FEA\" saranno aggiunti ai parametri della chiamata tutti i campi anagrafici che possono essere stati inseriti o modificati dal firmatario durante il processo di firma. In questo modo il proponente può mantenere aggiornato il proprio sistema.\n    \n\n**Esempi JSON callback**\n\nEsempio di parametri contenuti da una callback scaturita da un cambiamento di stato di un dossier:\n\n``` json\n{\"callback_object\":\"dossier\", \"callback_state\":\"signed\", \"customer_contract_hash\":\"b085520f-abe1-48f3-9587-6568af775223\", \"customer_dossier_id\":123, \"uuid\":\"3becb0e1-bbde-4918-a6d0-3d8e68f2f31f\", \"final_checksum\":\"0ea13b45552f7955e02dc5c463e961cc\", \"signed_document_url\":\"https://otpservice.io/.../a_signed_document.pdf\"}\n\n ```\n\nEsempio di parametri contenuti da una callback scaturita da un cambiamento di stato di un recipient:\n\n``` json\n{\"callback_object\":\"recipient\",\"customer_contract_hash\":\"b085520f-abe1-48f3-9587-6568af775216\",\"customer_dossier_id\":1,\"dossier_uuid\":\"26dfcb08-5baa-467a-8062-d1e1ca1b1900\",\"recipient_uuid\":\"f15a18db-f174-4a3e-a6ad-022773c960d8\",\"dossier_current_state\":\"signed\",\"recipient_current_state\":\"signed\",\"recipient_callback_state\":\"signed\"}\n\n ```\n\n**Tentativi callbacks**: se la callback fallisce viene ritentata altre tre volte con un delay calcolato con la seguente formula:\n\n`(retry_count ** 4) + 15 + rand(30)`\n\nIn pratica ritentata dopo:\n\n- tentativo 1 -> 16 secondi + una quantità casuale di secondi (da 0 a 30)\n    \n- tentativo 2 -> 31 secondi + una quantità casuale di secondi (da 0 a 30)\n    \n- tentativo 3 -> 96 secondi + una quantità casuale di secondi (da 0 a 30)\n    \n\n# Stati del processo\n\nI nomi da usare per indicare quali callback attivare sono indicati tra parentesi in inglese nelle prime due colonne della tabella che segue:\n\n| Pratica | Firmatario | Descrizione |\n| --- | --- | --- |\n| Bozza (draft) | Nuovo (just_created) | La pratica inizia in bozza da UI per poter creare i punti firma e da API se è stata creata con il parametro `\"state\": \"draft\"`  <br>Potrà essere modificata o eliminata. Per inviarla ai destinatari si dovrà effettuare una UPDATE con parametro `\"end_draft\": true` |\n| Nuovo (just_created) | \" | E' il primo stato se creata da API senza `\"state\": \"draft\"`. In questo stato non è più modificabile ed è il momento in cui viene addebitato il costo. |\n| Notificato (notified) | In notifica (notifying) | Se presente l'opzione, viene presa in carico la notifica del documento ad ogni destinatario della pratica |\n| \" | Notificato (notified) | Il server SMTP mittente comunica che il documento è stata inviato (ATTENZIONE non è uno stato definitivo e potrà essere rettificato in caso di errori) |\n| \" | Errore notifica (not_notifiable) | Quando si verifica un errore dopo l'invio, indirizzo inesistente o in risposta dal server smtp del ricevente |\n| \" | Visualizzato (viewed) | Quando un firmatario apre il suo link alla pratica |\n| In firma (signing) | Accettazione (accepting) | Quando il primo firmatario accetta il primo punto firma, la pratica progredisce in firma |\n| \" | Accettato (accepted) | Quando il firmatario ha accettato tutti i punti firma, la pratica rimane in firma |\n| \" | Convalida (validating) | Quando il firmatario ha inviato l'OTP per validare l'accettazione |\n| \" | Identificazione (identifying) | Quando il firmatario ha verificato l'OTP e validato l'accettazione ma è in corso il riconoscimento (solo FEA) |\n| \" | Firmato (signed) | Quando il firmatario ha verificato l'OTP e validato l'accettazione (FS e FEA per i firmatari già riconosciuti) |\n| Firmato (signed) | \" | Quando tutti i firmatari hanno firmato la pratica progredisce |\n| Contratto in generazione (generating_signed_document) | \" | Se presente l'opzione, viene generato il contratto pdf |\n| Contratto caricato (signed_document_loaded) | \" | Altrimenti deve essere caricato (pensato per uso da API) |\n| Contratto inviato (signed_document_sent) | Documento firmato in spedizione (sending_signed_document) | Se presente l'opzione, viene inviato il contratto firmato ad ogni firmatario. Viene inviata un'email distinta ad ogni firmatario e questo stato indica che è in preparazione. |\n| \" | Documento firmato inviato (signed_document_sent) | Il server smtp mittente comunica che il documento è stata inviato (ATTENZIONE non è uno stato definitivo e potrà essere rettificato in caso di errori) |\n| Completato (completed) | \" | Dopo la firma e l'invio del documento firmato a tutti, la pratica può considerarsi completata |\n| \" | Errore invio documento firmato (signed_document_not_sendable) | Quando si verifica un errore dopo l'invio, il tentativo per un nuovo invio è manuale |\n\nLa progressione degli stati è automatica in base ai dati, alle opzioni della pratica oppure si può attendere un'azione manuale specifica.  \nAd esempio: se si crea la pratica con l'opzione \"Invia documento da firmare\" lo stato del destinatario progredirà in automatico fino \"Notificato\" e ci rimarrà fino quando il firmatario aprirà il documento, inizierà l'accettazione ecc. Se invece l'opzione non è presente (perchè il proponente ha un proprio sistema di notifica), lo stato si fermerà a \"Nuovo\".\n\n# Esempio di server callback\n\nPer facilitare i test delle callback forniamo un semplice script Python 3 che ritorna 200 ad ogni chiamata ricevuta e mostra il request body a schermo. Il server deve essere accessibile via internet. Per gestire chiamate https deve essere posto dietro ad un reverse proxy che termini la connessione https prima di inviargliela.\n\n``` Python\nfrom http.server import BaseHTTPRequestHandler, HTTPServer\nclass SimpleHTTPRequestHandler(BaseHTTPRequestHandler):\n    def do_PUT(self):\n        return self.ok()\n    def do_POST(self):\n        return self.ok()\n    def ok(self):\n        print(self.rfile.read(int(self.headers.get('Content-Length', 0))).decode('utf-8'))\n        self.send_response(200)\n        self.send_header('Content-type', 'application/json')\n        self.end_headers()\n        self.wfile.write('{}'.encode('utf-8'))\nif __name__ == '__main__':\n    port = 9876\n    httpd = HTTPServer(('localhost', port), SimpleHTTPRequestHandler)\n    print(f'Starting httpd server on port {port}...')\n    httpd.serve_forever()\n\n ```\n\nPer verificarne il funzionamento, supponendo che un reverse proxy su `server.example.com` termini la connession https e la rediriga sulla porta 9876 dello stesso server\n\n```\ncurl -X POST https://server.example.com/otpservice-callbacks \\\n  --data-raw '{\"Hello\":\"World\"}'\n\n ```\n\n# Changelog\n\n_2024-11-30_\n\nDocumentato come mantenere una pratica nello stato `just_created` dopo la creazione ed inviarla in un secondo tempo con una PUT (Update).\n\n_2024-07-29_\n\nAggiunti i permessi punti firma. Rimossi i gruppi external / internal per recipient e punti firma.\n\n_2023-12-05_  \nAggiunta la possibilità di richiedere un ulteriore invio della OTP via SMS o via email.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"25768536","team":5903,"collectionId":"31df0733-cf51-46b5-8189-326f69b365dc","publishedId":"2sA3kPq4mN","public":true,"publicUrl":"https://documenter-api.postman.tech/view/25768536/2sA3kPq4mN","privateUrl":"https://go.postman.co/documentation/25768536-31df0733-cf51-46b5-8189-326f69b365dc","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.10.1","publishDate":"2024-07-15T15:33:36.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/5d6dac62cf90c6287a34e1cfb20d4e3aad5e757ce453addfde564f0828a84c77","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/2sA3kPq4mN"}