Consulta Bi

<h1>API de Consulta de Bilhete de Identidade</h1>

<h2>Visão Geral</h2>
<p>A API de Consulta de Bilhete de Identidade (BI) permite consultar dados de cidadãos angolanos através do número do Bilhete de Identidade.</p>

<h2>Funcionalidades</h2>
<ul>
    <li>Consulta de dados pessoais (nome, endereço, data de nascimento)</li>
    <li>Respostas rápidas e confiáveis</li>
    <li>Cache integrado para melhor performance</li>
    <li>Documentação completa e exemplos práticos</li>
</ul>

<h2>Casos de Uso</h2>
<ul>
    <li>Verificação de identidade em sistemas de validação</li>
    <li>Integração com sistemas de cadastro</li>
    <li>Consulta de dados de clientes</li>
    <li>Validação de documentos</li>
</ul>

<h1>Autenticação</h1>

<h2>Como obter uma chave de API</h2>
<p>Para utilizar a API de Consulta de Bilhete de Identidade, você precisa de uma chave de API válida.</p>

<h3>Passo 1: Solicitar chave</h3>
<p>Entre em contacto através do <a href="/contacto" style="color: var(--accent);">formulário de contacto</a> para solicitar sua chave de API.</p>

<h3>Passo 2: Receber chave</h3>
<p>Você receberá uma chave no formato:</p>
<pre><code>pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxx</code></pre>

<h3>Passo 3: Utilizar chave</h3>
<p>A chave deve ser enviada em todas as requisições no header:</p>
<pre><code>X-API-Key: sua-chave-aqui</code></pre>

<h2>Exemplo de requisição autenticada</h2>
<pre><code>curl -X GET "https://portfolio-joaotomas.test/api/gateway/consulta-bi/consultar/009261732KS048" \
  -H "X-API-Key: pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"</code></pre>

<h2>Códigos de erro de autenticação</h2>
<table>
    <thead>
        <tr>
            <th>Código</th>
            <th>Descrição</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>401</td>
            <td>Chave de API inválida ou não fornecida</td>
        </tr>
        <tr>
            <td>403</td>
            <td>Permissão negada</td>
        </tr>
        <tr>
            <td>429</td>
            <td>Muitas requisições (rate limit excedido)</td>
        </tr>
    </tbody>
</table>

<h1>Endpoints Disponíveis</h1>

<h2>Consultar Bilhete de Identidade</h2>

<h3>Endpoint</h3>
<pre><code>GET /consultar/{numero}</code></pre>

<h3>Parâmetros</h3>
<table>
    <thead>
        <tr>
            <th>Parâmetro</th>
            <th>Tipo</th>
            <th>Obrigatório</th>
            <th>Descrição</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>numero</td>
            <td>string</td>
            <td>Sim</td>
            <td>Número do Bilhete de Identidade (14 caracteres)</td>
        </tr>
    </tbody>
</table>

<h3>Exemplo de requisição</h3>
<pre><code>curl -X GET "https://portfolio-joaotomas.test/api/gateway/consulta-bi/consultar/009261732KS048" \
  -H "X-API-Key: sua-chave-aqui" \
  -H "Accept: application/json"</code></pre>

<h3>Resposta de sucesso</h3>
<pre><code>{
  "error": false,
  "name": "Lisboa Da Costa Coelho",
  "endereco": "SAMBA, NA, BAIRRO MUNDIAL-BENFICA",
  "data_de_nascimento": "1991-07-31"
}</code></pre>

<h3>Resposta de erro</h3>
<pre><code>{
  "error": true,
  "message": "O número do documento deve conter 14 caracteres"
}</code></pre>

<h2>Limitações</h2>
<ul>
    <li><strong>Rate Limit:</strong> 100 requisições por minuto</li>
    <li><strong>Cache:</strong> As respostas são cacheadas por 1 hora</li>
    <li><strong>Tamanho máximo:</strong> 1MB por requisição</li>
</ul>

<h1>Exemplos Práticos</h1>

<h2>Exemplo em PHP</h2>
<pre><code>&lt;?php

function consultarBI($numero, $apiKey) {
    $ch = curl_init('https://portfolio-joaotomas.test/api/gateway/consulta-bi/consultar/' . $numero);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-API-Key: ' . $apiKey,
        'Accept: application/json'
    ]);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Uso
