PHPackages                             liontecnologia/averbporto - 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. liontecnologia/averbporto

ActiveLibrary[API Development](/categories/api)

liontecnologia/averbporto
=========================

Biblioteca PHP para integração com a API da Porto Seguro - AverbePorto. Automatize o envio de XML/ZIP (NF-e, CT-e, MDF-e, NFC-e) para averbação.

00PHPCI passing

Since Mar 30Pushed 3mo agoCompare

[ Source](https://github.com/liontecnologia/averb-porto)[ Packagist](https://packagist.org/packages/liontecnologia/averbporto)[ RSS](/packages/liontecnologia-averbporto/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependenciesVersions (1)Used By (0)

AverbePorto - Biblioteca PHP para API da Porto Seguro
=====================================================

[](#averbeporto---biblioteca-php-para-api-da-porto-seguro)

[![Latest Version](https://camo.githubusercontent.com/4f500dfd631d003a13acac4affded826f3d579c999346d3769d20280e9126c4e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d322e302d626c75652e737667)](https://packagist.org/packages/liontecnologia/averbporto)[![PHP Version](https://camo.githubusercontent.com/357bd877e2ddaedc5a1a5fb1fda9f01dd98bf8d10a851fd6461708bd2ab0d6ad/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344372e342d3838393262652e737667)](https://www.php.net/)[![License](https://camo.githubusercontent.com/8bb50fd2278f18fc326bf71f6e88ca8f884f72f179d3e555e20ed30157190d0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e2e737667)](LICENSE)

Biblioteca PHP completa para integração com a API da Porto Seguro (AverbePorto). Automatize o envio de documentos fiscais (XML, ZIP) para averbação e consulte protocolos ANTT.

📋 Recursos
----------

[](#-recursos)

- ✅ Autenticação segura com sessão via cookie
- ✅ Upload de XML e ZIP para averbação
- ✅ Suporte a documentos (NF-e, CT-e, MDF-e, NFC-e e eventos de cancelamento)
- ✅ Consulta de protocolo ANTT por chave de acesso
- ✅ Consulta inversa (protocolo → chave)
- ✅ Tratamento robusto de erros
- ✅ Sessão persistente (validade de 1 semana com credenciais de API)

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

[](#-instalação)

### Via Composer

[](#via-composer)

```
composer require liontecnologia/averbporto
```

### Manualmente

[](#manualmente)

1. Baixe ou clone o repositório:

```
git clone https://github.com/liontecnologia/averbporto.git
```

2. No seu projeto, inclua a classe:

```
require_once 'path/to/AverbePorto.php';
```

📖 Uso Rápido
------------

[](#-uso-rápido)

### 1. Inicializar a Biblioteca

[](#1-inicializar-a-biblioteca)

```
use AverbePorto\AverbePorto;

// Credenciais geradas no módulo "Cadastro do Usuário" da API
$usuario = 'SEU_USUARIO_API_60_CARACTERES';
$senha   = 'SUA_SENHA_API_64_CARACTERES';

$ap = new AverbePorto($usuario, $senha);
```

### 2. Upload de XML

[](#2-upload-de-xml)

```
// Enviar conteúdo XML direto
$xmlContent = file_get_contents('/caminho/para/arquivo.xml');
$response = $ap->upload($xmlContent);

if (AverbePorto::uploadOk($response)) {
    $protocolo = AverbePorto::extrairProtocolo($response);
    echo "Sucesso! Protocolo ANTT: $protocolo";
} else {
    echo "Erro: " . AverbePorto::interpretarStatus($response);
}
```

### 3. Upload de Arquivo

[](#3-upload-de-arquivo)

```
try {
    $response = $ap->uploadArquivo('/caminho/para/arquivo.xml');

    if (AverbePorto::uploadOk($response)) {
        echo "Arquivo averbado com sucesso!";
        echo "Protocolo: " . AverbePorto::extrairProtocolo($response);
    }
} catch (RuntimeException $e) {
    echo "Erro: " . $e->getMessage();
}
```

### 4. Upload em ZIP

[](#4-upload-em-zip)

```
// Se tiver múltiplos XMLs em um ZIP
$zipContent = file_get_contents('/caminho/para/arquivo.zip');
$response = $ap->upload($zipContent, AverbePorto::RECIPIENT_AUTO, 'arquivos.zip');

// Para ZIPs, o protocolo retorna um array
$protocolos = AverbePorto::extrairProtocolo($response);
print_r($protocolos);
```

### 5. Consultar Protocolo ANTT por Chave

[](#5-consultar-protocolo-antt-por-chave)

```
$chaves = [
    '4401234567890123456789012345678901234567',
    '4402345678901234567890123456789012345678'
];

$response = $ap->consultarChave($chaves);

if (!empty($response['S'])) {
    foreach ($response['S'] as $item) {
        echo "Chave: {$item['chave']} → Protocolo: {$item['protocolo']}\n";
    }
}
```

### 6. Consulta Inversa (Protocolo → Chave)

[](#6-consulta-inversa-protocolo--chave)

```
$protocolos = [
    '1234567890123456789012345678901234567890',
    '9876543210987654321098765432109876543210'
];

$response = $ap->consultarProtocolo($protocolos);

if (!empty($response['S'])) {
    foreach ($response['S'] as $item) {
        echo "Protocolo: {$item['protocolo']} → Chave: {$item['chave']}\n";
    }
}
```

🔐 Tipos de Remetente (Recipient)
--------------------------------

[](#-tipos-de-remetente-recipient)

Especifique o tipo do documento quando necessário:

```
// Automático (recomendado)
$ap->upload($content, AverbePorto::RECIPIENT_AUTO);

// Embarcador/Emitente
$ap->upload($content, AverbePorto::RECIPIENT_EMBARCADOR);

// Fornecedor
$ap->upload($content, AverbePorto::RECIPIENT_FORNECEDOR);

// Transportador
$ap->upload($content, AverbePorto::RECIPIENT_TRANSPORTADOR);

// Duplo Ramo
$ap->upload($content, AverbePorto::RECIPIENT_DUPLO_RAMO);
```

⚙️ Configuração Avançada
------------------------

[](#️-configuração-avançada)

### Alterar Timeout (padrão: 60 segundos)

[](#alterar-timeout-padrão-60-segundos)

```
$ap = new AverbePorto($usuario, $senha, AverbePorto::ENDPOINT, AverbePorto::COMP, 120);
```

### Usar Endpoint Customizado

[](#usar-endpoint-customizado)

```
$ap = new AverbePorto(
    $usuario,
    $senha,
    'https://apis.averbeporto.com.br/php/conn.php',  // seu endpoint
    5,   // código da empresa
    60   // timeout
);
```

### Forçar Relogin

[](#forçar-relogin)

```
// Útil se a sessão expirar
$ap->relogin();
```

### Verificar Status da Sessão

[](#verificar-status-da-sessão)

```
if ($ap->estaLogado()) {
    echo "Sessão ativa";
} else {
    echo "Sem sessão ativa";
}
```

🛠️ Tratamento de Erros
----------------------

[](#️-tratamento-de-erros)

```
try {
    $response = $ap->uploadArquivo('/arquivo.xml');
} catch (RuntimeException $e) {
    $mensagem = $e->getMessage();

    if (strpos($mensagem, 'login falhou') !== false) {
        echo "Credenciais inválidas ou sessão expirada";
    } elseif (strpos($mensagem, 'captcha exigido') !== false) {
        echo "Acesse o sistema web para resolver o captcha";
    } elseif (strpos($mensagem, 'acesso bloqueado') !== false) {
        echo "Verificar User-Agent ou subdomínio";
    } else {
        echo "Erro genérico: " . $mensagem;
    }
}
```

📚 Interpretação de Respostas
----------------------------

[](#-interpretação-de-respostas)

### Status do Upload

[](#status-do-upload)

```
$response = $ap->upload($xmlContent);

// Interpreta o status
echo AverbePorto::interpretarStatus($response);

// Verifica se processado com sucesso
if (AverbePorto::uploadOk($response)) {
    // OK
}

// Extrai protocolo
$protocolo = AverbePorto::extrairProtocolo($response);
```

### Campos da Resposta (campo S)

[](#campos-da-resposta-campo-s)

CampoSignificado`P`Processado (guardado com sucesso)`D`Duplicado (XML já existente)`R`Rejeitado (XML não é do tipo correto)`N`Negado (não é XML ou ZIP)📝 Exemplos Práticos
-------------------

[](#-exemplos-práticos)

Veja a pasta [examples/](./examples/) para exemplos de:

- Upload simples
- Upload em lote (batch)
- Tratamento de erros
- Consultas de protocolo
- Integração com banco de dados

🔐 Importantes Notas de Segurança
--------------------------------

[](#-importantes-notas-de-segurança)

### Credenciais de API

[](#credenciais-de-api)

⚠️ **NÃO use** credenciais web no acesso à API. Gere credenciais específicas:

1. Acesse  ou
2. Vá no módulo **Cadastro do Usuário**
3. Clique no **X** para gerar novas credenciais de API
4. Use os valores gerados (60 caracteres de usuário, 64 de senha)

### User-Agent

[](#user-agent)

A API requer um User-Agent válido. Padrão da biblioteca:

```
Mozilla/5.0 AverbePorto-PHP/2.0

```

Se ajustar, evite nomes proibidos conforme: [https://hub-data.crowdsec.net/web/bad\_user\_agents.regex.txt](https://hub-data.crowdsec.net/web/bad_user_agents.regex.txt)

### Endpoint

[](#endpoint)

⚠️ Use sempre: `https://apis.averbeporto.com.br/php/conn.php`

❌ **NÃO** use subdomínios como `www`, `wws` ou `api`

📋 Requisitos
------------

[](#-requisitos)

- **PHP**: 7.4 ou superior
- **Extensões**: cURL
- **Certificado SSL**: Para HTTPS

📄 Documentação Completa
-----------------------

[](#-documentação-completa)

Consulte a documentação detalhada em [docs/](./docs/):

- [Manual de Integração](./docs/MANUAL.md)
- [API Reference](./docs/API.md)
- [Troubleshooting](./docs/TROUBLESHOOTING.md)

🤝 Contribuindo
--------------

[](#-contribuindo)

Contribuições são bem-vindas! Por favor:

1. Faça fork do projeto
2. Crie uma branch para sua feature (`git checkout -b feature/algo-incrível`)
3. Commit suas mudanças (`git commit -m 'Adiciona algo incrível'`)
4. Push para a branch (`git push origin feature/algo-incrível`)
5. Abra um Pull Request

📜 Licença
---------

[](#-licença)

Este projeto está licenciado sob a [MIT License](LICENSE).

🙋 Suporte
---------

[](#-suporte)

- 📧 Envie um email:
- 🐛 Abra uma issue: [Github Issues](https://github.com/liontecnologia/averbporto/issues)
- 📚 Wiki: [Github Wiki](https://github.com/liontecnologia/averbporto/wiki)

🔗 Recursos Externos
-------------------

[](#-recursos-externos)

- [Portal AverbePorto](https://www.averbeporto.com.br)
- [API Manual Oficial](https://www.averbeporto.com.br/proxy/manual.php?format=pdf)
- [Especificação NF-e](http://sped.rfb.gov.br/pagina/show/1328)
- [Especificação CT-e](http://sped.rfb.gov.br/pagina/show/1126)
- [Especificação MDF-e](http://sped.rfb.gov.br/pagina/show/1515)

---

**Desenvolvido com ❤️ para a comunidade PHP brasileira**

###  Health Score

18

—

LowBetter than 8% of packages

Maintenance55

Moderate activity, may be stable

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity12

Early-stage or recently created project

 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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/567e6f558ae2cee94b1753f05915700f2eb385b8bb558ff9311e067d2684e05a?d=identicon)[ajoabe](/maintainers/ajoabe)

---

Top Contributors

[![liontecnologia](https://avatars.githubusercontent.com/u/55816003?v=4)](https://github.com/liontecnologia "liontecnologia (2 commits)")

### Embed Badge

![Health badge](/badges/liontecnologia-averbporto/health.svg)

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

###  Alternatives

[exsyst/swagger

A php library to manipulate Swagger specifications

35816.3M7](/packages/exsyst-swagger)[hubspot/api-client

Hubspot API client

24015.5M18](/packages/hubspot-api-client)[pocketmine/bedrock-protocol

An implementation of the Minecraft: Bedrock Edition protocol in PHP

172437.8k11](/packages/pocketmine-bedrock-protocol)[botman/driver-telegram

Telegram driver for BotMan

94452.6k6](/packages/botman-driver-telegram)

PHPackages © 2026

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