1. Home
2. Aiuto
3. Strumenti di gestione TLS
4. Lavoro manuale con l'API, con l'utilizzo dello strumento Postman

Lavoro manuale con l'API, con l'utilizzo dello strumento Postman

Se non vuoi integrare le nostre API nei tuoi processi esistenti o non sai dove integrarli, ti sarà utile questa guida all'invio delle richieste API tramite lo strumento Postman. Postman ti offre sia un ambiente pronto per l'invio delle richieste che le funzioni da noi preconfigurate, il che ti permette di utilizzare l'API dell'SSLmarket anche non conoscendo la programmazione e, conseguentemente, di risparmiare tempo.

L'integrazione dell'API dell'SSLmarket in altri ambienti ti offre il vantaggio di poter eseguire complessivamente le soluzioni. La soluzione descritta nelle istruzioni non potrà mai funzionare automaticamente: è manuale ma nonostante questo ti farà risparmiare tempo.

Installazione dell'applicazione Postman

Scarica dal sito web la versione adatta per il tuo desktop . L'applicazione Postman esiste anche in una versione web che però non è adatta al nostro scopo (non funziona).

La versione per Windows viene installata in modo tradizionale, mentre su Linux probabilmente troverai Postman nel pacchetto in formato snap. Digitare nel terminale:

sudo snap install postman

Impostazioni dell'applicazione per l'SSLmarket

Per rendere molto più semplice il lavoro con l'API e con il programma, abbiamo predisposto una "raccolta" di chiamate in file JSON: è sufficiente importare il file per avere subito a disposizione tutte le funzioni. Importa la raccolta (pulsante "Import" in alto a sinistra), quindi seleziona file JSON, che abbiamo predisposto. Nella cartella Collections sono presenti la voce SSLmarket e dieci funzioni. Clicca con il pulsante destro sulla raccolta dell'SSLmarket e imposta le variabili in "Edit → Variables".

La cosa più importante è impostare la variabile X-Auth-Token con il valore del conto utente. Di sicuro riuscirai ad attribuire logicamente i valori corretti alle altre variabili, tuttavia ne troverai più avanti una panoramica.

Significato dei campi dati

• X-Auth-Token – campo in cui inserire la chiave API
• owner_### - dati specificativi del futuro proprietario del certificato
• auth_### - dati della persona di contatto per l'autorizzazione che conferma l'ordine dei certificati con autenticazione
• tech_### - dati del contatto tecnico. Lo stesso non interviene nel processo di autenticazione ma riceve via e-mail il certificato emesso.
• invoice_### - campo per specificare i dati di fatturazione; queste informazioni definiscono l'acquirente nella fattura

Questi dati predefiniti verranno proposti nelle variabili (per esempio, quando si effettua un ordine) e tu non dovrai inserirli nuovamente. Se non comprendi il significato di alcuni campi, puoi consultare la documentazione dell' API.

Completata la configurazione e inserite tutte le informazioni, puoi iniziare a inviare le richieste all'API dell'SSLmarket.

Invio delle richieste

Dopo aver configurato il programma, puoi iniziare a inviare le richieste e, soprattutto, i nuovi ordini. Il CSR deve essere privo di spazi, interruzioni della riga e ritorni a capo che a loro volta vanno sistemati con una sequenza escape. Troverai ulteriori informazioni nel paragrafo successivo.

Nella raccolta seleziona la funzione API che desideri utilizzare. Successivamente, nella parte destra (grande) della finestra, nella scheda Body, potrai vedere la struttura della richiesta. Esempio: inserito un ordine, vengono visualizzate tutte le informazioni relative al futuro certificato (nello spazio corrispondente all'ordine sul sito web). Se un'informazione viene riportata tra parentesi, significa che verrà utilizzata una variabile definita in precedenza, per esempio {{owner_name}}. Modifica queste voci solo se desideri utilizzare dati diversi da quelli predefiniti.

Dati per inserire un ordine

I dati del richiedente e del contatto saranno caricati in base ai dati predefiniti. Per ogni ordine è necessario indicare i seguenti dati specifici:

• domain - nome comune del certificato
• dns_names - elenco dei SAN nel certificato
• years - numero di anni di validità dell'ordine (la validità del certificato è limitata ma l'ordine può avere una durata pluriennale)
• csr - inserisci qui il CSR (deve essere privo di spazi e di ritorni a capo, vedi più avanti). È un dato opzionale: puoi inserire il CSR nell'SSLmarket anche dopo aver effettuato l'ordine tramite l'API.
• dv_auth_method - seleziona il metodo di convalida DCV (e-mail, dns, ftp)

Quando sono stati inseriti tutti i dati e la richiesta è pronta, puoi inviarla all'API facendo clic sul pulsante blu Send.

Lo stato di avanzamento e il risultato della richiesta sono visibili nella parte inferiore della finestra. Se il risultato è positivo, riceverai le informazioni richieste o, se hai effettuato l'ordine, il numero dell'ordine. In caso contrario, ti verrà restituito un messaggio di errore con la specificazione dell'errore o dell'omissione presente nella richiesta.

Esempio di inserimento riuscito di un ordine:

{
    "order_id": "155252"
}

Esempio di messaggio di errore:

   {
    "error": [
        "dv_auth_method => isEmpty - La voce è obbligatoria: la casella non deve rimanere vuota"
    ]
}

Possibili conflitti durante l'invio degli ordini

• URL utilizzati – al posto del solo sslmarket.tld, utilizza l'URL endpoint nel formato www.sslmarket.tld. Sul dominio di base è attivo il reindirizzamento che fa sorgere i problemi con le richieste.
• Richiesta CSR - Fai attenzione a non dividere il CSR in più righe. Se non riesci a inserire il CSR nel formato corretto, invia l'ordine senza il CSR e inserisci il CSR in modo standard tramite l'amministrazione.
  • Non è possibile inviare il CSR diviso in diverse righe anche se l'hai acquisito in tale formato dal server.
  • Il CSR deve essere privo di spazi, interruzioni di riga e ritorni a capo. Le righe vanno terminate con "sequenza escape" rn.
  • Con un solo clic puoi modificare facilmente il CSR nel formato adatto, utilizzando lo strumento Remove or replace line breaks. Seleziona „Replace line breaks with customer text“ e imposta rn come testo del cliente. Deseleziona le altre opzioni e fai clic sul pulsante verde sottostante.

FAQ per l'utilizzo manuale dell'API