Metadata-Version: 2.4
Name: arcalib
Version: 0.2.0
Summary: Bindings Python para los webservices de ARCA (ex AFIP) de Argentina
Author-email: mileo <mileo@kmee.com.br>
License: MIT
Project-URL: Homepage, https://github.com/kmee/arcalib
Project-URL: Source, https://github.com/kmee/arcalib
Keywords: arca,afip,wsfe,wsfev1,argentina,factura-electronica,cae,xml,xsdata,webservices
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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: Topic :: Office/Business :: Financial
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: xsdata
Provides-Extra: sign
Requires-Dist: cryptography; extra == "sign"
Provides-Extra: transmissao
Requires-Dist: cryptography; extra == "transmissao"
Requires-Dist: requests; extra == "transmissao"
Requires-Dist: lxml; extra == "transmissao"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: lxml; extra == "test"

# arcalib

Bindings Python para os webservices da **ARCA** (Agencia de Recaudación y Control
Aduanero, ex-AFIP) da Argentina, gerados automaticamente a partir dos XSD/WSDL
oficiais via **xsdata**, no mesmo padrão da [nfelib](https://github.com/akretion/nfelib)
(Brasil) e da [sifen](https://github.com/kmee/sifen) (Paraguai).

Cobre:

- **WSAA**: autenticação por certificado (Login Ticket Request/Response, CMS/PKCS#7).
- **WSFEv1**: factura electrónica, mercado interno (CAE).
- **WSFEXv1**: factura electrónica, exportación (fora do MVP, incluído porque o
  binding sai de graça da geração).
- **WSCDC**: constatación de comprobantes de terceiros (fatura de fornecedor).
- **WSBFEv1**: bono fiscal electrónico (bindings dos tipos apenas; sem camada de
  transmissão. Ver `script.sh` sobre o contorno necessário para gerar este WSDL).
- **Padrón A5** (`personaServiceA5`): consulta de dados cadastrais do contribuinte
  (razão social, endereço, regime tributário) a partir do CUIT.

## Princípio central

Zero código manual para o schema. Todo binding é gerado pelo xsdata a partir
dos WSDL oficiais da ARCA (vendorizados em `arcalib/<serviço>/schemas/`).
Código escrito à mão se limita a `CommonMixin`, `transmissao/`, os dois XSD do
WSAA que a ARCA não publica (`loginTicketRequest.xsd`, `loginTicketResponse.xsd`,
com a proveniência documentada no cabeçalho de cada um), testes e o script de
geração.

## Por que existe

O core do Odoo 18 já traz o motor fiscal argentino (`l10n_ar`, `l10n_latam_*`,
LGPL-3, autoria ADHOC SA). O que falta é só o delta do Enterprise: `l10n_ar_edi`
(EDI) e `l10n_ar_reports` (relatórios). Esta lib cobre o transporte do EDI, sem
depender de `zeep` (parse de WSDL em runtime, sem tipos versionados) nem de
`pyafipws`/`pysimplesoap` (PyPI parado desde 2016, `external_dependencies` de
URL git impede publicação de módulo OCA: foi o motivo do PR
[OCA/l10n-argentina#88](https://github.com/OCA/l10n-argentina/pull/88) ter
morrido). Contexto completo, plano de execução e decisões de arquitetura no
brain `oca/l10n-argentina` (workspace interno da KMEE).

## Instalação

```bash
pip install arcalib              # só os bindings
pip install "arcalib[sign]"      # + assinatura CMS/PKCS#7 (cryptography)
pip install "arcalib[transmissao]"  # + camada de transporte SOAP completa
```

## Uso

```python
from arcalib.transmissao import WSAA, HOMOLOGACION, TransmissaoWSFEv1
from arcalib.wsfev1.bindings.wsfev1 import (
    AlicIva, ArrayOfAlicIva, ArrayOfFecaedetRequest,
    FecaecabRequest, FecaedetRequest, Fecaerequest,
)

wsaa = WSAA(HOMOLOGACION, cert_pem, key_pem)
wsfe = TransmissaoWSFEv1(HOMOLOGACION, wsaa, cuit=20111111112)

det = FecaedetRequest(
    Concepto=1, DocTipo=99, DocNro=0,
    CbteDesde=1, CbteHasta=1, CbteFch="20260729",
    ImpTotal=121.0, ImpTotConc=0.0, ImpNeto=100.0,
    ImpOpEx=0.0, ImpTrib=0.0, ImpIVA=21.0,
    MonId="PES", MonCotiz=1.0, CondicionIVAReceptorId=5,
    Iva=ArrayOfAlicIva(AlicIva=[AlicIva(Id=5, BaseImp=100.0, Importe=21.0)]),
)
req = Fecaerequest(
    FeCabReq=FecaecabRequest(CantReg=1, PtoVta=1, CbteTipo=6),
    FeDetReq=ArrayOfFecaedetRequest(FECAEDetRequest=[det]),
)
response = wsfe.fecae_solicitar(req)
```

`cert_pem`/`key_pem` são o certificado e a chave privada da empresa em PEM. No
addon Odoo, vêm do modelo `certificate.certificate`/`certificate.key` do core
(LGPL-3), exportados para PEM antes de chegar aqui: esta lib é agnóstica de
Odoo e testável isoladamente.

## Estrutura do projeto

```
arcalib/
├── .xsdata.xml              # config do xsdata (originalCase, CommonMixin extension)
├── pyproject.toml
├── script.sh                # gera/regenera todos os bindings
├── arcalib/
│   ├── CommonMixin.py       # from_xml, to_xml
│   ├── wsaa/
│   │   ├── schemas/         # wsaa.wsdl (oficial) + os 2 XSD escritos à mão
│   │   └── bindings/        # gerados (NÃO editar manualmente)
│   ├── wsfev1/  wsfexv1/  wscdc/  wsbfev1/    # mesmo padrão
│   └── transmissao/
│       ├── config.py        # endpoints producción/homologación
│       ├── wsaa.py           # WSAA: login, cache de token, assinatura CMS
│       ├── base.py           # envelope SOAP 1.1, extração de corpo, SoapFault
│       ├── wsfev1.py  wscdc.py  wsfexv1.py
├── tests/
└── .github/workflows/
```

## Comandos frequentes

```bash
pip install -e ".[sign,transmissao,test]"
./script.sh              # gerar/regenerar bindings (após alterar XSD ou .xsdata.xml)
pytest tests/ -v
ruff check arcalib/ tests/
```

## Convenções

- **Bindings são gerados**: nunca editar `arcalib/*/bindings/` manualmente.
- **FieldName originalCase**: campos mantêm o nome do WSDL (`CantReg`, `ImpIVA`,
  `CondicionIVAReceptorId`), não snake_case.
- **Nomes de classe/campo usados nesta lib e nos testes foram confirmados por
  leitura direta do binding gerado**, nunca adivinhados: a superfície do WSDL
  da ARCA tem inconsistências (ver `wscdc.py` vs `wsfev1.py`: nomes de operação
  e de campo de autenticação diferem entre webservices).
- Testes não tocam rede, exceto `TestSchemaUpdates` (`tests/test_schema_versions.py`),
  que só roda com `CHECK_SCHEMA_UPDATES=1` (job agendado do CI).

## Licença

MIT. Copyright (c) 2026 KMEE.
