canonical: https://jentic.com/apis/notaguard.com.br/notaguard

# Notaguard API NotaGuard

The NotaGuard API reads the Brazilian fiscal documents that NotaGuard monitors for a company: NF-e, NFC-e, and NFS-e. A client can list and filter documents by type, status, the company's role as issuer or recipient, CFOP, value range, and reference or issue dates in Brasilia time, then open one document with optional blocks for taxes, references, tags, payment installments, and CFOPs. It returns line items and SEFAZ events, downloads the authorised XML, and renders the DANFE or DANFSe PDF. The API is read-only apart from one operation, which creates an asynchronous or direct batch export of XML and PDF files as a ZIP.

## For AI agents

List and filter a company's NF-e, NFC-e, and NFS-e fiscal documents, read their items, taxes, and SEFAZ events, and download the authorised XML or DANFE PDF.

## Scope

Does not issue, cancel, or register manifestations on fiscal documents with SEFAZ, and does not calculate tax. Use for reading and exporting a company's monitored NF-e, NFC-e, and NFS-e documents only.

## Capabilities

- List NF-e, NFC-e, and NFS-e documents filtered by tipo, status, vinculo, cfop, valor_min, and date ranges
- Open one fiscal document by UUID or access key and add taxes, references, tags, or installments with incluir
- Read a document's line items with per-item CFOP and the SEFAZ events recorded against it
- Download the authorised XML and render the DANFE or DANFSe PDF for a document
- Get aggregated totals for a filtered set of documents to close a period
- Sync incrementally by passing the last atualizada_em value to data_atualizacao_apos
- Create a batch ZIP export of XML and PDF files and poll its status

## Use cases

### AI bookkeeping agent for received invoices

An AI bookkeeping agent needs the invoices a Brazilian company received so it can match them against payables. Through Jentic the agent searches for 'list received fiscal documents', gets the NotaGuard list operation with its input schema, and calls it with vinculo=receptor and a data_ref_de to data_ref_ate period. It opens each document with incluir=tributos,duplicatas to read taxes and payment installments, with the bearer key injected at call time.

Example prompt: Call GET `/v1/notas` with tipo=NFe, vinculo=receptor, data_ref_de=2026-07-01, and data_ref_ate=2026-07-31, then call GET `/v1/notas/{id}` with incluir=tributos,duplicatas for each result and total the installments

### Incremental ERP sync

An ERP integration keeps a local copy of fiscal documents without rescanning the whole archive. It stores the highest atualizada_em it has received and passes that instant to data_atualizacao_apos on the next run, paging with proximo_cursor until tem_mais is false. Filtering by vinculo=receptor returns the received archive, which arrives with complete XML.

Example prompt: Call GET `/v1/notas` with vinculo=receptor and data_atualizacao_apos=2026-11-09T00:00:00Z, follow proximo_cursor until tem_mais is false, and record the highest atualizada_em for the next run

### Period close with totals and batch export

At month end, an accountant needs aggregated values and the document files for the period. GET `/v1/notas/resumo` returns totals for the same filters as the listing, and POST `/v1/notas/exportacoes` creates a ZIP export with the required formatos field set to xml, pdf, or both. The default arquivo delivery runs asynchronously and is tracked through GET `/v1/notas/exportacoes/{id}.`

Example prompt: Call GET `/v1/notas/resumo` with tipo=NFe and the month's data_ref_de and data_ref_ate range, then call POST `/v1/notas/exportacoes` with formatos set to xml and pdf and the same filtros, and poll GET `/v1/notas/exportacoes/{id}` until it is done

### Document audit by CFOP and SEFAZ events

A tax reviewer wants every document carrying specific CFOPs and its event history. The cfop filter on GET `/v1/notas` matches documents with any item in the listed codes, GET `/v1/notas/{id}/itens` shows the CFOP per item, and GET `/v1/notas/{id}/eventos` lists the SEFAZ events such as manifestations recorded on the document.

