Exemplos Python
Os exemplos usam a biblioteca requests.
pip install requests
Cliente
# tesselys.py
import json
import os
import random
import time
import requests
BASE_URL = os.environ.get("TESSELYS_URL", "https://erp-api.ideros.api.br/external/v1")
class TesselysError(Exception):
def __init__(self, status, body, request_id=None):
body = body or {}
super().__init__(body.get("friendlyMessage") or f"HTTP {status}")
self.status = status
self.code = body.get("code")
self.errors = body.get("errors", [])
self.request_id = request_id
class TesselysClient:
def __init__(self, api_key: str, secret: str):
self.api_key = api_key
self.secret = secret
self.access_token = None
self.company_token = None
self.expires_at = 0.0
self.session = requests.Session()
def authenticate(self):
res = self.session.post(
f"{BASE_URL}/auth",
headers={"x-api-key": self.api_key},
json={"secret": self.secret},
timeout=30,
)
body = res.json()
if not res.ok:
raise TesselysError(res.status_code, body)
self.access_token = body["accessToken"]
self.company_token = body["companyToken"]
# renova 30 segundos antes do vencimento informado
self.expires_at = time.time() + body["expiresIn"] - 30
def request(self, method, path, params=None, body=None, tentativa=0):
if not self.access_token or time.time() >= self.expires_at:
self.authenticate()
if params and isinstance(params.get("relations"), dict):
params = {**params, "relations": json.dumps(params["relations"])}
res = self.session.request(
method,
f"{BASE_URL}{path}",
headers={
"Authorization": f"Bearer {self.access_token}",
"x-company-token": self.company_token,
},
params=params,
json=body,
timeout=30,
)
data = res.json() if res.content else None
# token ou sessão da empresa vencidos: autentica de novo e repete uma vez
sessao_vencida = res.status_code == 401 or (
res.status_code == 403 and (data or {}).get("code") == "COMPANY_SESSION_EXPIRED"
)
if sessao_vencida and tentativa == 0:
self.authenticate()
return self.request(method, path, params, body, 1)
# limite de requisições: espera e tenta de novo
if res.status_code == 429 and tentativa < 5:
retry_after = res.headers.get("Retry-After")
espera = int(retry_after) if retry_after else 2 ** tentativa
time.sleep(espera + random.uniform(0, 0.5))
return self.request(method, path, params, body, tentativa + 1)
if not res.ok:
raise TesselysError(res.status_code, data, res.headers.get("X-Request-ID"))
return data
def list(self, resource, page=1, limit=25, relations=None):
params = {"page": page, "limit": limit}
if relations:
params["relations"] = relations
return self.request("GET", f"/{resource}", params=params)
def list_all(self, resource, limit=100, relations=None):
page = 1
while True:
result = self.list(resource, page=page, limit=limit, relations=relations)
yield from result["items"]
if page >= result["meta"]["totalPages"]:
return
page += 1
def get(self, resource, id):
data = self.request("GET", f"/{resource}/{id}")
return data if data and data.get("id") else None # {} significa "não encontrado"
def create(self, resource, body):
return self.request("POST", f"/{resource}", body=body)
def update(self, resource, id, body):
return self.request("PUT", f"/{resource}/{id}", body=body)
Uso
import os
from tesselys import TesselysClient, TesselysError
tesselys = TesselysClient(os.environ["TESSELYS_API_KEY"], os.environ["TESSELYS_SECRET"])
try:
# procura a pessoa pelo código do seu sistema; cria se não existir
encontradas = tesselys.list("persons", relations={"where": {"externalCode": "ERP-000123"}})
pessoa = encontradas["items"][0] if encontradas["items"] else tesselys.create(
"persons",
{
"personType": "COMPANY",
"name": "Tech Solutions Tecnologia Ltda",
"socialName": "Tech Solutions",
"documentNumber": "12345678000195",
"genre": "INDEFINITE",
"classifications": ["CUSTOMER"],
"externalCode": "ERP-000123",
},
)
# percorre todas as receitas do mês
filtro = {
"where": {
"typeCategory": "REVENUE",
"originalDueDate": {"gte": "2026-11-01", "lte": "2026-11-30"},
}
}
for lancamento in tesselys.list_all("financial-entries", relations=filtro):
print(lancamento["id"], lancamento.get("title"), lancamento.get("totalAmount"))
# abre um chamado
chamado = tesselys.create(
"tickets",
{
"requestedByType": "CUSTOMER",
"title": "Erro ao acessar relatório",
"description": "Ao abrir o relatório financeiro aparece uma mensagem de erro.",
"category": "INCIDENT",
"priority": "HIGH",
},
)
print("Chamado:", chamado["id"])
except TesselysError as err:
print(f"[{err.status}] {err}", err.code or "", err.request_id or "")
Recebendo webhooks
Veja o exemplo com Flask em Validação da assinatura.
Ainda com dúvida?
A nossa equipe ajuda você a configurar e usar esse recurso.