Kit de Ferramentas para Automação Zendesk

Runtime Cybertron V2

Para uma automação nova, cadastre primeiro o bot e o seu time no Cybertron. O Infisical injeta CYBERTRON_V2_API_URL, CYBERTRON_V2_API_TOKEN, CYBERTRON_AUTOMATION_ID. A área é resolvida pelo catálogo no backend. A biblioteca não contém domínios nem rotas da API: ela descobre o contrato no servidor.

from cybertron_spark import AutomationRuntime

runtime = AutomationRuntime.from_env()
runtime.start(metadata={"environment": "production"})
runtime.update_queue(12, external_id="12345")
runtime.waiting()

# ao iniciar e concluir um caso
runtime.running()
runtime.record_processed(
    "15110987",
    source_type="zendesk",
    processed_type="ticket",
    input_snapshot={"status": "open"},
    decision_data={"action": "enrich"},
    output_data={"result": "updated"},
)
runtime.checkpoint()

Um segredo obrigatório ausente interrompe o boot e informa seu nome. Use runtime.fail_critical(exc) para registrar a falha fatal antes de o processo encerrar e o Kubernetes assumir a recuperação.

Uma biblioteca Python projetada para acelerar o desenvolvimento de robôs de automação de processos (RPA) que interagem com a plataforma Zendesk. Ela combina a automação de interface de usuário (UI) com o Selenium e a interação via API com o Zenpy, além de fornecer componentes integrados para monitoramento (Heartbeat) e logging estruturado (BotsLogger).

Principais Funcionalidades 🚀 Gerenciamento de Driver: Crie e gerencie drivers do Selenium (Chrome, Firefox) de forma simplificada, com suporte para execução local e remota (Selenoid).

Automação UI Zendesk: Um conjunto de métodos de alto nível para interagir com a interface do Zendesk, como fazer login, preencher campos, submeter tickets, aplicar macros e muito mais.

Integração API Zendesk: Um wrapper conveniente para a biblioteca Zenpy que facilita a autenticação e a extração de dados da API do Zendesk, como buscar tickets em uma visualização.

Monitoramento e Alertas: Para novas automações, AutomationRuntime registra execução, progresso, filas, itens processados e falhas críticas exclusivamente na API Cybertron V2. Heartbeat permanece disponível somente para compatibilidade dos bots ainda não migrados.

Logging Estruturado: A classe BotsLogger gera eventos JSON no stdout, com identificação do bot, execução, ambiente e contexto por ticket. Dados enviados nos atributos com chaves sensíveis são mascarados automaticamente.

Runtime para RPAs: AutomationRuntime é o runtime padrão para RPAs e DAGs migrados. BotRuntime é apenas um alias temporário de compatibilidade para o mesmo runtime V2; ele não envia chamadas para a API legada.

Instalação Instale a biblioteca usando o pip:

Bash

pip install cybertron-spark==0.3.3 Como Usar A biblioteca é dividida em componentes modulares que podem ser usados em conjunto para construir um robô robusto.

1. Configurando o Driver do Selenium (Driver_Selenium) Esta classe abstrai a configuração do WebDriver.

Python

from cybertron_spark import Driver_Selenium

Configura um driver remoto (Selenoid) para o Chrome em modo headless

config_driver = Driver_Selenium( ipselenoid='http://seu-ip-selenoid:4444/wd/hub', browser='chrome', headless=True )

Cria a instância do driver

driver = config_driver.criar_driver()

print("Driver criado com sucesso!")

... seu código de automação aqui ...

driver.quit()

2. Monitorando o Robô (Heartbeat) Envie o status do seu robô para um painel de acompanhamento.

from cybertron_spark import Heartbeat

Instancia o Heartbeat com as credenciais da sua API de monitoramento

heartbeat = Heartbeat( bot_id='MEU_BOT_ZENDESK_01', endpoint='https://api.meupainel.com/status', token='SEU_TOKEN_SECRETO' )

Envia um status

heartbeat.alertas(status=execucao) print("Status 'EM EXECUÇÃO' enviado.")

