csc-cia-stne

Biblioteca interna desenvolvida e mantida pelo time CSC-CIA da Stone, voltada ao desenvolvimento de RPAs e rotinas automatizadas.

Reúne integrações com sistemas internos e externos (Stone Admin, ServiceNow, Salesforce, Waccess, BC Correios, BC STA, GCP — BigQuery / Storage / Document AI / Drive, Slack, e-mail, FTP/SFTP, Provio, Jerry/IA) e utilitários comuns para bots (logging, segredos, datetime, base64, PDF, configuração por ambiente, etc.).

O objetivo é não precisar reimplementar, em cada novo robô, funcionalidades que já são usadas com frequência pelo time.

Instalação

Em projetos novos, recomendamos o uso do uv:

uv init meu-projeto
uv add csc-cia-stne

Para adicionar a uma rotina já existente:

uv add csc-cia-stne

Também é possível instalar via pip:

pip install csc-cia-stne

Python suportado: 3.10+ (recomendado 3.11 ou superior).

Recursos / Módulos

A lib é organizada em módulos por integração/funcionalidade. Os principais são:

Todas as classes abaixo são importadas diretamente do pacote raiz: from csc_cia_stne import <Classe>.

Integrações Stone / internas

Classe	Descrição
`StoneAdmin`	Stone Banking / Open Bank API — verificação de cliente, extratos, recibos, titularidade
`ServiceNow`	ServiceNow — tickets, anexos, tasks, variáveis e listagem com paginação
`SalesForce`	Salesforce (JWT Bearer) — Cases, feed completo (Chatter + alterações de campo + e-mails), anexos de 3 fontes, encerramento, owner
`Karavela`	Helpers para execução em ambiente Karavela (health-check de container)
`Waccess`	Waccess — usuários, fotos, grupos e cartões de acesso físico
`Provio`	Provio — exportação do relatório geral de provisões
`JerryClient`	Cliente da API Jerry (IA / OCR / chat completions Stone via Databricks)

Banco Central / órgãos externos

Classe	Descrição
`BC_Correios`	Automação do BC Correios
`BC_STA`	Automação do BC STA (Sistema de Transferência de Arquivos)

Google Cloud

Classe	Descrição
`BigQuery`	Consultas, inserções e utilitários para BigQuery
`GCPBucket`	Upload/download de arquivos em buckets GCS
`GCPDocumentAIClient`	OCR e extração via Google Document AI
`GoogleDrive`	Upload/download e organização de arquivos no Google Drive

Comunicação e arquivos

Classe	Descrição
`Slack`	Envio de mensagens, arquivos, threads e attachments (highlights) para canais Slack
`Email`	Envio de e-mails via SMTP do Gmail (com anexos, CC, CCO, máscara de remetente)
`FTP`	Cliente FTP/FTPS/SFTP (pycurl) com retry automático
`web_screen`	Factory de automação web (Selenium / BotCity)

Logging

Símbolo	Descrição
`logger`	Factory: `log = logger("meu_modulo")`. Decide automaticamente entre formato Rich (local/console) e JSON (Karavela/container) conforme a variável `ambiente_de_execucao`.

Utilitários (`csc_cia_stne.utilitarios`)

Segredos e configuração

get_secret — resolução de segredos com fallback (env → ./secrets/ → ./.secrets/ → ./private/ → ./.private/ → /secrets/ → BotMaestro)
get_config — leitura de settings.yaml por ambiente (dev/qa/prod)

Apresentação

titulo — header padronizado do robô (printa em local / loga em Karavela)

Base64 e conversões

b64encode / b64decode — utilidades base64 para strings UTF-8
convert_bquery_result_to_json — converte RowIterator do BigQuery em list[dict]
validate_json — valida e converte string JSON em objeto Python

Arquivos e pastas

recriar_pasta — remove e recria uma pasta
delete_file / delete_folder — exclusão segura com retorno padronizado

Datetime

now_sp — datetime atual no fuso de São Paulo (America/Sao_Paulo)

PDF — extração parcial (útil antes de OCR/IA, para economizar tokens)

extrair_x_paginas_pdf — primeiras N páginas a partir de um arquivo em disco
extrair_paginas_intervalo_pdf — intervalo arbitrário (1-indexed)
extrair_x_paginas_pdf_from_base64 — mesma coisa a partir de string base64

Quickstart

Setup mínimo de uma rotina

from csc_cia_stne import logger
from csc_cia_stne.utilitarios import titulo

log = logger(__name__)

titulo(
    project_name="Minha rotina",
    project_version="0.1.0",
    project_dev_name="Roberto Lins",
    project_dev_mail="roberto.lins@stone.com.br",
)

log.info("rotina iniciada")

Lendo um segredo com fallback automático

from csc_cia_stne.utilitarios import get_secret

# Resolve, nesta ordem: env var → ./secrets/MINHA_SECRET → ./.secrets/... → /secrets/... → BotMaestro
senha = get_secret(name="MINHA_SECRET")

