PHPackages                             jcf/auvo - 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. jcf/auvo

ActiveLibrary[API Development](/categories/api)

jcf/auvo
========

Pacote Laravel para integração com a API do Auvo - Sistema de gestão de serviços de campo (field service management)

v1.0.0(5mo ago)00MITPHPPHP ^8.2CI passing

Since Dec 1Pushed 5mo agoCompare

[ Source](https://github.com/jotafurtado/auvo-laravel)[ Packagist](https://packagist.org/packages/jcf/auvo)[ Docs](https://github.com/jotacfurtado/auvo-laravel)[ RSS](/packages/jcf-auvo/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (5)Versions (2)Used By (0)

Jcf/Auvo
========

[](#jcfauvo)

[![Latest Version on Packagist](https://camo.githubusercontent.com/491c242cbdb083fd36947ab4d47e36aa4f6aa17123fc6664cd27842cb36d2ce8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a63662f6175766f2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/jcf/auvo)[![Total Downloads](https://camo.githubusercontent.com/c44c18c915c6985febfeb307648d2d1e68d81f426a68e3b55b87fb93c4576577/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6a63662f6175766f2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/jcf/auvo)[![Tests](https://camo.githubusercontent.com/19c822fb109f85933e3ea8d79554ec78ad1e1346805e76ac6816f007346269fd/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6a6f7461636675727461646f2f6175766f2d6c61726176656c2f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/jotacfurtado/auvo-laravel/actions/workflows/tests.yml)[![License](https://camo.githubusercontent.com/061424a28644efccfaf38d616cc7b45edf4b86c9a6c906bd58179bff96895fb4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6a63662f6175766f2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/jcf/auvo)

Pacote Laravel para integração com a API do Auvo - Sistema de gestão de serviços de campo (field service management).

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

[](#instalação)

```
composer require jcf/auvo
```

Configuração
------------

[](#configuração)

Publicar o arquivo de configuração:

```
php artisan vendor:publish --provider="Jcf\Auvo\Providers\AuvoServiceProvider" --tag=config
```

Configurar as variáveis de ambiente no arquivo `.env`:

```
API_AUVO_API_KEY=sua-api-key
API_AUVO_API_TOKEN=seu-api-token
API_AUVO_BASE_URL=https://api.auvo.com.br/v2
AUVO_TIMEOUT=30
AUVO_RETRY=3
AUVO_RETRY_DELAY=100
AUVO_LOG_REQUESTS=false
```

**Importante:** A API Key e API Token podem ser obtidos em [Menu > Integração](https://app.auvo.com.br/integracao) na sua conta Auvo.

Autenticação
------------

[](#autenticação)

O pacote gerencia automaticamente a autenticação JWT com a API do Auvo. Os tokens têm validade de 30 minutos e são renovados automaticamente quando necessário.

**Nota importante:** A API Auvo não suporta refresh token. Quando o token expira (após 30 minutos), o pacote faz automaticamente um novo login.

### Métodos de Autenticação

[](#métodos-de-autenticação)

```
use Jcf\Auvo\Facades\Auvo;

// Fazer login manualmente
$token = Auvo::auth()->signIn();

// Obter token válido (renova automaticamente se necessário)
$token = Auvo::auth()->getValidToken();

// Obter apenas o access token
$accessToken = Auvo::auth()->getAccessToken();
```

Uso
---

[](#uso)

### Consultas Básicas

[](#consultas-básicas)

```
use Jcf\Auvo\Facades\Auvo;

// Buscar todos os usuários - retorna AuvoResponse
$response = Auvo::users()->get();

// Acessar entidades da resposta
$usuarios = $response->entityList();

// Buscar um usuário específico - retorna Collection
$usuario = Auvo::users()->first(123);

// Buscar todos os clientes
$response = Auvo::customers()->get();
$clientes = $response->entityList();

// Buscar uma tarefa específica
$tarefa = Auvo::tasks()->first(456);
```

### Objeto de Resposta AuvoResponse

[](#objeto-de-resposta-auvoresponse)

Requisições GET que retornam listas retornam um objeto `AuvoResponse` com métodos úteis para acessar dados e metadados da resposta:

```
use Jcf\Auvo\Facades\Auvo;

$response = Auvo::tasks()
    ->period('2024-01-01', '2024-01-31')
    ->get();

// Acessar a lista de entidades como Collection
$tasks = $response->entityList();

// Acessar dados de paginação
$totalItems = $response->totalItems();
$currentPage = $response->currentPage();
$pageSize = $response->pageSize();
$hasMore = $response->hasMorePages();

// Acessar links HATEOAS
$links = $response->links();

// Acessar todos os dados de paginação
$paginationData = $response->pagedSearchReturnData();

// Acessar dados brutos da resposta
$raw = $response->raw();

// Usar métodos de Collection diretamente (delegação mágica)
$filtered = $response->filter(fn($task) => $task['finished'] === true);
$mapped = $response->map(fn($task) => $task['taskID']);
$firstTask = $response->first();
$count = $response->count();
```

### Paginação Automática

[](#paginação-automática)

O pacote oferece métodos para buscar automaticamente todos os registros, iterando sobre todas as páginas da API:

```
use Jcf\Auvo\Facades\Auvo;

// Buscar TODOS os usuários (itera todas as páginas automaticamente)
// Retorna Collection diretamente
$todosUsuarios = Auvo::users()->getAll();

// Buscar TODAS as tarefas de um período
$todasTarefas = Auvo::tasks()
    ->period('2024-01-01', '2024-12-31')
    ->type(197448)
    ->getAll();

// Buscar TODOS os clientes ativos
$todosClientes = Auvo::customers()
    ->active()
    ->getAll();

// Buscar TODAS as equipes ativas
$todasEquipes = Auvo::teams()
    ->active()
    ->getAll();

// Para maior controle, use allPages() que retorna o objeto AllPagesQuery
$allPagesQuery = Auvo::tasks()->period('2024-01-01', '2024-12-31')->allPages();
$todasTarefas = $allPagesQuery->get(); // Retorna Collection
```

> **Nota:** O método `getAll()` itera automaticamente sobre todas as páginas, fazendo múltiplas requisições à API. Use com cuidado para não exceder o limite de 400 requisições por minuto.

### Query Builders Disponíveis

[](#query-builders-disponíveis)

O pacote oferece Query Builders completos para os seguintes recursos:

#### Users (Usuários)

[](#users-usuários)

```
// Buscar usuários administradores
$response = Auvo::users()->userType(3)->get();
$admins = $response->entityList();

// Buscar usuários disponíveis para tarefas
$response = Auvo::users()->availableForTasks()->get();
$disponiveis = $response->entityList();

// Buscar por email
$response = Auvo::users()->email('usuario@exemplo.com')->get();
$usuario = $response->entityList()->first();

// Combinar filtros
$response = Auvo::users()
    ->userType(2) // 1 - user | 2 - team manager | 3 - administrator
    ->availableForTasks()
    ->get();

$usuarios = $response->entityList();
```

#### Tasks (Tarefas)

[](#tasks-tarefas)

```
// Buscar tarefas por período
$response = Auvo::tasks()
    ->period('2024-01-01', '2024-01-31')
    ->get();

$tarefas = $response->entityList();

// Buscar tarefas de um usuário
$response = Auvo::tasks()
    ->userId(123)
    ->get();

$tarefas = $response->entityList();

// Buscar tarefas agendadas
$response = Auvo::tasks()->scheduled()->get();
$agendadas = $response->entityList();

// Buscar tarefas concluídas
$response = Auvo::tasks()->completed()->get();
$concluidas = $response->entityList();

// Combinar múltiplos filtros com paginação e seleção de campos
$response = Auvo::tasks()
    ->period('2024-01-01', '2024-01-31')
    ->userId(123)
    ->customerId(456)
    ->type(197448)
    ->page(1)
    ->pageSize(100)
    ->selectFields('taskID,customerId,customerDescription,finished')
    ->get();

$tarefas = $response->entityList();
$totalItens = $response->totalItems();
$hasMorePages = $response->hasMorePages();
```

#### Customers (Clientes)

[](#customers-clientes)

```
// Buscar clientes ativos
$response = Auvo::customers()->active()->get();
$clientes = $response->entityList();

// Buscar por CNPJ/CPF
$response = Auvo::customers()->document('12345678901')->get();
$cliente = $response->entityList()->first();

// Buscar por email
$response = Auvo::customers()->email('cliente@exemplo.com')->get();
$cliente = $response->entityList()->first();

// Buscar por segmento
$response = Auvo::customers()
    ->segmentId(10)
    ->active()
    ->get();

$clientes = $response->entityList();
```

#### Teams (Equipes)

[](#teams-equipes)

```
// Buscar equipes ativas
$response = Auvo::teams()->active()->get();
$equipes = $response->entityList();

// Buscar equipes por líder/gerente
$response = Auvo::teams()->managerId(123)->get();
$equipes = $response->entityList();

// Buscar por nome
$response = Auvo::teams()->name('Equipe A')->get();
$equipe = $response->entityList()->first();
```

### Operações CRUD

[](#operações-crud)

Todos os Query Builders suportam operações completas de CRUD:

```
// GET - Buscar recursos
$response = Auvo::users()->get();
$usuarios = $response->entityList();

// GET - Buscar recurso único
$usuario = Auvo::users()->first(123);

// POST - Criar novo recurso (retorna array)
$novoUsuario = Auvo::users()->create([
    'name' => 'João Silva',
    'email' => 'joao@exemplo.com',
    'smartPhoneNumber' => '11999999999',
    'culture' => 'pt-BR',
    'jobPosition' => 'Técnico',
    'userType' => 1,
    'password' => 'senha123',
    // ... outros campos
]);

// PATCH - Atualizar recurso (retorna array)
$usuarioAtualizado = Auvo::users()
    ->find(123)
    ->update([
        'name' => 'João Silva Santos',
        'email' => 'joao.novo@exemplo.com',
    ]);

// DELETE - Excluir recurso (retorna array)
$resultado = Auvo::users()->find(123)->delete();
```

### Filtros Genéricos

[](#filtros-genéricos)

Todos os Query Builders suportam filtros genéricos com o método `where()`:

```
$response = Auvo::users()
    ->where('campo', 'valor')
    ->where('outro_campo', 'outro_valor')
    ->get();

$usuarios = $response->entityList();
```

Rate Limiting
-------------

[](#rate-limiting)

**Importante:** A API Auvo tem limite de **400 requisições por minuto** por endereço IP.

Se o limite for excedido, você receberá uma exception `RateLimitException`. O pacote detecta automaticamente quando o rate limit é atingido.

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

[](#características)

- ✅ Autenticação JWT automática
- ✅ Renovação automática de tokens (novo login após 30 minutos)
- ✅ Tratamento automático de erros de autenticação
- ✅ Query Builders estilo Laravel para recursos core
- ✅ Suporte completo a CRUD (GET, POST, PATCH, DELETE)
- ✅ Métodos específicos para filtros comuns
- ✅ Suporte a filtros genéricos com `where()`
- ✅ **Objeto de resposta AuvoResponse para acesso simplificado aos dados**
- ✅ **Métodos mágicos de Collection em AuvoResponse**
- ✅ Paginação automática com `getAll()` e `allPages()`
- ✅ **Retorna Collections em vez de arrays para melhor manipulação**
- ✅ Métodos auxiliares para paginação manual (`page()`, `pageSize()`)
- ✅ Seleção de campos específicos (`selectFields()`)
- ✅ **Método `first()` para buscar entidades únicas**
- ✅ Detecção automática de rate limit
- ✅ Logs de requisições (opcional)
- ✅ Configuração via variáveis de ambiente
- ✅ Testes unitários e de integração completos

Exceptions
----------

[](#exceptions)

O pacote lança exceções específicas para diferentes tipos de erro:

- `AuvoException` - Erro genérico da API
- `AuthenticationException` - Erro de autenticação (401, 403)
- `NotFoundException` - Recurso não encontrado (404)
- `ValidationException` - Erro de validação (400, 422)
- `RateLimitException` - Rate limit excedido (403 com mensagem específica)

```
use Jcf\Auvo\Exceptions\RateLimitException;

try {
    $response = Auvo::users()->get();
    $usuarios = $response->entityList();
} catch (RateLimitException $e) {
    // Rate limit excedido - aguarde antes de tentar novamente
    sleep(60);
} catch (\Exception $e) {
    // Outro tipo de erro
    logger()->error('Erro na API Auvo: ' . $e->getMessage());
}
```

Documentação da API
-------------------

[](#documentação-da-api)

A documentação completa da API Auvo v2 está disponível em:

- `docs/api/auvoapiv2.apib` - Especificação API Blueprint

Requisitos
----------

[](#requisitos)

- PHP ^8.1
- Laravel ^10.0|^11.0|^12.0

Testes
------

[](#testes)

```
cd packages/jcf/auvo
composer install
./vendor/bin/phpunit
```

Licença
-------

[](#licença)

MIT

Suporte
-------

[](#suporte)

Para issues e dúvidas, utilize o [repositório no GitHub](https://github.com/jotacfurtado/auvo-laravel/issues).

Créditos
--------

[](#créditos)

Desenvolvido por [João C. Furtado](https://github.com/jotacfurtado).

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance70

Regular maintenance activity

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

169d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/780f9f462d79aec5189728479735d339b890a5db9d389f0b4ec6bb0627fd3ab7?d=identicon)[jotafurtado](/maintainers/jotafurtado)

---

Top Contributors

[![jotafurtado](https://avatars.githubusercontent.com/u/748350?v=4)](https://github.com/jotafurtado "jotafurtado (10 commits)")

---

Tags

apilaravelfsmIntegraçãoauvofield-service

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/jcf-auvo/health.svg)

```
[![Health](https://phpackages.com/badges/jcf-auvo/health.svg)](https://phpackages.com/packages/jcf-auvo)
```

###  Alternatives

[essa/api-tool-kit

set of tools to build an api with laravel

52680.5k](/packages/essa-api-tool-kit)[resend/resend-laravel

Resend for Laravel

1191.4M6](/packages/resend-resend-laravel)[smodav/mpesa

M-Pesa API implementation

16363.7k1](/packages/smodav-mpesa)[simplestats-io/laravel-client

Client for SimpleStats!

4515.5k](/packages/simplestats-io-laravel-client)[ardakilic/mutlucell

Mutlucell SMS API wrapper for sending sms text messages for Laravel

457.3k](/packages/ardakilic-mutlucell)[dariusiii/tmdb-laravel

Laravel Package for TMDB ( The Movie Database ) API. Provides easy access to the wtfzdotnet/php-tmdb-api library.

1821.1k](/packages/dariusiii-tmdb-laravel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)