transdesk-importer-python-sdk
SDK Python para leitura e transformacao de planilhas de apolices da Transdesk
no formato interno consumido pela 77seg-core-api.
O SDK e puro: ele apenas le, transforma e valida a planilha, devolvendo modelos tipados. Ele nao grava no banco, nao cadastra leads/corretoras e nao gera link de assinatura -- essas responsabilidades ficam na core-api (ver Referencia de enrichment).
Instalacao
pip install transdesk-importer-python-sdk
Requer Python >= 3.11.
Uso
A entrada pode ser bytes (upload em memoria), um objeto file-like binario ou
um caminho de arquivo. O formato (.xls/.xlsx) e detectado automaticamente
por magic bytes -- nao depende da extensao.
from transdesk.importer import TransdeskImporter
# 1) a partir de bytes (ex.: upload de um endpoint)
file_bytes = request.files["file"].file.read()
result = TransdeskImporter().import_policies(file_bytes)
# 2) a partir de um caminho
result = TransdeskImporter().import_policies("apolices.xls")
if not result.is_valid:
# result.errors -> list[ValidationError]
for err in result.errors:
print(err)
else:
for policy in result.policies: # list[InternalPolicy]
print(policy.reference_id, len(policy.data.items))
# serializacao pronta para JSON
payload = result.to_dict() # dict
as_json = result.to_json() # str (ensure_ascii=False)
Retorno
import_policies(file) devolve um ImportResult:
| Campo | Tipo | Descricao |
|---|---|---|
policies |
list[InternalPolicy] |
Apolices ja no formato interno |
errors |
list[ValidationError] |
Divergencias encontradas na validacao |
is_valid |
bool |
True quando errors esta vazio |
Helpers: result.to_dict() e result.to_json(**kwargs).
Principais modelos
- Saida (EN):
InternalPolicy,PolicyData,ResellerData,Broker,Lead,CustomerInfo,Telephone,Mobile,Address,InternalItem. - Canonico (PT, em
InternalPolicy.original_data):CanonicalPolicy,CanonicalItem,Subestipulante,Cliente,Endereco,DadosBancarios,UnidadeVenda,Cobertura,Complemento.
InternalItem tem um schema "achatado" e consistente: todos os campos de
cobertura e de risco estao sempre presentes; os que nao se aplicam ao tipo do
item (ex.: campos de vida num veiculo) vem como null.
Campos adicionais de veiculo/reboque (colunas apos CHAVE_PIX na planilha):
| Coluna planilha | Campo InternalItem |
Observacao |
|---|---|---|
EMPRESA_RASTREAMENTO |
vehicle_tracker_company |
Somente quando has_vehicle_tracker |
CATEGORIA |
vehicle_classification |
Classificacao do veiculo (texto) |
MARCA |
brand_name / brand |
Veiculo; reboque usa MARCA_REBOQUE |
MODELO |
model_description / model |
Veiculo; reboque usa MODELO_REBOQUE |
RENAVAM |
renavam |
|
COR |
color |
|
ANO |
model_year, manufacture_year |
Mesmo valor nos dois campos |
EIXOS |
axles |
|
CAMBIO |
transmission |
|
ALIENADO |
is_alienated |
N/A ou vazio = false |
Validacao
O ValidationError cobre tres tipos:
policy_count-- divergencia na contagem de apolices;item_count-- divergencia na contagem de itens de uma apolice;premium-- divergencia (apos arredondamento) entre o premio somado no canonico e o premio somado no formato interno de um item.
Arquitetura
planilha (bytes/file-like/path)
|
v
ExcelReader -> DataFrame
|
v
ApoliceBuilder -> list[CanonicalPolicy] (camada canonica, PT)
|
v
InternalMapper -> list[InternalPolicy] (camada interna, EN)
|
v
InternalPolicyValidator-> list[ValidationError]
|
v
ImportResult (policies + errors)
Desenvolvimento
python -m venv venv && source venv/bin/activate
pip install -e ".[dev]"
pytest
Publicacao: criar uma tag vX.Y.Z dispara o workflow de publish no PyPI
(.github/workflows/publish.yml).
Referencia de enrichment (core-api)
Esta secao nao faz parte do SDK. Ela preserva, como referencia, a logica de "enrichment" e persistencia que saiu do importer e deve ser portada para a
77seg-core-api.
Apos obter as InternalPolicy do SDK, a core-api deve:
- Completar os dados de cada apolice (cadastrar lead e unidade/corretora,
injetar
enterprise_id/reseller_ide os defaults da venda); - Persistir os registros das vendas no banco;
- Gerar o link de assinatura (Paperless) e atualizar o status para
pending_signature.
Codigo original (removido do SDK), que serve de base para a implementacao na core-api:
class InternalImportPipeline:
def __init__(self, enterprise_id, reseller_id):
self.enterprise_id = enterprise_id
self.reseller_id = reseller_id
def execute(self, policies):
policies = [self._complete_data(policy) for policy in policies]
policies = self._create_db_records(policies)
policies = self._generate_signature_link(policies)
return policies
def _complete_data(self, policy):
lead = policy.get('data').get('lead')
# TODO: gerar o cadastro do lead no BD
broker = policy.get('data').get('reseller').get('broker')
# TODO: gerar o cadastro da unidade (corretora) no BD
# TODO: gerar o cadastro do vendedor padrao da unidade (corretora) no BD
# preencher os dados faltantes
policy.update({
'enterprise': {'id': self.enterprise_id},
'reseller': {'id': self.reseller_id, 'person': broker},
'lead': lead,
'status': 'quotation_completed',
'payment_method': 'bank_slip',
'multi': True,
'active': True,
'deleted': False
})
return policy
def _create_db_records(self, policies):
# TODO: insere os registros no BD
return policies
def _generate_signature_link(self, policies):
# TODO: gera o link de assinatura (via Paperless) para cada venda
# TODO: atualiza o status da venda p/ pending_signature
return policies
Ponto de integracao na core-api (esboco):
from transdesk.importer import TransdeskImporter
result = TransdeskImporter().import_policies(file_bytes)
if not result.is_valid:
... # retornar result.errors
policies = [p.to_dict() if hasattr(p, "to_dict") else p for p in result.policies]
# aplicar _complete_data / _create_db_records / _generate_signature_link aqui
Metadata
Release files for transdesk-importer-python-sdk 1.3.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| transdesk_importer_python_sdk-1.3.3.tar.gz | 25.7 kB | Without provenance | Details for transdesk_importer_python_sdk-1.3.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| transdesk_importer_python_sdk-1.3.3-py3-none-any.whl | Python 3 | none | any | Details for transdesk_importer_python_sdk-1.3.3-py3-none-any.whl |
Total release size: 51.2 kB
Release files / transdesk_importer_python_sdk-1.3.3.tar.gz
| Download URL | transdesk_importer_python_sdk-1.3.3.tar.gz |
|---|---|
| Size | 25.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c4fdc09f7313ac423d7c7cff547d9b61fa8835f1313bed221760fb13b8585492
|
|
BLAKE2b-256 checksum How to use checksums |
c420851a9bd408da8029409086eabd8b952a8f263c2871585a28bdde40081938
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / transdesk_importer_python_sdk-1.3.3-py3-none-any.whl
| Download URL | transdesk_importer_python_sdk-1.3.3-py3-none-any.whl |
|---|---|
| Size | 25.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
211e109353c6dd062746f7d2935417435d971f01452544f59896b8d15f92bc9a
|
|
BLAKE2b-256 checksum How to use checksums |
decd8f324951287cb400577e61547c223c2f64fd9b6221a50b33c7fc78c0bae8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for transdesk-importer-python-sdk 1.3.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.