Pular para conteúdo

Guia de Início Rápido

Este guia apresenta os passos mínimos para começar a usar o PLDPro SDK rapidamente.

Pré-requisitos

  • Python versão 3.10.16 ou superior
  • O gerenciador de pacotes e projetos uv instalado (opcional, mas recomendado)
  • Acesso ao servidor de API do PLDPro
  • Chave de API válida

Instalação do SDK

Obtendo o Pacote do SDK

Obtenha o pacote de SDK junto à equipe responsável pelo projeto do PLDPro, através do e-mail ecomerc@cepel.br.

O pacote terá o nome pldpro_sdk-x.y.z-py3-none-any.whl, onde x.y.z é a versão do SDK.

Ambiente Virtual

É recomendado criar um ambiente virtual para isolar as dependências do SDK.

Para criar e ativar um ambiente virtual, utilize os comandos abaixo conforme seu sistema operacional:

python3 -m venv venv
source ./venv/bin/activate

Caso tenha o uv instalado, você pode criar o ambiente virtual, instalar o Python 3.10 e ativá-lo diretamente com os seguintes comandos:

uv venv --python 3.10
source ./venv/bin/activate 

python -m venv venv
venv\Scripts\activate

Caso tenha o uv instalado, você pode criar o ambiente virtual, instalar o Python 3.10 e ativá-lo diretamente com os seguintes comandos:

uv venv --python 3.10
venv\Scripts\activate

Com o ambiente virtual ativo, instale o SDK utilizando o comando a seguir, substituindo pldpro_sdk-x.y.z-py3-none-any.whl pelo nome correto do arquivo recebido:

pip install pldpro_sdk-x.y.z-py3-none-any.whl

uv pip install pldpro_sdk-x.y.z-py3-none-any.whl

Autenticação

A autenticação junto ao PLDPro API é feita via API Key, que pode ser fornecida de duas formas:

  • Variável de ambiente (APP_API_KEY)
  • Parâmetro explícito no cliente 
    # Exemplo conceitual de criação do cliente com API Key explícita
PLDProClient(config, api_key="sua_api_key")

Exemplo de Uso

Com o SDK instalado e a API Key obtida, você já pode começar a utilizá-lo.

Crie um arquivo Python (por exemplo, quickstart.py) e adicione o código abaixo. Esse código é um exemplo básico de como criar um cliente, listar os nodes registrados e criar um novo caso.

"""Exemplo de uso básico do PLDPro SDK (quickstart.py)."""
import os
from pldpro_sdk import PLDProClient, SDKConfig
from pldpro_sdk.core.helpers import logger

def list_nodes(client: PLDProClient):
    """Lista os nodes registrados no servidor PLDPro API."""
    logger.info("Listando nodes registrados:")
    for node in client.nodes.list_nodes():
        logger.info(node.to_dict())

def create_empty_case_example(client: PLDProClient):
    """Cria um novo caso vazio."""
    logger.info("Criando um novo caso vazio...")
    caso = client.casos.create_caso("Caso de Exemplo Vazio")

    if caso:
        logger.info(caso.to_dict())

        # Removendo o caso criado para limpeza
        result = client.casos.delete_caso(caso.uuid)
        if result:
            logger.info(f"Caso {caso.uuid} removido com sucesso!")
        else:
            logger.warning(f"Caso {caso.uuid} não pôde ser removido!")


if __name__ == "__main__":
    # Busca da API Key na variável de ambiente
    api_key = os.getenv("APP_API_KEY")
    if not api_key:
        raise ValueError("A variável de ambiente 'APP_API_KEY' não está definida.")

    # Criação do cliente PLDPro SDK
    config = SDKConfig(
        host="https://pldpro-api.cepel.br/v1",
        retries=3)

    client = PLDProClient(config, api_key=api_key)

    # Listar nodes registrados
    list_nodes(client)

    # Criar um novo caso
    create_empty_case_example(client)

Abra um terminal, ative o ambiente virtual (se estiver usando) e execute os seguinte comando para rodar o script:

export APP_API_KEY="sua_api_key_aqui"
python quickstart.py

$Env:APP_API_KEY = "sua_api_key_aqui"
python quickstart.py

set APP_API_KEY="sua_api_key_aqui"
python quickstart.py

Atenção

Substitua "sua_api_key_aqui" pela chave de API válida.

Se tudo estiver configurado corretamente, o script irá listar os nodes registrados e criar um novo caso vazio, exibindo as informações no console.