Skip to content

About

SDK PHP para Emissor Fiscal e Monitor Fiscal da Webmania.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Webmania

Webmania SDK para PHP

Através do emissor fiscal da Webmania®, você conta com a emissão e o arquivamento dos seus documentos fiscais, cálculo automático de impostos, geração do DANFE para impressão e envio automático de e-mails para os clientes. Com este SDK, o seu sistema em PHP se integra à nossa REST API para emitir, consultar e cancelar NF-e, NFC-e, NFS-e, CT-e, MDF-e, NFCom e DC-e, baixar XML e PDF dos documentos e usar o Monitor Fiscal.

  • Emissor de Nota Fiscal Webmania®: Saiba mais
  • Documentação da REST API: Visualizar
  • Índice da documentação para assistentes de IA: llms.txt

Requisitos

  • Contrate um dos planos de Nota Fiscal Eletrônica da Webmania®: Assine agora mesmo.
  • PHP 8.3 ou superior, com as extensões curl, json, mbstring, dom e zlib.
  • Instale o Composer.
  • Credenciais de acesso da sua empresa, disponíveis no Painel de Controle.

Instalação

O SDK é distribuído pelo repositório github.com/webmaniabr/webmania-php e ainda não está publicado no Packagist. Clone o repositório e use o clone como repositório Composer path no seu projeto:

git clone https://github.com/webmaniabr/webmania-php.git /caminho/webmania-php
{"repositories":[{"type":"path","url":"/caminho/webmania-php","options":{"symlink":false}}],"require":{"webmaniabr/sdk":"@dev"}}

Execute composer install no seu projeto e carregue o autoload do Composer (require __DIR__ . '/vendor/autoload.php';).

Credenciais

Cada serviço usa a sua própria credencial. Guarde-as em variáveis de ambiente (ou em um cofre de segredos) no servidor e nunca as escreva no código-fonte:

Variável de ambiente Uso
WEBMANIA_CONSUMER_KEY, WEBMANIA_CONSUMER_SECRET, WEBMANIA_ACCESS_TOKEN, WEBMANIA_ACCESS_TOKEN_SECRET NF-e e NFC-e (NfeClient) e arquivos da NF-e (NfeFileClient)
WEBMANIA_ISSUER_TOKEN NFS-e, CT-e, MDF-e, NFCom e DC-e (EmissorClient) e seus arquivos (EmissorFileClient)
WEBMANIA_MONITOR_TOKEN Monitor Fiscal (MonitorClient)
<?php
require __DIR__ . '/vendor/autoload.php';

use Webmania\EmissorClient;
use Webmania\NfeClient;
use Webmania\NfeFileClient;
use Webmania\Requests\Api1\NfeIssueRequest;
use Webmania\Requests\Api2\Nfse\EmitterCancelNfsePayload;
use Webmania\Requests\Api2\Nfse\EmitterIssueNfsePayload;

$credenciais = [
    'consumerKey' => getenv('WEBMANIA_CONSUMER_KEY'),
    'consumerSecret' => getenv('WEBMANIA_CONSUMER_SECRET'),
    'accessToken' => getenv('WEBMANIA_ACCESS_TOKEN'),
    'accessTokenSecret' => getenv('WEBMANIA_ACCESS_TOKEN_SECRET'),
];
$nfe = new NfeClient(...$credenciais);                          // NF-e e NFC-e
$emissor = new EmissorClient(getenv('WEBMANIA_ISSUER_TOKEN'));  // NFS-e, CT-e, MDF-e, NFCom e DC-e

Os métodos devolvem arrays associativos com os campos da resposta da API.

Utilização

Os exemplos abaixo usam o ambiente de homologação (ambiente 2), em que os documentos não têm validade fiscal. Para emitir em produção, envie ambiente 1. Informe valores decimais como texto ('44.90') para manter a precisão.

Status do SEFAZ e certificado A1

$sefaz = $nfe->consultarSefaz();
echo $sefaz['status'];                 // online ou offline

$certificado = $nfe->consultarCertificado();
echo $certificado['expiration'];       // dias até o vencimento do certificado A1

Emitir NF-e

Para emitir uma NF-e, utilize o método emitirNota. O mesmo método emite NFC-e com modelo: 2.

$nota = $nfe->emitirNota(new NfeIssueRequest(
    operacao: 1,                                            // 1 = saída
    naturezaOperacao: 'Venda de produção do estabelecimento',
    modelo: 1,                                              // 1 = NF-e, 2 = NFC-e
    finalidade: 1,                                          // 1 = NF-e normal
    ambiente: 2,                                            // 2 = homologação, 1 = produção
    cliente: [
        'cpf' => '000.000.000-00',
        'nome_completo' => 'Nome do Cliente',
        'endereco' => 'Av. Brg. Faria Lima',
        'numero' => '1000',
        'bairro' => 'Itaim Bibi',
        'cidade' => 'São Paulo',
        'uf' => 'SP',
        'cep' => '00000-000',
        'email' => 'nome@email.com',
    ],
    produtos: [[
        'nome' => 'Nome do produto',
        'codigo' => 'nome-do-produto',
        'ncm' => '6109.10.00',
        'quantidade' => '1',
        'unidade' => 'UN',
        'origem' => 0,
        'subtotal' => '44.90',
        'total' => '44.90',
        'classe_imposto' => 'REF1000',                      // classe de imposto cadastrada no Painel
    ]],
    pedido: [
        'presenca' => 2,                                    // operação não presencial, pela internet
        'modalidade_frete' => 9,                            // sem frete
        'pagamento' => 0,                                   // pagamento à vista
        'forma_pagamento' => '01',                          // dinheiro
        'total' => '44.90',
    ],
));

