checkCpfRestApiGoCgo

RESTful API to verify physical person registers status on Brazilian entities.
A GO (Golang) solution wrapped to C code that uses libCurl implementation (github.com/curl).

The routing API receives a CPF (Brazilian Physical Person Register) to be checked.
Then the CPF is validated on SERPRO (Brazilian Federal Data Processing Service) that also uses a RESTful API.

The HTTP request implementation is forwarded to C source code files.
The C code links with the pre-installed C/C++ library libCurl (github.com/curl).
GO support to C source code files is provided by CGO (golang.org/cmd/cgo).

The API may also receives more informative data, like Name and RG (Brazilian General Registry), not being validated now.
The API routing implementation uses the library gorilla/mux (github.com/gorilla/mux).

Quick Start (on Linux)

Install GO compiler

sudo apt install gccgo-go

This application was tested with GO release 1.12.2. To check the installed version of GO compiler, run:

go version

Install Gorilla Mux router library

go get -u github.com/gorilla/mux

Install lib Curl for Development

sudo apt-get install libcurl-dev

This application was tested with the library libcurl4-openssl-dev on release 7.68.0

Build and run checkCpfRestApiGoCgo (from the project root folder)

go build -gccgoflags="-lcurl"
./checkCpfRestApiGoCgo

Attention: The -lcurl flag is necessary to link with the installed Curl library.

API description

URL : api/v1/verify

Method : POST

Auth required : NO

Permissions required : None

Required fields : cpf

Non-required fields : name, rg (number, issued, entity)

Request example:

 {
  "name":"Heitor Peralles",
  "cpf":"40442820135",
  "rg": { "number":"209921899", "issued":"2020/5/20", "entity":"DETRAN-RJ" }
 }

Success Response

Code : 200 Register OK

Response example:

 {
  "status":"True"
 }

Error Responses

Code : 400 Invalid format or registry number

Code : 403 Problem with the registry, NOT OK

Code : 500 Server Error

Response example:

 {
  "status":"False",
  "message":"Invalid CPF Format."
 }

Testing the API

Unit tests

Unfortunately GO does not support automated testing of applications that use CGO.

Testing manually

A simple way to test the API on Linux:

Install CURL, a recommended library to deal with requests.

sudo apt-get install curl

Trigger a request to the primary endpoint as follows.

curl localhost:8000/api/v1/verify -i -X POST -d '{"cpf":"40442820135"}'

Remembering that checkCpfRestApiGoCgo must be running to receive the request.

List of testing CPFs provided by SERPRO:

The application uses a service provided by SERPRO, so any test depends on this service being online.
The CPFs provided by SERPRO for testing are:

40442820135: Regular (Register OK)
63017285995: Regular (Register OK)
91708635203: Regular (Register OK)
58136053391: Regular (Register OK)
40532176871: Suspended (Problem with the registry)
47123586964: Suspended (Problem with the registry)
07691852312: Regularization Pending (Problem with the registry)
10975384600: Regularization Pending (Problem with the registry)
01648527949: Canceled by Multiplicity (Problem with the registry)
47893062592: Canceled by Multiplicity (Problem with the registry)
98302514705: Null (Problem with the registry)
18025346790: Null (Problem with the registry)
64913872591: Registration Canceled (Problem with the registry)
52389071686: Registration Canceled (Problem with the registry)
05137518743: Deceased Holder (Problem with the registry)
08849979878: Deceased Holder (Problem with the registry)

Implementation

File structure

The application is composed by a set of source code files:

app.go : Main file, with main() function.

api_model.go : API structures.
api_routing.go : API routing implementation using Gorilla Mux.
api.go : Code to handle provided API requests and responses.

middleware.h : C header file with definitions of functions and SERPRO structures.
middleware.c : C source file with the core implementation of the REQUEST to SERPRO service.

README.md : This file, explaining how the application works.
.gitignore : List of non-versioned files (such as the compiled binary).

After the compilation process, the non-versioned binary file checkCpfRestApiGoCgo will be generated.

API Credentials

The application is configured with a personal TOKEN, please change it.
Its possible to generate a new TOKEN on SERPRO service page: servicos.serpro.gov.br.

The in use TOKEN is specified on the top of middleware.c file.
If going to production the SERPRO service URL must also be changed (at the same file).

Author

Heitor Peralles
[email protected]
linkedin.com/in/heitorperalles

Source

github.com/heitorperalles/checkCpfRestApiGoCgo

License

MIT licensed. See the LICENSE file for details.