DNS

Listado de dominios

Ofrece un listado de los dominios que pueden ser gestionados a través de la API

GET /dns/domains

---

Request

Header

Key	Value	Description
x-api-key	{{x-api-key}}	Clave suministrada por Sarenet en la activación del servicio

Response

Body

{
    "domains": [
        "dominio1.com",
        "dominio2.com",
        "dominio3.com",
        ...
    ]
}

Registros de un dominio

Ofrece un listado de todos registros configurados en el DNS

GET /dns/domains/{{domain}}

Query

Key	Description
domain	Dominio

---

Request

Header

Key	Value	Description
x-api-key	{{x-api-key}}	Clave suministrada por Sarenet en la activación del servicio

Códigos de respuesta

Status	Error	Description
200		OK
400	No domain specified.	No se ha especificado un dominio
400	No valid domain.	El dominio no existe o no es válido

Response

Body

{
    "records": [
        {
            "id": "924383",
            "zone": "dominio1.com",
            "host": "@",
            "type": "SOA",
            "data": "ns1.sarenet.es.",
            "ttl": 172800,
            "priority": null,
            "timestamp": "2022-01-04 16:25:00",
            "note": ""
        },
        {
            "id": "924384",
            "zone": "dominio1.com",
            "host": "",
            "type": "NS",
            "data": "ns1.sarenet.es.",
            "ttl": 72800,
            "priority": null,
            "timestamp": "2020-05-13 14:18:48",
            "note": ""
        },
        {
            "id": "924385",
            "zone": "dominio1.com",
            "host": "",
            "type": "NS",
            "data": "ns2.sarenet.es.",
            "ttl": 72800,
            "priority": null,
            "timestamp": "2020-05-13 14:18:48",
            "note": ""
        },
        {
            "id": "924387",
            "zone": "dominio1.com",
            "host": "@",
            "type": "MX",
            "data": "smtp.sarenet.es.",
            "ttl": 172800,
            "priority": 5,
            "timestamp": "2020-05-13 14:52:44",
            "note": ""
        },
        {
            "id": "924388",
            "zone": "dominio1.com",
            "host": "autoconfig",
            "type": "CNAME",
            "data": "autodiscover.saremail.com.",
            "ttl": 172800,
            "priority": null,
            "timestamp": "2020-05-13 14:52:45",
            "note": ""
        },
        {
            "id": "924389",
            "zone": "dominio1.com",
            "host": "autodiscover",
            "type": "CNAME",
            "data": "autodiscover.saremail.com.",
            "ttl": 172800,
            "priority": null,
            "timestamp": "2020-05-13 14:52:45",
            "note": ""
        },
        {
            "id": "924390",
            "zone": "dominio1.com",
            "host": "_dmarc",
            "type": "TXT",
            "data": "\"v=DMARC1; p=reject; rua=mailto:postmaster@dominio1.com; adkim=r; aspf=s; pct=100; sp=none\"",
            "ttl": 172800,
            "priority": null,
            "timestamp": "2020-05-13 14:52:45",
            "note": ""
        },
        {
            "id": "924391",
            "zone": "dominio1.com",
            "host": "_carddavs._tcp",
            "type": "SRV",
            "weight": "5",
            "port": "443",
            "data": "dominio1com.organizer.sarenet.es",
            "ttl": 172800,
            "priority": "0",
            "timestamp": "2020-05-13 14:52:45",
            "note": ""
        },
        {
            "id": "924392",
            "zone": "dominio1.com",
            "host": "_caldavs._tcp",
            "type": "SRV",
            "weight": "5",
            "port": "443",
            "data": "dominio1com.organizer.sarenet.es",
            "ttl": 172800,
            "priority": "0",
            "timestamp": "2020-05-13 14:52:45",
            "note": ""
        },
        {
            "id": "924393",
            "zone": "dominio1.com",
            "host": "@",
            "type": "TXT",
            "data": "\"v=spf1 include:sarenet.es -all\"",
            "ttl": 172800,
            "priority": null,
            "timestamp": "2020-05-13 14:52:45",
            "note": ""
        },
        {
            "id": "924426",
            "zone": "dominio1.com",
            "host": "webmail",
            "type": "A",
            "data": "194.30.0.206",
            "ttl": 3600,
            "priority": null,
            "timestamp": "2020-06-05 11:50:09",
            "note": ""
        },
        {
            "id": "940308",
            "zone": "dominio1.com",
            "host": "webmail",
            "type": "TXT",
            "data": "\"pvwn37l2r9q2z5yncz0j922dlgrkq0py\"",
            "ttl": 300,
            "priority": null,
            "timestamp": "2021-09-22 13:13:35",
            "note": ""
        }
    ]
}