echo $nota['uuid'];        // identificador único da nota fiscal
echo $nota['status'];      // aprovado, reprovado, processamento, contingencia...
echo $nota['nfe'];         // número da NF-e
echo $nota['serie'];       // série
echo $nota['chave'];       // chave de acesso
echo $nota['xml'];         // URL do XML
echo $nota['danfe'];       // URL do DANFE (PDF)
echo $nota['motivo'];      // retorno do SEFAZ

Somente o status aprovado indica uma nota autorizada. Quando o retorno for processamento, consulte a nota alguns segundos depois.

Consultar NF-e

$consulta = $nfe->consultarNota(uuid: $nota['uuid']);
echo $consulta['status'];

A consulta também aceita a chave de acesso (chave:).

Cancelar NF-e

$cancelamento = $nfe->cancelarNota('Cancelamento por erro no pedido.', uuid: $nota['uuid']);  // motivo: mínimo de 15 caracteres
echo $cancelamento['status'];

Baixar o DANFE e o XML

$arquivos = new NfeFileClient(...$credenciais);

file_put_contents('danfe.pdf', $arquivos->baixarDanfe($nota['uuid'])->bytes);
file_put_contents('nfe.xml', $arquivos->baixarXml($nota['uuid'])->bytes);

Emitir, consultar e cancelar NFS-e

A NFS-e é emitida a partir de um ou mais RPS com o método emitirNfse do EmissorClient:

$nfse = $emissor->emitirNfse(new EmitterIssueNfsePayload(
    ambiente: 2,                                            // 2 = homologação, 1 = produção
    rps: [[
        'servico' => [
            'valor_servicos' => '15.00',
            'discriminacao' => 'Prestação de serviço referente ao mês 10/2026',
            'classe_imposto' => 'REF000000',                // classe de imposto cadastrada no Painel
        ],
        'tomador' => ['cpf' => '000.000.000-00', 'nome_completo' => 'Nome do tomador'],
    ]],
));
echo $nfse['uuid'], ' ', $nfse['status'];

$consultaNfse = $emissor->consultarNfse($nfse['uuid']);
echo $consultaNfse['status'];

$canceladaNfse = $emissor->cancelarNfse(new EmitterCancelNfsePayload(
    uuid: $nfse['uuid'],
    motivo: '1',                                            // código do motivo (veja a documentação da NFS-e)
    justificativa: 'Serviço cancelado a pedido do tomador.', // mínimo de 15 caracteres
));
echo $canceladaNfse['status'];

Tratamento de erros

As falhas lançam exceções derivadas de Webmania\Exception\SdkException; a recusa da API chega como ApiException:

try {
    $nota = $nfe->emitirNota($pedido);
} catch (Webmania\Exception\ApiException $erro) {
    echo $erro->httpStatus;        // status HTTP
    echo $erro->getMessage();      // mensagem, com dados sensíveis mascarados
    if ($erro->outcomeUnknown) {
        // A requisição pode ter sido processada: consulte a nota antes de emitir de novo.
    }
} catch (Webmania\Exception\SdkException $erro) {
    echo $erro::class, ': ', $erro->getMessage();  // validação local, transporte ou resposta inválida
}

O SDK não repete requisições automaticamente. Se uma emissão ou um cancelamento terminar com resultado desconhecido (outcomeUnknown verdadeiro), consulte o documento antes de tentar novamente, para não emitir em duplicidade.

Métodos disponíveis

NF-e e NFC-e — NfeClient

  • emitirNota: Emissão de NF-e ou NFC-e junto ao SEFAZ.
  • consultarNota: Consulta da nota fiscal pelo UUID, pela chave de acesso ou pelo ID do pedido.
  • cancelarNota: Cancelamento de NF-e ou NFC-e.
  • emitirCartaCorrecao: Carta de correção.
  • inutilizarNumeracao: Inutilização de sequência de numeração.
  • emitirDevolucao: Emissão de NF-e de devolução.
  • emitirComplemento: Emissão de NF-e complementar.
  • emitirAjuste: Emissão de NF-e de ajuste.
  • manifestarNota: Manifestação do destinatário.
  • registrarConciliacao / cancelarConciliacao: Evento de conciliação financeira (ECONF) e o seu cancelamento.
  • registrarEventoIbsCbs / cancelarEventoIbsCbs: Eventos de IBS/CBS e o seu cancelamento.
  • listarClassesImposto / salvarClassesImposto / excluirClassesImposto: Classes de imposto.
  • gerarOuConsultarRelatorio: Relatórios fiscais.
  • atualizarEmpresa: Atualização dos dados da empresa emissora.
  • consultarSefaz: Verifica se o SEFAZ está online ou offline.
  • consultarCertificado: Verifica quantos dias faltam para o certificado A1 expirar.