$apiKey = 'pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxx';
$dados = consultarBI('009261732KS048', $apiKey);

if (!$dados['error']) {
    echo "Nome: " . $dados['name'] . "\n";
    echo "Endereço: " . $dados['endereco'] . "\n";
    echo "Data Nascimento: " . $dados['data_de_nascimento'] . "\n";
}
</code></pre>

<h2>Exemplo em JavaScript (Node.js)</h2>
<pre><code>const axios = require('axios');

async function consultarBI(numero, apiKey) {
    try {
        const response = await axios.get(
            `https://portfolio-joaotomas.test/api/gateway/consulta-bi/consultar/${numero}`,
            {
                headers: {
                    'X-API-Key': apiKey,
                    'Accept': 'application/json'
                }
            }
        );
        return response.data;
    } catch (error) {
        return { error: true, message: 'Erro na requisição' };
    }
}

// Uso
const apiKey = 'pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxx';
const dados = await consultarBI('009261732KS048', apiKey);

if (!dados.error) {
    console.log('Nome:', dados.name);
    console.log('Endereço:', dados.endereco);
    console.log('Data Nascimento:', dados.data_de_nascimento);
}
</code></pre>

<h2>Exemplo em JavaScript (Frontend)</h2>
<pre><code>async function consultarBI(numero, apiKey) {
    try {
        const response = await fetch(
            `https://portfolio-joaotomas.test/api/gateway/consulta-bi/consultar/${numero}`,
            {
                headers: {
                    'X-API-Key': apiKey,
                    'Accept': 'application/json'
                }
            }
        );
        return await response.json();
    } catch (error) {
        return { error: true, message: 'Erro na requisição' };
    }
}

// Uso
const apiKey = 'pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxx';
const dados = await consultarBI('009261732KS048', apiKey);

if (!dados.error) {
    document.getElementById('nome').textContent = dados.name;
    document.getElementById('endereco').textContent = dados.endereco;
    document.getElementById('data').textContent = dados.data_de_nascimento;
}
</code></pre>

<h1>Erros Comuns e FAQ</h1>

<h2>Códigos de Erro</h2>
<table>
    <thead>
        <tr>
            <th>Código</th>
            <th>Descrição</th>
            <th>Solução</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>200</td>
            <td>Sucesso</td>
            <td>-</td>
        </tr>
        <tr>
            <td>400</td>
            <td>Requisição inválida</td>
            <td>Verifique os parâmetros enviados</td>
        </tr>
        <tr>
            <td>401</td>
            <td>Não autorizado</td>
            <td>Verifique sua chave de API</td>
        </tr>
        <tr>
            <td>403</td>
            <td>Permissão negada</td>
            <td>Sua chave não tem permissão para este recurso</td>
        </tr>
        <tr>
            <td>404</td>
            <td>Recurso não encontrado</td>
            <td>Verifique o número do documento</td>
        </tr>
        <tr>
            <td>429</td>
            <td>Muitas requisições</td>
            <td>Aguarde e tente novamente</td>
        </tr>
        <tr>
            <td>500</td>
            <td>Erro interno</td>
            <td>Contacte o suporte</td>
        </tr>
    </tbody>
</table>

<h2>FAQ</h2>

<h3>1. Como obtenho uma chave de API?</h3>
<p>Entre em contacto através do <a href="/contacto" style="color: var(--accent);">formulário de contacto</a> no site.</p>

<h3>2. Qual é o limite de requisições?</h3>
<p>O limite padrão é de 100 requisições por minuto.</p>

<h3>3. Os dados são cacheados?</h3>
<p>Sim, as respostas são cacheadas por 1 hora para melhor performance.</p>

<h3>4. Como identifico um erro?</h3>
<p>Todas as respostas de erro contêm um campo <code>error: true</code> e uma mensagem descritiva.</p>

<h3>5. A API é gratuita?</h3>
<p>Contacte para informações sobre planos e preços.</p>

<h2>Contacto</h2>
<p>Para suporte ou dúvidas: <a href="/contacto" style="color: var(--accent);">Formulário de Contacto</a></p>