Constaia
SDKs

SDK de Python

Referencia del SDK oficial constaia para Python 3.9+: clientes síncrono y asíncrono, entradas, opciones, paginación, errores, concurrencia y webhooks.

constaia es el SDK oficial para Python. Trae un cliente síncrono (Constaia) y otro asíncrono (AsyncConstaia) sobre httpx, respuestas tipadas con TypedDict, errores tipados, reintentos, límite de concurrencia en el cliente y verificación de webhooks. Requiere Python ≥ 3.9. Versión actual: 0.2.0.

pip install constaia

Primeros pasos

verify.py
from constaia import Constaia

client = Constaia()  # lee CONSTAIA_API_KEY

analysis = client.analyze(
    "dni_valid.jpg",
    expect="es_dni",
    checks={"not_expired": True, "holder": {"full_name": "María García López"}},
    language="es",
)

verdict = analysis["verdict"]
if verdict and verdict["status"] == "valid":
    print(analysis["fields"]["document_number"]["value"])  # 12345678Z
elif verdict and verdict["status"] == "review":
    print("Revisión manual:", analysis["warnings"])
else:
    for reason in verdict["reasons"] if verdict else []:
        print(reason["code"], reason["message"])

Con una clave ck_test_… no se gastan créditos y la respuesta depende del nombre del fichero. Ver Modo test.

Asíncrono

verify_async.py
import asyncio

from constaia import AsyncConstaia


async def main() -> None:
    async with AsyncConstaia() as client:
        analysis = await client.analyze(file_url="https://example.com/dni.jpg", expect="es_dni")
        print(analysis["verdict"])
        async for item in client.analyses.list(status="completed"):
            print(item["id"])


asyncio.run(main())

El cliente asíncrono tiene los mismos métodos con await. Ciérralo con await client.close() (o con async with).

Configuración

import httpx
from constaia import Constaia

client = Constaia(
    api_key="ck_live_...",  # por defecto: CONSTAIA_API_KEY
    base_url="https://api.constaia.com",  # por defecto; o CONSTAIA_BASE_URL
    timeout=60.0,  # segundos por intento
    max_retries=2,  # 0 desactiva los reintentos
    max_concurrency=4,  # peticiones en vuelo a la vez; el resto espera en el cliente
    default_headers={"X-Team": "ops"},
    http_client=httpx.Client(proxy="http://proxy:8080"),  # opcional
)

Crea un cliente por proceso y reutilízalo: comparte conexiones y el límite de concurrencia.

Qué ficheros acepta

analyze() y classify() reciben exactamente una de estas entradas:

EntradaEjemplo
Ruta (str o pathlib.Path)client.analyze("scans/dni.jpg")
Bytesclient.analyze(data, filename="dni.jpg")
Fichero binario abiertoclient.analyze(open("dni.pdf", "rb")), UploadedFile de Django, FileStorage.stream de Flask
Tupla (nombre, bytes)client.analyze(("dni.jpg", data))
URL remotaclient.analyze(file_url="https://example.com/dni.jpg")
Base64client.analyze(file_base64=b64, filename="dni.jpg")

JPEG, PNG, WEBP, HEIC y PDF, hasta 20 MB y 30 páginas en análisis síncrono. El SDK lee el fichero una vez en memoria para que los reintentos envíen los mismos bytes.

Opciones

Los nombres son los de la API (snake_case). Como async es palabra reservada en Python, la opción se llama async_.

analysis = client.analyze(
    "dni.jpg",
    expect=["es_dni", "es_nie", "passport"],  # sin expect: veredicto contra el tipo detectado
    checks={
        "not_expired": True,
        "min_age_years": 18,
        "holder": {"full_name": "María García López", "document_number": "12345678Z"},
        "require_fields": ["birth_date"],
    },
    extract=True,  # o tu propio JSON Schema (dict)
    storage="none",  # "none" | "temporary" | "persistent"
    ttl_hours=24,  # con "temporary"
    keep_results=True,
    async_=False,  # True → 202 y webhook
    export=["xlsx", "json"],
    metadata={"registration_id": "123"},
    language="es",
    idempotency_key="registration-123-dni",  # opcional: la tuya
    timeout=90,
)

Cada opción se explica en POST /v1/analyze y Comprobaciones.

processing

processing="sovereign" | "standard" elige qué proveedores de IA pueden procesar el documento; la respuesta trae analysis["processing"] con el perfil, la región y los proveedores usados. Ver Residencia de datos.

Métodos

client.analyze(file, **opciones)
client.classify(file, expect="invoice")  # 0,2 créditos

client.analyses.get("an_01J…")
page = client.analyses.list(limit=50, status="completed", type="es_dni", metadata={"event": "42"})
page.data, page.has_more  # primera página
for a in client.analyses.list(type="es_dni"):  # iterar recorre todas las páginas
    print(a["id"])
