v4.0.417 comercio exterior y manifiestos verificados end-to-end

Alinea la version con el API (4.0.417) y deja los dos endpoints validados
contra el API real, no solo por construccion de modelos.

Verificacion end-to-end:
- Timbrados los 18 escenarios de comercio exterior (9 por valores y 9 por
  referencias) y firmada la carta manifiesto. Sin CCE122 ni CFDI40179: la
  escala decimal sobrevive intacta a la serializacion.

Ejemplos de comercio exterior:
- La fecha de emision se toma al vuelo con datetime.now(). Antes estaba fija
  en una fecha literal, lo que hacia que los ejemplos fallaran con CCE121 en
  cuanto pasaban 72 horas. El resto de los ejemplos del repo ya usaba
  datetime.now(); esto los alinea.
- tipo_cambio documenta que debe ser el valor del DOF para la fecha de
  emision y que el propio error del PAC informa el esperado.
- Normalizada la indentacion del bloque __main__.

Person:
- sat_cfdi_use usaba el alias "cfdiUse" y nunca se poblaba; el API expone el
  catalogo expandido como "satCfdiUse".
- Agregados manifest_status_id y manifest_status, que reflejan el resultado
  de firmar la carta manifiesto.
- capital_regime marcado como deprecado: el API no expone esa propiedad.
- InvoiceRecipient.foreign_country_code marcado como deprecado en favor de
  country_id, que es el campo que el API acepta.

Deuda tecnica:
- Retirados los 49 json_encoders de los modelos. Estan deprecados en Pydantic
  v2 y eran redundantes: send_request serializa con model_dump(mode="json"),
  que ya rinde Decimal como cadena y datetime como ISO-8601. Comprobado que
  los payloads quedan byte a byte identicos en los 18 escenarios.
- Purgadas de examples.py una api key y un tenant reales que estaban
  commiteados en bloques cURL comentados; quedan los placeholders.
  La llave sigue expuesta en el historial: hay que rotarla.

Documentacion:
- README con secciones de uso de comercio exterior y firma de manifiesto,
  ambas ejecutadas y timbradas antes de documentarlas, mas el indice completo
  de ejemplos.
- CLAUDE.md documenta manifest_service.py, los modulos de modelos por
  complemento y el criterio de escala decimal que exige el SAT.

Author: mendozagit

CLAUDE.md

@@ -48,6 +48,7 @@ FiscalApiClient (Facade)
         ├── catalog_service.py        → SAT catalog searches
         ├── stamp_service.py          → Stamp/validation credit ledger transactions
         ├── sat_validation_service.py → SAT validations (structure, seals, status, 69-B blacklists)
+        ├── manifest_service.py       → Manifest signing with the taxpayer's FIEL
         └── download_*_service.py     → Bulk download management
 ```
 
@@ -63,13 +64,17 @@ client.invoices.create(invoice)
 client.people.get_list(page_num, page_size)
 client.stamps.get_list(page_num, page_size)
 client.sat_validations.validate(request)
+client.manifests.sign(request)
 ```
 
 ### Models (Pydantic v2)
 
 Located in `fiscalapi/models/`:
 - **common_models.py** - Base DTOs: `ApiResponse[T]`, `PagedList[T]`, `ValidationFailure`, `FiscalApiSettings`
 - **fiscalapi_models.py** - Domain models: `Invoice`, `Person`, `Product`, `TaxFile`, payroll complements, stamp transactions and the ledger enums (`CreditType`, `StampTransactionType`, `StampTransactionStatus`)
+- **comercio_exterior_models.py** - Comercio Exterior complement, reached through `InvoiceComplement.comercio_exterior`
+- **carta_porte_models.py** - Carta Porte complement, reached through `InvoiceComplement.carta_porte`
+- **manifest_models.py** - `SignManifestRequest` / `SignManifestResponse`
 - **sat_validation_models.py** - SAT validation models and the `SatValidationTypeIds` / `SatValidationStatusIds` id enums
 
 **Key Pattern - Field Aliasing:** Models use Pydantic `Field(alias="...")` for API JSON field mapping. When serializing, use `by_alias=True` and `exclude_none=True`.
@@ -162,6 +167,18 @@ pip install -r requirements.txt
 - Use `list[T]` and `dict[K,V]` (Python 3.9+ built-in generics) instead of `List[T]` and `Dict[K,V]`
 - Use `default_factory=list` for mutable defaults, never `default=[]`
 - All Field() calls should have explicit `default=...` for required fields
