Consultar NIF

GET /v2/consultar-nif

Consulta os dados de um contribuinte na base da AGT. Útil para validar NIFs antes de emitir documentos ou preencher dados do cliente automaticamente.

Request

Autenticação

Authorization: Bearer feak_...

ou

x-api-key: feak_...

Scope necessário: nif:consultar ou *

Query Parameters

Exemplo

GET /v2/consultar-nif?nif=5002097788

Response

Sucesso — NIF encontrado (200 OK)

{
  "success": true,
  "nif": "5002097788",
  "nome": "AMANTENTE SOFT - COMERCIO & SERVIÇOS, LDA",
  "tipo": "Colectivo",
  "estado": "Activo",
  "regimeIva": "EXCL",
  "naoResidente": false
}

NIF não encontrado (200 OK)

{
  "success": false,
  "error": "Nao ha dados para o filtro informado",
  "code": "NIF_NOT_FOUND"
}

Campos da Resposta

Erros

Exemplos de Código

TypeScript / Node.js

const API_KEY = "feak_...";
const GATEWAY_URL = "https://connect.factflexi.com";

async function consultarNIF(nif: string) {
  const response = await fetch(
    `${GATEWAY_URL}/v2/consultar-nif?nif=${nif}`,
    {
      headers: { "x-api-key": API_KEY },
    },
  );

  const data = await response.json();

  if (!data.success) {
    console.log(`NIF não encontrado: ${data.error}`);
    return null;
  }

  console.log(`${data.nif} — ${data.nome}`);
  console.log(`  Tipo: ${data.tipo}`);
  console.log(`  Estado: ${data.estado}`);
  console.log(`  IVA: ${data.regimeIva}`);

  return data;
}

const contribuinte = await consultarNIF("5002097788");

Python

import requests

API_KEY = "feak_..."
GATEWAY_URL = "https://connect.factflexi.com"

def consultar_nif(nif: str) -> dict | None:
    response = requests.get(
        f"{GATEWAY_URL}/v2/consultar-nif",
        params={"nif": nif},
        headers={"x-api-key": API_KEY},
    )
    data = response.json()

    if not data.get("success"):
        print(f"NIF não encontrado: {data.get('error')}")
        return None

    print(f"{data['nif']} — {data['nome']}")
    print(f"  Tipo: {data['tipo']}")
    print(f"  Estado: {data['estado']}")
    print(f"  IVA: {data['regimeIva']}")

    return data

contribuinte = consultar_nif("5002097788")

PHP

<?php
define('API_KEY', 'feak_...');
define('GATEWAY_URL', 'https://connect.factflexi.com');

function consultarNIF(string $nif): ?array {
    $ch = curl_init(GATEWAY_URL . '/v2/consultar-nif?nif=' . urlencode($nif));
    curl_setopt_array($ch, [
        CURLOPT_HTTPHEADER => ['x-api-key: ' . API_KEY],
        CURLOPT_RETURNTRANSFER => true,
    ]);

    $data = json_decode(curl_exec($ch), true);
    curl_close($ch);

    if (!$data['success']) {
        echo "NIF não encontrado: {$data['error']}\n";
        return null;
    }

    echo "{$data['nif']} — {$data['nome']}\n";
    echo "  Tipo: {$data['tipo']}\n";
    echo "  Estado: {$data['estado']}\n";
    echo "  IVA: {$data['regimeIva']}\n";

    return $data;
}

$contribuinte = consultarNIF('5002097788');