Integração ISSNet
O MIDDAG Account integra-se ao ISSNet para emissão de notas fiscais eletrônicas de serviço (NFSe -- Nota Fiscal de Serviço Eletrônica) para o município de Brasília/DF. A integração utiliza o padrão ABRASF 2.04 via SOAP.
O que faz
Quando um pagamento é confirmado, o plugin gera automaticamente uma NFSe. A nota fiscal é submetida à autoridade tributária municipal, e o plugin acompanha seu status por meio de polling até que a NFSe seja emitida ou um erro ocorra.
Configuração
Pré-requisitos
- Um certificado digital A1 válido (arquivo .pfx) emitido para a empresa.
- Uma inscrição municipal válida em Brasília/DF.
- O arquivo do certificado deve ser armazenado fora da raiz do servidor web por segurança.
Configurações
Todas as configurações são armazenadas em wp_options com o prefixo middag_issnet_:
| Configuração | Descrição | Exemplo |
|---|---|---|
middag_issnet_cnpj_prestador | CNPJ da empresa (apenas dígitos) | 12345678000190 |
middag_issnet_inscricao_municipal | Número da inscrição municipal | 0123456789 |
middag_issnet_certificado_path | Caminho absoluto para o arquivo .pfx | /etc/ssl/middag.pfx |
middag_issnet_certificado_senha | Senha do certificado (armazenada criptografada) | --- |
middag_issnet_ambiente | homologacao ou producao | homologacao |
middag_issnet_codigo_servico | Código do serviço conforme LC 116/2003 | 1.01 |
middag_issnet_aliquota_iss | Alíquota do ISS | 0.05 |
A senha do certificado é criptografada em wp_options -- nunca é armazenada em texto plano.
Ambientes
| Ambiente | Endpoint WSDL |
|---|---|
| Homologação | https://www.issnetonline.com.br/homologaabrasf/webservicenfse204/nfse.asmx |
| Produção | Configurável via opção middag_issnet_wsdl_producao |
Sempre teste em homologação antes de fazer alterações na configuração de produção.
Quando é acionado
O fluxo de emissão inicia quando o plugin dispara o evento middag_order_payment_confirmed:
Se a configuração do ISSNet estiver ausente ou incompleta, o plugin registra um aviso e pula a emissão. O restante do fluxo do pedido continua normalmente (degradação graciosa).
Rastreamento de status
A entidade TaxInvoice rastreia o ciclo de vida completo:
| Status | Significado |
|---|---|
PENDING | TaxInvoice criada, ainda não submetida |
PROCESSING | RPS submetido, aguardando resposta municipal |
ISSUED | NFSe emitida com sucesso |
FAILED | Emissão falhou após retentativas |
CANCELLED | NFSe cancelada (dentro do prazo legal) |
Quando a NFSe é emitida, o plugin armazena o número da NFSe, o código de verificação e a URL pública do documento emitido.
Operações SOAP
| Operação | Direção | Finalidade |
|---|---|---|
RecepcionarLoteRps | Saída | Submeter um lote de RPS (um RPS por lote) |
ConsultarSituacaoLoteRps | Polling | Verificar status de processamento do lote |
ConsultarNfseServicoPrestado | Polling | Recuperar dados da NFSe emitida |
CancelarNfse | Saída | Cancelar uma NFSe emitida (com motivo) |
Cancelamento
O cancelamento de NFSe é permitido em até 15 dias após a emissão (regulamentação de Brasília/DF). Após esse prazo, o cancelamento requer um processo administrativo junto à prefeitura. O plugin bloqueia a ação de cancelamento após o prazo ter expirado.
Tratamento de erros
| Cenário | Ação |
|---|---|
| Código de erro SOAP | Log detalhado, status da TaxInvoice definido como FAILED, admin notificado |
| Certificado expirado | Emissão bloqueada, admin notificado por e-mail e aviso no admin |
| Timeout SOAP | Retentativa via WP-Cron com backoff exponencial (máximo 3 tentativas) |
| Configuração incompleta | Registrar aviso, aviso no admin exibido. Emissão não tentada. |
| CNPJ/CPF do tomador inválido | Status da TaxInvoice definido como FAILED com mensagem de erro específica |
| Arquivo de certificado não encontrado | Emissão bloqueada, admin notificado |
Política de retentativa
| Tentativa | Timing |
|---|---|
| 1 | Imediata |
| 2 | +2 minutos |
| 3 | +10 minutos |
| Após 3 | Status: FAILED |
Um admin pode reprocessar manualmente uma TaxInvoice com falha pela interface admin.
Hooks
| Hook | Quando | Payload |
|---|---|---|
middag_taxinvoice_pending | TaxInvoice criada | $tax_invoice_id |
middag_taxinvoice_issued | NFSe emitida com sucesso | $tax_invoice_id, $nfse_number |
middag_taxinvoice_failed | Emissão falhou | $tax_invoice_id, $error |
middag_taxinvoice_cancelled | NFSe cancelada | $tax_invoice_id, $nfse_number |
middag_issnet_certificate_expiring | Certificado expira em menos de 30 dias | $days_remaining |