NFS-e — EmissorClient

  • emitirNfse: Emissão de NFS-e a partir de RPS.
  • consultarNfse: Consulta da NFS-e.
  • cancelarNfse: Cancelamento da NFS-e.
  • substituirNfse: Substituição de NFS-e.
  • manifestarNfse: Manifestação sobre NFS-e nacional.
  • consultarStatusNfse: Recursos do provedor de NFS-e do município da empresa.

CT-e e CT-e OS — EmissorClient

  • emitirCte / emitirCteSimplificado: Emissão de CT-e, CT-e OS e CT-e simplificado.
  • consultarCte: Consulta do CT-e.
  • cancelarCte: Cancelamento do CT-e.
  • corrigirCte: Carta de correção do CT-e.
  • confirmarEntregaCte / cancelarEntregaCte: Comprovante de entrega e o seu cancelamento.
  • vincularPagamentoCte / cancelarVinculoPagamentoCte / consultarEventosPagamentoCte: Eventos de pagamento do CT-e.

MDF-e — EmissorClient

  • emitirMdfe: Emissão do MDF-e.
  • consultarMdfe: Consulta do MDF-e pela chave de acesso.
  • encerrarMdfe: Encerramento do MDF-e.
  • cancelarMdfe: Cancelamento do MDF-e.
  • incluirCondutorMdfe: Inclusão de condutor.

NFCom e DC-e — EmissorClient

  • emitirNfcom / consultarNfcom / cancelarNfcom: Emissão, consulta e cancelamento da NFCom.
  • consultarEventosPagamentoNfcom: Eventos de pagamento da NFCom.
  • consultarStatusNfcom: Disponibilidade do serviço da NFCom no SEFAZ.
  • emitirDce / consultarDce / cancelarDce: Emissão, consulta e cancelamento da DC-e.

Arquivos (XML e PDF) — NfeFileClient e EmissorFileClient

  • baixarDanfe / baixarDanfeSimples / baixarDanfeEtiqueta: DANFE completo, simplificado e etiqueta.
  • baixarXml / baixarCancelamentoXml: XML da NF-e e do cancelamento.
  • baixarCartaCorrecaoPdf / baixarCartaCorrecaoXml: PDF e XML da carta de correção.
  • baixarNfseXml / baixarNfsePdf / baixarNfseRpsPdf: XML e PDF da NFS-e e PDF do RPS.
  • baixarCteXml / baixarCtePdf / baixarMdfeXml / baixarMdfePdf / baixarNfcomXml / baixarNfcomPdf / baixarDceXml / baixarDcePdf: XML e PDF de CT-e, MDF-e, NFCom e DC-e.

Monitor Fiscal — MonitorClient

  • buscarDocumentos / consultarDocumento / listarEventosDocumento: Busca e consulta de documentos recebidos e do histórico de eventos.
  • manifestarDocumento: Manifestação do destinatário.
  • importarDocumento / consultarImportacao: Importação por chave de acesso, XML ou ZIP.
  • listarEmpresas / criarEmpresa / atualizarEmpresa: Empresas monitoradas.

Gerencial B2B — ResellerClient

  • criarEmpresas / listarEmpresas / consultarNotasProcessadas: Cadastro de empresas, listagem e contagem de notas processadas por empresa.

A lista completa, com todos os métodos do Monitor Fiscal e dos arquivos, está em docs/OPERATIONS.md.

Exemplo completo em homologação

A pasta examples/homologacao traz um programa que emite, consulta, baixa os arquivos e cancela uma NF-e e uma NFS-e em homologação, usando as credenciais das variáveis de ambiente. Por segurança, ele só envia requisições quando WEBMANIA_LIVE=1 está definido e WEBMANIA_LIVE_ALLOWED_HOSTS lista os hosts da API. Para rodar só as consultas (status do SEFAZ, certificado e provedor de NFS-e):

WEBMANIA_LIVE=1 WEBMANIA_LIVE_SCOPE=readonly WEBMANIA_LIVE_ALLOWED_HOSTS=webmania.com.br,nfe.webmania.com.br,api.webmania.com.br sh examples/homologacao/run.sh

As variáveis aceitas e o formato da saída estão em examples/homologacao/README.md.

Documentação

Suporte

Qualquer dúvida entre em contato na nossa Central de Ajuda ou acesse o Painel de Controle para conversar em tempo real no Chat ou Abrir um chamado.

Licença

Licença proprietária Webmania®: veja LICENSE e os Termos de Uso. As dependências de terceiros mantêm as suas próprias licenças.

About

SDK PHP para Emissor Fiscal e Monitor Fiscal da Webmania.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages