README

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

✅ 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

Via Composer

composer require liontecnologia/averbporto

Manualmente

Baixe ou clone o repositório:

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

No seu projeto, inclua a classe:

require_once 'path/to/AverbePorto.php';

📖 Uso Rápido

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

// 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

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

// 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

$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)

$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)

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

Alterar Timeout (padrão: 60 segundos)

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

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

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

Verificar Status da Sessão

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

🛠️ 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

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)

Campo	Significado
`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

Veja a pasta 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

Credenciais de API

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

Acesse https://wws.averbeporto.com.br ou https://www.averbeporto.com.br
Vá no módulo Cadastro do Usuário
Clique no X para gerar novas credenciais de API
Use os valores gerados (60 caracteres de usuário, 64 de senha)

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

Endpoint

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

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

📋 Requisitos

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

📄 Documentação Completa

Consulte a documentação detalhada em docs/:

🤝 Contribuindo

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

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

📜 Licença

Este projeto está licenciado sob a MIT License.

🙋 Suporte

📧 Envie um email: seu.email@exemplo.com
🐛 Abra uma issue: Github Issues
📚 Wiki: Github Wiki

🔗 Recursos Externos

Desenvolvido com ❤️ para a comunidade PHP brasileira

liontecnologia / averbporto

Maintainers

Package info

Statistics

Security