+- Do not use `json_encoders`: it is deprecated in Pydantic v2 and redundant here, because
+  `BaseService.send_request` serializes with `model_dump(mode="json", ...)`, which already
+  renders `Decimal` as a JSON string and `datetime` as ISO-8601
+
+### Decimal Scale
+
+Monetary and rate fields are `decimal.Decimal`, never `float`. The SAT validates the *scale*
+(number of decimal places) of several CFDI attributes and rejects comprobantes that do not match,
+so trailing zeros must survive serialization. Build values from string literals with the exact
+scale (`Decimal("0.160000")`, not `Decimal(0.16)`); `model_dump(mode="json")` preserves them.
+Known rejections caused by the wrong scale: `CFDI40179` on `taxRate` (6 decimals) and `CCE122`
+on `valorDolares` (feeds the computed `TotalUSD`, 2 decimals).
 
 ### Type Annotations
 

README.md

@@ -38,6 +38,7 @@
 - **Configuración de datos fiscales** (RFC, domicilio fiscal, régimen fiscal)
 - **Datos de empleado** (agrega/actualiza/elimina datos de empleado a una persona. CFDI Nómina)
 - **Datos de empleador** (agrega/actualiza/elimina datos de empleador a una persona. CFDI Nómina)
+- **Firma de carta manifiesto** (firma el manifiesto de una persona con su e.firma/FIEL)
 
 ## 🛍️ Gestión de Productos/Servicios
 - **Gestión de productos y servicios** con catálogo personalizable
