Invoices

Response — 202 Accepted

{
  "data": {
    "id": "6c4d2e81-0a3b-4c5d-9e7f-1a2b3c4d5e6f",
    "companyId": "3f1c8a90-6b2e-4d5a-9c11-8e2f0a7b4d11",
    "environment": "test",
    "externalId": "pedido_123",
    "idempotencyKey": "pedido_123_emissao",
    "status": "queued",
    "amount": 150.5,
    "currency": "BRL",
    "competenceDate": "2026-10-01T00:00:00.000Z",
    "stage": "pending",
    "createdAt": "2026-10-10T12:00:00.000Z"
  }
}

Send an Idempotency-Key header: with the same key, account and environment and equivalent content, the hash recovers the same invoice; different content returns 409 (ERROR_IDEMPOTENCY_CONFLICT). The hash is computed before fiscal normalization, with canonical JSON keys and the competence date. Do not change how fields are represented between retries: a CNPJ with and without punctuation can produce different hashes. Without a key there is no deduplication.

Issuance is asynchronous — see the Async issuance guide. Track the invoice with GET /v1/invoices/:id or webhooks. The customer address is reduced to city and state in the snapshot; street, zip and country are not preserved — do not rely on them in the response.

Response — 202 Accepted

{
  "data": {
    "total": 3,
    "accepted": 2,
    "rejected": 1,
    "results": [
      {
        "index": 0,
        "status": "accepted",
        "invoice": {
          "id": "6c4d2e81-0a3b-4c5d-9e7f-1a2b3c4d5e6f",
          "companyId": "3f1c8a90-6b2e-4d5a-9c11-8e2f0a7b4d11",
          "environment": "test",
          "idempotencyKey": "planilha-out-linha-2",
          "status": "queued",
          "amount": 150.5,
          "currency": "BRL",
          "competenceDate": "2026-10-01T00:00:00.000Z",
          "stage": "pending",
          "createdAt": "2026-10-10T12:00:00.000Z"
        }
      },
      {
        "index": 1,
        "status": "accepted",
        "replayed": true,
        "invoice": {
          "id": "0b7a1f52-3c4d-4e6f-8a9b-2c3d4e5f6a7b",
          "status": "queued",
          "idempotencyKey": "planilha-out-linha-3",
          "amount": 300
        }
      },
      {
        "index": 2,
        "status": "rejected",
        "error": {
          "code": "ERROR_VALIDATION",
          "message": "Request validation failed",
          "details": [
            { "field": "amount", "code": "ERROR_OUT_OF_RANGE", "message": "amount must be greater than 0" }
          ]
        }
      }
    ]
  }
}

**All or nothing for the valid ones, never for the batch.** Every accepted item is saved in one single commit, with its credit reservation and its queue message. An invalid item (validation, company not found or not ready, missing certificate in live, plan limit) comes back rejected and is discarded without affecting the others. If something unexpected fails while saving, nothing at all is saved and you can repeat the same batch safely.

**Reading the result.** results has one entry per item, in the order sent: use index to match each result to the row of your spreadsheet or to your own record. Fix only the rejected rows and send them again; the accepted ones are already saved. Always send an idempotencyKey per item (for example file-row-7): after a timeout, repeating the whole batch returns the saved ones as replayed: true and retries only the missing ones. A key repeated inside the same batch is rejected with ERROR_DUPLICATE_IDEMPOTENCY_KEY_IN_BATCH.

In live, each accepted item reserves one credit, like POST /v1/invoices. When the monthly or daily limit is reached in the middle of the batch, the items that fit are saved and the rest come back rejected with ERROR_MONTHLY_LIMIT_EXCEEDED, ERROR_DAILY_LIMIT_EXCEEDED or ERROR_PLAN_BLOCKED. The route accepts up to 10 batches per minute per tenant (429 with Retry-After). For AI agents, the MCP tool nfse_issue_batch has the same contract.

Response — 200 OK