Listado de registros de un tipo especifico

Ofrece un listado de los registros del dominio que son modificables

GET /dns/domain_records/{{domain}}/{{type}}

GET /dns/domain_records/{{domain}}/{{type}}/{{host}}

Query

Key	Description
domain	Dominio
type	Tipo de registro ('A', 'AAAA', 'CAA', 'CNAME', 'MX', 'NAPTR', 'NS', 'PTR', 'SOA', 'SRV', 'TXT', 'TYPE257')
host	Texto para filtrar el host (opcional)

---

Códigos de respuesta

Status	Error	Description
200		OK
400	No domain specified.	No se ha especificado un dominio
400	No valid domain.	El dominio no existe o no es válido

Request

Header

Key	Value	Description
x-api-key	{{x-api-key}}	Clave suministrada por Sarenet en la activación del servicio

Response

Body

 {
    "records": [
        {
            "id": "924390",
            "zone": "dominio1.com",
            "host": "_dmarc",
            "type": "TXT",
            "data": "\"v=DMARC1; p=reject; rua=mailto:postmaster@dominio1.com; adkim=r; aspf=s; pct=100; sp=none\"",
            "ttl": 172800,
            "priority": null,
            "timestamp": "2020-05-13 14:52:45",
            "note": ""
        },
        {
            "id": "924393",
            "zone": "dominio1.com",
            "host": "@",
            "type": "TXT",
            "data": "\"v=spf1 include:sarenet.es -all\"",
            "ttl": 172800,
            "priority": null,
            "timestamp": "2020-05-13 14:52:45",
            "note": ""
        },
        {
            "id": "940308",
            "zone": "dominio1.com",
            "host": "webmail",
            "type": "TXT",
            "data": "\"pvwn37l2r9q2z5yncz0j922dlgrkq0py\"",
            "ttl": 300,
            "priority": null,
            "timestamp": "2021-09-22 13:13:35",
            "note": ""
        }
    ]
}

Crear un registro en un dominio

POST /dns/domain_records/{{domain}}

Query

Key	Description
domain	Dominio

---

Request

Header

Key	Value	Description
x-api-key	{{x-api-key}}	Clave suministrada por Sarenet en la activación del servicio

Body

Key	Description
type	Tipo de registro ('A', 'AAAA', 'CAA', 'CNAME', 'MX', 'NAPTR', 'PTR', 'SRV', 'TXT', 'TYPE257')
host	Host del registro ('@', '*', cadena de texto)
ttl	Entero que indica el tiempo de validez del registro (300, 3600, ...) mínimo 300
data	Datos asociados al registro
weight (opcional si no es SRV)	Peso asociado al registro SRV
port (opcional si no es SRV)	Puerto asociado al registro SRV
flags (opcional si no es CAA)	Un número entero sin signo entre 0 y 255 que se utiliza para los registros CAA
tag (opcional si no es CAA)	La etiqueta de parámetro para registros CAA. Los valores válidos son "issue", "issuewild", o "iodef"
priority(optional si no es MX o SRV)	Si el registro es de tipo MX o SRV será un entero que indique la prioridad del mismo
note (opcional)	Texto de hasta 1000 caracteres. Si se omite, no se toca la nota; una cadena vacía la borra.

