Referencia de API

Autenticación

Todas las solicitudes a la API requieren autenticación mediante una clave API. Pasa la clave en el encabezado Authorization como un token Bearer. La clave API debe comenzar con el prefijo nxd_.

Authorization: Bearer nxd_your_api_key_here

El firewall de la API no tiene estado – cada solicitud se autentica de forma independiente. No hay sesiones ni cookies.

Mantén tu clave API en secreto. No la compartas en código del lado del cliente, repositorios públicos ni URLs. Si una clave se ve comprometida, revócala inmediatamente y crea una nueva.

Errores de autenticación

Formato de respuesta

Todas las respuestas son JSON. Las respuestas exitosas tienen la siguiente estructura:

Recurso individual

{
    "status": "success",
    "data": {
        "id": 42,
        "public_id": "xK9mP2",
        "name": "example.com",
        ...
    }
}

Lista paginada

{
    "status": "success",
    "data": [ ... ],
    "meta": {
        "total": 150,
        "page": 1,
        "per_page": 25,
        "last_page": 6
    }
}

Respuesta de error

{
    "status": "error",
    "error": {
        "code": "validation_error",
        "message": "Validation failed.",
        "details": {
            "name": ["Domain name is required."]
        }
    }
}

IDs públicos

Cada recurso se identifica mediante un id opaco (por ejemplo, xK9mQ2), usado en las rutas de URL. Los IDs numéricos de la base de datos nunca se exponen ni se aceptan.

Paginación

Los endpoints de listado que devuelven resultados paginados aceptan los siguientes parámetros de consulta:

Zonas

Gestiona zonas DNS. Requiere zones.read para operaciones de lectura y zones.write para operaciones de escritura.

GET /v1/zones

Listar todas las zonas del usuario autenticado.

Parámetros de consulta

• search – filtrar zonas por nombre
• page, per_page – paginación

Campos de respuesta

Campos: id, name, type (master/slave), status, ns_group, created_at, updated_at

GET /v1/zones/{id}

Obtener información detallada sobre una zona específica, incluyendo datos SOA, servidores de nombres y cantidad de registros.

Campos de respuesta adicionales

Campos: records_count, soa (primary_ns, admin_email, serial, refresh, retry, expire, minimum), nameservers (array), ns_group (id, slug, name)

POST /v1/zones

Crear una nueva zona DNS. La creación de zonas se bloquea si el usuario tiene facturas vencidas.

Cuerpo de la solicitud (JSON)

{
    "name": "example.com",
    "type": "master",
    "ns_group_id": 1,
    "master_ip": ""
}

• name (obligatorio) – nombre de dominio
• type – "master" (predeterminado) o "slave"
• ns_group – grupo NS al que asignar la zona (opcional, usa el predeterminado si se omite)
• master_ip – obligatorio para zonas secundarias; debe ser una dirección IP válida

Devuelve 201 Created con el objeto de zona.

DELETE /v1/zones/{id}

Eliminar una zona y todos sus registros.

Devuelve 204 No Content en caso de éxito.

GET /v1/zones/{id}/export

Exportar una zona en formato BIND o como JSON estructurado.

Parámetros de consulta

• format – "bind" (predeterminado) devuelve texto de archivo de zona BIND; "json" devuelve un array estructurado de registros con name, type, content y ttl

Registros

Gestiona registros DNS dentro de una zona. Todos los endpoints de registros están anidados bajo una zona. Requiere records.read para operaciones de lectura y records.write para operaciones de escritura.

GET /v1/zones/{zoneId}/records

Listar todos los registros de una zona.

Parámetros de consulta

• type – filtrar por tipo de registro (p. ej., A, CNAME, MX)
• name – filtrar por nombre de registro (coincidencia parcial)
• search – buscar en nombre y contenido

Campos de respuesta

id, name, type, content, ttl, disabled, fields (campos específicos según el tipo)

GET /v1/zones/{zoneId}/records/{recordId}

Obtener un registro individual por su ID.

POST /v1/zones/{zoneId}/records

Crear un nuevo registro DNS.

Cuerpo de la solicitud (JSON)

{
    "type": "A",
    "name": "www",
    "ttl": 3600,
    "content": "93.184.216.34"
}

