README

Pacote Composer para integrar a API Consulta CPF da SERPRO em projetos Laravel, com autenticação OAuth2 (Bearer Token) e consulta de CPF.

Requisitos

• PHP 8.1+
• Laravel 10, 11, 12 ou 13
• Contrato da API com consumer_key e consumer_secret na Área do Cliente SERPRO

Instalação

Via GitHub (recomendado para uso interno)

1. Crie um repositório no GitHub e envie este pacote (veja seção Publicação no GitHub).
2. No composer.json do seu projeto Laravel, adicione o repositório VCS:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/samueletur/serpro-laravel"
        }
    ],
    "require": {
        "incode/serpro-consulta-cpf-laravel": "^1.0"
    }
}

1. Instale o pacote:

composer require incode/serpro-consulta-cpf-laravel

Para repositórios privados, configure autenticação do GitHub (token ou SSH) no Composer.

Via Packagist (opcional, repositório público)

Se o pacote estiver publicado no Packagist, basta executar:

composer require incode/serpro-consulta-cpf-laravel

Publicar configuração

php artisan vendor:publish --tag=serpro-consulta-cpf-config

Variáveis de ambiente

SERPRO_CONSUMER_KEY=seu_consumer_key
SERPRO_CONSUMER_SECRET=seu_consumer_secret
SERPRO_TOKEN_URL=https://gateway.apiserpro.serpro.gov.br/token
SERPRO_CPF_BASE_URL=https://gateway.apiserpro.serpro.gov.br/consulta-cpf-df
SERPRO_CPF_API_PREFIX=/v2
SERPRO_TIMEOUT=15
SERPRO_ACCEPT=application/json

Uso

Via Facade

use Serpro\ConsultaCpf\Facades\SerproConsultaCpf;

$dados = SerproConsultaCpf::consultaCpf('12345678909'); // CPF fictício para exemplo

Via injeção de dependência

use Serpro\ConsultaCpf\SerproConsultaCpfClient;

class ConsultaController
{
    public function show(SerproConsultaCpfClient $client)
    {
        $dados = $client->consultaCpf('12345678909'); // CPF fictício para exemplo

        return response()->json($dados);
    }
}

Observações importantes

• O token OAuth2 é renovado automaticamente quando necessário.
• O pacote normaliza CPF com máscara para apenas dígitos.
• Por padrão, o pacote aponta para a API v2 em produção (consulta-cpf-df + /v2/cpf/{cpf}). Para trial, use consulta-cpf-df-trial com prefixo /v1.
• SERPRO_TOKEN_URL e SERPRO_CPF_BASE_URL devem usar HTTPS e apontar para domínios *.serpro.gov.br; URLs inválidas impedem o boot da aplicação.
• Em consultaCpf(), os headers Authorization e Accept são sempre definidos pelo pacote e não podem ser sobrescritos. Não passe input de usuário em $headers.

Referência de documentação

• Introdução da API Consulta CPF: https://apicenter.estaleiro.serpro.gov.br/documentacao/consulta-cpf/pt/
• Guia rápido (OAuth2 e exemplo de chamada): https://apicenter.estaleiro.serpro.gov.br/documentacao/consulta-cpf/pt/quick_start/