# FiscalAPI SDK para Python
[](https://badge.fury.io/py/fiscalapi)
[](https://github.com/FiscalAPI/fiscalapi-python/blob/main/LICENSE.txt)
**SDK oficial de FiscalAPI para Python**, la API de facturación CFDI y otros servicios fiscales en México. Simplifica la integración con los servicios de facturación electrónica, eliminando las complejidades del SAT y facilitando la generación de facturas, notas de crédito, complementos de pago, nómina, carta porte, y más. ¡Facturar sin dolor ahora es posible!
## 🚀 Características
- Soporte completo para **CFDI 4.0**
- Compatible con Python 3.7+
- Dos modos de operación: **Por valores** o **Por referencias**
- Manejo simplificado de errores
- Búsqueda en catálogos del SAT
- Documentación completa y ejemplos prácticos
## 📦 Instalación
**pip**:
```bash
pip install fiscalapi
```
**poetry**:
```bash
poetry add fiscalapi
```
## ⚙️ Configuración
### Configuración Básica
1. **Crea un objeto de configuración** con [tus credenciales](https://docs.fiscalapi.com/credentials-info):
```python
from fiscalapi.models.common_models import FiscalApiSettings
settings = FiscalApiSettings(
api_url="https://test.fiscalapi.com", # https://live.fiscalapi.com (producción)
api_key="<API_KEY>",
tenant="<TENANT_KEY>"
)
```
2. **Crea la instancia del cliente**:
```python
from fiscalapi.services.fiscalapi_client import FiscalApiClient
client = FiscalApiClient(settings=settings)
```
## 🔄 Modos de Operación
FiscalAPI admite dos [modos de operación](https://docs.fiscalapi.com/modes-of-operation):
- **Por Referencias**: Envía solo IDs de objetos previamente creados en el dashboard de FiscalAPI.
Ideal para integraciones ligeras.
- **Por Valores**: Envía todos los campos requeridos en cada petición, con mayor control sobre los datos.
No se requiere configuración previa en el dashboard.
## 📝 Ejemplos de Uso
### 1. Crear una Persona (Emisor o Receptor)
```python
from fiscalapi.models.fiscalapi_models import Person
person = Person(
legal_name="Empresa Python SA de CV",
email="mail7@gmail.com",
password="TestPassword1234!"
)
api_response = client.people.create(person)
```
### 2. Subir Certificados CSD
```python
from fiscalapi.models.fiscalapi_models import TaxFile
# Subir certificado (CER)
certificado_csd = TaxFile(
person_id="3f3478b4-60fd-459e-8bfc-f8239fc96257",
tin="FUNK671228PH6",
base64_file="MIIFgDCCA2igAwIBAgIUMzAwMDEwMDAwMDA1MDAwMDM0NDYwDQYJKo...",
file_type=0, # 0 para certificado, 1 para llave privada
password="12345678a"
)
# Subir llave privada (KEY)
clave_privada_csd = TaxFile(
person_id="3f3478b4-60fd-459e-8bfc-f8239fc96257",
tin="FUNK671228PH6",
base64_file="MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQIAg...",
file_type=1,
password="12345678a"
)
api_response_cer = client.tax_files.create(certificado_csd)
api_response_key = client.tax_files.create(clave_privada_csd)
```
### 3. Crear un Producto o Servicio
```python
from fiscalapi.models.fiscalapi_models import Product
product = Product(
description="Producto python sin impuestos",
unit_price=Decimal("100.00")
)
api_response = client.products.create(product)
```
### 4. Actualizar Impuestos de un Producto
```python
from fiscalapi.models.fiscalapi_models import Product, ProductTax
product = Product(
id="f4bf4df3-5a91-4a30-b137-52cb517d13c4",
description="Producto python sin impuestos",
unit_price=Decimal("100.00"),
product_taxes=[
ProductTax(
rate=Decimal("0.160000"),
taxId="002",
taxFlagId="T",
taxTypeId="Tasa"
),
ProductTax(
rate=Decimal("0.106667"),
taxId="002",
taxFlagId="R",
taxTypeId="Tasa"
),
ProductTax(
rate=Decimal("0.100000"),
taxId="001",
taxFlagId="R",
taxTypeId="Tasa"
)
]
)
api_response = client.products.update(product)
```
### 5. Crear una Factura de Ingreso (Por Referencias)
```python
from datetime import datetime
from decimal import Decimal
from fiscalapi.models.fiscalapi_models import Invoice, InvoiceIssuer, InvoiceItem, InvoiceRecipient
invoice = Invoice(
version_code="4.0",
series="F",
date=datetime.now().strftime("%Y-%m-%dT%H:%M:%S"),
payment_form_code="01",
payment_conditions="Contado",
currency_code="MXN",
type_code="I",
expedition_zip_code="42501",
payment_method_code="PUE",
exchange_rate=1,
export_code="01",
issuer=InvoiceIssuer(
id="3f3478b4-60fd-459e-8bfc-f8239fc96257"
),
recipient=InvoiceRecipient(
id="96b46762-d246-4a67-a562-510a25dbafa9"
),
items=[
InvoiceItem(
id="114a4be5-fb65-40b2-a762-ff0c55c6ebfa",
quantity=Decimal("1.5"),
discount=Decimal("255.85")
)
]
)
api_response = client.invoices.create(invoice)
```
### 6. Crear la Misma Factura de Ingreso (Por Valores)
```python
from fiscalapi.models.fiscalapi_models import Invoice, InvoiceIssuer, InvoiceItem, InvoiceRecipient, ItemTax, TaxCredential
invoice = Invoice(
version_code="4.0",
series="F",
date=datetime.now().strftime("%Y-%m-%dT%H:%M:%S"),
payment_form_code="01",
currency_code="MXN",
type_code="I",
expedition_zip_code="42501",
payment_method_code="PUE",
exchange_rate=1,
export_code="01",
issuer=InvoiceIssuer(
tin="FUNK671228PH6",
legal_name="KARLA FUENTE NOLASCO",
tax_regime_code="621",
tax_credentials=[
TaxCredential(
base64_file="MIIFgDCCA2igAwIBAgIUMzAwMDEwMDAwMDA1MDAwMDM0NDYwDQYJKo...",
file_type=0,
password="12345678a"
),
TaxCredential(
base64_file="MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQIAg...",
file_type=1,
password="12345678a"
)
]
),
recipient=InvoiceRecipient(
tin="EKU9003173C9",
legal_name="ESCUELA KEMPER URGATE",
zip_code="42501",
tax_regime_code="601",
cfdi_use_code="G01",
email="mail@domain.com"
),
items=[
InvoiceItem(
item_code="84111506",
quantity=Decimal("9.5"),
unit_of_measurement_code="E48",
description="Invoicing software as a service",
unit_price=Decimal("3587.75"),
tax_object_code="02",
item_sku="7506022301697",
discount=Decimal("255.85"),
item_taxes=[
ItemTax(
tax_code="002",
tax_type_code="Tasa",
tax_rate=Decimal("0.160000"),
tax_flag_code="T"
)
]
)
]
)
api_response = client.invoices.create(invoice)
```
### 7. Búsqueda en Catálogos del SAT
```python
# Buscar registros que contengan 'inter' en el catalogo 'SatUnitMeasurements' (página 1, tamaño página 10)
api_response = client.catalogs.search_catalog("SatUnitMeasurements", "inter", 1, 10)
if api_response.succeeded:
for item in api_response.data.items:
print(f"Unidad: {item.description}")
else:
print(api_response.message)
```
## 📋 Operaciones Principales
- **Facturas (CFDI)**
Crear facturas de ingreso, notas de crédito, complementos de pago, cancelaciones, generación de PDF/XML.
- **Personas (Clientes/Emisores)**
Alta y administración de personas, gestión de certificados (CSD).
- **Productos y Servicios**
Administración de catálogos de productos, búsqueda en catálogos SAT.
## 🤝 Contribuir
1. Haz un fork del repositorio.
2. Crea una rama para tu feature: `git checkout -b feature/AmazingFeature`
3. Realiza commits de tus cambios: `git commit -m 'Add some AmazingFeature'`
4. Sube tu rama: `git push origin feature/AmazingFeature`
5. Abre un Pull Request en GitHub.
## 🐛 Reportar Problemas
1. Asegúrate de usar la última versión del SDK.
2. Verifica si el problema ya fue reportado.
3. Proporciona un ejemplo mínimo reproducible.
4. Incluye los mensajes de error completos.
## 📄 Licencia
Este proyecto está licenciado bajo la Licencia **MPL**. Consulta el archivo [LICENSE](LICENSE.txt) para más detalles.
## 🔗 Enlaces Útiles
- [Documentación Oficial](https://docs.fiscalapi.com)
- [Portal de FiscalAPI](https://fiscalapi.com)
- [Ejemplos en Python](https://github.com/FiscalAPI/fiscalapi-samples-python)
---
Desarrollado con ❤️ por [Fiscalapi](https://www.fiscalapi.com)
Raw data
{
"_id": null,
"home_page": "https://www.fiscalapi.com",
"name": "fiscalapi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "factura, cfdi, facturacion, mexico, sat, fiscalapi",
"author": "Fiscalapi",
"author_email": "contacto@fiscalapi.com",
"download_url": "https://files.pythonhosted.org/packages/7e/9c/71a70dd7d96bd4ff6b2dd6da7bd7efdaa3a09077a2c79f94ca40cfa4f128/fiscalapi-4.0.120.tar.gz",
"platform": null,
"description": "# FiscalAPI SDK para Python\n\n[](https://badge.fury.io/py/fiscalapi)\n[](https://github.com/FiscalAPI/fiscalapi-python/blob/main/LICENSE.txt)\n\n**SDK oficial de FiscalAPI para Python**, la API de facturaci\u00f3n CFDI y otros servicios fiscales en M\u00e9xico. Simplifica la integraci\u00f3n con los servicios de facturaci\u00f3n electr\u00f3nica, eliminando las complejidades del SAT y facilitando la generaci\u00f3n de facturas, notas de cr\u00e9dito, complementos de pago, n\u00f3mina, carta porte, y m\u00e1s. \u00a1Facturar sin dolor ahora es posible!\n\n## \ud83d\ude80 Caracter\u00edsticas\n\n- Soporte completo para **CFDI 4.0**\n- Compatible con Python 3.7+\n- Dos modos de operaci\u00f3n: **Por valores** o **Por referencias**\n- Manejo simplificado de errores\n- B\u00fasqueda en cat\u00e1logos del SAT\n- Documentaci\u00f3n completa y ejemplos pr\u00e1cticos\n\n## \ud83d\udce6 Instalaci\u00f3n\n\n**pip**:\n```bash\npip install fiscalapi\n```\n\n**poetry**:\n```bash\npoetry add fiscalapi\n```\n\n## \u2699\ufe0f Configuraci\u00f3n\n\n### Configuraci\u00f3n B\u00e1sica\n\n1. **Crea un objeto de configuraci\u00f3n** con [tus credenciales](https://docs.fiscalapi.com/credentials-info):\n```python\nfrom fiscalapi.models.common_models import FiscalApiSettings\n\nsettings = FiscalApiSettings(\n api_url=\"https://test.fiscalapi.com\", # https://live.fiscalapi.com (producci\u00f3n)\n api_key=\"<API_KEY>\",\n tenant=\"<TENANT_KEY>\"\n)\n```\n\n2. **Crea la instancia del cliente**:\n```python\nfrom fiscalapi.services.fiscalapi_client import FiscalApiClient\n\nclient = FiscalApiClient(settings=settings)\n```\n\n## \ud83d\udd04 Modos de Operaci\u00f3n\n\nFiscalAPI admite dos [modos de operaci\u00f3n](https://docs.fiscalapi.com/modes-of-operation):\n\n- **Por Referencias**: Env\u00eda solo IDs de objetos previamente creados en el dashboard de FiscalAPI. \n Ideal para integraciones ligeras.\n\n- **Por Valores**: Env\u00eda todos los campos requeridos en cada petici\u00f3n, con mayor control sobre los datos. \n No se requiere configuraci\u00f3n previa en el dashboard.\n\n## \ud83d\udcdd Ejemplos de Uso\n\n### 1. Crear una Persona (Emisor o Receptor)\n\n```python\nfrom fiscalapi.models.fiscalapi_models import Person\n\nperson = Person(\n legal_name=\"Empresa Python SA de CV\",\n email=\"mail7@gmail.com\",\n password=\"TestPassword1234!\"\n)\n\napi_response = client.people.create(person)\n```\n\n### 2. Subir Certificados CSD\n\n```python\nfrom fiscalapi.models.fiscalapi_models import TaxFile\n\n# Subir certificado (CER)\ncertificado_csd = TaxFile(\n person_id=\"3f3478b4-60fd-459e-8bfc-f8239fc96257\",\n tin=\"FUNK671228PH6\",\n base64_file=\"MIIFgDCCA2igAwIBAgIUMzAwMDEwMDAwMDA1MDAwMDM0NDYwDQYJKo...\",\n file_type=0, # 0 para certificado, 1 para llave privada\n password=\"12345678a\" \n)\n\n# Subir llave privada (KEY)\nclave_privada_csd = TaxFile(\n person_id=\"3f3478b4-60fd-459e-8bfc-f8239fc96257\",\n tin=\"FUNK671228PH6\",\n base64_file=\"MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQIAg...\",\n file_type=1,\n password=\"12345678a\"\n)\n\napi_response_cer = client.tax_files.create(certificado_csd)\napi_response_key = client.tax_files.create(clave_privada_csd)\n```\n\n### 3. Crear un Producto o Servicio\n\n```python\nfrom fiscalapi.models.fiscalapi_models import Product\n\nproduct = Product(\n description=\"Producto python sin impuestos\",\n unit_price=Decimal(\"100.00\")\n)\n\napi_response = client.products.create(product)\n```\n\n### 4. Actualizar Impuestos de un Producto\n\n```python\nfrom fiscalapi.models.fiscalapi_models import Product, ProductTax\n\nproduct = Product(\n id=\"f4bf4df3-5a91-4a30-b137-52cb517d13c4\",\n description=\"Producto python sin impuestos\",\n unit_price=Decimal(\"100.00\"),\n product_taxes=[\n ProductTax(\n rate=Decimal(\"0.160000\"),\n taxId=\"002\",\n taxFlagId=\"T\",\n taxTypeId=\"Tasa\"\n ),\n ProductTax(\n rate=Decimal(\"0.106667\"),\n taxId=\"002\",\n taxFlagId=\"R\",\n taxTypeId=\"Tasa\"\n ),\n ProductTax(\n rate=Decimal(\"0.100000\"),\n taxId=\"001\",\n taxFlagId=\"R\",\n taxTypeId=\"Tasa\"\n )\n ]\n)\n\napi_response = client.products.update(product)\n```\n\n### 5. Crear una Factura de Ingreso (Por Referencias)\n\n```python\nfrom datetime import datetime\nfrom decimal import Decimal\nfrom fiscalapi.models.fiscalapi_models import Invoice, InvoiceIssuer, InvoiceItem, InvoiceRecipient\n\ninvoice = Invoice(\n version_code=\"4.0\",\n series=\"F\",\n date=datetime.now().strftime(\"%Y-%m-%dT%H:%M:%S\"),\n payment_form_code=\"01\",\n payment_conditions=\"Contado\",\n currency_code=\"MXN\",\n type_code=\"I\",\n expedition_zip_code=\"42501\",\n payment_method_code=\"PUE\",\n exchange_rate=1,\n export_code=\"01\",\n issuer=InvoiceIssuer(\n id=\"3f3478b4-60fd-459e-8bfc-f8239fc96257\"\n ),\n recipient=InvoiceRecipient(\n id=\"96b46762-d246-4a67-a562-510a25dbafa9\"\n ),\n items=[\n InvoiceItem(\n id=\"114a4be5-fb65-40b2-a762-ff0c55c6ebfa\",\n quantity=Decimal(\"1.5\"),\n discount=Decimal(\"255.85\")\n )\n ]\n)\n\napi_response = client.invoices.create(invoice)\n```\n\n### 6. Crear la Misma Factura de Ingreso (Por Valores)\n\n```python\nfrom fiscalapi.models.fiscalapi_models import Invoice, InvoiceIssuer, InvoiceItem, InvoiceRecipient, ItemTax, TaxCredential\n\ninvoice = Invoice(\n version_code=\"4.0\",\n series=\"F\",\n date=datetime.now().strftime(\"%Y-%m-%dT%H:%M:%S\"),\n payment_form_code=\"01\",\n currency_code=\"MXN\",\n type_code=\"I\",\n expedition_zip_code=\"42501\",\n payment_method_code=\"PUE\",\n exchange_rate=1,\n export_code=\"01\",\n issuer=InvoiceIssuer(\n tin=\"FUNK671228PH6\",\n legal_name=\"KARLA FUENTE NOLASCO\",\n tax_regime_code=\"621\",\n tax_credentials=[\n TaxCredential(\n base64_file=\"MIIFgDCCA2igAwIBAgIUMzAwMDEwMDAwMDA1MDAwMDM0NDYwDQYJKo...\",\n file_type=0,\n password=\"12345678a\"\n ),\n TaxCredential(\n base64_file=\"MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQIAg...\",\n file_type=1,\n password=\"12345678a\"\n )\n ]\n ),\n recipient=InvoiceRecipient(\n tin=\"EKU9003173C9\",\n legal_name=\"ESCUELA KEMPER URGATE\",\n zip_code=\"42501\",\n tax_regime_code=\"601\",\n cfdi_use_code=\"G01\",\n email=\"mail@domain.com\"\n ),\n items=[\n InvoiceItem(\n item_code=\"84111506\",\n quantity=Decimal(\"9.5\"),\n unit_of_measurement_code=\"E48\",\n description=\"Invoicing software as a service\",\n unit_price=Decimal(\"3587.75\"),\n tax_object_code=\"02\",\n item_sku=\"7506022301697\",\n discount=Decimal(\"255.85\"),\n item_taxes=[\n ItemTax(\n tax_code=\"002\",\n tax_type_code=\"Tasa\",\n tax_rate=Decimal(\"0.160000\"),\n tax_flag_code=\"T\"\n )\n ]\n )\n ]\n)\n\napi_response = client.invoices.create(invoice)\n```\n\n### 7. B\u00fasqueda en Cat\u00e1logos del SAT\n\n```python\n# Buscar registros que contengan 'inter' en el catalogo 'SatUnitMeasurements' (p\u00e1gina 1, tama\u00f1o p\u00e1gina 10)\napi_response = client.catalogs.search_catalog(\"SatUnitMeasurements\", \"inter\", 1, 10)\n\nif api_response.succeeded:\n for item in api_response.data.items:\n print(f\"Unidad: {item.description}\")\nelse:\n print(api_response.message)\n```\n\n## \ud83d\udccb Operaciones Principales\n\n- **Facturas (CFDI)** \n Crear facturas de ingreso, notas de cr\u00e9dito, complementos de pago, cancelaciones, generaci\u00f3n de PDF/XML.\n- **Personas (Clientes/Emisores)** \n Alta y administraci\u00f3n de personas, gesti\u00f3n de certificados (CSD).\n- **Productos y Servicios** \n Administraci\u00f3n de cat\u00e1logos de productos, b\u00fasqueda en cat\u00e1logos SAT.\n\n## \ud83e\udd1d Contribuir\n\n1. Haz un fork del repositorio.\n2. Crea una rama para tu feature: `git checkout -b feature/AmazingFeature`\n3. Realiza commits de tus cambios: `git commit -m 'Add some AmazingFeature'`\n4. Sube tu rama: `git push origin feature/AmazingFeature`\n5. Abre un Pull Request en GitHub.\n\n## \ud83d\udc1b Reportar Problemas\n\n1. Aseg\u00farate de usar la \u00faltima versi\u00f3n del SDK.\n2. Verifica si el problema ya fue reportado.\n3. Proporciona un ejemplo m\u00ednimo reproducible.\n4. Incluye los mensajes de error completos.\n\n## \ud83d\udcc4 Licencia\n\nEste proyecto est\u00e1 licenciado bajo la Licencia **MPL**. Consulta el archivo [LICENSE](LICENSE.txt) para m\u00e1s detalles.\n\n## \ud83d\udd17 Enlaces \u00datiles\n\n- [Documentaci\u00f3n Oficial](https://docs.fiscalapi.com)\n- [Portal de FiscalAPI](https://fiscalapi.com)\n- [Ejemplos en Python](https://github.com/FiscalAPI/fiscalapi-samples-python)\n\n---\n\nDesarrollado con \u2764\ufe0f por [Fiscalapi](https://www.fiscalapi.com)\n",
"bugtrack_url": null,
"license": "MPL-2.0",
"summary": "Genera facturas CFDI v\u00e1lidas ante el SAT consumiendo el API de https://www.fiscalapi.com",
"version": "4.0.120",
"project_urls": {
"Homepage": "https://www.fiscalapi.com"
},
"split_keywords": [
"factura",
" cfdi",
" facturacion",
" mexico",
" sat",
" fiscalapi"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "77ba8b98c99becffc3d465f27614562e11d1f52de73724454c21ee9686558a0e",
"md5": "b8adcde4af8f1b448a263abec4df42d4",
"sha256": "4a125a3b50557529fd72fbd4522c3a5d0f6dbdb8cca9c76c8269e778f03a6107"
},
"downloads": -1,
"filename": "fiscalapi-4.0.120-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b8adcde4af8f1b448a263abec4df42d4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 23055,
"upload_time": "2025-02-16T21:15:23",
"upload_time_iso_8601": "2025-02-16T21:15:23.207702Z",
"url": "https://files.pythonhosted.org/packages/77/ba/8b98c99becffc3d465f27614562e11d1f52de73724454c21ee9686558a0e/fiscalapi-4.0.120-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7e9c71a70dd7d96bd4ff6b2dd6da7bd7efdaa3a09077a2c79f94ca40cfa4f128",
"md5": "8093967e6968421e03d4c178ddbf6d80",
"sha256": "d631b16ebf4a0c200bcd24a98010bb88a27520d3d74c883b4ff5f95241ed1add"
},
"downloads": -1,
"filename": "fiscalapi-4.0.120.tar.gz",
"has_sig": false,
"md5_digest": "8093967e6968421e03d4c178ddbf6d80",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 23182,
"upload_time": "2025-02-16T21:15:27",
"upload_time_iso_8601": "2025-02-16T21:15:27.553732Z",
"url": "https://files.pythonhosted.org/packages/7e/9c/71a70dd7d96bd4ff6b2dd6da7bd7efdaa3a09077a2c79f94ca40cfa4f128/fiscalapi-4.0.120.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-16 21:15:27",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "fiscalapi"
}
JSON