Example de request body

 {
    "type": "TXT",
    "host": "@",
    "ttl": 300,
    "data": "prueba",
    "note": "Alta solicitada por el cliente."
}

Códigos de respuesta

Status	Error	Description
200		OK
200	Ver mensajes de fallos parciales	La operación DNS se ha completado, pero ha fallado la nota; devuelve estado=KO y parcial=true.
400	note must be a string.	La nota debe ser una cadena de texto.
400	note must not exceed 1000 characters.	La nota supera los 1000 caracteres.
400	Invalid response	Problemas de acceso a la API
400	No domain specified.	No se ha especificado un dominio
400	No valid domain.	El dominio no existe o no es válido
400	No type specified.	Falta el parámetro type
400	No host specified.	Falta el parámetro host
400	No ttl specified.	Falta el parámetro ttl
400	No weight specified.	Falta el parámetro weight
400	No port specified.	Falta el parámetro port
400	No flags specified.	Falta el parámetro flags
400	No tag specified.	Falta el parámetro tag
400	No priority specified.	Falta el parámetro priority
400	Ttl should be greater than 300.	El parámetro ttl es menor de 300
400	DNS-API:*	Parámetros incorrectos

Response

Devuelve el registro creado.

Body

 {
    "record":
        {
            "id": "924390",
            "zone": "dominio1.com",
            "host": "_dmarc",
            "type": "TXT",
            "data": "\"v=DMARC1; p=reject; rua=mailto:postmaster@dominio1.com; adkim=r; aspf=s; pct=100; sp=none\"",
            "ttl": 172800,
            "priority": null,
            "timestamp": "2020-05-13 14:52:45",
            "note": "Cambio solicitado por el cliente."
        }
}

Modificar un registro de un dominio

PUT /dns/domain_records/{{domain}}

Query

Key	Description
domain	Dominio

---

Request

Header

Key	Value	Description
x-api-key	{{x-api-key}}	Clave suministrada por Sarenet en la activación del servicio

Body

Key	Description
id	Identificador del registro que se quiere modificar
host	Host del registro ('@', '*', cadena de texto)
ttl	Entero que indica el tiempo de validez del registro (300, 3600, ...) mínimo 300
data	Datos asociados al registro
weight (opcional si no es SRV)	Peso asociado al registro SRV
port (opcional si no es SRV)	Puerto asociado al registro SRV
flags (opcional si no es CAA)	Un número entero sin signo entre 0 y 255 que se utiliza para los registros CAA
tag (opcional si no es CAA)	La etiqueta de parámetro para registros CAA. Los valores válidos son "issue", "issuewild", o "iodef"
priority (opcional si no es MX o SRV)	Si el registro es de tipo MX o SRV será un entero que indique la prioridad del mismo
note (opcional)	Texto de hasta 1000 caracteres. Si se omite, no se toca la nota; una cadena vacía la borra.

Example de request body

 {
    "id": "944145",
    "type": "TXT",
    "host": "@",
    "ttl": 300,
    "data": "prueba modificada",
    "note": "Cambio solicitado por el cliente."
 }

Códigos de respuesta

Status	Error	Description
200		OK
200	Ver mensajes de fallos parciales	La operación DNS se ha completado, pero ha fallado la nota; devuelve estado=KO y parcial=true.
400	note must be a string.	La nota debe ser una cadena de texto.
400	note must not exceed 1000 characters.	La nota supera los 1000 caracteres.
400	No valid record.	No se pudo encontrar el registro para modificar únicamente su nota.
500	The note could not be saved.	Ha fallado una petición que modifica únicamente la nota.
400	Invalid response	Problemas de acceso a la API
400	No domain specified.	No se ha especificado un dominio
400	No valid domain.	El dominio no existe o no es válido
400	No id specified.	Falta el parámetro id
400	No type specified.	Falta el parámetro type
400	No host specified.	Falta el parámetro host
400	No ttl specified.	Falta el parámetro ttl
400	No weight specified.	Falta el parámetro weight
400	No port specified.	Falta el parámetro port
400	No flags specified.	Falta el parámetro flags
400	No tag specified.	Falta el parámetro tag
400	No priority specified.	Falta el parámetro priority
400	Ttl should be greater than 300.	El parámetro ttl es menor de 300
400	DNS-API:*	Parámetros incorrectos