Envia o ID de um ticket processado para contagem

heartbeat.alertas(ticket_id='12345') print("Registro do ticket 12345 enviado.")

Ao final, informa que o bot está ocioso

heartbeat.alertas(status=aguardando) print("Status 'AGUARDANDO CASOS' enviado.")

3. Usando a API do Zendesk (Zendesk_Zenpy) Busque tickets de uma visualização específica antes de iniciar a automação da UI.

from cybertron_spark import Zendesk_Zenpy

Autentica na API do Zendesk

zen_api = Zendesk_Zenpy( zlogin='seu_email@empresa.com/token', zpass='SEU_TOKEN_DA_API_ZENDESK', instancia='sua-instancia-zendesk' )

Pega todos os tickets da visualização com ID 9000

ID_DA_FILA = 9000 tickets_para_processar = zen_api.pegar_tickets(fila=ID_DA_FILA)

if tickets_para_processar: print(f"Encontrados {len(tickets_para_processar)} tickets: {tickets_para_processar}") else: print("Nenhum ticket encontrado na fila.") 4. Automatizando a Interface (Zendesk_Selenium) Após obter um ticket, use o Selenium para interagir com ele.

Python

from cybertron_spark import Zendesk_Selenium, Driver_Selenium

(Supondo que você já tenha um 'driver' criado)

driver = Driver_Selenium(...).criar_driver()

Instancia o controlador da UI do Zendesk

zen_ui = Zendesk_Selenium( driver=driver, usuario='seu_usuario_zendesk', senha='sua_senha_zendesk', instancia='sua-instancia-zendesk' )

Realiza o login

zen_ui.login() print("Login realizado com sucesso.")

Navega até um ticket e realiza ações

ticket_id = '12345' driver.get(f"https://sua-instancia-zendesk.zendesk.com/agent/tickets/{ticket_id}")

zen_ui.esperar_carregamento()

Aplica uma macro

zen_ui.aplicar_macro("Nome da Macro::Opção")

Adiciona uma observação interna

zen_ui.enviar_mensagem("Este ticket foi processado pelo robô.")

Submete o ticket como resolvido

zen_ui.enviar_ticket('resolvido') print(f"Ticket {ticket_id} resolvido.")

driver.quit()

5. Logging Estruturado (BotsLogger) Emita eventos JSON para o coletor de logs da plataforma. O logger não depende do Heartbeat: cada mecanismo permanece responsável por sua própria finalidade.

Python

from cybertron_spark import BotsLogger

logs = BotsLogger(bot_id='meu_bot', environment='production') logger = logs.get_logger(name)

ticket_id = '12345'

try: # Simula um erro raise ValueError("Ocorreu um problema inesperado.") except Exception as e: logger.exception( 'Falha ao processar ticket', extra={ 'event': 'ticket.processing_failed', 'ticket_id': ticket_id, }, )

logger.info('Ticket iniciado', extra={'event': 'ticket.started', 'ticket_id': ticket_id})

6. Runtime para RPAs Contínuos (AutomationRuntime)

Facilitadores V2 (0.3.4)

caso.confirm_zendesk(zenpy, status='open', previous_updated_at=antes.updated_at, comment_body=mensagem, previous_comment_ids=ids_anteriores) reconsulta a API a cada 5s, por até 60s, e retorna a evidência confirmada. Também aceita tag, custom_fields e expected_fields. Cada etapa tem seu próprio prazo, sem repetir envio ou adicionar tags novamente. caso.confirm(callback) oferece o mesmo mecanismo para outras origens. O callback deve apenas ler dados. O helper Zendesk limpa o cache de tickets Zenpy antes de cada consulta para não confundir objeto antigo/alterado em memória com persistência confirmada. Timeout sem evidência gera erro crítico; falha de auditoria permanece imediata. Chamadas de rede precisam de timeout próprio, pois não são interrompidas pelo prazo de polling. Zendesk_Playwright.fechar_ticket_atual() agora sempre espera 5s antes do atalho de fechamento para permitir a execução dos gatilhos.

