Metadata-Version: 2.4
Name: verifiquemos
Version: 0.14.0
Summary: Official Python SDK for the Verifiquemos compliance API
Project-URL: Homepage, https://verifiquemos.com/developers
Project-URL: Documentation, https://api.verifiquemos.com/scalar
Author-email: Verifiquemos <soporte@verifiquemos.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api,compliance,guatemala,kyc,ofac,renap,sdk,verifiquemos
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic[email]>=2.7
Requires-Dist: python-ulid>=3.0
Provides-Extra: dev
Requires-Dist: datamodel-code-generator>=0.26; extra == 'dev'
Requires-Dist: hatch>=1.13; extra == 'dev'
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.7; extra == 'dev'
Description-Content-Type: text/markdown

# verifiquemos

Official Python SDK for the [Verifiquemos](https://verifiquemos.com) 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

```bash
pip install verifiquemos
```

## Quickstart (sync)

```python
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)

```python
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.

```python
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

```python
# 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

```python
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("Payment required (402)")
        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`](./CHANGELOG.md)

## Development

```bash
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:

```bash
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`](./CHANGELOG.md) before tagging.

## License

MIT
