Usando o SDK do Python (zinn-sdk)

O zinn-sdk é o nosso cliente Python oficial para a API da Zinn Digital®, publicado no PyPI e importado como zinn_sdk. Ele é gerado a partir da mesma especificação OpenAPI na qual a API é construída, cada operação possui variantes síncronas e asyncio, e uma nova versão é publicada automaticamente sempre que a especificação é alterada. Este guia realiza a instalação, a autenticação e as suas primeiras chamadas.

Instalação

pip install zinn-sdk

Requer o Python 3.11 ou posterior e é licenciado sob a MIT.

Criar uma chave de API

Abra a página Chaves de API do seu painel (app.zinndigital.com/api-keys) e pressione Criar uma chave. Dê um nome à chave e atribua apenas as permissões de que seu código precisa — por exemplo, sites.view para listar sites. A chave é exibida apenas uma vez; armazene-a em uma variável de ambiente ou em seu cofre de segredos, nunca no código-fonte. Você pode revogar uma chave a qualquer momento na mesma página.

Endpoints de catálogo público, como regiões de hospedagem e planos, não precisam de chave alguma.

Suas primeiras chamadas

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)

Localizando uma operação

As operações são agrupadas por área da API em zinn_sdk.api e nomeadas de acordo com o id da operação em snake_case. A listagem de sites é zinn_sdk.api.hosting.list_sites; domínios e DNS estão em zinn_sdk.api.domains; faturamento em zinn_sdk.api.billing. A referência da API exibe o id de cada operação.

Síncrono, assíncrono e a resposta completa

Cada módulo de operação possui quatro funções:

• sync(...) retorna o modelo analisado, ou None em caso de status inesperado.
• sync_detailed(...) retorna um Response com status_code, headers e parsed.
• asyncio(...) e asyncio_detailed(...) são idênticos, porém aguardáveis (awaitable).

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())

Use as variantes _detailed quando precisar distinguir um 403 (a chave não tem permissão) de um 404.

Para onde ir a seguir

• O guia em nosso site: zinndigital.com/developers/sdk-python
• Cada endpoint, seus parâmetros e sua permissão: zinndigital.com/developers/api
• O pacote no PyPI: pypi.org/project/zinn-sdk