Support for 3 services: Validating CFDIs (use cases for income inference and validation, RFC Homoclave generation with digit verification and CURP Generation.
It is also a great tutorial to learn the amazing FastAPI framework, and run it with uvicorn as multithreaded, and wrap an old SOAP Webservice call. As a bonus, you can build a docker image and deploy it. It truly is extremely fast and practically works anywhere. Enjoy!
Explore the docs »
Table of Contents
This is a REST API front for undocumented, public SOAP/WebService from the Mexican Government SAT (Secretaría de Administración Tributaria), in order to verify invoices and or W2 (Payroll Receipts) online.
This is an example of how you can setup your project locally, and how to build it and run it locally in Docker. You may push docker image to AWS, Azure or GCP using containers. To get a local copy up and running follow these simple example steps.
Make sure you have both brew and python installed. I will be explaining how to run this on a Mac OSx, (I use a Apple M1 MacBook Pro and will show some tricks to build docker and push to azure), but you can do this on any Windows or linux setup.
If you have brew installed, skip this step.
- Brew (The missing package manager for Mac OSx)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"If you have pyhton3 installed, with anaconda or anything you like, skip this step.
- python3
brew install python3
This will install python3 and pip to install python libraries.
-
Clone the repo.
git clone https://github.com/mexmarv/mx-sat-toolkit.git
-
Install Python libraries (you can use pip only if you´ve sourced to pip3).
pip3 install fastapi pip3 install suds-py3 pip3 install pyfiscal pip3 uvicorn
-
You can run uvicorn with reload option so you can modify code as you test things out.
uvicorn main:app --reload
-
You will run default on your local machine on port :80
INFO: Will watch for changes in these directories: ['/Users/marvin/Documents/Code/mx-sat-toolkit'] INFO: Uvicorn running on http://127.0.0.1:80 (Press CTRL+C to quit) INFO: Started reloader process [35729] using watchgod INFO: Started server process [35731] INFO: Waiting for application startup. INFO: Application startup complete.
-
If you prefer to run it on Docker, make sure you have it installed prior to this.
docker build -t mx-sat-toolkit .Then just make sure (the script that will run initially will run uvicorn on port 80 multithreaded.
For M1 Apple Chip Mac OS users: Little trick, I tried for ours building and deploying to Azure (make sure you are logged in and can publish a container), you need to build the docker image with AMD/Intel in mind in order to run.
docker buildx build --platform=linux/amd64 --load -t mx-sat-toolkit .... and now you are good to go and push that amd64 image to the cloud.
Now head to a favorite browser and open http://localhost:80/sat-cfdi as an example. You will get the required paameters in order to return the validation with the SAT.
{"detail":[{"loc":["query","rfce"],"msg":"field required","type":"value_error.missing"},{"loc":["query","rfcr"],"msg":"field required","type":"value_error.missing"},{"loc":["query","monto"],"msg":"field required","type":"value_error.missing"},{"loc":["query","folio"],"msg":"field required","type":"value_error.missing"}]}The required parameters are:
- rfce (RFC Emisor or the originating party´s RFC (Registro Federal de Contribuyentes), the one that signed the Invoice or W2)
- rfcr (RFC Receptor or the RFC of the party that was granted the Invoice or W2)
- monto (amount to verify in the document)
- folio (this is the folio unique number of the document)
All these parameters can be consulted on any valid printed invoice or payroll receipt.
Also you can enter this in the whole GET statement:
- Curl:
curl -X 'GET' \
'http://localhost:80/sat?rfce=XXX1234567&rfcr=YYY12345678&monto=1000&folio=AXBVVDGGDGD' \
-H 'accept: application/json'- http:
http://localhost:80/sat?rfce=XXX1234567&rfcr=YYY12345678&monto=1000&folio=AXBVVDGGDGDAll these parameters can be consulted on any valid printed invoice or payroll receipt.
The response (TB Documented), but its pretty intuitive throws something like this:
{
"CodigoEstatus": "N - 601: La expresión impresa proporcionada no es válida.",
"EsCancelable": null,
"Estado": "No Encontrado",
"EstatusCancelacion": null,
"ValidacionEFOS": null
}If you get a Y then its valid and you make sure Estado is not cancelled, and you have just verified if an Invoice or Payroll Receipt is valid. This allows you to determine validity, your companies submitted invoices, and even determine income deteremination for loans in a fintech/neobank space.
To view the Swagger, OpenAPI spec to use on Postman or any other cool tool, just browse to http://localhost:80/docs or http://localhost:80/redoc. You can even invoke the API from the /docs endpoint.
(Simple Metrics) FastAPI/Uvicorn/Python/Container and SAT Homoclave Calculation
Uploaded the docker image to Google Cloud Container and published it under the free tear demo account so I could try to Load Test it and see response times. Please see Below Images, but in summary:
- 100-125 concurrent sessions over time, with a total of 6,000+ cummulative sessions.
- It took 7.5 min to do full test scenario.
- Response time was less than 10ms per API Response and calculation.
- There were no errors and console in GCP is included which shows throttling at 18.12 sessions/sec, at an average 10% CPU utilization at full load, so theoretically with this container we could do 180 sessions/sec at heavy load.
- FastAPI + Uvicorn simply rock at these speeds !
Execution Plan in Time
GCP Load @ 18.12 s/sec
Average Response Time
Number of Sessions
Cummulative Sessions
Distributed under the Creative Commons Zero 1.0 License. See LICENSE.txt for more information.
Marvin Nahmias - mexmarv@gmail.com & marvin.nahmias@broxel.com Project Link: https://github.com/mexmarv/mx-sat-toolkit
Lets build on Financial Inclusion for all! #vamoscontodo. Marvs.