Creare un record

Aggiunge un record alla zona DNS di un dominio.

• Metodo: POST
• Indirizzo: https://console.icbs.it/api/v1/domains/{dominio}/dns/records
• Permesso: DNS — creazione, modifica ed eliminazione record

Parametri

Il dominio va nell'indirizzo, il resto nel corpo della richiesta in formato JSON.

Parametro	Posizione	Obbligatorio	Descrizione
dominio	indirizzo	sì	Il nome a dominio, per esempio esempio.it.
type	corpo	sì	Tipo di record: A, AAAA, CNAME, MX, TXT, SPF, SRV, NS, PTR, CAA, SSHFP, HINFO, RP, HTTPS, SVCB, OPENPGPKEY, WR.
host	corpo	no	Il sottodominio. Ometti o lascia vuoto per il dominio principale.
record	corpo	dipende	Il valore del record. Obbligatorio per quasi tutti i tipi; fanno eccezione HINFO e CAA, che usano campi propri.
ttl	corpo	no	Tempo di vita in secondi. Se omesso vale il valore predefinito della zona.

Parametri aggiuntivi per tipo

Alcuni tipi richiedono campi propri oltre a quelli sopra:

Tipo	Parametri aggiuntivi
MX	priority (numero, predefinito 10)
SRV	priority, weight, port (numeri, predefiniti 0)
CAA	caa_flag (numero), caa_type, caa_value — al posto di record
SSHFP	algorithm, fp_type (numeri)
HINFO	cpu, os — al posto di record
RP	mail; il valore va in record
HTTPS, SVCB	priority (numero), params (testo)

Esempio di richiesta

Un record TXT di verifica, il caso più comune nell'automazione dei certificati:

curl -X POST \
  -H "Authorization: Bearer $ICBS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "TXT",
    "host": "_acme-challenge",
    "record": "valore-di-verifica-fornito-dalla-CA",
    "ttl": 300
  }' \
  https://console.icbs.it/api/v1/domains/esempio.it/dns/records

Un record A per un sottodominio:

curl -X POST \
  -H "Authorization: Bearer $ICBS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"A","host":"www","record":"93.184.216.34","ttl":3600}' \
  https://console.icbs.it/api/v1/domains/esempio.it/dns/records

Un record MX, che richiede la priorità:

curl -X POST \
  -H "Authorization: Bearer $ICBS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"MX","host":"","record":"mail.esempio.it","priority":10,"ttl":3600}' \
  https://console.icbs.it/api/v1/domains/esempio.it/dns/records

Esempio di risposta

{
  "domain": "esempio.it",
  "created": {
    "type": "TXT",
    "host": "_acme-challenge"
  }
}

La risposta non contiene l'id del nuovo record: per ottenerlo richiama l'elenco dei record. Se il tuo script deve poi eliminare il record che ha appena creato — come fa la verifica di un certificato — prevedi questa seconda chiamata.

Possibili errori

Codice	Causa
400	Tipo di record non valido, campo obbligatorio mancante, valore rifiutato dalla zona, oppure corpo della richiesta non in JSON valido.
401	Chiave assente, non valida, scaduta o revocata.
403	Alla chiave manca il permesso di scrittura DNS, oppure il dominio è protetto o inattivo.
404	Il dominio non esiste o la chiave non vi ha accesso.
429	Superato il limite di richieste. Il tetto orario è più basso per le scritture che per le letture.