CryptoSys Home > FirmaSAT > Python Interface

Python Interface to FirmaSAT

A Python interface to FirmaSAT for Windows.

Download and installation

Automatic install from PyPi

pip install firmasatpy

To upgrade if an older version is already installed:

> pip install --upgrade firmasatpy

Manual install

Download the distribution zip file: firmasatpy-<x.x.x>.zip from the Python Package Index (PyPi).
Open a command-line console in the same directory as the zip file and type
```
pip install firmasatpy-<x.x.x>.zip
```

Documentation

Read the FirmaSAT Py documentation.

Classes

Sello: Operates on the sello (signature) node in a SAT XML document.
Tfd: Operates on the Timbre Fiscal Digital (TFD) element, if present.
Pkix: PKI X.509 security utilities. Operates on private keys and X.509 certificates.
Xmlu: XML utilities. Operates on SAT-specific XML documents.
Gen: General info about the core library DLL, e.g. version number, compile date.
Err: Details of errors returned by the core library DLL.

All code in is one module firmasat.py for simplicity of distribution. All methods are static methods.

Examples

To use in Python's REPL:

>>> from firmasat import *
>>> Gen.version()
105028

If you don't like import * and find firmasat a bit long to type each time, try

>>> import firmasat as fs
>>> fs.Gen.version()
105028

To sign a CFDI document, create the base XML file (example XML base) with all the required data except the following nodes

Sello=""
Certificado=""
NoCertificado="30001000000300023708"

You must add the 20-digit serial number of your signing certificate to the NoCertificado node. See below.

Then run the Sello.sign_xml() method with full paths to your key and cer files.

n = Sello.sign_xml('new.xml', 'base.xml', "emisor.key", password, "emisor.cer")

This creates a new file new.xml with the sello and certificado nodes completed (example XML signed).

Finding a certificate's serial number

>>> firmasat.Pkix.query_cert('emisor.cer', 'serialNumber')
'30001000000300023708'

or using FirmaSAT from the command line

> firmasat NUMBERCERT emisor.cer
30001000000300023708

More examples. See also tests below.

>>> Sello.make_digest('cfdv40-ejemplo.xml')
'c1492662dbd98ddbb7892d027c10808236e296eded13deec87179c2a8fdc742e'

>>> Pkix.query_cert('AC4_SAT.cer', Pkix.Query.KEYSIZE)
'4096'

>>> Xmlu.get_attribute('cfdv40-ejemplo.xml', "Nombre", "cfdi:Emisor")
'Esta es una demostración'

Errors

Most errors (missing files, invalid format) will result in a firmasat.Error exception, although some methods are more forgiving and will return a negative error code instead. Passing a bad argument will result in an ArgumentError exception

>>> Sello.make_digest('missingfile.xml')
Traceback (most recent call last):
...
firmasat.Error: ERROR CODE 1: Cannot open input file/No se puede abrir archivo de entrada: 
Cannot open file 'missingfile.xml'/No se puede abrir el archivo
>>>
>>> Pkix.query_cert('AC4_SAT.cer', 666)
Traceback (most recent call last):
...
ctypes.ArgumentError: argument 4: <type 'exceptions.TypeError'>: wrong type
>>>

Tests

There is a series of tests in test/test_firmasat.py (source code). You should find an example there of what you want to do.

These tests require a subdirectory work in the same folder which must contain all the required test files.

test
|   test_firmasat.py
|
\---work
    |   emisor.cer
    |   emisor.key
    |   <...all required test files>
    |
    \---tmp.XXXXXXXX
            <..temporary files...>

The test function creates a new temporary subdirectory each time, which is deleted automatically. If you want to keep this temp folder for debugging, then add the argument nodelete on the command line.

This structure is already set up in the distribution file, so unzip the file firmasat-x.x.x.zip and open a command-line prompt in the test subdirectory. You can do any of the following.

```
python test_firmasat.py
```
```
py.test -v
```
Open the file test_firmasat.py using IDLE and select Run > Run Module (F5).

We've tested this using the Python 3.10.8 interpreter and IDLE, PyCharm 2020.3, and py.test.

System requirements

Windows platforms only. Python 3 must be installed on your system (at least 3.6). FirmaSAT v10.50 or above must also be installed.

Contact

To comment on this page, make a suggestion for improvement, or just to say you liked it, please send us a message.

This page first published 28 August 2016. Last updated 19 April 2023.