• type (obligatorio) – tipo de registro (A, AAAA, CNAME, MX, TXT, SRV, CAA, NS, PTR, ALIAS, DNAME, DS, TLSA)
• name – nombre del registro relativo a la zona (predeterminado: @ para el ápice de la zona)
• ttl – tiempo de vida en segundos (predeterminado: 3600)
• content – valor del registro (IP para A/AAAA, nombre de host para CNAME/NS/PTR, texto para TXT, servidor de correo para MX)

Campos específicos por tipo

• MX: priority (por defecto: 10)
• SRV: campos priority, weight, port
• CAA: flags (por defecto: 0), tag (por defecto: «issue»)
• DS: campos keytag, algorithm, digest_type
• TLSA: campos usage, selector, matching_type

Devuelve 201 Created con el objeto de registro.

PUT /v1/zones/{zoneId}/records/{recordId}

Actualizar un registro existente. Incluye solo los campos que quieres cambiar; los campos omitidos conservan sus valores actuales.

{
    "content": "93.184.216.35",
    "ttl": 7200
}

Devuelve 200 OK con el objeto de registro actualizado. Nota: el ID del registro puede cambiar después de una actualización, ya que se calcula a partir del nombre, tipo y contenido del registro.

DELETE /v1/zones/{zoneId}/records/{recordId}

Eliminar un registro de la zona.

Devuelve 204 No Content en caso de éxito.

DNSSEC

Gestiona DNSSEC para tus zonas. Requiere zones.read para ver el estado y zones.write para habilitar o deshabilitar.

GET /v1/zones/{id}/dnssec

Obtener el estado de DNSSEC de una zona, incluyendo claves y registros DS.

Campos de respuesta

enabled (booleano), keys (array de registros DNSKEY), ds_records (array de registros DS para configurar en el registrador)

POST /v1/zones/{id}/dnssec/enable

Habilitar DNSSEC para una zona. Genera claves de firma automáticamente.

Devuelve el estado de DNSSEC con las claves generadas y los registros DS.

POST /v1/zones/{id}/dnssec/disable

Deshabilitar DNSSEC para una zona. Elimina todas las claves de firma.

Devuelve {"enabled": false, "keys": [], "ds_records": []}.

Grupos NS

Lista los grupos de servidores de nombres disponibles. Use el id de un grupo como ns_group al crear una zona. Cualquier clave de API válida puede leer este endpoint.

GET /v1/ns-groups

Lista los grupos de servidores de nombres activos.

Campos de respuesta por grupo

id, name, slug

Cuenta

Ver información de la cuenta y gestionar claves API.

GET /v1/account

Obtener información de la cuenta actual, incluyendo detalles de suscripción.

Campos de respuesta

Campos: id (UUID), email, name, role, status, language, timezone, created_at

subscription – objeto con plan, billing_cycle, status, current_period_start, current_period_end (o null si no hay suscripción)

GET /v1/account/api-keys

Listar todas las claves API del usuario autenticado.

Campos de respuesta por clave

id, name, key_prefix (primeros 8 caracteres), permissions (array), last_used_at, expires_at, created_at

POST /v1/account/api-keys

Crear una nueva clave API.

Cuerpo de la solicitud (JSON)

{
    "name": "CI/CD Pipeline",
    "permissions": ["zones.read", "records.read", "records.write"],
    "expires_at": "2027-01-01"
}

• name (obligatorio) – nombre legible (máximo 255 caracteres)
• permissions (obligatorio) – array de permisos (al menos uno requerido): zones.read, zones.write, records.read, records.write, webhooks.read, webhooks.write
• expires_at – fecha de expiración opcional (ISO 8601 o YYYY-MM-DD); debe ser una fecha futura

La respuesta incluye la clave API completa en el campo key. Esta es la única vez que se devuelve la clave completa. Almacénala de forma segura.

Devuelve 201 Created con los detalles de la clave, incluyendo el valor completo de key.

DELETE /v1/account/api-keys/{id}

Revocar (eliminar permanentemente) una clave API.

Devuelve 204 No Content en caso de éxito.

Facturación

Ver suscripción, planes y facturas. Estos endpoints son de solo lectura.

GET /v1/billing/subscription

Obtener los detalles de la suscripción actual. Devuelve null si no hay suscripción activa.

Campos de respuesta

Campos: id, plan, billing_cycle, status, current_period_start, current_period_end, created_at

GET /v1/billing/plans

Listar todos los planes disponibles con precios y funciones.

Campos de respuesta por plan

Campos: id, name, slug, description, price_monthly, price_yearly, currency, max_domains, max_records, features (array)

GET /v1/billing/invoices

Lista las facturas del usuario autenticado, las más recientes primero.

