Metadata-Version: 2.4
Name: xfep-gre
Version: 0.1.0
Summary: Cliente async para SUNAT GRE (Guias de Remision Electronica)
Project-URL: Homepage, https://github.com/Xpertik/xfep-gre
Project-URL: Repository, https://github.com/Xpertik/xfep-gre
Project-URL: Issues, https://github.com/Xpertik/xfep-gre/issues
Project-URL: Documentation, https://github.com/Xpertik/xfep-gre#readme
Author-email: Jhonatan Mosquera Tabra <jhonatanmt83@gmail.com>
Maintainer-email: Jhonatan Mosquera Tabra <jhonatanmt83@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: async,gre,guia-remision,guia-remision-electronica,httpx,peru,sunat
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Natural Language :: Spanish
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Office/Business :: Financial :: Accounting
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# xfep-gre

Cliente async para **SUNAT GRE** (Guías de Remisión Electrónica) — Perú.

Parte del [ecosistema XFEP](https://github.com/Xpertik). Implementa el flujo OAuth2 `client_credentials` y el envío/consulta de guías contra la API REST de SUNAT GRE.

## Instalación

```bash
pip install xfep-gre
```

## Uso

```python
import asyncio
from xfep.gre import GreClient

async def main():
    async with GreClient(
        client_id="tu_client_id",
        client_secret="tu_client_secret",
        production=False,  # True = SUNAT prod, False = SUNAT beta
    ) as client:
        # Enviar guía de remisión firmada
        result = await client.send_despatch(
            xml_bytes=xml_firmado,
            filename="20123456789-09-T001-1",
        )
        print("Ticket:", result.ticket)

        # Consultar estado por ticket
        status = await client.get_status(result.ticket)
        print(status.status, status.description)

asyncio.run(main())
```

## Características

- **OAuth2 con caché de token** — Renovación automática con margen de seguridad de 30s.
- **Reintento automático en 401** — Invalida token y reintenta una vez.
- **Ambientes separados** — `production=False` usa SUNAT Beta (`api-cpe-beta.sunat.gob.pe`).
- **Excepciones tipadas** — `AuthenticationError`, `GreError`.
- **100% async/await** — Construido sobre `httpx.AsyncClient`.
- **Context manager** — `async with` garantiza cierre del cliente HTTP.

## API

### `GreClient`

```python
GreClient(
    client_id: str,
    client_secret: str,
    *,
    production: bool = False,
    http_client: httpx.AsyncClient | None = None,
)
```

**`send_despatch(xml_bytes: bytes, filename: str) -> GreResponse`**
Envía una guía de remisión firmada. `filename` sigue el formato `{RUC}-{TIPO}-{SERIE}-{CORRELATIVO}`, ej: `20123456789-09-T001-1`.

**`get_status(ticket: str) -> GreResponse`**
Consulta el estado de un envío previo por su número de ticket.

### Enums

- `GreStatus` — estados retornados por SUNAT (ACCEPTED, REJECTED, IN_PROCESS, etc.)

### Excepciones

- `AuthenticationError` — Autenticación falló después del retry.
- `GreError` — Errores 5xx, timeout, u otros.

## Stack

- **Python** >= 3.13
- **httpx** >= 0.27
- **Build**: Hatchling
- **Tests**: pytest + pytest-asyncio

## Desarrollo

```bash
git clone https://github.com/Xpertik/xfep-gre.git
cd xfep-gre

python3.13 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

pytest -v
```

## Licencia

Apache License 2.0 — ver [LICENSE](LICENSE).
