Uso del SDK de Python (zinn-sdk)

zinn-sdk es nuestro cliente oficial de Python para la API de Zinn Digital®, publicado en PyPI e importado como zinn_sdk. Se genera a partir de la misma especificación OpenAPI sobre la que está construida la API, cada operación cuenta con variantes sincrónicas y asyncio, y se publica una nueva versión automáticamente cada vez que la especificación cambia. Esta guía lo instala, lo autentica y realiza sus primeras llamadas.

Instalar

pip install zinn-sdk

Requiere Python 3.11 o posterior y cuenta con licencia MIT.

Crear una clave de API

Abra la página Claves de API de su panel de control (app.zinndigital.com/api-keys) y pulse Crear una clave. Asigne un nombre a la clave y solo los permisos que su código necesite; por ejemplo, sites.view para listar sitios. La clave se muestra una sola vez; guárdela en una variable de entorno o en su almacén de secretos, nunca en el código fuente. Puede revocar una clave en cualquier momento en la misma página.

Los extremos públicos del catálogo, como las regiones de alojamiento y los planes, no necesitan ninguna clave.

Sus primeras llamadas

import os

from zinn_sdk import AuthenticatedClient, Client
from zinn_sdk.api.catalog import list_public_hosting_regions
from zinn_sdk.api.hosting import list_sites

# Public catalogue endpoints need no key.
public = Client(base_url="https://api.zinndigital.com")
regions = list_public_hosting_regions.sync(client=public)
print([region.slug for region in regions.data])

# Everything else uses a per-organisation API key.
api = AuthenticatedClient(base_url="https://api.zinndigital.com", token=os.environ["ZINN_API_KEY"])
page = list_sites.sync(client=api, limit=5)
for site in page.data:
    print(site.name, site.status)

Cómo encontrar una operación

Las operaciones se agrupan por área de la API en zinn_sdk.api y se nombran según su id de operación en formato snake case. Listar sitios es zinn_sdk.api.hosting.list_sites; dominios y DNS se encuentran en zinn_sdk.api.domains; facturación en zinn_sdk.api.billing. La referencia de la API muestra el id de cada operación.

Síncrono, asíncrono y respuesta completa

Cada módulo de operación tiene cuatro funciones:

• sync(...) devuelve el modelo analizado, o None ante un estado inesperado.
• sync_detailed(...) devuelve un Response con status_code, headers y parsed.
• asyncio(...) y asyncio_detailed(...) son equivalentes, pero ejecutables con await.

import asyncio

from zinn_sdk.api.hosting import list_sites

async def main() -> None:
    response = await list_sites.asyncio_detailed(client=api, limit=5)
    print(response.status_code, len(response.parsed.data))

asyncio.run(main())

Utilice las variantes _detailed cuando necesite distinguir un 403 (la clave carece de permiso) de un 404.

Adónde ir a continuación

• La guía en nuestro sitio web: zinndigital.com/developers/sdk-python
• Cada punto de conexión, sus parámetros y su permiso: zinndigital.com/developers/api
• El paquete en PyPI: pypi.org/project/zinn-sdk