ISSNet Integration
MIDDAG Account integrates with ISSNet to issue Brazilian electronic service invoices (NFSe -- Nota Fiscal de Servico Eletronica) for the municipality of Brasilia/DF. The integration uses the ABRASF 2.04 standard over SOAP.
What it does
When a payment is confirmed, the plugin automatically generates an NFSe. The tax invoice is submitted to the municipal tax authority, and the plugin tracks its status through polling until the NFSe is issued or an error occurs.
Setup
Prerequisites
- An active A1 digital certificate (.pfx file) issued for the company.
- A valid municipal registration (inscricao municipal) in Brasilia/DF.
- The certificate file must be stored outside the web root for security.
Configuration
All settings are stored in wp_options with the prefix middag_issnet_:
| Setting | Description | Example |
|---|---|---|
middag_issnet_cnpj_prestador | Company CNPJ (digits only) | 12345678000190 |
middag_issnet_inscricao_municipal | Municipal registration number | 0123456789 |
middag_issnet_certificado_path | Absolute path to the .pfx file | /etc/ssl/middag.pfx |
middag_issnet_certificado_senha | Certificate password (stored encrypted) | --- |
middag_issnet_ambiente | homologacao or producao | homologacao |
middag_issnet_codigo_servico | Service code per LC 116/2003 | 1.01 |
middag_issnet_aliquota_iss | ISS tax rate | 0.05 |
The certificate password is encrypted in wp_options -- it is never stored as plaintext.
Environments
| Environment | WSDL endpoint |
|---|---|
| Homologacao | https://www.issnetonline.com.br/homologaabrasf/webservicenfse204/nfse.asmx |
| Producao | Configurable via middag_issnet_wsdl_producao option |
Always test in homologacao before making changes to production configuration.
When it triggers
The emission flow starts when the plugin fires the middag_order_payment_confirmed event:
If ISSNet configuration is missing or incomplete, the plugin logs a warning and skips the emission. The rest of the order flow continues normally (graceful degradation).
Status tracking
The TaxInvoice entity tracks the full lifecycle:
| Status | Meaning |
|---|---|
PENDING | TaxInvoice created, not yet submitted |
PROCESSING | RPS submitted, awaiting municipal response |
ISSUED | NFSe issued successfully |
FAILED | Emission failed after retries |
CANCELLED | NFSe cancelled (within legal deadline) |
When the NFSe is issued, the plugin stores the NFSe number, verification code, and the public URL for the issued document.
SOAP operations
| Operation | Direction | Purpose |
|---|---|---|
RecepcionarLoteRps | Outbound | Submit an RPS lot (one RPS per lot) |
ConsultarSituacaoLoteRps | Polling | Check lot processing status |
ConsultarNfseServicoPrestado | Polling | Retrieve issued NFSe data |
CancelarNfse | Outbound | Cancel an issued NFSe (with reason) |
Cancellation
NFSe cancellation is allowed within 15 days of issuance (Brasilia/DF regulation). After this deadline, cancellation requires an administrative process with the municipality. The plugin blocks the cancellation action after the deadline has passed.
Error handling
| Scenario | Action |
|---|---|
| SOAP error code | Detailed log, TaxInvoice status set to FAILED, admin notified |
| Certificate expired | Emission blocked, admin notified by email and admin notice |
| SOAP timeout | Retry via WP-Cron with exponential backoff (max 3 attempts) |
| Incomplete configuration | Log warning, admin notice displayed. Emission not attempted. |
| Invalid payer CNPJ/CPF | TaxInvoice status set to FAILED with specific error message |
| Certificate file not found | Emission blocked, admin notified |
Retry policy
| Attempt | Timing |
|---|---|
| 1 | Immediate |
| 2 | +2 minutes |
| 3 | +10 minutes |
| After 3 | Status: FAILED |
An admin can reprocess a failed TaxInvoice manually from the admin UI.
Hooks
| Hook | When | Payload |
|---|---|---|
middag_taxinvoice_pending | TaxInvoice created | $tax_invoice_id |
middag_taxinvoice_issued | NFSe issued successfully | $tax_invoice_id, $nfse_number |
middag_taxinvoice_failed | Emission failed | $tax_invoice_id, $error |
middag_taxinvoice_cancelled | NFSe cancelled | $tax_invoice_id, $nfse_number |
middag_issnet_certificate_expiring | Certificate expires in < 30 days | $days_remaining |