recent = client.analyses.list().to_list(200)
client.analyses.delete("an_01J…")
client.analyses.export("an_01J…", "xlsx", save_to="analisis.xlsx")  # devuelve los bytes

# Revisión humana (solo clave secreta)
for a in client.reviews.list(status="pending"):  # más antiguos primero, todas las páginas
    print(a["id"])
original = client.analyses.file("an_01J…")  # bytes; NotFoundError file_not_stored si ya no está
client.analyses.review("an_01J…", decision="approve", reason="Datos correctos", idempotency_key="review-an_01J…")

client.batches.create(items=[{"file_url": "https://example.com/1.pdf"}], options={"expect": "invoice"})
client.batches.create(files=["a.jpg", "b.pdf"], options={"expect": "payment_receipt"})
client.batches.get("bat_01J…")

client.document_types.list(language="es")
client.document_types.get("medical_certificate_sport")

endpoint = client.webhook_endpoints.create(
    url="https://example.com/webhooks/constaia",
    events=["analysis.completed", "analysis.review_required"],
)
endpoint["secret"]  # whsec_… — solo aparece ahora
client.webhook_endpoints.list()
client.webhook_endpoints.get("we_01J…")
client.webhook_endpoints.delete("we_01J…")

client.balance()
client.usage(from_="2026-09-01", to="2026-09-30")

analyses.list() devuelve la primera página (.data, .has_more, .next_page()); al iterarla, el SDK pide las siguientes con starting_after. En el cliente asíncrono, await da la primera página y async for las recorre todas. Ver Paginación.

Tipos

Las respuestas son dict normales con la misma forma que el JSON de la API, tipados con TypedDict (constaia.types.Analysis, Classification, Batch, WebhookEndpoint…). mypy y pyright comprueban los nombres de los campos; en tiempo de ejecución no se valida nada, así que los campos nuevos de la API no rompen versiones antiguas del SDK.

from constaia.types import Analysis


def is_ok(a: Analysis) -> bool:
    return a["verdict"] is not None and a["verdict"]["status"] == "valid"

Errores

Todas las excepciones heredan de ConstaiaError, con message, status, type, code, param y request_id.

ClaseCuándo
InvalidRequestError400, 409, 413, 415, 422 (code, param).
AuthenticationError401.
InsufficientCreditsError402.
PermissionDeniedError403.
NotFoundError404.
RateLimitError429 tras agotar los reintentos (retry_after).
APIError5xx (por ejemplo 503 live_mode_unavailable).
APIConnectionError / APITimeoutErrorProblemas de red.
WebhookVerificationErrorFirma de webhook no válida.
from constaia import (
    ConstaiaError,
    InsufficientCreditsError,
    InvalidRequestError,
    RateLimitError,
)

try:
    client.analyze("dni.jpg", expect="es_dni")
except InvalidRequestError as e:
    print(e.code, e.param)  # p. ej. unsupported_file_type, file
except InsufficientCreditsError:
    notify_billing()
except RateLimitError as e:
    print(f"reintenta en {e.retry_after} s")
except ConstaiaError as e:
    print(e.status, e.type, e.request_id)

Todos los códigos, en Errores.

Reintentos, concurrencia y límites

  • Reintenta 429, 408, 409 idempotency_in_progress, 5xx (salvo 501) y errores de red hasta max_retries veces, esperando Retry-After (hasta 60 s) o con backoff exponencial y jitter.
  • Envía la misma Idempotency-Key en cada reintento: un análisis reintentado no se cobra dos veces.
  • Mantiene como máximo max_concurrency peticiones en vuelo por cliente (hilos o tareas asyncio); las demás esperan.
  • Expone las últimas cabeceras de límite:
client.balance()
client.last_rate_limit  # RateLimit(limit=10, remaining=9, reset=1, policy='10;w=1', retry_after=None)
client.last_request_id  # "req_…": inclúyelo si escribes a soporte

Con varios procesos o workers, el límite por clave es compartido: mantén max_concurrency × procesos cerca de tu límite de peticiones por segundo. Ver Límites de uso.

Webhooks

import constaia

event = constaia.webhooks.verify(raw_body, headers, "whsec_...")  # lanza WebhookVerificationError
if event["type"] == "analysis.completed":
    save(event["data"])

Pasa siempre el cuerpo sin procesar (request.body en Django, request.get_data() en Flask, await request.body() en FastAPI). Tolerancia por defecto: 300 s (tolerance=). Para tus tests, constaia.webhooks.sign(payload, secret) genera cabeceras válidas. Más en Webhooks.

Guías por framework

Plantillas, expedientes, sesiones y privacidad

El SDK también cubre client.templates, client.dossiers, client.sessions, client.analytics() y client.analyses.delete_by_metadata() / export_by_metadata(). Los campos y ejemplos están en Plantillas, Expedientes, Sesiones y claves publicables, Analítica y Privacidad avanzada.

Siguientes pasos

En esta página