if senha is None:
    raise RuntimeError("Segredo MINHA_SECRET não encontrado")

Consultando tickets no ServiceNow

from csc_cia_stne import ServiceNow
from csc_cia_stne.utilitarios import get_secret

svc = ServiceNow(
    username=get_secret(name="SERVICENOW_USERNAME"),
    password=get_secret(name="SERVICENOW_PASSWORD"),
    env="qa",
)

resultado = svc.listar_tickets(
    tabela="x_stps2_services_catalog_base_task",
    campos=["number", "sys_id", "state"],
    query="assignment_group=45251cd61bed42544867a68fe54bcbe3",
    limite=50,
)

for ticket in resultado["content"]["result"]:
    print(ticket["number"]["display_value"])

Karavela: secrets e health-check

from csc_cia_stne import Karavela

k = Karavela()
token = k.get_secret(name="MEU_TOKEN")

k.create_health_check_file(health_check_filename="./healthy_check/healthy")
# ... execução do robô ...
k.destroy_health_check_file()

Salesforce: listar Cases e baixar anexos

from csc_cia_stne import SalesForce
from csc_cia_stne.utilitarios import get_secret

sf = SalesForce(
    iss=get_secret(name="SF_CLIENT_ID"),
    sub=get_secret(name="SF_USERNAME"),
    version="60.0",
    private_key_content=get_secret(name="SF_PRIVATE_KEY"),
)
if not sf.is_connected:
    raise RuntimeError(sf.error)

# Listagem paginada de Cases (datas já convertidas para SP)
casos = sf.listar_casos(
    query="SELECT Id, CaseNumber, Subject FROM Case WHERE Status = 'Novo'",
    paginar=True,
)

# Anexos consolidados (Files + Attachments + EmailAttachments)
arquivos = sf.listar_arquivos_caso(caso_id=casos.data["records"][0]["Id"])

Variáveis de ambiente

Variável	Descrição
`ambiente_de_execucao`	Quando definida como `karavela`, o logger passa para o formato JSON e o helper `titulo` passa a logar (em vez de printar).
`log_level`	Nível mínimo do logger (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`).

Demais variáveis específicas (credenciais, URLs, etc.) são consumidas por cada módulo conforme necessidade — consulte a documentação interna.

Convenções importantes

Antes de usar a lib em produção, é importante conhecer alguns padrões:

Envelope de retorno: a maioria dos métodos retorna dict no formato {success/status, data/result, error}. Em geral, não levantam exceção nas operações de negócio — sempre cheque o status do dict.
.env no cwd: várias classes carregam um .env do diretório atual via python-dotenv no __init__. Em jobs que rodam fora do diretório do projeto, garanta que o .env seja resolvido de outra forma.
Conexões silenciosas: alguns construtores não levantam exceção quando a conexão falha. Cheque atributos como is_connected e error antes de usar.
Logger é factory: from csc_cia_stne import logger devolve uma função. Use log = logger("meu_modulo"). O formato (Rich x JSON) é decidido automaticamente pelo ambiente.
Detecção de ambiente Karavela: definindo ambiente_de_execucao=karavela, o logger e o titulo mudam para o modo container/JSON sem alteração de código.

Documentação

A documentação completa, com exemplos por classe e receitas (padrões maduros usados em produção: logger console+arquivo, agente Jerry+LangChain com saída Pydantic, OCR + classificação por IA, pipeline GCS → Google Drive, etc.), está no repositório interno:

GitHub — stone-payments/cia-libs (acesso restrito)

Suporte

Time mantenedor: CSC-CIA / Stone
Contato: cia@stone.com.br
Licença: MIT

Release files for csc-cia-stne 0.1.80

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for csc-cia-stne 0.1.80
File	Size	Uploaded
csc_cia_stne-0.1.80.tar.gz	129.1 kB	Aug 4, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for csc-cia-stne 0.1.80
File	Interpreter	ABI	Platform	Reset
csc_cia_stne-0.1.80-py3-none-any.whl 145.2 kB Aug 4, 2026	Python 3	none	any	Details

Total release size: 274.3 kB

Release files / csc_cia_stne-0.1.80.tar.gz

Download URL	csc_cia_stne-0.1.80.tar.gz
Size	129.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`c4f22d0330c7240bab7227a2b9460f30eeca08d19e2fc0187064c4b5ed326d7c`
BLAKE2b-256 checksum How to use checksums	`587712af2d9bcd9caa4d60dc5929c3a46c9d9e2168dc1afcf9163bdf76621872`
Upload date	Aug 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.9`

Release files / csc_cia_stne-0.1.80-py3-none-any.whl

Download URL	csc_cia_stne-0.1.80-py3-none-any.whl
Size	145.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`82c0321d3a9ada71a33ea030528c1c44bbbb4b16b0649366b343b7b4e0b5b359`
BLAKE2b-256 checksum How to use checksums	`ee2ec85c9dc7fd9a10c6f884c96ff82d568556027065a8d44805b32d4cd557d2`
Upload date	Aug 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.9`