API REST — Documentación

URL base

https://webdominios.com/api/v1

Todas las respuestas son JSON. Todos los precios están en dólares (USD) y como cadenas de texto, no números: "13.41", no 13.41.

¿Por qué los precios son texto? Para que no pierdas centavos. Los números decimales en coma flotante no representan el dinero con exactitud: 0.1 + 0.2 da 0.30000000000000004 en casi todos los lenguajes. Trata nuestros precios como texto y conviértelos con una librería de decimales.

Autenticación

Manda tu clave en la cabecera Authorization:

curl https://webdominios.com/api/v1/account \
  -H "Authorization: Bearer dw_live_tuclaveaqui"

Tu clave se muestra una sola vez. Guardamos solo un hash: ni nosotros podemos recuperarla. Si la pierdes, la revocas y generas otra desde tu panel.

Puedes restringir cada clave a una lista de IPs desde tu panel. Recomendado si tu sistema tiene IP fija.

Límites

Situación	Límite
Con clave válida	120 peticiones/minuto por clave
Sin clave	20/minuto por IP

Cada respuesta incluye x-ratelimit-limit y x-ratelimit-remaining. Si superas el límite recibes 429.

Consulta con cabeza. El límite es por clave, no por IP: si compartes hosting con otro revendedor, no se pisan. Cachea los precios (cambian poco) y no consultes disponibilidad en cada tecla que escribe tu usuario.

Cómo funcionan los precios

Los precios que te devolvemos ya tienen aplicado el descuento de tu nivel. No ves el precio de lista ni el de otros niveles: ves el tuyo.

Nivel	Descuento	Ejemplo `.com`
Cliente (lista)	—	$14.90
Revendedor Bronce	−5%	$14.15
Revendedor Plata	−10%	$13.41
Revendedor Oro	−15%	$12.66

El precio que le cobres a tu cliente lo decides tú. Nosotros te damos tu costo.

Ofertas de primer año. Cuando un dominio tiene oferta, te devolvemos promo_first_year junto a renew. Muestra los dos a tu cliente: un .shop a $3.59 el primer año que renueva a $46.80 genera una devolución si el cliente no lo sabía.

GET /account

Tu cuenta, tu nivel y tu saldo.

curl https://webdominios.com/api/v1/account \
  -H "Authorization: Bearer dw_live_tuclave"

{
  "tenant": {
    "slug": "revendedor-demo",
    "name": "Revendedor Demo CA",
    "status": "active",
    "currency": "USD"
  },
  "tier": { "slug": "plata", "name": "Revendedor Plata", "discount": 10 },
  "balance": "0.00",
  "api_key": { "label": "Demo", "scopes": ["domains:read","pricing:read"] }
}

GET /domains/check

Comprueba disponibilidad. Devuelve el dominio pedido y alternativas en otras extensiones.

Parámetro	Tipo	Descripción
`domain`	string	Obligatorio. Con o sin extensión. Acepta acentos y ñ.

curl "https://webdominios.com/api/v1/domains/check?domain=miidea.com" \
  -H "Authorization: Bearer dw_live_tuclave"

{
  "query": "miidea.com",
  "results": [
    {
      "domain": "miidea.com",
      "tld": "com",
      "available": true,
      "pricing": { "currency": "USD", "price": "13.41", "renew": "13.41" }
    },
    {
      "domain": "miidea.shop",
      "tld": "shop",
      "available": true,
      "pricing": {
        "currency": "USD",
        "price": "46.80",
        "renew": "46.80",
        "promo_first_year": "3.59",
        "discount_percent": 92
      }
    },
    { "domain": "miidea.io", "tld": "io", "available": false }
  ]
}

Dominios con acentos. Puedes mandar añejo.com tal cual: lo convertimos a punycode (xn--aejo-gqa.com) por ti. No lo hagas a mano.

GET /pricing

Tu lista de precios completa, o filtrada por extensión.

Parámetro	Tipo	Descripción
`tld`	string	Opcional. Sin él, devuelve el catálogo completo.

curl "https://webdominios.com/api/v1/pricing?tld=com" \
  -H "Authorization: Bearer dw_live_tuclave"

{
  "tier": "plata",
  "discount": 10,
  "count": 1,
  "pricing": [
    {
      "tld": "com",
      "currency": "USD",
      "register": "13.23",
      "renew": "13.41",
      "transfer": "12.60"
    }
  ]
}

Cachea esto. Los precios cambian cuando cambia el catálogo, no cada minuto. Pídelo una vez al día y guárdalo.

Errores

Todos los errores tienen la misma forma:

{ "error": { "code": "invalid_key", "message": "La API key no es válida o fue revocada." } }

HTTP	`code`	Qué pasó
401	`unauthenticated`	Falta la cabecera `Authorization`
401	`invalid_key_format`	La clave no tiene el formato correcto
401	`invalid_key`	Clave inexistente o revocada
401	`key_expired`	La clave venció
403	`ip_not_allowed`	Tu IP no está en la lista de la clave
403	`tenant_suspended`	Tu cuenta no está activa
422	—	Parámetros inválidos
429	—	Superaste el límite de peticiones
503	`upstream_unavailable`	No pudimos consultar el registro. Reintenta en unos segundos.

Próximamente

La API de hoy es de solo lectura. Estamos trabajando en:

POST /domains/register — registrar dominios
POST /domains/renew — renovar
POST /domains/transfer — transferir
Gestión de contactos y DNS
Webhooks de vencimiento

¿Por qué no está el registro todavía? Porque mueve dinero. Antes de abrirlo queremos idempotencia real, límites de gasto y confirmación explícita — para que un bucle mal escrito en tu sistema no te vacíe el saldo. Preferimos tardar a que pierdas plata.