@@ -399,6 +400,137 @@ params = StampTransactionParams(
 api_response = client.stamps.transfer_stamps(params)
 ```
 
+### 10. Factura de Comercio Exterior
+
+El complemento se envía en `Invoice.complement.comercio_exterior`. Puede combinarse con carta porte en el mismo comprobante.
+
+> **Escala decimal:** el SAT valida la cantidad de decimales de varios campos. Construye siempre los montos con `Decimal("...")` a partir de una cadena con la escala exacta (`Decimal("0.160000")`, no `Decimal(0.16)`): el SDK preserva los ceros finales al serializar. Una escala incorrecta produce rechazos `CFDI40179` (en `taxRate`) o `CCE122` (en `valorDolares`).
+
+> **Tipo de cambio:** `tipo_cambio_usd` debe ser el publicado en el DOF para la fecha de emisión, y la fecha del comprobante no puede exceder 72 horas al momento del timbrado. Si no coinciden, el PAC responde `CCE121` e indica el valor esperado.
+
+```python
+from datetime import datetime
+from decimal import Decimal
+
+from fiscalapi.models import (
+    Invoice, InvoiceIssuer, InvoiceRecipient, InvoiceItem, ItemTax,
+    InvoiceComplement, TaxCredential,
+    ComercioExteriorComplement, ComercioExteriorEmisor, ComercioExteriorEmisorDomicilio,
+    ComercioExteriorReceptor, ComercioExteriorReceptorDomicilio, ComercioExteriorMercancia,
+)
+
+invoice = Invoice(
+    version_code="4.0",
+    payment_form_code="99",
+    payment_method_code="PPD",
+    currency_code="USD",
+    type_code="I",
+    expedition_zip_code="42501",
+    series="CCE",
+    date=datetime.now().replace(microsecond=0),
+    export_code="02",
+    issuer=InvoiceIssuer(
+        tin="EKU9003173C9",
+        legal_name="ESCUELA KEMPER URGATE",
+        tax_regime_code="601",
+        tax_credentials=[
+            TaxCredential(base64_file="<CER_BASE64>", file_type=0, password="<CSD_PASSWORD>"),
+            TaxCredential(base64_file="<KEY_BASE64>", file_type=1, password="<CSD_PASSWORD>"),
+        ],
+    ),
+    # Receptor extranjero: country_id (ResidenciaFiscal) es obligatorio si se envía foreign_tin.
+    recipient=InvoiceRecipient(
+        tin="XEXX010101000",
+        legal_name="U.S. 0026 SW",
+        zip_code="42501",
+        tax_regime_code="616",
+        cfdi_use_code="S01",
+        country_id="USA",
+        foreign_tin="123456789",
+    ),
+    items=[
+        InvoiceItem(
+            item_code="50211503",
+            item_sku="131494-1055",  # debe coincidir con mercancia.no_identificacion
+            quantity=Decimal("2"),
+            unit_of_measurement_code="H87",
+            description="Cigarros",
+            unit_price=Decimal("200.00"),
+            discount=Decimal("0"),
+            tax_object_code="02",
+            item_taxes=[
+                ItemTax(tax_code="002", tax_type_code="Tasa", tax_rate=Decimal("0.160000"), tax_flag_code="T"),
+            ],
+        ),
+    ],
+    complement=InvoiceComplement(
+        comercio_exterior=ComercioExteriorComplement(
+            clave_de_pedimento_id="A1",
+            certificado_origen=0,  # 0 = no funge como certificado de origen, 1 = sí
+            incoterm_id="FOB",
+            tipo_cambio_usd=Decimal("16.9722"),
+            # Domicilio del emisor: campos de catálogo SAT, con sufijo Id.
+            emisor=ComercioExteriorEmisor(
+                domicilio=ComercioExteriorEmisorDomicilio(
+                    calle="CALLE DEL PAPEL",
+                    colonia_id="0214",
+                    localidad_id="01",
+                    municipio_id="014",
+                    estado_id="QUE",
+                    pais_id="MEX",
+                    codigo_postal_id="76199",
+                ),
+            ),
+            # Domicilio del receptor: texto libre, sin sufijo Id (salvo pais_id).
+            receptor=ComercioExteriorReceptor(
+                num_reg_id_trib="123456789",
+                domicilio=ComercioExteriorReceptorDomicilio(
+                    calle="ST. A",
+                    estado="TX",
+                    pais_id="USA",
+                    codigo_postal="00000",
+                ),
+            ),
+            mercancias=[
+                ComercioExteriorMercancia(
+                    no_identificacion="131494-1055",
+                    fraccion_arancelaria_id="2402200100",
+                    cantidad_aduana=Decimal("117.64"),
+                    unidad_aduana_id="01",
+                    valor_unitario_aduana=Decimal("3.40"),
+                    valor_dolares=Decimal("400.00"),
+                ),
+            ],
+        ),
+    ),
+)
+
+api_response = client.invoices.create(invoice)
+```
+
+### 11. Firmar Carta Manifiesto
+
+Firma la carta manifiesto de una persona y devuelve el PDF resultante en base64.
+
+Requiere la **e.firma (FIEL)** del contribuyente, no el CSD de timbrado, y que exista una persona con ese RFC en el tenant.
+
+```python
+from fiscalapi.models import SignManifestRequest
+
+api_response = client.manifests.sign(SignManifestRequest(
+    base64_cer="<FIEL_CER_BASE64>",
+    base64_key="<FIEL_KEY_BASE64>",
+    password="<FIEL_PASSWORD>",
+))
+
+if api_response.succeeded:
+    print(api_response.data.file_name)       # EKU9003173C9.pdf
+    print(api_response.data.file_extension)  # .pdf
+    print(api_response.data.base64_file)     # PDF firmado en base64
+```
+
+Tras una firma exitosa, `client.people.get_by_id(...)` refleja el nuevo estado en `manifest_status_id`.
+
 ## 📋 Operaciones Principales
 
 - **Facturas (CFDI)**
@@ -411,6 +543,8 @@ api_response = client.stamps.transfer_stamps(params)
   Listar transacciones, transferir y retirar timbres o créditos de validación entre personas.
 - **Validaciones SAT**
   Validar estructura, certificado, sellos, estatus en el SAT y listas negras 69-B de un CFDI o un RFC.
+- **Carta manifiesto**
+  Firmar la carta manifiesto de una persona con su e.firma (FIEL) y obtener el PDF resultante.
 
 ## 📂 Más Ejemplos
 
@@ -420,6 +554,11 @@ api_response = client.stamps.transfer_stamps(params)
 - [Facturas de Nómina](examples/ejemplos-facturas-de-nomina.py)
 - [Impuestos Locales (Por Valores)](examples/ejemplos-factura-impuestos-locales-valores.py)
 - [Impuestos Locales (Por Referencias)](examples/ejemplos-factura-impuestos-locales-referencias.py)
+- [Comercio Exterior (Por Valores)](examples/ejemplos-factura-comercio-exterior-valores.py)
+- [Comercio Exterior (Por Referencias)](examples/ejemplos-factura-comercio-exterior-referencias.py)
+- [Carta Porte (Por Valores)](examples/ejemplos-factura-carta-porte-valores.py)
+- [Carta Porte (Por Referencias)](examples/ejemplos-factura-carta-porte-referencias.py)
+- [Firma de Cartas Manifiesto](examples/ejemplos-firma-manifiestos.py)
 
 ## 🤝 Contribuir
 

examples/ejemplos-factura-carta-porte-valores.py

@@ -43,8 +43,8 @@
 
 settings = FiscalApiSettings(
     api_url="https://test.fiscalapi.com",
-    api_key="API_KEY",
-    tenant="TENANT_ID"
+    api_key="<API_KEY>",
+    tenant="<TENANT_KEY>"
 )
 
 client = FiscalApiClient(settings=settings)

examples/ejemplos-factura-comercio-exterior-referencias.py

@@ -55,15 +55,20 @@
 
 settings = FiscalApiSettings(
     api_url="https://test.fiscalapi.com",
-    api_key="API_KEY",
-    tenant="TENANT_ID"
+    api_key="<API_KEY>",
+    tenant="<TENANT_KEY>"
 )
 
 client = FiscalApiClient(settings=settings)
 
 # Valores centralizados para todos los ejemplos (cambia aqui una sola vez)
-current_date = datetime.fromisoformat("2026-05-19T08:56:40")
-tipo_cambio = Decimal("17.3477")
+# Fecha de emision: el SAT rechaza con CCE121 un CFDI cuya fecha exceda 72 horas
+# respecto al momento del timbrado, por eso se toma la fecha actual.
+current_date = datetime.now().replace(microsecond=0)
+# Tipo de cambio USD publicado en el DOF para la fecha de emision. El PAC lo
+# valida contra el DOF y, cuando no coincide, el error CCE121 informa el valor
+# esperado; actualiza esta constante con ese valor.
+tipo_cambio = Decimal("16.9722")
 issuer_id = "2e7b988f-3a2a-4f67-86e9-3f931dd48581"  # ESCUELA KEMPER URGATE
 recipient_id = "109f4d94-63ea-4a21-ab15-20c8b87d8ee9"  # KARLA FUENTES
 
@@ -1171,7 +1176,7 @@ def factura_ce_unidades_de_medida_no_equivalentes_por_referencias():
 # MAIN
 # ============================================================================
 if __name__ == "__main__":
-     factura_ce_ingreso_con_carta_porte_31_por_referencias()
+    factura_ce_ingreso_con_carta_porte_31_por_referencias()
     # factura_ce_ingreso_diferentes_monedas_por_referencias()
     # factura_ce_kit_parte_por_referencias()
     # factura_ce_receptor_extranjero_por_referencias()

examples/ejemplos-factura-comercio-exterior-valores.py

@@ -39,8 +39,8 @@
 
 settings = FiscalApiSettings(
     api_url="https://test.fiscalapi.com",
-    api_key="API_KEY",
-    tenant="TENANT_ID"
+    api_key="<API_KEY>",
+    tenant="<TENANT_KEY>"
 )
 
 client = FiscalApiClient(settings=settings)
@@ -51,8 +51,13 @@
 password = "12345678a"
 
 # Valores centralizados para todos los ejemplos (cambia aqui una sola vez)
-current_date = datetime.fromisoformat("2026-05-19T08:56:40")
-tipo_cambio = Decimal("17.3477")
+# Fecha de emision: el SAT rechaza con CCE121 un CFDI cuya fecha exceda 72 horas
+# respecto al momento del timbrado, por eso se toma la fecha actual.
+current_date = datetime.now().replace(microsecond=0)
+# Tipo de cambio USD publicado en el DOF para la fecha de emision. El PAC lo
+# valida contra el DOF y, cuando no coincide, el error CCE121 informa el valor
+# esperado; actualiza esta constante con ese valor.
+tipo_cambio = Decimal("16.9722")
 issuer_id = "2e7b988f-3a2a-4f67-86e9-3f931dd48581" #ESCUELA KEMPER URGATE
 recipient_id = "109f4d94-63ea-4a21-ab15-20c8b87d8ee9" #KARLA FUENTES
 
@@ -1130,4 +1135,4 @@ def factura_ce_unidades_de_medida_no_equivalentes_por_valores():
     # factura_ce_traslado_con_carta_porte_31_por_valores()
     # factura_ce_traslado_traslado_mercancia_propia_por_valores()
     # factura_ce_traslado_traslado_por_valores()
-     factura_ce_unidades_de_medida_no_equivalentes_por_valores()
+    factura_ce_unidades_de_medida_no_equivalentes_por_valores()

examples/ejemplos-firma-manifiestos.py

@@ -15,8 +15,8 @@
 # Configuración de FiscalAPI
 settings = FiscalApiSettings(
     api_url="https://test.fiscalapi.com",
-    api_key="API_KEY",
-    tenant="TENANT_ID"
+    api_key="<API_KEY>",
+    tenant="<TENANT_KEY>"
 )
 
 # Credenciales FIEL de prueba (ESCUELA KEMPER URGATE)