{
  "data": {
    "preEmission": true,
    "status": "ready",
    "disclaimer": "Pre-emission calculation. Values are not a fiscal document and may differ from the final validation by Sefin.",
    "competenceDate": "2026-10-13",
    "taxRegime": "MEI",
    "classification": {
      "serviceCode": "060101",
      "source": "official_catalog",
      "operationNature": "SERVICE",
      "nbsCode": null,
      "cst": null,
      "classCode": null,
      "serviceProfileId": null,
      "catalogValidated": false
    },
    "applicability": {
      "customerRequired": false,
      "strategy": "mei",
      "iss": {
        "status": "NOT_APPLICABLE",
        "reason": "ISS recolhido no DAS-MEI"
      },
      "federalWithholding": {
        "status": "NOT_APPLICABLE",
        "reason": "no federal withholding on payments to Simples Nacional/MEI optants (IN RFB 1.234/2012, art. 4, XI)"
      },
      "cbs": {
        "status": "NOT_APPLICABLE",
        "reason": "MEI não destaca IBS/CBS na fase de teste de 2026"
      },
      "ibs": {
        "status": "NOT_APPLICABLE",
        "reason": "MEI não destaca IBS/CBS na fase de teste de 2026"
      }
    },
    "taxes": {},
    "withholdings": [],
    "netReceivableAmount": "50.00",
    "collectionWaived": false,
    "calculation": {
      "source": "none",
      "calculatorVersion": null,
      "rulesVersion": "2026.10-r1",
      "legalReferences": [
        "Ato Conjunto RFB/CGIBS nº 4/2026; orientação CGNFS-e de 07/08/2026"
      ]
    },
    "warnings": [
      {
        "code": "CLASSIFICATION_NOT_CATALOG_VALIDATED",
        "message": "Service tax classification was not validated against the official catalog",
        "step": "ServiceTaxClassifier"
      }
    ],
    "pendingFields": [],
    "blocking": null,
    "trace": [
      {
        "step": "CompanyFiscalProfile",
        "status": "applied",
        "durationMs": 2.4
      },
      {
        "step": "ServiceTaxClassifier",
        "status": "applied",
        "durationMs": 7.1
      },
      {
        "step": "TaxApplicabilityResolver",
        "status": "applied",
        "durationMs": 0.3
      },
      {
        "step": "RtcTaxCalculator",
        "status": "skipped",
        "durationMs": 0.03,
        "reason": "MEI não destaca IBS/CBS na fase de teste de 2026"
      },
      {
        "step": "FiscalValidator",
        "status": "applied",
        "durationMs": 0.1
      }
    ]
  }
}

status: "ready" means the fiscal data is complete and the calculation was done. It is a pre-emission estimate, not an authorization from Sefin. Amounts and rates are decimal strings. The response never returns the customer's name or CPF/CNPJ.

A fiscal problem is not an HTTP error: it returns 200 with status: "blocked", blocking (code, message, step) and pendingFields[] listing what is missing, for example FISCAL_CLASSIFICATION_REQUIRED or TAX_RATE_NOT_FOUND. Values already computed before the block stay in the response. Invalid input follows the normal envelope (404 unknown company, 422 invalid field).

503 with Retry-After (seconds) when the tax calculator is unavailable: retry later, never estimate. The rate limit is the same as any authenticated endpoint (429 with Retry-After). A future competence date is accepted only up to 15 days ahead.

Response — 200 OK

