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
- 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,domezlib. - Instale o Composer.
- Credenciais de acesso da sua empresa, disponíveis no Painel de Controle.
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';).
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-eOs métodos devolvem arrays associativos com os campos da resposta da API.
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.
$sefaz = $nfe->consultarSefaz();
echo $sefaz['status']; // online ou offline
$certificado = $nfe->consultarCertificado();
echo $certificado['expiration']; // dias até o vencimento do certificado A1Para 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 SEFAZSomente o status aprovado indica uma nota autorizada. Quando o retorno for processamento, consulte a nota alguns segundos depois.
$consulta = $nfe->consultarNota(uuid: $nota['uuid']);
echo $consulta['status'];A consulta também aceita a chave de acesso (chave:).
$cancelamento = $nfe->cancelarNota('Cancelamento por erro no pedido.', uuid: $nota['uuid']); // motivo: mínimo de 15 caracteres
echo $cancelamento['status'];$arquivos = new NfeFileClient(...$credenciais);
file_put_contents('danfe.pdf', $arquivos->baixarDanfe($nota['uuid'])->bytes);
file_put_contents('nfe.xml', $arquivos->baixarXml($nota['uuid'])->bytes);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'];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.
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.
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.shAs variáveis aceitas e o formato da saída estão em examples/homologacao/README.md.
- Documentação da REST API: NF-e / NFC-e · NFS-e · CT-e · MDF-e · NFCom · DC-e · Monitor Fiscal · Gerencial B2B
- Contratos OpenAPI: API 2.0 e NF-e
- Detalhes técnicos do SDK (URL base, arquivos, relatórios, limites): docs/INTEGRATION.md
- Lista completa de métodos: docs/OPERATIONS.md
- Desenvolvimento e testes do SDK: docs/TESTING.md
- Histórico de versões: CHANGELOG.md
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 proprietária Webmania®: veja LICENSE e os Termos de Uso. As dependências de terceiros mantêm as suas próprias licenças.