from cybertron_spark import AutomationRuntime, require_env

with AutomationRuntime(require_env('BOT_ID')) as runtime:
    # Cadastro prévio obrigatório; área/time obtidos somente do backend.
    logger = runtime.logger  # run_id real já vinculado; não alterar logs.context.
    driver = runtime.browser(playwright)  # configuração local/Selenwright validada.
    runtime.update_queue(len(tickets), external_id=fila)
    for ticket in tickets:
        with runtime.ticket(ticket, queue_id=fila) as caso:
            caso.input_snapshot = entrada_observada
            caso.decision_data = criterios
            caso.checkpoint('validated_before_submit')
            # Operação de negócio e confirmação no sistema de destino.
            caso.output_data = resultado_confirmado
            caso.success()  # ou caso.reject('codigo', 'motivo')
    runtime.waiting()

O context manager abre/finaliza o run, envia heartbeat em background e reporta falhas críticas. Exceções no contexto do ticket auditam FAILED e propagam; encerrar sem resultado explícito também não conta como sucesso. Falha de entrega da auditoria é crítica: não repetir a operação de negócio automaticamente. Checkpoint é telemetria de progresso, não persistência transacional/retomada. Logs JSON vão para stdout/SigNoz; casos e eventos críticos são persistidos na V2.

Desde 0.3.6, o log browser.connection_started inclui session_name, sem expor URL ou credenciais. A sessão remota recebe o nome do bot desde 0.3.5. A UI Selenwright deve ler caps.name de /status; versões que ignoram esse campo mostram um nome genérico mesmo quando a biblioteca enviou a identificação correta.

runtime.browser usa SELENWRIGHT_LOCAL=true para Playwright local. No modo remoto exige SELENWRIGHT_URL e SELENWRIGHT_TOKEN, sem URLs de fallback. O helper é opt-in: construtores Playwright e interfaces Heartbeat/Selenium/Zenpy legadas mantêm suas assinaturas. O fechamento Playwright passa a esperar 5s em todas as chamadas. Faltas de secrets mostram seu nome no erro. from_env() continua priorizando CYBERTRON_AUTOMATION_ID quando presente, com fallback para BOT_ID; usar o construtor com BOT_ID evita identidades herdadas incorretas quando esse valor é o identificador oficial do cadastro.

Nesta versão, BotRuntime é alias exclusivamente V2; as interfaces antigas do BotRuntime não são mantidas. Bots legados que usam Heartbeat permanecem iguais.

from cybertron_spark import AutomationRuntime

runtime = AutomationRuntime.from_env()
runtime.start(metadata={'execution_type': 'deployment', 'brands': ['magalu']})

try:
    # Fluxo de negócio do bot.
    runtime.record_processed('12345', source_type='zendesk', processed_type='ticket')
finally:
    runtime.finish()

O runtime abre a execução, envia heartbeat automático e registra progresso somente na V2. As variáveis obrigatórias são fornecidas por Infisical ou .env; se qualquer uma estiver ausente, o boot falha indicando o nome exato do segredo.

7. Consultas BigQuery auditáveis

Para bots que tomam decisões com dados do BigQuery, use o helper do runtime. Ele captura automaticamente o identificador do job, projeto, localização, datas, volume processado, uso de cache e o hash da SQL. A SQL integral não é enviada a logs nem ao payload.

from google.cloud import bigquery
from cybertron_spark import consultar_bigquery

consulta = consultar_bigquery(
    bigquery.Client(),
    "SELECT protocolo, status FROM operacao.protocolos",
    query_name="protocolos_pendentes_v1",
)

for linha in consulta.to_records(include_fields=["protocolo", "status"]):
    # Execute a regra de negócio e, ao publicar na API Cybertron V2, envie:
    payload = consulta.payload_do_item(linha)
    # payload["source_metadata"] identifica a consulta/job.
    # payload["input_snapshot"] preserva o retrato lido pelo bot.

Use include_fields para definir, por automação, quais colunas compõem a prova operacional. Isso evita persistir colunas que não contribuem para a auditoria. O helper é opcional: bots que não usam BigQuery não precisam instalar nem configurar nada adicional.