{
  "data": [
    {
      "id": "6c4d2e81-0a3b-4c5d-9e7f-1a2b3c4d5e6f",
      "status": "authorized",
      "amount": 150.5,
      "competenceDate": "2026-10-01T00:00:00.000Z",
      "createdAt": "2026-10-10T12:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "hasMore": true,
    "nextCursor": "eyJ2IjoxLCJjcmVhdGVkQXQiOiIyMDI2LTEwLTA5VDEyOjAwOjAwLjAwMDAwMFoiLCJpZCI6IjNmMWM4YTkwIn0"
  }
}

Ordering is createdAt DESC with an ID tie-break. Continue with pagination.nextCursor until hasMore: false; newer inserts do not show up when continuing, and there is no total.

Response — 200 OK

{
  "data": {
    "id": "6c4d2e81-0a3b-4c5d-9e7f-1a2b3c4d5e6f",
    "status": "authorized",
    "stage": "documents_ready",
    "documentsStatus": "ready",
    "accessKey": "35260712345678900000350010000000011000000019",
    "nfseNumber": 123
  }
}

Returns 404 if the invoice is not found in the account/environment. An id that is not a valid UUID returns 400 (ERROR_BAD_REQUEST).

Returns raw XML with Content-Type: application/xml and Content-Disposition: attachment; filename="nfse-<number-or-id>.xml" — no JSON envelope.

The invoice must be authorized, otherwise 404. Availability also depends on document storage.

Returns PDF bytes with Content-Type: application/pdf and Content-Disposition: inline; filename="nfse-<number-or-id>.pdf" — no JSON envelope.

The invoice must be authorized, otherwise 404. Availability also depends on document storage.

Response — 200 OK

{
  "data": [
    {
      "id": "e1d2c3b4-5a6f-4b7c-8d9e-0f1a2b3c4d5e",
      "invoiceId": "6c4d2e81-0a3b-4c5d-9e7f-1a2b3c4d5e6f",
      "fromStatus": "queued",
      "toStatus": "authorized",
      "reason": null,
      "createdAt": "2026-10-10T12:01:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "hasMore": false,
    "nextCursor": null
  }
}

Fields: id, invoiceId, fromStatus (string or null), toStatus, reason (string or null), createdAt.

Response — 200 OK

{
  "data": {
    "downloadUrl": "https://storage.example.com/documento-assinado",
    "expiresAt": "2026-10-10T15:00:00.000Z",
    "fileName": "nfse-123.pdf",
    "mimeType": "application/pdf"
  }
}

The response comes with Cache-Control: no-store. The URL is valid for 3600 seconds at the storage. Use it directly and protect it as a temporary credential.

The invoice must be authorized and have documentsReadyAt, otherwise 409. Missing invoice: 404. Storage unavailable: 503.

Response — 202 Accepted

{
  "data": {
    "emailId": "pedido_123_email",
    "status": "queued"
  }
}

Optional Idempotency-Key header: 1–64 characters, letters, numbers, _ and - only. Deduplication checks for the existence of this invoice/key job in the queue.

202 does not confirm delivery. On a repeat request the status may reflect the last state of the email. Errors: 404 invoice missing; 409 documents not ready; 422 customer without email or invalid idempotency key.

Response — 202 Accepted

{
  "data": {
    "id": "6f1c0e2a-4b7d-4c1e-9a55-2b8f7c3d9e10",
    "status": "cancelling",
    "stage": "completed",
    "cancellationReason": "issue_error",
    "cancellationDescription": "Service amount was informed incorrectly",
    "cancelledAt": null,
    "cancellationRequestedAt": null
  }
}

reason: issue_error, service_not_provided or other. description is required (15–255 characters) for an authorized NFS-e and optional for a queued invoice. A processing invoice also requires description; once it is authorized it is cancelled automatically at the Sefin and the credit is not refunded, and if the emission ends rejected or failed the request is discarded and the reservation refunded as usual. Repeating the request for a processing (first request wins), cancelling or cancelled invoice returns its current state.

202 does not confirm the cancellation: wait for nfse.invoice.cancelled or nfse.invoice.cancellation_rejected (the invoice returns to authorized with lastErrorCode). Cancelling an issued NFS-e does not refund the credit; cancelling a queued invoice releases the live reservation. Errors: 404 invoice missing; 409 ERROR_INVOICE_NOT_CANCELLABLE (e.g. retry_pending, reconciliation_required, manual_review); 422 ERROR_INVALID_CANCELLATION_REASON. If another request already cancelled the invoice, the current state is returned.