Parámetros de consulta

• status – filtrar por estado (draft, issued, sent, void)
• page, per_page – paginación

GET /v1/billing/invoices/{id}

Obtiene una factura por su <code>id</code>.

Campos de respuesta

Campos: id, number, status, amount (con impuestos), net_amount (sin impuestos), tax_amount, tax_rate, currency, issued_at, created_at. Los importes son cadenas decimales simples.

Webhooks

Gestione las suscripciones de webhook salientes para recibir notificaciones en tiempo real sobre cambios en zonas y registros. Requiere webhooks.read para lectura y webhooks.write para crear, modificar o eliminar.

GET /v1/webhooks

Lista todas las suscripciones de webhook del usuario autenticado.

Campos de respuesta por webhook

id, url, events (array), description, is_active, failure_count, last_triggered_at, created_at

POST /v1/webhooks

Crea una suscripción de webhook.

Cuerpo de la solicitud (JSON)

{
    "url": "https://example.com/webhook",
    "events": ["zone.created", "record.created"],
    "description": "Production webhook"
}

• url (obligatorio) – endpoint HTTPS que recibirá las cargas de eventos
• events (obligatorio) – array de tipos de evento a los que suscribirse
• description – etiqueta legible opcional

La respuesta incluye un secret para verificar las firmas de webhook (HMAC). Es la única vez que se devuelve el secret. Guárdelo en un lugar seguro.

Devuelve 201 Created con el id y el secret del webhook.

GET /v1/webhooks/{id}

Obtiene una suscripción de webhook junto con sus entregas más recientes.

PUT /v1/webhooks/{id}

Actualiza una suscripción de webhook. Incluya solo los campos que desee cambiar.

Devuelve 200 OK con el objeto de webhook actualizado.

DELETE /v1/webhooks/{id}

Elimina una suscripción de webhook.

Devuelve 204 No Content si tiene éxito.

POST /v1/webhooks/{id}/test

Envía un evento de prueba al endpoint del webhook para comprobar que es accesible.

Pone en cola una entrega de prueba con una carga "type": "test".

Tipos de evento disponibles

Suscríbase a cualquier combinación de estos tipos de evento:

zone.created, zone.deleted, record.created, record.updated, record.deleted, dnssec.enabled, dnssec.disabled, zone.health.problem, zone.health.resolved

Códigos de error

Todos los errores siguen un formato consistente con una cadena de code de error y un message legible.

Ejemplos de código

Todos los ejemplos usan curl. Reemplaza nxd_your_api_key con tu clave API real.

Listar tus zonas

curl -s "https://api.nexdns.tech/v1/zones" \
    -H "Authorization: Bearer nxd_your_api_key"

Crear una zona

curl -s -X POST "https://api.nexdns.tech/v1/zones" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"name": "example.com"}'

Añadir un registro A

curl -s -X POST "https://api.nexdns.tech/v1/zones/{zoneId}/records" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
        "type": "A",
        "name": "www",
        "ttl": 3600,
        "content": "93.184.216.34"
    }'

Añadir un registro MX

curl -s -X POST "https://api.nexdns.tech/v1/zones/{zoneId}/records" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
        "type": "MX",
        "name": "@",
        "ttl": 3600,
        "content": "mail.example.com",
        "priority": 10
    }'

Actualizar un registro

curl -s -X PUT "https://api.nexdns.tech/v1/zones/{zoneId}/records/{recordId}" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"content": "93.184.216.35", "ttl": 7200}'

Eliminar un registro

curl -s -X DELETE "https://api.nexdns.tech/v1/zones/{zoneId}/records/{recordId}" \
    -H "Authorization: Bearer nxd_your_api_key"

Exportar una zona (formato BIND)

curl -s "https://api.nexdns.tech/v1/zones/{zoneId}/export" \
    -H "Authorization: Bearer nxd_your_api_key"

Habilitar DNSSEC

curl -s -X POST "https://api.nexdns.tech/v1/zones/{zoneId}/dnssec/enable" \
    -H "Authorization: Bearer nxd_your_api_key"

Crear una clave API

curl -s -X POST "https://api.nexdns.tech/v1/account/api-keys" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Read-only key",
        "permissions": ["zones.read", "records.read"],
        "expires_at": "2027-12-31"
    }'

Obtener información de la cuenta

curl -s "https://api.nexdns.tech/v1/account" \
    -H "Authorization: Bearer nxd_your_api_key"