8. API Cybertron V2 e ambientes pelo Infisical

O endereço da V2 é definido pelo ambiente no Infisical, e não pelo código do bot. Configure a mesma chave nos dois ambientes, com valores distintos:

Configure CYBERTRON_V2_API_TOKEN no mesmo caminho de secrets. A biblioteca recebe as variáveis já injetadas pelo Infisical; ela não executa login no cofre, não grava .env e não possui URL fixa de ambiente.

O cadastro do time e da automação é feito pela interface Cybertron V2. Isso
centraliza propriedade, permissões, workload Kubernetes e política de saúde;
o script só recebe `CYBERTRON_AUTOMATION_ID` do
Infisical.

CYBERTRON_API_URL continua reservado ao Heartbeat dos bots ainda legados. AutomationRuntime nunca o lê nem envia telemetria para a V1.

Exemplo Completo: Estrutura de um Robô Juntando todos os componentes para criar um fluxo de automação robusto.

Python

from rpa_zendesk_toolkit import ( Heartbeat, BotsLogger, Driver_Selenium, Zendesk_Zenpy, Zendesk_Selenium, execucao, aguardando, erro ) import time

--- 1. CONFIGURAÇÃO INICIAL ---

HEARTBEAT_CONFIG = { 'bot_id': 'ZENDESK_PROCESSOR_01', 'endpoint': 'https://api.meupainel.com/status', 'token': 'SEU_TOKEN_SECRETO' }

ZENDESK_API_CREDS = { 'zlogin': 'seu_email@empresa.com/token', 'zpass': 'SEU_TOKEN_DA_API_ZENDESK', 'instancia': 'sua-instancia' }

ZENDESK_UI_CREDS = { 'usuario': 'seu_usuario_zendesk', 'senha': 'sua_senha_zendesk', 'instancia': 'sua-instancia' }

SELENOID_IP = 'http://seu-ip-selenoid:4444/wd/hub'

ID_FILA_ZENDESK = 9000

--- 2. INICIALIZAÇÃO DOS COMPONENTES ---

heartbeat = Heartbeat(**HEARTBEAT_CONFIG)

logger = BotsLogger(heartbeat_instancia=heartbeat)

zen_api = Zendesk_Zenpy(**ZENDESK_API_CREDS)

--- 3. LOOP PRINCIPAL DO ROBÔ ---

def main(): driver = None try: heartbeat.alertas(status=aguardando) tickets = zen_api.pegar_tickets(fila=ID_FILA_ZENDESK)

    if not tickets:
        print("Nenhum ticket na fila. Aguardando...")
        return

    heartbeat.alertas(status=execucao)

    # Cria o driver apenas se houver tickets para processar
    driver_manager = Driver_Selenium(ipselenoid=SELENOID_IP)
    driver = driver_manager.criar_driver()

    zen_ui = Zendesk_Selenium(driver=driver, **ZENDESK_UI_CREDS)
    zen_ui.login()

    for ticket_id in tickets:
        try:
            print(f"Processando ticket: {ticket_id}")
            driver.get(f"https://{ZENDESK_UI_CREDS['instancia']}.zendesk.com/agent/tickets/{ticket_id}")
            zen_ui.esperar_carregamento()

            # --- Lógica de negócio do seu robô ---
            zen_ui.enviar_mensagem(f"Processamento automático iniciado pelo bot {HEARTBEAT_CONFIG['bot_id']}.")
            time.sleep(2) # Simula trabalho
            zen_ui.enviar_ticket('pendente')
            zen_ui.esperar_carregamento()
            # ------------------------------------

            heartbeat.alertas(ticket_id=ticket_id) # Registra sucesso

        except Exception as e:
            logger.error(
                error=e,
                message=f"Erro ao processar ticket {ticket_id}",
                ticket_id=ticket_id
            )
            # Pular para o próximo ticket em caso de erro

