Identity API

Look up official Brazilian registry data by taxpayer identification number:

Both endpoints are GET: the signed body is the empty string and all path variables (CNPJ / CPF / date of birth) are part of the signed path — see Authentication & Signing. Responses are bare objects (no platform envelope); business errors are a bare {code, message} object — see General Conventions.

Why CPF requires a date of birth

The upstream source validates CPF and date of birth as a pair (Receita Federal semantics); a CPF alone returns nothing. A mismatched pair and a non-existent CPF return the same error code — they are deliberately not distinguished, otherwise the endpoint would become a tool for probing other people’s birth dates.

CNPJ lookup

Request

GET /openapi/v3/consultas/cnpj/{cnpj}

Complete example:

GET /openapi/v3/consultas/cnpj/40673061000134 HTTP/1.1
Host: api.v2.tffiscal.com
token: sk_live_9f8e7d6c5b4a
timestamp: 1786843552
sign: aa201527a7d8288c8d79dcdb6a776566
Language: en

Equivalent curl:

APP_SECRET="sk_live_9f8e7d6c5b4a"
CNPJ="40673061000134"
P="/openapi/v3/consultas/cnpj/${CNPJ}"
TS=$(date +%s)
SIGN=$(printf '%s' "${APP_SECRET}${P}${TS}" | md5sum | cut -d' ' -f1)
 
curl -X GET "https://api.v2.tffiscal.com${P}" \
  -H "token: ${APP_SECRET}" -H "timestamp: ${TS}" -H "sign: ${SIGN}" -H "Language: en"

Success response (HTTP 200)

The response is a bare object. The tables below list every possible field; when the source holds no data for a field it comes back empty, and such fields are left out of the example.

{
  "ni": "40673061000134",
  "tipoEstabelecimento": "1",
  "nomeEmpresarial": "TF SOFTWARE LTDA",
  "nomeFantasia": "TF SOFTWARE",
  "situacaoCadastral": {
    "codigo": "2",
    "data": "2021-02-02",
    "motivo": "SEM MOTIVO"
  },
  "naturezaJuridica": {
    "codigo": "2062",
    "descricao": "Sociedade Empresária Limitada"
  },
  "dataAbertura": "2021-02-02",
  "cnaePrincipal": {
    "codigo": "6201501",
    "descricao": "Desenvolvimento de programas de computador sob encomenda"
  },
  "endereco": {
    "tipoLogradouro": "PRACA",
    "logradouro": "JOAO DURAN ALONSO",
    "numero": "34",
    "complemento": "CONJ 32",
    "cep": "04571070",
    "bairro": "CIDADE MONCOES",
    "municipio": { "codigo": "7107", "descricao": "SAO PAULO" },
    "uf": "SP",
    "pais": { "codigo": "1058", "descricao": "BRASIL" }
  },
  "municipioJurisdicao": { "codigo": "7107", "descricao": "SAO PAULO" },
  "telefones": [ { "ddd": "11", "numero": "80783080" } ],
  "correioEletronico": "contato@example.com.br",
  "capitalSocial": 100000,
  "porte": "03"
}

Field reference (top level):

situacaoCadastral (registration status):

endereco (address):

To render a full street line, concatenate tipoLogradouro + logradouro yourself — the source returns them separately.

telefones[] element:

Code-value objects (naturezaJuridica / cnaePrincipal / municipioJurisdicao / municipio / pais):

CPF lookup

Request

GET /openapi/v3/consultas/cpf/{cpf}/{nascimento}

Complete example (the signature is reproducible with the values shown — see Signing examples):

GET /openapi/v3/consultas/cpf/40710536828/09011997 HTTP/1.1
Host: api.v2.tffiscal.com
token: sk_live_9f8e7d6c5b4a
timestamp: 1786843552
sign: 84a877ec34052db54cf41bb736f7c585
Language: en

Equivalent curl:

APP_SECRET="sk_live_9f8e7d6c5b4a"
CPF="40710536828"; NASC="09011997"
P="/openapi/v3/consultas/cpf/${CPF}/${NASC}"
TS=$(date +%s)
SIGN=$(printf '%s' "${APP_SECRET}${P}${TS}" | md5sum | cut -d' ' -f1)
 
curl -X GET "https://api.v2.tffiscal.com${P}" \
  -H "token: ${APP_SECRET}" -H "timestamp: ${TS}" -H "sign: ${SIGN}" -H "Language: en"

Success response (HTTP 200)

{
  "ni": "40710536828",
  "nome": "DANILO HIDEO CORREA",
  "situacao": {
    "codigo": "0",
    "descricao": "REGULAR"
  },
  "nascimento": "09011997"
}

situacao (registration status):

Common situacao.codigo values:

Business note: when codigo is not 0, it is up to the caller to decide whether the business flow may continue. Issuing an invoice to a deceased holder (3), for instance, usually warrants a block — this endpoint reports the status faithfully and does not make that judgment for you.

Error reference

Business and request-level errors (HTTP 400) are a bare object:

{ "code": 10016003, "message": "CPF not found" }

Format and check-digit errors are rejected locally by the platform and never reach the upstream source — they consume no quota and are not billed.

Authentication-layer errors (401 / 403 / 429) use the platform envelope — see Authentication & Signing.

Data protection

CPF is personal data of a natural person and is governed by Brazil’s LGPD (Law 13.709/2018):

• The platform does not persist CPF lookup results; every query hits the source in real time.
• Full CPF values never enter application logs — they are masked.
• Path variables in the call log are HMAC-processed before storage; no plaintext is retained.
• The upstream source lawfully withholds data for protected subjects (such as minors); those requests surface as “not found” (10016003).

Callers are expected to observe the same minimum-necessity principle: query only where there is a lawful business basis (such as invoice issuance), and do not retain personal data beyond what the business requires.

Response localization

The message field follows the request language: the Language header (en / pt / es / zh) takes precedence, then Accept-Language (supports pt-BR and q-values). Without a language header, responses default to Portuguese (pt).

For programmatic decisions always use the numeric code and enum values such as situacao.codigo — never match on description text.

Integration checklist

1. Obtain the app_secret and confirm both endpoints are subscribed.
2. Call with a real CNPJ → HTTP 200, ni echoes the input, situacaoCadastral.codigo is 2.
3. Call with a real CPF + date of birth → HTTP 200, nascimento echoes the input.
4. Negative case: correct CPF with a wrong date of birth → 400 + 10016003 (same code as not-found).
5. Negative case: CNPJ / CPF with bad check digits → 400 + 10016011 / 10016001 (rejected locally, not billed).
6. Negative case: date of birth as 1997-01-09 or 31021997 → 400 + 10016002.
7. Failure paths: call with a wrong sign → 401 + 10009003; call an unsubscribed endpoint → 403 + 10009005.

Troubleshooting

Signature never matches (401, code 10009003)? On these endpoints the usual causes are a GET that did not concatenate the body as the empty string, the date-of-birth segment left out of the CPF signature (both path variables must be signed), or a formatted CNPJ whose / split the path. Recompute the fixed values in Signing examples first.

CNPJ returns 404 or fails to route? The CNPJ parameter accepts 14 digits only. The / inside 40.673.061/0001-34 is treated as a path separator, so the request never reaches the endpoint.

CPF found but the business flow looks wrong? Check situacao.codigo first: anything other than 0 means the CPF is not in regular standing (deceased, suspended, pending regularisation, …). The data is valid; the business decision is yours.