Response

Devuelve el registro modificado.

Body

{
  "record":
      {
          "id": "924390",
          "zone": "dominio1.com",
          "host": "_dmarc",
          "type": "TXT",
          "data": "\"v=DMARC1; p=reject; rua=mailto:postmaster@dominio1.com; adkim=r; aspf=s; pct=100; sp=none\"",
          "ttl": 172800,
          "priority": null,
          "timestamp": "2020-05-13 14:52:45",
            "note": "Cambio solicitado por el cliente."
      }
}

Modificar o borrar únicamente la nota

Se utiliza el mismo PUT /dns/domain_records/{{domain}}, enviando solo id y note en el cuerpo. domain es el nombre del dominio (por ejemplo, dominio1.com, sin protocolo ni ruta), e id es el identificador de un registro de ese dominio obtenido mediante GET; no es el ID del dominio.

Para añadir o sustituir la nota:

{
    "id": "944145",
    "note": "Cambio solicitado por el cliente."
}

Para borrar la nota y conservar el registro DNS:

{
    "id": "944145",
    "note": ""
}

La respuesta correcta es HTTP 200 e incluye el ID y la nota guardada. Ejemplo al borrarla:

{
    "record": {
        "id": "944145",
        "note": ""
    }
}

En estas peticiones no se envían los campos DNS (type, host, ttl, priority, data, weight, port, flags y tag). Si se incluye alguno, se aplican los requisitos habituales de modificación del registro.

Borrar un registro de un dominio

DELETE /dns/domain_records/{{domain}}/{{id}}

Elimina el registro DNS y su nota. Para borrar únicamente la nota, utiliza PUT con id y note: "".

Query

Key	Description
domain	Dominio
id	Identificador del registro del dominio

---

Request

Header

Key	Value	Description
x-api-key	{{x-api-key}}	Clave suministrada por Sarenet en la activación del servicio

Códigos de respuesta

Status	Error	Description
200		OK
200	Ver mensajes de fallos parciales	La operación DNS se ha completado, pero ha fallado la nota; devuelve estado=KO y parcial=true.
400	Invalid response	Problemas de acceso a la API
400	No domain specified.	No se ha especificado un dominio
400	No valid domain.	El dominio no existe o no es válido
400	No id specified.	Falta el parámetro id
400	DNS-API:*	Parámetros incorrectos

Fallos parciales al guardar o borrar la nota

Si la creación, modificación o eliminación del registro DNS se completa, pero falla el guardado o borrado de su nota, la respuesta es HTTP 200 con status: 200, estado: "KO", parcial: true y un mensaje en error.

En creación y modificación se conservan los datos del registro devueltos por el servicio DNS, incluido su ID cuando esté disponible. La respuesta no incluye la nota solicitada como si se hubiera guardado. Si el servicio confirma la creación pero no devuelve el ID necesario para guardar la nota, también se informa del resultado parcial.

Operación	error
Crear	DNS record has been created, but its note could not be saved.
Crear sin ID en la respuesta DNS	DNS record has been created, but its ID is missing and its note could not be saved.
Modificar	DNS record has been modified, but its note could not be saved.
Borrar	DNS record has been deleted, but its note could not be deleted.

En el fallo parcial de borrado se devuelve el ID del registro eliminado:

{
    "status": 200,
    "error": "DNS record has been deleted, but its note could not be deleted.",
    "estado": "KO",
    "parcial": true,
    "record": {
        "id": "944145"
    }
}

El registro DNS ya está eliminado, aunque la nota no se haya podido borrar. No se debe repetir la operación DNS por este fallo.

Si la petición modifica solo la nota, un fallo de persistencia devuelve HTTP 500 con error: "The note could not be saved.", sin parcial: true, porque no se ha completado ninguna operación DNS.