except Exception as e:
    acao = logger.error(
        error=e,
        message="Erro crítico na execução principal do robô",
        ticket_id="N/A",
        error_type='CRITICAL'
    )
    if acao == 'stop':
        heartbeat.alertas(status=erro)
        # Adicione lógica para parar o robô de forma segura

finally:
    if driver:
        driver.quit()
    print("Ciclo finalizado.")

if name == 'main': while True: main() time.sleep(60) # Espera 1 minuto antes de verificar a fila novamente

Integração com Playwright e Selenwright 🚀

A biblioteca agora conta com suporte nativo ao Playwright, oferecendo automações muito mais rápidas, estáveis e resilientes (auto-wait) em comparação com o Selenium tradicional.

Foram adicionados módulos específicos para gerenciar instâncias de navegador e interagir com sistemas estratégicos (Zendesk, Sandiego e MLAdmin).

1. Configurando o Driver do Playwright

A classe Driver_Playwright gerencia a criação de contextos e páginas, com suporte a instâncias locais e remotas (Selenwright).

from playwright.sync_api import sync_playwright
from cybertron_spark.playwright_manager import Driver_Playwright

with sync_playwright() as p:
    driver_manager = Driver_Playwright(
        playwright_instance=p, 
        local=True, 
        headless=False 
    )
    browser, context, page = driver_manager.criar_browser()
  
    # ... passe o objeto 'page' para as classes de automação ...
  
    browser.close()

2. Automação Playwright: Zendesk

Realize fluxos completos na Zendesk de forma mais rápida.

from cybertron_spark.playwright_manager import Zendesk_Playwright

zen = Zendesk_Playwright(page=page, instancia="sua-instancia")
zen.login()

zen.abrir_ticket("1234567")
zen.aplicar_macro("Classificação::Teste")
zen.enviar_mensagem("<p>Nota interna automática via Playwright</p>", publica=False)
zen.enviar_ticket("aberto")
zen.fechar_ticket_atual() # Limpa a aba para não sobrecarregar a memória

3. Automação Playwright: Sandiego

Gerencie cancelamentos e trocas de pedidos diretamente no sistema Sandiego.

from cybertron_spark.playwright_manager import Sandiego_Playwright

sandiego = Sandiego_Playwright(page=page)
sandiego.login()

# Tenta realizar a troca e valida se o botão 'Abrir Ticket' está habilitado
sucesso = sandiego.gerar_troca(numero_pedido="1019386971")
if sucesso:
    print("Troca gerada com sucesso.")

4. Automação Playwright: MLAdmin

Gerencie fluxos para pedidos 1P (que possuem pacotes) no MLAdmin, incluindo suporte avançado a interceptação de alertas em tela (Dialog).

from cybertron_spark.playwright_manager import MLAdmin_Playwright

mladmin = MLAdmin_Playwright(page=page)
mladmin.login()

# Tenta gerar um vale-compras e o robô já intercepta alertas nativos do sistema
sucesso = mladmin.gerar_vale(pacote="987654321")
if sucesso:
    print("Vale gerado com sucesso.")

Licença
Este projeto está licenciado sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.


## 0.3.7 — decisões e fechamento Zendesk (preparada localmente)

`RuntimeCase.confirm_zendesk` registra em INFO status observado, motivo de espera,
evidência de comentário novo, presença de tag e resultado de campos, sem expor
comentários ou protocolos. `fechar_ticket_atual()` espera 5s pelos gatilhos,
aguarda save e confirma saída da rota do ticket por até 30s, também conferindo
remoção da aba quando o DOM fornece role/link. True comprova fechamento da tela,
nunca salvamento: confirmar persistência pela API antes de fechar.

Não descarta rascunhos por padrão. `descartar_alteracoes=True` é reservado à
rejeição explícita; mesmo nesse caminho verifica fechamento. O caller deve
interromper se False, sem acumular abas ou reenviar alterações. Envio aguarda
notificação real de erro; is_visible não espera timeout. Falhas ao abrir ticket,
ler status e preencher mensagem são propagadas, sem inventar sucesso/status.
Versão entregue como wheel nos bots; publicação PyPI não faz parte desta alteração.