README

SDK oficial PHP para a API NFS-e Emitare — emita Notas Fiscais de Serviço Eletrônicas em todos os 5.570 municípios do Brasil, sem depender de nenhuma biblioteca externa (só cURL + JSON).

Requisitos

PHP >= 7.4
Extensão ext-curl
Extensão ext-json

Instalação

composer require emitare/nfse-php

Configuração

Obtenha sua API Key no painel Emitare. Para testes, use a chave demo:

use Emitare\EmitareClient;
use Emitare\EmitareException;

// Produção
$client = new EmitareClient('sua-api-key-aqui');

// Sandbox (para testes)
$client = new EmitareClient(
    'demo-api-key-nfsapi-2024',
    'https://sandbox.emitare.com.br/api/v1'
);

Exemplos de Uso

Emitir NFS-e

use Emitare\EmitareClient;
use Emitare\EmitareException;

$client = new EmitareClient('sua-api-key');

try {
    $resultado = $client->emitir([
        'empresaId' => '550e8400-e29b-41d4-a716-446655440000',
        'rps' => [
            'numero' => '1001',
            'serie'  => 'A1',
            'tipo'   => 1,
        ],
        'tomador' => [
            'cpfCnpj'     => '12345678000195',
            'razaoSocial' => 'Empresa Tomadora Ltda',
            'email'       => 'financeiro@tomadora.com.br',
            'endereco' => [
                'logradouro' => 'Rua das Flores',
                'numero'     => '100',
                'bairro'     => 'Centro',
                'municipio'  => 'São Paulo',
                'uf'         => 'SP',
                'cep'        => '01310100',
            ],
        ],
        'servico' => [
            'codigoMunicipio'    => 3550308,   // IBGE São Paulo
            'codigoServico'      => '01.07',   // LC 116/2003
            'discriminacao'      => 'Desenvolvimento de software sob encomenda — Projeto X',
            'valorServicos'      => 5000.00,
            'valorDeducoes'      => 0.00,
            'aliquotaIss'        => 2.0,
            'issRetido'          => false,
        ],
    ]);

    echo "NFS-e emitida com sucesso!\n";
    echo "Número: " . $resultado['numero'] . "\n";
    echo "Código verificação: " . $resultado['codigoVerificacao'] . "\n";

} catch (EmitareException $e) {
    echo "Erro {$e->getStatusCode()}: {$e->getMessage()}\n";
    if ($e->isValidationError()) {
        print_r($e->getErrors());
    }
}

Validar Dados ANTES de Emitir

Valide os dados sem gerar documento fiscal — útil para pré-validar formulários:

$validacao = $client->validar([
    'empresaId' => '550e8400-e29b-41d4-a716-446655440000',
    'tomador'   => [ /* ... */ ],
    'servico'   => [ /* ... */ ],
]);

if ($validacao['valido']) {
    echo "Dados válidos, pode emitir!\n";
} else {
    foreach ($validacao['erros'] as $campo => $msgs) {
        echo "{$campo}: " . implode(', ', $msgs) . "\n";
    }
}

Listar NFS-e Emitidas

$pagina = $client->listar(
    companyId: '550e8400-e29b-41d4-a716-446655440000',
    page:  1,
    limit: 20
);

echo "Total: " . $pagina['total'] . " notas\n";
foreach ($pagina['data'] as $nfse) {
    echo "#{$nfse['numero']} — {$nfse['tomador']['razaoSocial']} — R$ {$nfse['servico']['valorServicos']}\n";
}

Consultar com Filtros

$resultado = $client->consultar(
    companyId: '550e8400-e29b-41d4-a716-446655440000',
    filtros: [
        'dataInicio'   => '2025-01-01',
        'dataFim'      => '2025-12-31',
        'status'       => 'emitida',
        'tomadorCnpj'  => '12345678000195',
    ]
);

Cancelar NFS-e

// Códigos de motivo (ABRASF):
// 1 = Erro na emissão
// 2 = Serviço não prestado
// 3 = Duplicidade da nota
// 4 = Outros

$client->cancelar(
    companyId:  '550e8400-e29b-41d4-a716-446655440000',
    nfseNumero: '1001',
    codigo:     '1',
    motivo:     'Emissão duplicada por erro no sistema'
);

echo "NFS-e cancelada.\n";

Gerar DANFSe (PDF)

$pdfBytes = $client->gerarDanfse('uuid-da-nfse');

// Salvar em disco
file_put_contents('/tmp/danfse-1001.pdf', $pdfBytes);

// Ou enviar direto ao navegador
header('Content-Type: application/pdf');
header('Content-Disposition: inline; filename="danfse.pdf"');
echo $pdfBytes;

Tratamento de Erros

use Emitare\EmitareException;

try {
    $nfse = $client->emitir([...]);
} catch (EmitareException $e) {
    if ($e->isNetworkError()) {
        // Sem conexão com a API
        error_log('Falha de rede: ' . $e->getMessage());
    } elseif ($e->isAuthError()) {
        // API Key inválida ou sem permissão
        error_log('Erro de autenticação: verifique a API Key.');
    } elseif ($e->isValidationError()) {
        // Dados inválidos — exibir campos com erro
        $erros = $e->getErrors();
        foreach ($erros['details'] ?? [] as $detalhe) {
            echo "Campo {$detalhe['field']}: {$detalhe['message']}\n";
        }
    } elseif ($e->isServerError()) {
        // Erro interno no servidor Emitare
        error_log('Erro no servidor Emitare (5xx): ' . $e->getStatusCode());
    }
}

Ambiente Sandbox

Para testes sem emissão real:

$client = new EmitareClient(
    'demo-api-key-nfsapi-2024',
    'https://sandbox.emitare.com.br/api/v1'
);

Cobertura de Municípios

Provedor	Protocolo	Municípios
Ginfes	SOAP/ABRASF 2.x	~1200
Issnet	SOAP/ABRASF 2.04	~800
Sigiss	SOAP proprietário	~500
Betha	SOAP/ABRASF 2.02	~400
IPM	REST/XML	~350
SimplISS	SOAP/ABRASF	~300
eGoverne	SOAP/ABRASF 2.02	~200
DSF	SOAP proprietário	~50
Prodam	SOAP proprietário	São Paulo
Nacional	REST/ADN 2026	Todos

Suporte

Documentação: emitare.com.br/docs
E-mail: suporte@emitare.com.br
Issues: github.com/emitare/nfse-php/issues

Licença

MIT — veja LICENSE.

emitare / nfse-php

Maintainers

Package info

Statistics

Security