Example prompt: Call GET `/v1/notas` with cfop=5905,6905, then call GET `/v1/notas/{id}/itens` and GET `/v1/notas/{id}/eventos` for each document and list items with their CFOP and the latest event

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/notas` | List fiscal documents |
| GET | `/v1/notas/{id}` | Get one fiscal document |
| GET | `/v1/notas/resumo` | Get aggregated totals |
| GET | `/v1/notas/{id}/itens` | List document items |
| GET | `/v1/notas/{id}/eventos` | List SEFAZ events |
| GET | `/v1/notas/{id}/xml` | Download the authorised XML |
| GET | `/v1/notas/{id}/pdf` | Render the DANFE or DANFSe PDF |
| POST | `/v1/notas/exportacoes` | Create a batch export |

## Key resources

- **Notas** — NF-e, NFC-e, and NFS-e documents with status, role, value, dates, and optional taxes, references, tags, installments, and CFOPs
- **Items and events** — Line items with per-item CFOP and the SEFAZ events recorded on each document
- **Files** — Authorised XML and the DANFE or DANFSe PDF for each document
- **Exports** — Batch ZIP exports of XML and PDF files with trackable status

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 56 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 99 / 100
  - Developer Experience & Jentic Compatibility: 69 / 100
  - AI-Readiness & Agent Experience: 28 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 94 / 100
- **View full report:** https://jentic.com/apis/notaguard.com.br/notaguard/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring NotaGuard by hand means sending a per-company bearer key, paging with proximo_cursor, handling Brasilia-time date filters, and polling asynchronous exports. Through Jentic you install once, import NotaGuard from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** NotaGuard puts the document id in the URL path (`/v1/notas/{id}/xml`, `/v1/notas/{id}/pdf`), so a rule can bound your agent to specific read operations, and since each key opens one company the credential itself limits which company's documents are reachable. You choose the operations it may call, so the batch export POST is not included unless you add it.
- **Credential handling:** Your NotaGuard API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list received fiscal documents' or 'download an invoice XML', and Jentic returns the matching NotaGuard operation with its input schema, including filters like vinculo, cfop, and data_ref_de, so the agent calls the right endpoint directly.

## Related APIs

- **Cobrat API v2** — Brazilian billing service for listing boletos and NFS-e records
- **Boleto Cloud API** — Issue and manage Brazilian boleto payment slips
- **AvaTax API** — Sales tax calculation and compliance across many jurisdictions

## FAQ

### What authentication does the NotaGuard API use?

Per its OpenAPI spec, the NotaGuard API uses HTTP bearer authentication with a company API key in the ng_live_ format, sent in the Authorization header. Keys are created in the NotaGuard panel under Configurações, Integrações, API, and each key opens the documents of a single company. Through Jentic the key is held by your own instance and injected at call time.

### Can I download the XML and DANFE PDF with the NotaGuard API?

Yes. GET `/v1/notas/{id}/xml` returns the authorised XML and GET `/v1/notas/{id}/pdf` renders the DANFE or DANFSe. The {id} can be the UUID from the listing or the document's access key. Documents that only have a summary still return a summary XML, but the PDF needs the complete XML.

### What are the rate limits for the NotaGuard API?

The spec states a usage limit of 60 cost units per minute, per key, and GET `/v1/me` reports the remaining limit in the current window. Optional incluir blocks cost only the reads you ask for. Check the NotaGuard documentation at https://notaguard.com.br for current details.

### Why does a NotaGuard document show status resumida without a value?

For a received document, SEFAZ delivers a summary first and the full document after the recipient registers a manifestation such as ciência da operação, so the state is usually transient. For a document your company issued, SEFAZ does not return the XML to the issuer, so it stays a summary until you upload the XML in the panel. Filtering with vinculo=receptor returns the received archive.

### How do I list received invoices for a month through Jentic?

Search Jentic for 'list received fiscal documents', load the NotaGuard list operation, and call GET `/v1/notas` with vinculo=receptor and data_ref_de and data_ref_ate set to the month. Follow proximo_cursor until tem_mais is false. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Is there a NotaGuard MCP server?

You do not need an MCP server to give your agent NotaGuard. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls the document, item, and file operations it needs on demand.

### Can I limit what my agent is allowed to do with the NotaGuard API?

Yes. Write a rule that allows GET `/v1/notas`, GET `/v1/notas/{id}`, and GET `/v1/notas/{id}/xml`, and the agent can find documents and fetch their XML but cannot start batch exports through POST `/v1/notas/exportacoes.` The calls it makes are logged for review.