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.