PHPackages                             ferreiramg/serasa - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. ferreiramg/serasa

ActiveLibrary[API Development](/categories/api)

ferreiramg/serasa
=================

Laravel package for consuming Tecnospeed Serasa API - Official API v2 integration with async consultation support

v1.0.2(9mo ago)05MITPHPPHP ^8.2CI passing

Since Jul 17Pushed 9mo agoCompare

[ Source](https://github.com/Ferreiramg/serasa)[ Packagist](https://packagist.org/packages/ferreiramg/serasa)[ Docs](https://github.com/Ferreiramg/serasa)[ RSS](/packages/ferreiramg-serasa/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (10)Versions (4)Used By (0)

Tecnospeed Serasa Package para Laravel
======================================

[](#tecnospeed-serasa-package-para-laravel)

[![PHP Version](https://camo.githubusercontent.com/c9f64f714c636ba27a3bba6dfd52f98426832db1262747efa54b212d16943651/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e322d626c7565)](https://packagist.org/packages/ferreiramg/serasa)[![Laravel Version](https://camo.githubusercontent.com/ec976ad699fb5ffbb43421eabc292424a8b0bc5bed7a28e11e6349c67e2b6599/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d25354531322e302d726564)](https://packagist.org/packages/ferreiramg/serasa)[![Latest Stable Version](https://camo.githubusercontent.com/95ba2964d7fb24d49ea9a99a80b3ceceb337429d0c8c49f5348510b6e800a097/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f66657272656972616d672f736572617361)](https://packagist.org/packages/ferreiramg/serasa)[![Total Downloads](https://camo.githubusercontent.com/80c17fd9721a3abcdd5a08725f1c622fcf3aa5582701347a419e3d7712ee7fb5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f66657272656972616d672f736572617361)](https://packagist.org/packages/ferreiramg/serasa)[![Tests](https://github.com/Ferreiramg/serasa/actions/workflows/ci.yml/badge.svg)](https://github.com/Ferreiramg/serasa/actions/workflows/ci.yml)[![Code Coverage](https://camo.githubusercontent.com/d84679bb71bf6492ca151b1d5c6f9af7ab5994707a4b600f8f666f9e5ada88f9/68747470733a2f2f636f6465636f762e696f2f67682f46657272656972616d672f7365726173612f6272616e63682f6d61696e2f67726170682f62616467652e737667)](https://codecov.io/gh/Ferreiramg/serasa)[![Code Style](https://camo.githubusercontent.com/f02c35dab5a5cb9b393877445f2ef1e32d0650d192320422a7e8a763207a1a26/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f64652532307374796c652d4c61726176656c25323050696e742d6f72616e6765)](https://github.com/laravel/pint)[![Static Analysis](https://camo.githubusercontent.com/688ad4b838379100ee8664927a602bbf318fb8645b6d4eb856e425ed7e3df94f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f737461746963253230616e616c797369732d5048505374616e2d626c7565)](https://phpstan.org/)[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](LICENSE)

Um pacote Laravel para consumir a API oficial Tecnospeed Serasa, permitindo consultas de crédito assíncronas através de CPF ou CNPJ.

Características
---------------

[](#características)

- ✅ API oficial Tecnospeed Serasa (v2)
- ✅ Consultas assíncronas com protocolo
- ✅ Validação de CPF e CNPJ
- ✅ Múltiplos tipos de consulta (Crednet, Relatórios Básicos e Avançados)
- ✅ Suporte a ambiente de homologação e produção
- ✅ Tratamento de erros personalizado
- ✅ Suporte a Laravel 12 e PHP 8.2+
- ✅ Facade para facilitar o uso
- ✅ Testes unitários e de integração (83%+ cobertura)
- ✅ Code Style com Laravel Pint
- ✅ Análise estática com PHPStan

Qualidade e Testes
------------------

[](#qualidade-e-testes)

Este pacote segue as melhores práticas de desenvolvimento Laravel:

- **83%+ Cobertura de Testes**: Testes unitários e de integração abrangentes com Pest
- **Code Style**: Formatação automática com Laravel Pint
- **Análise Estática**: Verificação de tipos e bugs com PHPStan + Larastan
- **CI/CD**: GitHub Actions com validação automática de qualidade
- **PSR-12**: Padrão de codificação seguido rigorosamente

```
# Executar todos os testes
composer test

# Executar testes com cobertura
composer test-coverage

# Verificar code style
vendor/bin/pint --test

# Análise estática
vendor/bin/phpstan analyse
```

Instalação
----------

[](#instalação)

Instale o pacote via Composer:

```
composer require ferreiramg/tecnospeed-serasa
```

### Publicar Configuração

[](#publicar-configuração)

Publique o arquivo de configuração:

```
php artisan vendor:publish --tag=tecnospeed-serasa-config
```

### Configuração do Ambiente

[](#configuração-do-ambiente)

Adicione as seguintes variáveis ao seu arquivo `.env`:

```
# Ambiente (homologacao ou producao)
TECNOSPEED_SERASA_ENVIRONMENT=homologacao

# URLs da API (normalmente não precisam ser alteradas)
TECNOSPEED_SERASA_BASE_URL_HML=https://api.consultanegativacao.com.br/v2/homologacao
TECNOSPEED_SERASA_BASE_URL_PROD=https://api.consultanegativacao.com.br/v2

# Credenciais de autenticação (fornecidas pela Tecnospeed)
TECNOSPEED_SERASA_CNPJ_SH=seu_cnpj_software_house
TECNOSPEED_SERASA_TOKEN_SH=seu_token_software_house
TECNOSPEED_SERASA_CNPJ_USUARIO=cnpj_do_usuario_final
TECNOSPEED_SERASA_LOGIN=login_scc
TECNOSPEED_SERASA_PASSWORD=senha_scc

# Configurações opcionais
TECNOSPEED_SERASA_TIMEOUT=30
TECNOSPEED_SERASA_RETRIES=3
TECNOSPEED_SERASA_CACHE_ENABLED=true
TECNOSPEED_SERASA_CACHE_TTL=300
```

Uso Básico
----------

[](#uso-básico)

### Usando a Facade

[](#usando-a-facade)

```
use Ferreiramg\TecnospeedSerasa\Facades\TecnospeedSerasa;

// Validar documento
$documento = '11144477735';
if (TecnospeedSerasa::validarDocumento($documento)) {
    // Solicitar consulta
    $response = TecnospeedSerasa::consultarPorDocumento($documento, 602, 'PR', 'HTML');

    if ($response->isSuccess()) {
        $protocolo = $response->getProtocolo();
        echo "Protocolo: {$protocolo}";

        // Consultar resultado posteriormente
        $resultado = TecnospeedSerasa::consultarProtocolo($protocolo);

        if ($resultado->isCompleted()) {
            echo "HTML: " . $resultado->getHtml();
        }
    }
}
```

### Usando Injeção de Dependência

[](#usando-injeção-de-dependência)

```
use Ferreiramg\TecnospeedSerasa\Services\TecnospeedSerasaService;
use Ferreiramg\TecnospeedSerasa\DTOs\ConsultationRequest;

class MeuController extends Controller
{
    public function consultar(TecnospeedSerasaService $serasa, $documento)
    {
        try {
            // Método 1: Usando método de conveniência
            $response = $serasa->consultarPorDocumento($documento, 602, 'PR', 'HTML');

            // Método 2: Usando DTO (mais flexível)
            $request = new ConsultationRequest($documento, 602, 'PR', 'HTML');
            $response = $serasa->solicitarConsulta($request);

            return response()->json([
                'protocolo' => $response->getProtocolo(),
                'status' => $response->getStatus()
            ]);
        } catch (\Exception $e) {
            return response()->json(['error' => $e->getMessage()], 500);
        }
    }
}
```

Tipos de Consulta Disponíveis
-----------------------------

[](#tipos-de-consulta-disponíveis)

CódigoDescrição1Crednet PF ou PJ TOP600Relatório Básico PF601Relatório Básico PJ602Relatório Avançado PF603Relatório Avançado PJMétodos Disponíveis
-------------------

[](#métodos-disponíveis)

### TecnospeedSerasaService

[](#tecnospeedserasaservice)

#### `consultarPorDocumento(string $documento, int $codConsulta = 602, ?string $uf = null, string $retorno = 'HTML'): ConsultationResponse`

[](#consultarpordocumentostring-documento-int-codconsulta--602-string-uf--null-string-retorno--html-consultationresponse)

Método de conveniência para solicitar consulta.

#### `solicitarConsulta(ConsultationRequest $request): ConsultationResponse`

[](#solicitarconsultaconsultationrequest-request-consultationresponse)

Solicita consulta usando objeto DTO.

#### `consultarProtocolo(string $protocolo): ConsultationResponse`

[](#consultarprotocolostring-protocolo-consultationresponse)

Consulta o resultado usando o protocolo retornado.

#### `validarDocumento(string $documento): bool`

[](#validardocumentostring-documento-bool)

Valida se o documento (CPF ou CNPJ) é válido.

#### `getTiposConsulta(): array`

[](#gettiposconsulta-array)

Retorna os tipos de consulta disponíveis.

### ConsultationResponse

[](#consultationresponse)

#### Métodos de Dados da Solicitação

[](#métodos-de-dados-da-solicitação)

- `getProtocolo(): ?string` - Protocolo da consulta
- `getStatus(): ?string` - Status da consulta
- `getDocumento(): ?string` - Documento consultado
- `getCodConsulta(): ?string` - Código da consulta

#### Métodos de Resultado

[](#métodos-de-resultado)

- `getResultado(): ?string` - Resultado da consulta
- `getHtml(): ?string` - HTML do resultado (quando disponível)

#### Métodos de Erro

[](#métodos-de-erro)

- `getCode(): ?int` - Código de erro HTTP
- `getMessage(): ?string` - Mensagem de erro
- `getErrors(): array` - Lista de erros detalhados
- `getErrorMessage(): ?string` - Primeira mensagem de erro

#### Métodos de Status

[](#métodos-de-status)

- `isSuccess(): bool` - Verifica se a solicitação foi bem-sucedida
- `isProcessing(): bool` - Verifica se está processando
- `isCompleted(): bool` - Verifica se foi finalizada
- `isUnauthorized(): bool` - Verifica se erro 401
- `isUnprocessableEntity(): bool` - Verifica se erro 422

Fluxo de Consulta Assíncrona
----------------------------

[](#fluxo-de-consulta-assíncrona)

A API Tecnospeed Serasa funciona de forma assíncrona:

1. **Solicitar Consulta**: Envie os dados e receba um protocolo
2. **Aguardar Processamento**: A consulta é processada em background
3. **Consultar Resultado**: Use o protocolo para obter o resultado

```
// 1. Solicitar consulta
$response = TecnospeedSerasa::consultarPorDocumento('11144477735', 602);
$protocolo = $response->getProtocolo();

// 2. Aguardar (pode implementar polling, webhook, etc.)
sleep(5);

// 3. Consultar resultado
$resultado = TecnospeedSerasa::consultarProtocolo($protocolo);

if ($resultado->isCompleted()) {
    $html = $resultado->getHtml();
    // Processar resultado
}
```

Exemplo de Controller Laravel Completo
--------------------------------------

[](#exemplo-de-controller-laravel-completo)

```