osvaldovictor/validate-docs-ao

There is no license information available for the latest version (v1.0.0) of this package.

Biblioteca PHP para validação de documentos pessoais angolanos, como Número de Identificação Fiscal (NIF), Bilhete de Identidade (BI) e outros. Ele é uma versão do Nifvalidation que uma lib js

v1.0.0 2026-04-11 18:07 UTC

Requires

• php: ^8.1
• ext-curl: *
• ext-dom: *
• ext-libxml: *

Unknown License

• Djosekispy

README

Biblioteca em PHP para consulta de dados de NIF de contribuintes em Angola, reproduzindo a arquitetura da lib JavaScript nifvalidation.

Esta biblioteca automatiza uma consulta pública do portal do contribuinte. O uso é de sua responsabilidade; respeite os termos de uso do serviço e a legislação aplicável.

Instalação

composer require osvaldovictor/validate-docs-ao

Requisitos

• PHP 8.1 ou superior
• Extensões curl, dom e libxml
• Acesso à internet

Uso básico

<?php

require __DIR__ . '/vendor/autoload.php';

use function Osvaldovictor\ValidateDocsAo\getNifData;

$data = getNifData('0000000000000');

echo $data->nif . PHP_EOL;
echo $data->name . PHP_EOL;
echo $data->type . PHP_EOL;
echo $data->state . PHP_EOL;
echo $data->vatRegime . PHP_EOL;
echo $data->residenciaFiscal . PHP_EOL;

API

getNifData(string $nif, array $options = []): NifEntity

Função de alto nível para consultar os dados de um NIF/BI.

Opções suportadas:

• browserAdapter: adaptador de sessão HTTP customizado
• provider: provedor customizado que implemente INifProvider
• retries: quantidade de tentativas extras em falhas temporárias
• timeoutMs: timeout da requisição inicial
• resultTimeoutMs: timeout da requisição de resultado
• enableCache: ativa cache em memória por NIF
• cacheTtlMs: TTL do cache em milissegundos
• debug: ativa logs internos
• logger: array com callbacks debug, warn e error
• verifySsl: controla a verificação SSL do adaptador cURL padrão
• caFile: caminho explícito para um arquivo CA bundle PEM
• caPath: diretório de certificados para o cURL
• userAgent: user-agent usado pelo adaptador cURL padrão

NifService

Serviço responsável por:

• Validar a entrada
• Controlar retries com backoff simples
• Fazer cache opcional em memória
• Delegar a consulta ao provider
• Validar os dados extraídos antes de retornar NifEntity

PortalContribuinteProvider

Provider padrão do portal do contribuinte. Ele simula a chamada AJAX JSF usada pela página pública de consulta de NIF.

Testes

composer test

Teste de integração real, opcional:

$env:VALIDATE_DOCS_AO_TEST_NIF="007532143HA045"
composer test:integration

Se o seu PHP/cURL no Windows falhar por cadeia de certificados, prefira apontar um bundle atualizado em vez de desativar SSL:

$data = getNifData('007639171HA042', [
	'caFile' => 'C:/caminho/para/cacert.pem',
]);

Use verifySsl => false apenas para depuração local.

SSL no Windows

Se ocorrer erro como SSL certificate problem: unable to get local issuer certificate:

1. Baixe um cacert.pem atualizado.
2. Configure curl.cainfo e, opcionalmente, openssl.cafile no php.ini.
3. Ou informe caFile diretamente nas opções da função.

No ambiente atual, o PHP estava com curl.cainfo configurado, então o problema provável era bundle desatualizado.