API de OuiHeberg: crear una clave API y hacer tu primera llamada

El área de cliente de OuiHeberg tiene su propia API. Con una clave API, un script o un programa consulta tu cuenta sin pasar por la interfaz, por ejemplo para vigilar tus dominios o tus facturas. Esta guía explica dónde crear una clave, cómo leer la documentación, hacer una primera llamada, respetar los límites y revocar una clave.

Abrir la sección Claves API

Inicia sesión en dash.ouiheberg.com.
Arriba a la derecha, haz clic en tu nombre y luego en Mi perfil.
En el menú de la página Ajustes de la cuenta, elige Claves API.

El enlace directo es dash.ouiheberg.com/settings?section=apikeys.

Sección Claves API de los ajustes de la cuenta, con los botones Documentación de la API y Nueva clave

Aquí aparecen tus claves. Mientras no hayas creado ninguna, verás Todavía no hay ninguna clave API. Cada clave solo accede a tu propia cuenta.

Crear una clave

Haz clic en Nueva clave.
Ponle un nombre claro, el del script o la herramienta que la va a usar. El día que ese script desaparezca, sabrás qué clave revocar.
Confirma la creación de la clave.
El área de cliente muestra la clave una sola vez. Cópiala enseguida y guárdala en un lugar seguro, por ejemplo en un gestor de contraseñas. No podrás volver a verla.

Una clave también se puede limitar a ciertas direcciones IP, por ejemplo las de los servidores que la usan. Sin lista, funciona desde cualquier dirección. Con lista, se rechaza toda llamada que llegue desde otra dirección.

💡 Si el área de cliente te pide activar la autenticación de dos factores antes de crear una clave, sigue nuestra guía Activar la autenticación de dos factores (2FA) y vuelve después a Claves API.

Leer la documentación de la API

El botón Documentación de la API de esta sección abre dash.ouiheberg.com/settings/api-docs.

Página de documentación de la API con la introducción, la autenticación, los errores y la lista de endpoints por familia

Esta documentación está hecha a medida de tu cuenta. Solo muestra los endpoints abiertos para ti, ordenados por familia (dominios, tienda, cuenta…). Cada línea indica su método, GET para leer, POST, PUT o PATCH para enviar o modificar, DEL para eliminar. Arriba, unas etiquetas indican cuántos endpoints tienes abiertos y cuántos modifican tu cuenta. El buscador de arriba a la izquierda encuentra un endpoint a partir de una palabra como «factura» o «dominio».

Conviene retener tres puntos de la introducción.

La dirección base de la API es https://dash.ouiheberg.com/api/v1.
Todas las respuestas están en JSON. Envía el encabezado Accept: application/json y añade Content-Type: application/json cuando la petición lleve un cuerpo.
Arriba de la página, Mis claves API te devuelve a tus claves y Área de cliente al área de cliente.

¿Falta un endpoint que necesitas? Entonces no está abierto para tu cuenta. Escríbenos un ticket explicando lo que quieres automatizar.

Hacer una primera llamada

Cada llamada lleva tu clave en el encabezado Authorization, precedida de la palabra Bearer. Guarda la clave en una variable de entorno, aquí OH_API_KEY, en lugar de escribirla en tus comandos. Una clave pegada en un script compartido o en un ticket es una clave que hay que revocar.

Esta es la primera llamada que propone la documentación.

curl -H "Authorization: Bearer $OH_API_KEY" -H "Accept: application/json" https://dash.ouiheberg.com/api/v1/domains/check

Para ver los parámetros de un endpoint y lo que devuelve, despliégalo en la documentación.

Probar desde la página

La documentación también te deja lanzar una llamada sin instalar nada. Pega una de tus claves en la página. No se guarda y desaparece si recargas. Luego lanza la prueba desde el endpoint desplegado.

Estas pruebas son llamadas reales. Una llamada que modifica tu cuenta la modifica de verdad, y la página te pide confirmación antes del envío. Una llamada que hace un pedido emite una factura real, igual que un pedido en la tienda.

Importar en Postman

La sección Importar en Postman ofrece una colección lista para importar, con tus endpoints ordenados por familia. El archivo no contiene tu clave. La introduces en Postman, en la variable prevista para ello.

Postman no te pide ninguna confirmación. Una llamada que modifica tu cuenta o hace un pedido sale en cuanto la envías.

Límites de llamadas

Cada clave tiene su propio límite de llamadas por minuto y por día, fijado al crearla. Todas las llamadas cuentan, incluidas las pruebas lanzadas desde la documentación. La sección Límites de llamadas de la documentación explica el funcionamiento.

Por encima del límite, la API responde con un error 429. Incluye una pausa en tus scripts en lugar de repetir la llamada en bucle. El límite por minuto se libera al cabo de un minuto, el diario al día siguiente.

Entender los errores

Una llamada rechazada devuelve un código HTTP y un cuerpo JSON. El campo code da el motivo exacto y no cambia de una versión a otra. Es el campo que deben leer tus programas. El campo message está pensado para personas.

Respuesta	Significado
`401`	La clave falta, es desconocida, está desactivada o ha caducado. Comprueba que la has copiado entera.
`403` `ip_not_allowed`	La clave solo acepta ciertas direcciones IP, y la llamada llegó desde otra.
`403` `endpoint_not_granted`	Este endpoint no está abierto para tu cuenta. Escríbenos para obtenerlo.
`403` `route_not_allowed`	El endpoint está abierto para tu cuenta, pero esta clave no lo cubre. Modifica la clave o usa otra.
`403` `api_access_blocked`	El acceso a la API de tu cuenta está suspendido. Escríbenos para saber el motivo.
`429` `rate_limit_exceeded`	Se ha alcanzado el límite por minuto de la clave. La respuesta indica cuánto esperar.
`429` `daily_quota_exceeded`	Se ha alcanzado el límite diario de la clave.

Revocar una clave

Revoca una clave en cuanto deje de usarse, o ante la menor duda, por ejemplo si se pegó en un ticket, se compartió en un script o se quedó en un ordenador perdido.

Abre Ajustes de la cuenta › Claves API.
En la línea de la clave, haz clic en Revocar.

Los programas que usaban esta clave reciben a partir de ahora un error 401. Si deben seguir funcionando, crea una clave nueva y sustituye la antigua en su configuración.

💡 ¿Eres revendedor? Las claves de la API de revendedor no se crean aquí, sino desde el área de revendedor, que se abre desde la sección Cuenta de revendedor.

¿Necesitas ayuda?

Para que abramos un endpoint o restablezcamos un acceso a la API, abre un ticket desde Tickets › Abrir un ticket (dash.ouiheberg.com/tickets/new) y describe lo que quieres automatizar. No pegues nunca tu clave en el ticket.
También puedes escribirnos en nuestro Discord.