NF-e Invoices

Issues an NF-e (model 55). The issuing company is identified by the token header; do not send company_id in the body.

Required headers

Body — top-level fields

Body — cliente (object, required)

Body — products[] (array, at least 1 item)

Body — products[].impostos

{
  "icms": { "codigo_cfop": "6102", "situacao_tributaria": "00",
            "aliquota": "4", "aliquota_fcp": "2" }
}

{
  "icms": { "codigo_cfop": "6102", "situacao_tributaria": "00",
            "aliquota": "4", "aliquota_fcp": "1",
            "difal_desconta_icms_inter": true,
            "difal_base_por_dentro": true }
}

{
  "icms": { "aliquota": "4", "aliquota_fcp": "1", "v_bc_uf_dest": "122.29" }
}

Body — products[].ii (Import Tax)

Body — products[].import_declarations[]

Body — shipping_address / delivery_address (objects, optional)

Body — transportation (object, optional)

Body — pag_info[] (array, optional)

* Required field.

Response fields (data)

Response — rejection / error

        {
          "success": false,
          "data": {
            "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
            "status": "Failed",
            "motivo": "Rejeição 226: Código da UF do Emitente diverge da UF autorizadora / 拒绝 226: 发件人所在州代码与授权州不一致",
            "nfe": 100,
            "serie": 1,
            "chave": "",
            "modelo": "nfe",
            "epec": false,
            "xml": ""
          }
        }

Lists the company's NF-e with pagination. Parameters are passed via query string (not in the body). The time filter is optional, but if used, both start_create_time and end_create_time are required.

Required headers

Query string

* Required field.

Returns the details of a specific NF-e by UUID or by access key. Includes XML URL, DANFE URLs (full, simplified, and label) and metadata.

Required headers

Query string

Provide uuid or chave (at least one). If both are sent, uuid takes precedence.

Queries the current NF-e status at the tax authority and updates the local record. Useful when issuance remained in processing or contingency.

Required headers

Body

* Required field.

Cancels an authorized NF-e. The justification sent to the tax authority is fixed: "Erro no preenchimento da nota fiscal." — it cannot be configured via payload.

Required headers

Body

* Required field.

Response fields (data)

Response — error

        {
          "success": false,
          "message": "Rejeição: NF-e já está cancelada na base de dados da tax authority"
        }

Invalidates a contiguous range of NF-e numbers that were never authorized (not to be confused with cancellation — cancellation applies to already-authorized invoices). The operation is registered at the tax authority and is irreversible.

Required headers

Body

* Required field.

Response fields (data)

Response — error

        {
          "success": false,
          "message": "Rejeição: Faixa de numeração já inutilizada"
        }

Returns three URLs for an NF-e DANFE: the full DANFE (PDF), the simplified DANFE PDF (receipt format) and the simplified DANFE as a PNG (label image). PDFs are generated on demand from the authorized XML and cached in OSS. On subsequent calls, if the invoice status has not changed, the existing cache is returned; if the status has changed (e.g. the invoice was cancelled), PDFs are regenerated.

Required headers

Body

⚠ Either uuid or chave is required.

Response fields

Error responses

Starts an asynchronous bulk export task for the user's invoices, filtering by period and status. Can generate an Excel spreadsheet (metadata only) or a ZIP package with the XMLs. The first call creates the task and returns status: "Processing"; subsequent calls with the same parameters return the progress until status: "Success", when the url field contains the download link.

Required headers

Body

* Required field.

Response fields

Error responses

Consults the current status of an NF-e or NFC-e directly at the tax authority using the access key (44 digits), via the NfeConsultaProtocolo4 service. Works for both own invoices (issued by the token company) and third-party invoices (e.g. captured via DistDFe). The model (NF-e/NFC-e) is detected automatically from positions 20-21 of the key.

Required headers

Body

* Required field.

Response fields

Status mapping

Error responses

Issues a return NF-e (model 55, purpose 4) from an original NF-e. Two modes are supported: full return (reference the original invoice via uuid or chave — the return is a full clone of the original NF-e) or partial/custom return (send chave + the complete invoice fields in the request body itself, same structure as /api/invoice/create).

Required headers

Body — fields always read from the root

Body — fields inside return_detail

All fields below go inside the return_detail object. Placing them at the request root has no effect — the endpoint returns an error instead of silently falling back to a full return.

* Required field. uuid OR chave is also required (exactly one).

Automatic on returns: payment goes out as 90 (No Payment) — pag_info is ignored; empty natureza_operacao defaults to "Devolução de Mercadoria"; item taxation (CST/CSOSN, PIS/COFINS, IPI, IBS/CBS) comes from the fiscal category of category_id, matched by person type and scenario, or is sent inline per item via impostos — either one.

Required Headers

Required Headers

The request body and validation are identical to /api/invoice/create. The difference is that it does not wait for the tax authority: once validated, the request is queued and the receipt number task_id is returned immediately; issuance completes in the background. Fetch the result by polling /api/invoice/v2/task/get or receive it on the webhook address configured in the portal (see “Webhook callbacks” below).

Required headers

Body

Processing rules

Response fields

Response — rejected

{ "success": false, "message": "Rate limit exceeded for this CNPJ, please slow down" }

Query task status and result by task_id. The canonical path is /api/invoice/v2/task/get; the legacy path /api/invoice/task/get remains available with identical behaviour and billing. Only tasks submitted by the same account can be queried, otherwise Task not found. Poll every 1–2 seconds; tasks usually finish within seconds.

Required headers

Body

status

Sends a CC-e (event 110110) to the tax authority to correct data of an already authorized NF-e. The sequence (nSeqEvento) is calculated automatically — do not send it. Only non-fiscal data can be corrected (does not correct values, CNPJ, IE, etc.).

Required headers

Body

* Required field. At least one of uuid or chave is also required.

Invoices issued elsewhere can also receive a correction letter: the letter is an event independent of the original invoice, and the only requirement is that the issuer tax number embedded in the access key belongs to a company under this token. For such invoices the platform holds no original record, so the sequence number cannot be derived and defaults to 1. If the tax authority reports that an event with that number already exists, resubmit with a higher n_seq_evento. Correction letter PDF is not available for these invoices; only the event XML is.

Returns all CC-e (Correction Letters) issued for a specific NF-e, ordered from most recent to oldest.

Required headers

Body

At least one of uuid or chave is required.

Returns the CC-e PDF URL. The PDF is generated on demand on the first call (rendered from the invoice XML + CC-e XML) and stored in OSS; subsequent calls return the existing URL.

Required headers

Body

* Required field.

Returns the URL of the signed CC-e XML (already stored in OSS after submission to the tax authority).

Required headers

Body

* Required field.