verifiquemos 0.13.0

Official Python SDK for the Verifiquemos compliance API

verifiquemos

Official Python SDK for the Verifiquemos compliance API.

KYC, RENAP, OFAC, ONU, Lista Engel, PEP, CPE — Guatemala-specific compliance in one API call.

Requirements

• Python >= 3.10 (tested on 3.10, 3.11, 3.12, 3.13, 3.14)

Install

pip install verifiquemos

Quickstart (sync)

from verifiquemos import VerifiquemosClient

with VerifiquemosClient(api_key="vfq_...") as client:
    validation = client.validations.create(
        naturaleza="persona_individual",
        cui="1234567890101",
        nombre_completo="Juan Pérez",
        actividad_economica="asalariados",
        tipo_cliente="individual_nacional_renap",
        producto_servicio="cuenta_ahorros",
        perfil_ingreso="baja",
    )
    print(f"Validation submitted: {validation['id']}")

Quickstart (async)

import asyncio
from verifiquemos import AsyncVerifiquemosClient

async def main():
    async with AsyncVerifiquemosClient(api_key="vfq_...") as client:
        validation = await client.validations.create(
            naturaleza="persona_juridica",
            nit="1234567",
            razon_social="ACME S.A.",
            actividad_economica="comercio_mayorista",
            tipo_cliente="juridica_nacional",
            producto_servicio="cuenta_monetaria",
            perfil_ingreso="alta",
        )
        print(f"Validation submitted: {validation['id']}")

asyncio.run(main())

Poll and download the report

create() returns immediately; the validation runs asynchronously. Poll get() until the status reaches a terminal state, then fetch the report via the signed URL the API returns.

import time
import httpx

while True:
    result = client.validations.get(validation["id"])
    if result["status"] in ("completed", "completed_partial", "failed", "cancelled"):
        break
    time.sleep(3)

# A report is only generated for completed runs. Skip the round-trip on
# failed / cancelled so the example doesn't make a noisy request for an
# artifact the API won't return.
if result["status"] in ("completed", "completed_partial"):
    report = client.validations.report(validation["id"])
    # report = {"report_url": "https://...", "expires_at": None}
    # report_url is always present per the schema; expires_at may be None
    # until the SAS-signing layer lands on the server.
    pdf = httpx.get(report["report_url"]).content
    with open("report.pdf", "wb") as f:
        f.write(pdf)

List, cancel and catalogs

# Paginated list (filter by status optional)
page = client.validations.list(status="pending", limit=20, offset=0)
print(page["total"], "validations,", len(page["items"]), "in this page")

# Cancel an in-flight validation (idempotent — second call replays the first)
cancelled = client.validations.cancel(validation["id"])

# Catalogs the SDK exposes for client-side dropdowns
client.catalogs.naturalezas()           # 2 SIB-regulated values
client.catalogs.actividades_economicas()
client.catalogs.tipos_cliente()
client.catalogs.productos_servicios()
client.catalogs.perfiles_ingreso()

# Country lookups (Guatemala-specific compliance: OFAC/GAFI sanctions list)
client.countries.list(search="guate")
client.countries.list_sanctioned()

Error handling

from verifiquemos import ApiError, RateLimitError, NetworkError, VerifiquemosClient

with VerifiquemosClient(api_key="vfq_...") as client:
    try:
        client.validations.create(...)
    except RateLimitError as e:
        print(f"Retry after {e.retry_after_seconds}s")
    except ApiError as e:
        if e.is_payment_required:
            print("Buy more credits")
        else:
            raise
    except NetworkError:
        print("Connection failed")

Configuration

Argument	Default	Description
api_key	(required)	Server-issued API key. Starts with vfq_.
base_url	https://api.verifiquemos.com/external/v1	Override for staging/dev.
timeout	30.0	httpx timeout in seconds.

Documentation

• API reference: https://api.verifiquemos.com/scalar
• Developer portal: https://verifiquemos.com/developers
• Release notes: CHANGELOG.md

Development

cd verifiquemos-sdk-python
pip install -e ".[dev]"
pytest tests/ -v                              # tests (respx mockea httpx)
ruff check verifiquemos/ tests/
mypy verifiquemos/ --ignore-missing-imports

# Los modelos en verifiquemos/_generated/ se generan desde el OpenAPI externo
# del API. No editarlos a mano; regenerar tras cambios de contrato (requiere
# el repo hermano ../verifiquemos-api):
bash scripts/regen_models.sh             # lee ../verifiquemos-api/openapi-external.json

Release

Publishing to PyPI is triggered by pushing a git tag v<version>. On the tag the Azure pipeline runs the test matrix (Python 3.10–3.14) and then the Publish stage, which is exactly:

pip install hatch twine
hatch build                                   # wheel + sdist → dist/
TWINE_USERNAME=__token__ TWINE_PASSWORD=$PYPI_TOKEN twine upload dist/* --skip-existing

Bump version in pyproject.toml and __version__ in verifiquemos/__init__.py (they must match) and update CHANGELOG.md before tagging.

License

MIT