> ## Documentation Index > Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt > Use this file to discover all available pages before exploring further. # Crear una zona > Crear una nueva zona DNS. Los registros SOA y NS se generan automáticamente en la lista de servidores de nombres de la plataforma; la zona se puede consultar inmediatamente en caso de éxito. Por defecto, una zona pública. Pase `visibility: private` más al menos una entrada `vpcs` para una zona que resuelve solo dentro de esas VPCs: una zona privada sin VPC o una zona pública que lleva `vpcs` se rechaza con 400 en lugar de ser forzada silenciosamente. Requiere la acción de IAM **`dns:CreateZone`**. Consulte [permisos de DNS](/es/dns/permissions) para obtener la lista completa, lo que cubre cada una y un ejemplo de política. ## OpenAPI ````yaml /es/api-reference/specs/dns.yaml post /v1/zones openapi: 3.0.3 info: title: Basaltic DNS API version: 1.0.0 description: > Zonas alojadas autorizadas y sus registros, firmados con DNSSEC. Una zona solo se sirve una vez que se verifica su propiedad; asociar una zona con una VPC la hace resoluble de forma privada dentro de esa red. contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://dns.basaltic.sh description: Endpoint de API global security: - BearerAuth: [] paths: /v1/zones: post: tags: - DNS summary: Crear una zona description: > Crear una nueva zona DNS. Los registros SOA y NS se generan automáticamente en la lista de servidores de nombres de la plataforma; la zona se puede consultar inmediatamente en caso de éxito. Por defecto, una zona pública. Pase `visibility: private` más al menos una entrada `vpcs` para una zona que resuelve solo dentro de esas VPCs: una zona privada sin VPC o una zona pública que lleva `vpcs` se rechaza con 400 en lugar de ser forzada silenciosamente. operationId: createZone parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ZoneCreateRequest' responses: '201': description: Zona creada content: application/json: schema: $ref: '#/components/schemas/ZoneResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: > Esta cuenta ya tiene una zona con este nombre. Otra CUENTA que tenga el dominio no es un conflicto: varias cuentas pueden tener una reclamación sobre el mismo nombre, y la que la delegación del registrador señale es la que la sirve. Así es como un dominio se mueve entre cuentas: crea la zona aquí y luego vuelve a apuntar al registrador a los servidores de nombres con los que regresa. content: application/json: schema: $ref: '#/components/schemas/Error' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' security: - BearerAuth: [] components: parameters: IdempotencyKey: name: Idempotency-Key in: header description: >- Clave opcional generada por el cliente que hace que una creación sea segura para la reproducción. Al volver a intentar una solicitud con la misma clave, se devuelve el resultado original literalmente en lugar de crear un recurso duplicado. Se rechaza la reutilización de una clave con un cuerpo de solicitud diferente (422); una solicitud cuya clave todavía se está procesando devuelve 409. Los registros se mantienen durante 24 horas. Usa un UUID o un token único similar. required: false schema: type: string maxLength: 255 example: 550e8400-e29b-41d4-a716-446655440000 schemas: ZoneCreateRequest: type: object required: - name properties: name: type: string description: >- Zona de FQDN. Los nombres de los recursos no deben comenzar con el prefijo literal crn: ni ser UUID (en cualquier caso, en las formas canónica, compacta, entre corchetes o urn:uuid:). example: example.com description: type: string description: Nota de forma libre almacenada y devuelta en la zona. example: Production apex visibility: type: string enum: - public - private default: public description: > `private` restringe la zona a las VPCs nombradas en `vpcs` y requiere al menos una; `public` (el valor predeterminado) rechaza `vpcs` directamente en lugar de ignorarlos. No se puede cambiar después. example: public dnssec: type: boolean default: true description: > Firmar la zona con DNSSEC. Encendido a menos que usted diga lo contrario, y casi todas las zonas deben dejarlo encendido. **Desactiva solo si este dominio es servido por otro proveedor de DNS al mismo tiempo que nosotros.** Una zona firmada pone nuestro registro DS en el padre, y ese DS cubre solo las respuestas que firmamos, por lo que un resolver de validación que le pregunta al otro proveedor obtiene una firma que no puede verificar y falla la búsqueda. Aproximadamente la mitad de sus consultas, de forma impredecible, lo que es peor que cualquier proveedor por sí solo. Sin firmar es la única configuración que funciona para esa configuración hoy en día. Fijado en la creación. Si desactivas la firma más tarde, el dominio se interrumpe hasta que el DS se retira en el registrador y esa retirada se ha propagado, lo cual es una secuencia que esta API no puede gestionar por ti. example: true import_existing_records: type: boolean default: false description: > Lee los registros del dominio de los servidores de nombres que lo sirven HOY y cópielos en esta zona, antes de mover la delegación aquí. Vale la pena preguntar cuando estás migrando un dominio activo. La delegación es la prueba de propiedad, así que el momento en que usted señala a su registrador a esta zona es el momento en que comenzamos a responder por ella — y una zona vacía responde con nada, lo que lleva el sitio y el correo hasta que haya vuelto a escribir todo. Se ejecuta en segundo plano; la zona se crea inmediatamente. Poll GET /v1/zones/{zone_id}/record-import para ver el resultado. El mejor esfuerzo, y el resultado dice lo bueno que fue. Una transferencia de zona es exhaustiva y casi siempre se rechaza; el fallback consulta una lista de nombres comunes y no puede encontrar un registro que no pensó en pedir. Compruebe `record_import.complete` antes de desactivar su antiguo proveedor. Los registros que ya haya creado nunca se sobrescriben y los registros que esta plataforma gestiona por sí misma (el SOA, la cadena DNSSEC, los servidores de nombres de la zona) nunca se importan. example: true vpcs: type: array items: type: string description: > UUID de VPC de propiedad de la cuenta o CRN de red/vpc en los que se resuelve la zona. Los nombres desnudos se rechazan con 400 porque la solicitud no fija ninguna región. Los CRN se resuelven en su región con nombre; los UUID buscan en todas las regiones habilitadas para DNS. Las VPC que faltan, de cuenta extranjera o de región no configurada devuelven 404. Las búsquedas de UUID incompletas o las identidades de UUID regionales duplicadas fallan con un error de servidor. Las referencias se deduplican por UUID. Requerido cuando visibility=private, rechazado cuando visibility=public. Más se pueden asociar más tarde a través de POST /v1/zones/{zone_id}/vpc-associations. example: - c3d4e5f6-a7b8-4901-c2d3-e4f5a6b7c8d9 tags: $ref: '#/components/schemas/Tags' ZoneResponse: type: object properties: zone: $ref: '#/components/schemas/Zone' Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: Código de error que identifica el tipo de error example: INVALID_INPUT message: type: string description: Mensaje de error legible por el ser humano example: Invalid request parameters params: type: object additionalProperties: true description: >- Valores no sensibles opcionales para la interpolación de errores localizados, codificados por código de error. Nunca presente por errores del servidor. example: instances: 2 pools: 0 request_id: type: string format: uuid description: Solicitar ID para depuración example: 550e8400-e29b-41d4-a716-446655440000 Tags: type: object additionalProperties: type: string example: environment: production team: backend Zone: type: object properties: id: type: string format: uuid readOnly: true example: 550e8400-e29b-41d4-a716-446655440000 crn: type: string readOnly: true description: Nombre de recurso de nube. example: crn:dns::my-account:zone/example.com name: type: string description: >- Zona de FQDN. Los nombres de los recursos no deben comenzar con el prefijo literal crn: ni ser UUID (en cualquier caso, en las formas canónica, compacta, entre corchetes o urn:uuid:). example: example.com description: type: string description: Descripción de forma libre, editable con PATCH. example: Public zone for the marketing site nameservers: type: array items: type: string description: > Servidores de nombres autorizados para la zona: el conjunto NS de vértice. Copie esta lista textualmente en la configuración del servidor de nombres de su registrador para delegar la zona a la plataforma. Estos nombres son únicos para ESTA zona: cada uno lleva una etiqueta por zona, que es lo que hace que la delegación sea doble como prueba de propiedad (ver `ownership`). Dos zonas para el mismo dominio reciben nombres diferentes, y la que apunta el registrador es la que sirve. Úselos exactamente como están escritos: los nombres de servidor de nombres desnudos de Basaltic no verificarán la zona. example: - 028t5cy4tqkff.triton.dns.basaltic.cloud - 028t5cy4tqkff.proteus.dns.basaltic.cloud soa: $ref: '#/components/schemas/SOA' visibility: type: string enum: - public - private readOnly: true description: > `public` las zonas responden en los servidores de nombres orientados a Internet; `private` Las zonas de VPC responden solo dentro de las VPC asociadas a ellas (consulte los extremos de asociaciones de vpc). example: public dnssec: $ref: '#/components/schemas/ZoneDNSSEC' tags: $ref: '#/components/schemas/Tags' ownership: $ref: '#/components/schemas/ZoneOwnership' SOA: type: object properties: primary_ns: type: string description: SOA `mname` — primer servidor de nombres autorizado para la zona. example: 028t5cy4tqkff.triton.dns.basaltic.cloud admin_email: type: string format: email readOnly: true description: > SOA `rname` — el contacto de operaciones DNS de la plataforma. Estampado en el lado del servidor; no configurable por el cliente. example: hostmaster@basaltic.sh refresh: type: integer example: 10800 retry: type: integer example: 3600 expire: type: integer example: 604800 minimum: type: integer description: Caché de NXDOMAIN TTL. example: 3600 ZoneDNSSEC: type: object description: > Estado de firma DNSSEC. Presente una vez que el firmante ha iniciado la zona, que está siempre activada para las zonas creadas a través de esta API; ausente en una zona que no está firmada. `ds_records` es lo que el cliente pega en el registrador principal para completar la cadena de confianza. `rdata` es la forma de archivo de zona del mismo registro, para los registradores que toman una cadena. required: - enabled properties: enabled: type: boolean readOnly: true example: true ksk_key_tag: type: integer readOnly: true description: >- Etiqueta de la clave de firma de clave — coincide con los registros DS a continuación. example: 12345 zsk_key_tag: type: integer readOnly: true description: Etiqueta de la clave de firma de zona. example: 54321 algorithm: type: integer readOnly: true description: Número de algoritmo DNSSEC. 13 = ECDSA P-256 SHA-256. example: 13 ds_records: type: array readOnly: true items: $ref: '#/components/schemas/ZoneDSRecord' ZoneOwnership: type: object description: > Prueba de propiedad del dominio. Una zona sin ninguna zona existente encima de ella en la plataforma no se resuelve hasta que `verified` es verdadero — establece los `nameservers` de la zona en tu registrador, luego POST /v1/zones/{zone_id}/verify-ownership. No hay ningún registro para publicar. Los servidores de nombres de la zona llevan una etiqueta única para ella, por lo que delegar el dominio en ellos es la prueba en sí misma: solo quien controla el dominio en su registrador puede hacerlo, y los nombres no se pueden heredar de una zona que solía tener este dominio. Usa los `nameservers` propios de la zona y nada más. Los nombres de servidores de nombres de Basaltic no prueban nada por sí mismos — cualquiera puede apuntar un dominio a ellos — por lo que una delegación que los nombre deja la zona sin verificar. Los servidores de nombres de otros proveedores pueden estar junto al tuyo si alojas el dominio en dos proveedores. Lo que NO funciona es delegar a dos zonas basalticas a la vez: mientras un dominio nombra los servidores de nombres de otra zona así como el de ésta, ninguno de ellos es servido, y el remedio es eliminar los que esta zona no lista. Ese es el estado que se espera a mitad de camino al mover un dominio entre cuentas. Una zona creada debajo de una zona que ya posee hereda la prueba de su padre y se verifica en la creación. La prueba es un contrato de arrendamiento, no una escritura: se vuelve a confirmar periódicamente mientras se sirva la zona, por lo que un dominio que caduca o cambia de manos deja de ser servido desde aquí. `checked_at` es la última confirmación; `recheck_deadline` aparece solo cuando la confirmación falla y es el campo desde el que se genera una advertencia. properties: verified: type: boolean readOnly: true description: >- Si la zona ha demostrado la propiedad. Las zonas no verificadas no se resuelven. example: false verified_at: type: string format: date-time readOnly: true nullable: true description: >- Cuando se probó por primera vez la propiedad. Ausente mientras no se verifica. example: '2026-01-15T09:30:00Z' checked_at: type: string format: date-time readOnly: true description: > Cuando la prueba fue confirmada por última vez. `verified_at` mantiene el significado "primero demostrado" y no se mueve; esto lo hace, en cada pase que pasa. Ausente hasta que la zona se ha reconfirmado al menos una vez. example: '2026-04-14T09:30:00Z' recheck_deadline: type: string format: date-time readOnly: true description: > Presente SOLO mientras la re-prueba periódica está fallando: el instante en que la zona deja de responder a menos que pase de nuevo. Ausente significa sano. Cada paso vuelve a comprobar una zona de fallo, por lo que para llegar a esta fecha se necesita un fallo sostenido, no una mala tarde: un problema de resolución transitorio se aclara en el siguiente paso. Para borrarlo deliberadamente, apunta la delegación del dominio de nuevo a los `nameservers` de esta zona y POST /v1/zones/{zone_id}/verify-ownership. El propietario de la organización recibe un correo electrónico cuando se establece esta fecha y de nuevo si la zona deja de resolver. Una zona nunca se quita del aire antes de que ese mensaje haya salido, por lo que la fecha aquí es la más temprana que la zona puede dejar de responder y nunca la única advertencia. example: '2026-04-28T09:30:00Z' ZoneDSRecord: type: object description: Un registro DS para publicar en la zona principal. required: - key_tag - algorithm - digest_type - digest - rdata properties: key_tag: type: integer example: 12345 algorithm: type: integer example: 13 digest_type: type: integer description: 2 = SHA-256. example: 2 digest: type: string example: B8FA03AA1BB49CC702C32C5C3FE6061BBDD0808371F43A28A8E8BE2738CC9861 rdata: type: string description: >- Forma completa de archivo de zona — ` `. example: >- 12345 13 2 B8FA03AA1BB49CC702C32C5C3FE6061BBDD0808371F43A28A8E8BE2738CC9861 responses: BadRequest: description: Parámetros de solicitud no válidos content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_INPUT message: Invalid request parameters request_id: 550e8400-e29b-41d4-a716-446655440000 Unauthorized: description: Se requiere autenticación o el token no es válido content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Authentication required request_id: 550e8400-e29b-41d4-a716-446655440000 Forbidden: description: Permisos insuficientes content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ACCESS_DENIED message: You don't have permission to perform this action request_id: 550e8400-e29b-41d4-a716-446655440000 NotFound: description: No se encontró el recurso content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: Resource not found request_id: 550e8400-e29b-41d4-a716-446655440000 UnprocessableEntity: description: > La solicitud está bien formada, pero no se puede procesar como se envió. En las operaciones que aceptan `Idempotency-Key` este es el caso de reutilización de clave: la clave fue vista por primera vez con una carga de solicitud diferente, por lo que la reproducción del resultado almacenado respondería a una pregunta que el llamador no hizo. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: IDEMPOTENCY_KEY_REUSED message: >- This Idempotency-Key was already used with a different request payload request_id: 550e8400-e29b-41d4-a716-446655440000 InternalServerError: description: Error interno del servidor content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INTERNAL_ERROR message: An internal error occurred request_id: 550e8400-e29b-41d4-a716-446655440000 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >+ Un token bearer de OAuth 2.0, enviado como `Authorization: Bearer `. Esta es la forma recomendada de autenticación. Obtén el token intercambiando el par de claves de acceso de una cuenta de servicio en `POST /v1/oauth/token` con `grant_type=client_credentials`. Es el flujo estándar de credenciales de cliente; las bibliotecas compatibles con OAuth pueden obtener y renovar el token por ti. ``` curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \ https://iam.basaltic.sh/v1/oauth/token ``` Los tokens duran una hora por defecto. El mismo par de claves de acceso también sirve como credencial AWS SigV4 para el endpoint de objetos compatible con S3, que solo acepta ese método de autenticación. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.