> ## Documentation Index > Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt > Use this file to discover all available pages before exploring further. # List realm attachments > Lists the attachments of every organization in your realm, newest first. Only realm admins can list them. Any other caller gets a 403 — including an organization admin and an API client, which are scoped to their organizations: they list each organization's attachments with the organization route instead. Each attachment carries the `organizationId` it belongs to. Deleted attachments are left out unless `status` asks for them. Filter by ID, by name or by the automatic summary; a list parameter takes comma-separated values (`?status=AVAILABLE,DELETED`). Paginated — see [Pagination](https://developers.portao3.com.br/api-reference/pagination.md). ## OpenAPI ````yaml /api-reference/attachment.openapi.json get /realms/{realmId}/attachments openapi: 3.0.3 info: title: Attachment version: 1.0.0 description: >- Portão 3 attachment API. Every endpoint requires a bearer token in the Authorization header (Authorization: Bearer ) unless its page states otherwise; see the Authentication guide. That requirement is not repeated per endpoint. Generated by tools/openapi from code (routes + security) and the hand-written spec (request/response bodies). Shared file store: upload a file once, keep its ID, and read back its preview, an automatic summary and, for a nota fiscal or invoice, its fiscal data. Confidence tiers: generated:typed=9 copied:manual=0 unknown=0. servers: - url: https://api.attachment.v2.portao3.com.br/ description: production - url: https://api.attachment.dev.3pers.com.br/ description: development security: [] tags: - name: Attachments paths: /realms/{realmId}/attachments: get: tags: - Attachments summary: List realm attachments description: Lists the attachments of every organization in your realm, newest first. operationId: getRealmsByRealmIdAttachments parameters: - name: realmId in: path required: true description: |- ID of your realm. Format: `UUID` schema: type: string format: uuid example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b - name: ids in: query required: false description: >- Only the attachments with these IDs. Sent but empty, it matches no attachment. --- Example (comma-separated list): `?ids=3f6c2a1e-8b4d-4f7a-9c2e-5d1b7a9e4c60,4bb31747-6c7f-44d2-8e7d-21b1ef129ea6` schema: maxItems: 100 type: array items: type: string style: form explode: false - name: name in: query required: false description: Only attachments whose name contains this text (case-insensitive). schema: type: string maxLength: 256 example: cupom - name: summary in: query required: false description: >- Only attachments whose `summary` contains this text (case-insensitive). schema: type: string maxLength: 256 example: abastecimento - name: search in: query required: false description: >- Only attachments whose name or `summary` contains this text (case-insensitive). schema: type: string maxLength: 256 example: posto - name: status in: query required: false description: >- Only attachments in one of these statuses. Without it, every attachment except the `DELETED` ones is listed. --- Example (comma-separated list): `?status=AVAILABLE,PENDING_UPLOAD` schema: type: array items: type: string enum: - PENDING_UPLOAD - AVAILABLE - DELETED style: form explode: false - name: next in: query required: false description: >- Cursor returned as `next` by the previous page. Omit for the first page. schema: type: string example: NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy - name: limit in: query required: false description: >- Page size, 1–100. Defaults to 15 — or, when you send more than 15 distinct `ids`, to their number, so one page holds every match. schema: type: integer minimum: 1 maximum: 100 example: 15 responses: '200': description: Successful response content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string description: >- ID of the attachment. Store it wherever the file is used. example: 3f6c2a1e-8b4d-4f7a-9c2e-5d1b7a9e4c60 format: uuid realmId: type: string description: ID of the realm the attachment belongs to. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b format: uuid organizationId: type: string description: ID of the organization the attachment belongs to. example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 format: uuid status: type: string enum: - PENDING_UPLOAD - AVAILABLE - DELETED description: >- Lifecycle of a stored file: `PENDING_UPLOAD` once created and an upload URL has been issued, `AVAILABLE` once the upload is confirmed, `DELETED` after removal. Deletion is permanent — an attachment cannot be restored. example: AVAILABLE name: type: string description: Name of the file, as sent when it was created. example: cupom-fiscal-posto.jpg contentType: type: string description: >- Media type of the file, as declared when it was created. example: image/jpeg sizeBytes: type: number description: Size of the file in bytes. example: 2457600 ai: type: object properties: status: type: string enum: - PENDING - PROCESSING - DONE - FAILED - SKIPPED description: >- Progress of the automatic content analysis (a short summary plus extracted facts, in pt-BR). `PENDING` and `PROCESSING` are transient — analysis runs asynchronously after upload — settling on `DONE`, `SKIPPED` (the file type is not analysable) or `FAILED`. example: DONE executedAt: type: string description: When the analysis finished. example: '2026-10-15T14:32:41.000Z' format: date-time modelId: type: string description: >- Identifier of the model that produced the analysis. Opaque — it changes when the model does. example: doc-analysis-2026-09 error: type: string description: >- Why the analysis is `SKIPPED` or `FAILED`. Absent otherwise. A `SKIPPED` status reports `UNSUPPORTED_CONTENT_TYPE` (the file is not a PDF, a JPEG/PNG image or an XML document) or `FILE_TOO_LARGE` (an image above 3,700,000 bytes, or a PDF/XML above 4,000,000). A `FAILED` status reports the underlying error, and its text is not a stable token — **branch on `status`, never on this string.** required: - status description: >- Progress of the automatic content analysis. Always present. thumbnail: type: object properties: status: type: string enum: - PENDING - PROCESSING - DONE - FAILED - SKIPPED description: >- Progress of the attachment's preview image. `PENDING` and `PROCESSING` are transient — a preview is generated asynchronously shortly after upload, so a freshly created attachment reports one of them until it settles on `DONE`, `SKIPPED` (the file is not an image we can render) or `FAILED`. example: DONE data: type: string description: >- The preview image as base64-encoded JPEG, without a `data:` prefix — render it as `data:;base64,`, with the `contentType` of this preview (not the attachment's own). Present only once `status` is `DONE`. (The example is shortened.) example: >- /9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/ contentType: type: string description: >- Media type of `data` (currently always `image/jpeg`). example: image/jpeg width: type: number description: >- Width of the preview image in pixels (square): 96 for an image, 128 for a PDF page. example: 96 height: type: number description: >- Height of the preview image in pixels (square): 96 for an image, 128 for a PDF page. example: 96 sizeBytes: type: number description: >- Size of the decoded preview in bytes (the base64 string is about a third larger). example: 3104 generatedAt: type: string description: When the preview was generated. example: '2026-10-15T14:32:20.000Z' format: date-time error: type: string description: >- Why the preview is `SKIPPED` or `FAILED` — e.g. `NOT_AN_IMAGE`. Absent when `DONE`. required: - status description: >- The attachment's preview image. Always present; check `status` before reading `data`. image: type: object properties: width: type: number description: >- Width — in pixels for an image, in points (1/72 inch) for a PDF. example: 3024 height: type: number description: >- Height — in pixels for an image, in points (1/72 inch) for a PDF. example: 4032 format: type: string description: >- The detected format: `jpg` | `png` | `gif` | `bmp` | `tiff` | `webp` | `pdf` | … example: jpg pageCount: type: number description: Number of pages. Only present for a PDF. required: - width - height - format description: >- Dimensions and format of the original file. Absent when the file's header could not be read. ⚠️ `width` and `height` are in PIXELS for an image and in POINTS (1/72 inch) for a PDF — check `format` to tell which. An A4 page reports `595 x 842` points, not pixels. summary: type: string description: >- A short description of the file, in Portuguese, written by the automatic analysis. Present once `ai.status` is `DONE`. example: >- Cupom fiscal eletrônico (NFC-e) do Posto Exemplo Ltda., de 15/10/2026: 40 litros de gasolina comum, total de R$ 250,00, pago com cartão de crédito. contents: type: array items: type: string example: >- Emitente: Posto Exemplo Ltda., CNPJ 11.222.333/0001-81 description: >- Short facts read from the file (values, dates, names, document numbers), in Portuguese. Empty until `ai.status` is `DONE`. --- Example: `["Emitente: Posto Exemplo Ltda., CNPJ 11.222.333/0001-81","Gasolina comum: 40 L a R$ 6,25","Total: R$ 250,00","Pagamento: cartão de crédito"]` extractedReceipt: type: object properties: type: type: string enum: - NFE - NFCE - NFSE - CTE - MDFE - NFCOM - INVOICE - UNKNOWN description: >- The document family. Optional, but every consumer branches on it — always write it. externalId: type: string description: >- The source's own identifier for this body — a **lookup key, not a uniqueness guarantee.** Nothing deduplicates on it. The same document may be attached more than once, and a client that retries a fetch can legitimately end up with two records carrying the same `externalId`, so do not treat it as an identity. For DOCUMENT identity use `accessKey` **when it is present**. A municipal NFS-e has none, and for those the identity is the composite `number` + `verificationCode` + issuer `federalDocument` + `service.serviceProvisionCityCode`. Do not assume `accessKey` is always available. accessKey: type: string description: >- Chave de acesso. **44 characters for NF-e/NFC-e, 50 for a national-standard NFS-e**, and genuinely absent for a municipal NFS-e that predates that standard. **May contain letters** (alphanumeric CNPJ, 2026); never parse it as a number. model: type: string description: >- SEFAZ model code: `"55"` NF-e, `"65"` NFC-e, `"57"` CT-e, `"58"` MDF-e. number: type: string series: type: string verificationCode: type: string description: >- Código de verificação — how an NFS-e is validated where there is no access key. environment: type: string enum: - LIVE - TEST description: >- `tpAmb`. A `TEST` document is a homologation emission and must never be shown as a real expense. currency: type: string enum: - '784' - '971' - '008' - '051' - '973' - '032' - '036' - '533' - '944' - '977' - '052' - '050' - '048' - '108' - '060' - '096' - '068' - '984' - '986' - '044' - '064' - '072' - '933' - '084' - '124' - '976' - '947' - '756' - '948' - '990' - '152' - '156' - '170' - '970' - '188' - '192' - '132' - '203' - '262' - '208' - '214' - '012' - '818' - '232' - '230' - '978' - '242' - '238' - '826' - '981' - '936' - '292' - '270' - '324' - '320' - '328' - '344' - '340' - '332' - '348' - '360' - '376' - '356' - '368' - '364' - '352' - '388' - '400' - '392' - '404' - '417' - '116' - '174' - '408' - '410' - '414' - '136' - '398' - '418' - '422' - '144' - '430' - '426' - '434' - '504' - '498' - '969' - '807' - '104' - '496' - '446' - '929' - '480' - '462' - '454' - '484' - '979' - '458' - '943' - '516' - '566' - '558' - '578' - '524' - '554' - '512' - '590' - '604' - '598' - '608' - '586' - '985' - '600' - '634' - '946' - '941' - '643' - '646' - '682' - '090' - '690' - '938' - '752' - '702' - '654' - '925' - '706' - '968' - '728' - '930' - '222' - '760' - '748' - '764' - '972' - '934' - '788' - '776' - '949' - '780' - '901' - '834' - '980' - '800' - '840' - '997' - '940' - '858' - '927' - '860' - '926' - '928' - '704' - '548' - '882' - '396' - '950' - '961' - '959' - '955' - '956' - '957' - '958' - '951' - '532' - '960' - '952' - '964' - '953' - '962' - '994' - '963' - '965' - '999' - '886' - '710' - '967' - '924' description: >- The document's denomination — **the currency of every monetary value in this body**, unless a nearer `currency` overrides it (see the header's precedence rule). `"986"` (BRL) for anything Brazilian; `"840"` (USD) for that US SaaS invoice. Always write it: a `Cents` value whose currency is unknown cannot be rendered correctly, only plausibly. status: type: string enum: - AUTHORIZED - CANCELED - DENIED - VOIDED - PENDING - UNKNOWN description: >- The document's standing at the tax authority. **Read this before rendering any amount** — a `CANCELED` document must never be presented as an ordinary one, and an absent value means `UNKNOWN`, never authorized. ⚠️ It is a **point-in-time snapshot**, taken at `source.retrievedAt`, and nothing refreshes it. A document canceled after that moment still reads `AUTHORIZED` here. Show `source.retrievedAt` alongside the status, or re-verify, rather than presenting it as current. statusReason: type: string description: >- The authority's own words for that status (`"Autorizado o uso da NF-e"`, a cancellation motive). statusCode: type: string description: >- The authority's numeric status code (`"100"` = authorized), preserved. issuedAt: type: string description: >- Emission timestamp, ISO 8601 with offset where known. authorizedAt: type: string description: When the authority authorized it. canceledAt: type: string description: >- When it was canceled — the presence of this alone should change the UI. operationAt: type: string description: >- Goods entry/exit timestamp (`dhSaiEnt`), when it differs from emission. competenceDate: type: string description: >- Competence of an NFS-e — the period the service belongs to, not when it was billed. `YYYY-MM-DD`, or `YYYY-MM` when only the month is known — never a free-text period. authorizationProtocol: type: string description: Protocolo de autorização. issuer: type: object properties: type: type: string enum: - PERSON - COMPANY description: >- `PERSON` or `COMPANY` — how to read `federalDocument`. name: type: string description: >- Razão social, or an individual's full name — one field for both. tradeName: type: string description: >- Nome fantasia — the trading name, usually the one a user recognises. federalDocument: type: string description: >- CPF (`PERSON`) or CNPJ (`COMPANY`), unmasked. A CPF is 11 digits. A CNPJ is 14 characters and, from 2026, **may contain letters** — accept it as an opaque string and never strip non-digits or validate it as numeric. stateDocument: type: string description: >- Inscrição estadual (state tax registration) — relevant to ICMS. municipalDocument: type: string description: >- Inscrição municipal — relevant to ISS, so usually present on an NFS-e provider. suframaRegistration: type: string description: >- SUFRAMA registration (Manaus free-trade-zone incentives). cnae: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- CNAE — the party's primary economic-activity code. Providers disagree on FORMAT, not just value (`"6311900"` vs `"8211-3/00"` both occur in the stored bodies), so normalise to digits-only in `code` and keep whatever was printed in `description`. taxRegime: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- Tax regime, from the NF-e `CRT` table: `1` Simples Nacional, `2` Simples Nacional with a sublimit, `3` Regime Normal, `4` MEI. `code` carries that digit; `description` carries whatever the document printed, which varies in wording between issuers. email: type: string phone: type: string description: >- Contact phone exactly as the document carried it — an unnormalised national number (`"11999999999"`), not E.164. Display only. address: type: object properties: street: type: string number: type: string description: >- House/building number. A string, not a number — a real NF-e carries `"."`, `"S/N"`, `"KM 50"`. complement: type: string neighbourhood: type: string description: Bairro. city: type: string cityCode: type: number description: >- IBGE municipality code (7 digits, e.g. `3550308` = São Paulo) — the reliable city join key. state: type: string description: Two-letter UF (`"SP"`). stateCode: type: number description: IBGE state code (2 digits, `35` = SP). postalCode: type: string description: >- Postal code, unmasked but otherwise **verbatim**. A Brazilian CEP is 8 digits and sources report it both masked (`"12345-678"`) and unmasked, so strip the punctuation. ⚠️ Do NOT strip non-digits generally: a non-Brazilian invoice carries a postal code that is legitimately alphanumeric (`"SW1A 1AA"`, `"K1A 0B1"`, `"1012 AB"`), and digit-normalising one destroys it irreversibly. Key the normalisation on `country`. country: type: string countryCode: type: string description: >- BACEN/SEFAZ country code — `"1058"` is Brazil. description: >- A postal address. `cityCode`/`stateCode` are IBGE codes. description: Emitente / prestador — who issued the document. recipient: type: object properties: type: type: string enum: - PERSON - COMPANY description: >- `PERSON` or `COMPANY` — how to read `federalDocument`. name: type: string description: >- Razão social, or an individual's full name — one field for both. tradeName: type: string description: >- Nome fantasia — the trading name, usually the one a user recognises. federalDocument: type: string description: >- CPF (`PERSON`) or CNPJ (`COMPANY`), unmasked. A CPF is 11 digits. A CNPJ is 14 characters and, from 2026, **may contain letters** — accept it as an opaque string and never strip non-digits or validate it as numeric. stateDocument: type: string description: >- Inscrição estadual (state tax registration) — relevant to ICMS. municipalDocument: type: string description: >- Inscrição municipal — relevant to ISS, so usually present on an NFS-e provider. suframaRegistration: type: string description: >- SUFRAMA registration (Manaus free-trade-zone incentives). cnae: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- CNAE — the party's primary economic-activity code. Providers disagree on FORMAT, not just value (`"6311900"` vs `"8211-3/00"` both occur in the stored bodies), so normalise to digits-only in `code` and keep whatever was printed in `description`. taxRegime: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- Tax regime, from the NF-e `CRT` table: `1` Simples Nacional, `2` Simples Nacional with a sublimit, `3` Regime Normal, `4` MEI. `code` carries that digit; `description` carries whatever the document printed, which varies in wording between issuers. email: type: string phone: type: string description: >- Contact phone exactly as the document carried it — an unnormalised national number (`"11999999999"`), not E.164. Display only. address: type: object properties: street: type: string number: type: string description: >- House/building number. A string, not a number — a real NF-e carries `"."`, `"S/N"`, `"KM 50"`. complement: type: string neighbourhood: type: string description: Bairro. city: type: string cityCode: type: number description: >- IBGE municipality code (7 digits, e.g. `3550308` = São Paulo) — the reliable city join key. state: type: string description: Two-letter UF (`"SP"`). stateCode: type: number description: IBGE state code (2 digits, `35` = SP). postalCode: type: string description: >- Postal code, unmasked but otherwise **verbatim**. A Brazilian CEP is 8 digits and sources report it both masked (`"12345-678"`) and unmasked, so strip the punctuation. ⚠️ Do NOT strip non-digits generally: a non-Brazilian invoice carries a postal code that is legitimately alphanumeric (`"SW1A 1AA"`, `"K1A 0B1"`, `"1012 AB"`), and digit-normalising one destroys it irreversibly. Key the normalisation on `country`. country: type: string countryCode: type: string description: >- BACEN/SEFAZ country code — `"1058"` is Brazil. description: >- A postal address. `cityCode`/`stateCode` are IBGE codes. description: >- Destinatário / consumidor / tomador — who received it. May be absent on an anonymous NFC-e. recipientRole: type: string enum: - RECIPIENT - CONSUMER - SERVICE_TAKER description: >- What to CALL the receiving party on screen: `RECIPIENT` (destinatário, NF-e), `CONSUMER` (consumidor, NFC-e) or `SERVICE_TAKER` (tomador, NFS-e). intermediary: type: object properties: type: type: string enum: - PERSON - COMPANY description: >- `PERSON` or `COMPANY` — how to read `federalDocument`. name: type: string description: >- Razão social, or an individual's full name — one field for both. tradeName: type: string description: >- Nome fantasia — the trading name, usually the one a user recognises. federalDocument: type: string description: >- CPF (`PERSON`) or CNPJ (`COMPANY`), unmasked. A CPF is 11 digits. A CNPJ is 14 characters and, from 2026, **may contain letters** — accept it as an opaque string and never strip non-digits or validate it as numeric. stateDocument: type: string description: >- Inscrição estadual (state tax registration) — relevant to ICMS. municipalDocument: type: string description: >- Inscrição municipal — relevant to ISS, so usually present on an NFS-e provider. suframaRegistration: type: string description: >- SUFRAMA registration (Manaus free-trade-zone incentives). cnae: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- CNAE — the party's primary economic-activity code. Providers disagree on FORMAT, not just value (`"6311900"` vs `"8211-3/00"` both occur in the stored bodies), so normalise to digits-only in `code` and keep whatever was printed in `description`. taxRegime: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- Tax regime, from the NF-e `CRT` table: `1` Simples Nacional, `2` Simples Nacional with a sublimit, `3` Regime Normal, `4` MEI. `code` carries that digit; `description` carries whatever the document printed, which varies in wording between issuers. email: type: string phone: type: string description: >- Contact phone exactly as the document carried it — an unnormalised national number (`"11999999999"`), not E.164. Display only. address: type: object properties: street: type: string number: type: string description: >- House/building number. A string, not a number — a real NF-e carries `"."`, `"S/N"`, `"KM 50"`. complement: type: string neighbourhood: type: string description: Bairro. city: type: string cityCode: type: number description: >- IBGE municipality code (7 digits, e.g. `3550308` = São Paulo) — the reliable city join key. state: type: string description: Two-letter UF (`"SP"`). stateCode: type: number description: IBGE state code (2 digits, `35` = SP). postalCode: type: string description: >- Postal code, unmasked but otherwise **verbatim**. A Brazilian CEP is 8 digits and sources report it both masked (`"12345-678"`) and unmasked, so strip the punctuation. ⚠️ Do NOT strip non-digits generally: a non-Brazilian invoice carries a postal code that is legitimately alphanumeric (`"SW1A 1AA"`, `"K1A 0B1"`, `"1012 AB"`), and digit-normalising one destroys it irreversibly. Key the normalisation on `country`. country: type: string countryCode: type: string description: >- BACEN/SEFAZ country code — `"1058"` is Brazil. description: >- A postal address. `cityCode`/`stateCode` are IBGE codes. description: >- Marketplace/payment intermediary (`infIntermed`), when the sale went through one. technicalResponsible: type: object properties: type: type: string enum: - PERSON - COMPANY description: >- `PERSON` or `COMPANY` — how to read `federalDocument`. name: type: string description: >- Razão social, or an individual's full name — one field for both. tradeName: type: string description: >- Nome fantasia — the trading name, usually the one a user recognises. federalDocument: type: string description: >- CPF (`PERSON`) or CNPJ (`COMPANY`), unmasked. A CPF is 11 digits. A CNPJ is 14 characters and, from 2026, **may contain letters** — accept it as an opaque string and never strip non-digits or validate it as numeric. stateDocument: type: string description: >- Inscrição estadual (state tax registration) — relevant to ICMS. municipalDocument: type: string description: >- Inscrição municipal — relevant to ISS, so usually present on an NFS-e provider. suframaRegistration: type: string description: >- SUFRAMA registration (Manaus free-trade-zone incentives). cnae: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- CNAE — the party's primary economic-activity code. Providers disagree on FORMAT, not just value (`"6311900"` vs `"8211-3/00"` both occur in the stored bodies), so normalise to digits-only in `code` and keep whatever was printed in `description`. taxRegime: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- Tax regime, from the NF-e `CRT` table: `1` Simples Nacional, `2` Simples Nacional with a sublimit, `3` Regime Normal, `4` MEI. `code` carries that digit; `description` carries whatever the document printed, which varies in wording between issuers. email: type: string phone: type: string description: >- Contact phone exactly as the document carried it — an unnormalised national number (`"11999999999"`), not E.164. Display only. address: type: object properties: street: type: string number: type: string description: >- House/building number. A string, not a number — a real NF-e carries `"."`, `"S/N"`, `"KM 50"`. complement: type: string neighbourhood: type: string description: Bairro. city: type: string cityCode: type: number description: >- IBGE municipality code (7 digits, e.g. `3550308` = São Paulo) — the reliable city join key. state: type: string description: Two-letter UF (`"SP"`). stateCode: type: number description: IBGE state code (2 digits, `35` = SP). postalCode: type: string description: >- Postal code, unmasked but otherwise **verbatim**. A Brazilian CEP is 8 digits and sources report it both masked (`"12345-678"`) and unmasked, so strip the punctuation. ⚠️ Do NOT strip non-digits generally: a non-Brazilian invoice carries a postal code that is legitimately alphanumeric (`"SW1A 1AA"`, `"K1A 0B1"`, `"1012 AB"`), and digit-normalising one destroys it irreversibly. Key the normalisation on `country`. country: type: string countryCode: type: string description: >- BACEN/SEFAZ country code — `"1058"` is Brazil. description: >- A postal address. `cityCode`/`stateCode` are IBGE codes. description: >- Responsável técnico — the software house that emitted it. Support/diagnostics only. amounts: type: object properties: currency: type: string enum: - '784' - '971' - '008' - '051' - '973' - '032' - '036' - '533' - '944' - '977' - '052' - '050' - '048' - '108' - '060' - '096' - '068' - '984' - '986' - '044' - '064' - '072' - '933' - '084' - '124' - '976' - '947' - '756' - '948' - '990' - '152' - '156' - '170' - '970' - '188' - '192' - '132' - '203' - '262' - '208' - '214' - '012' - '818' - '232' - '230' - '978' - '242' - '238' - '826' - '981' - '936' - '292' - '270' - '324' - '320' - '328' - '344' - '340' - '332' - '348' - '360' - '376' - '356' - '368' - '364' - '352' - '388' - '400' - '392' - '404' - '417' - '116' - '174' - '408' - '410' - '414' - '136' - '398' - '418' - '422' - '144' - '430' - '426' - '434' - '504' - '498' - '969' - '807' - '104' - '496' - '446' - '929' - '480' - '462' - '454' - '484' - '979' - '458' - '943' - '516' - '566' - '558' - '578' - '524' - '554' - '512' - '590' - '604' - '598' - '608' - '586' - '985' - '600' - '634' - '946' - '941' - '643' - '646' - '682' - '090' - '690' - '938' - '752' - '702' - '654' - '925' - '706' - '968' - '728' - '930' - '222' - '760' - '748' - '764' - '972' - '934' - '788' - '776' - '949' - '780' - '901' - '834' - '980' - '800' - '840' - '997' - '940' - '858' - '927' - '860' - '926' - '928' - '704' - '548' - '882' - '396' - '950' - '961' - '959' - '955' - '956' - '957' - '958' - '951' - '532' - '960' - '952' - '964' - '953' - '962' - '994' - '963' - '965' - '999' - '886' - '710' - '967' - '924' description: >- Overrides the document-level `currency` for this block only. Normally unset. totalValue: type: number description: >- The document's total value — the headline figure. productsValue: type: number description: Sum of goods lines (`vProd`). servicesValue: type: number description: >- Sum of service lines — the NFS-e equivalent of `productsValue`. discounts: type: number description: Total discount applied. unconditionalDiscounts: type: number description: >- Desconto incondicionado / condicionado, when the source distinguishes them (NFS-e always does). conditionalDiscounts: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. freightValue: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. insuranceValue: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. otherCostsValue: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. deductions: type: number description: >- Deduções (NFS-e) — amounts removed before the ISS base. netValue: type: number description: >- Net/payable amount after discounts and withholdings. receivedValue: type: number description: >- Amount actually received, when the source reports it separately (NFS-e `valor_recebido`). approximateTax: type: number description: >- `vTotTrib` — total approximate taxes, for disclosure. Never a charge; never add it to a total. approximateTaxSource: type: string description: >- The legal basis printed beside that figure (`"IBPT"`, `"Lei Federal 12.741/12"`). Free text by nature — issuers print it however they like (both `"IBPT [A601D4]"` and `"IBPT- PR 30"` occur) — so render it verbatim next to `approximateTax` and never parse it. description: >- The headline money block — everything a card, header or summary panel renders. `totalValue` is THE number: `vNF` on an NF-e/NFC-e, the service value on an NFS-e. `netValue` is what was actually payable after conditional discounts and withholdings, which on an NFS-e is routinely lower — showing only one of the two misstates the expense. **Every amount here is an integer number of cents**, denominated in the document's `currency` — `550000` is R$ 5.500,00, and `4900` with a `currency` of `"840"` (USD) is $49.00. Never render one without reading `currency`. taxes: type: object properties: icmsBase: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. icmsAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. icmsStBase: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. icmsStAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. icmsExemptAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. fcpAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. ipiAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. pisAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. cofinsAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. importDuty: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. issBase: type: number description: ISS — the NFS-e headline tax. issRate: type: number description: >- A **percentage**, not a fraction — `5` means 5%, as printed on the DANFE/DANFSE. issAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. issWithheldAtSource: type: boolean description: >- Whether ISS was withheld by the taker rather than paid by the provider (`iss_retido`). issWithheldAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. icmsOriginStateAmount: type: number description: >- DIFAL — the interstate ICMS split on a sale to a final consumer in another state. icmsDestinationStateAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. approximateFederal: type: number description: >- The "tributos aproximados" breakdown printed on a consumer receipt — a DISCLOSURE of taxes already embedded in the price, never a charge. The total of these is `amounts.approximateTax`, and its legal basis is `amounts.approximateTaxSource`. approximateState: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. approximateMunicipal: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. approximateOther: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. ibsAmount: type: number description: >- IBS and CBS, aggregated across the document's lines. cbsAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. otherAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. description: >- Tax detail, for a collapsed panel. Every amount is integer **cents** in the document's `currency`; every `…Rate` is a **percentage** (`5` means 5%). withholdings: type: object properties: pisAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. cofinsAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. inssAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. irAmount: type: number description: Imposto de Renda. csllAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. cpAmount: type: number description: Contribuição previdenciária patronal. otherAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. totalAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. description: >- NFS-e federal withholdings, in integer **cents** — the taker retains these and pays them directly, which is why `amounts.netValue` sits below `amounts.totalValue`. items: type: array items: type: object properties: sequence: type: number description: >- 1-based position on the document (`nItem`) — the order a DANFE prints. code: type: string description: >- The issuer's own SKU (`cProd`). A consultation source may return it as a number; keep it a string. description: type: string ean: type: string description: >- GTIN/EAN. A real NF-e may carry the literal string `"SEM GTIN"`. ncm: type: string description: >- NCM — 8-digit goods classification. Leading zeros matter; hence a string. cest: type: string description: >- CEST — substituição-tributária code, 7 digits. cfop: type: string description: >- CFOP — 4-digit operation code; what the operation IS, fiscally. origin: type: string description: >- Origem da mercadoria, mirrored from `taxes.icms.origin` for a flat items table. unit: type: string description: >- Commercial unit as printed (`"UN"`, `"KG"`, `"RS"`). quantity: type: number description: >- Commercial quantity. Up to 4 decimals in the NF-e layout. unitPrice: type: string description: >- Unit price as a DECIMAL STRING, exactly as the source reported it. Not cents, and deliberately not a float: the NF-e layout allows a unit price with up to 10 decimal places (fuel, bulk chemicals, per-gram pricing), which integer cents cannot represent and a float rounds. Multiply-then-round for display; `total` below is the authoritative line total. total: type: number description: >- Line total (quantity × unit price), in cents — the number a UI shows on the right. discount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. freight: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. insurance: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. otherCosts: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. approximateTax: type: number description: >- `vTotTrib` — approximate taxes borne by this line, for legal disclosure. Not a charge. taxes: type: object properties: icms: type: object properties: cst: type: string description: >- CST (Regime Normal) or CSOSN (Simples Nacional) — e.g. `"00"`, `"41"`, `"102"`. origin: type: string description: >- Origem da mercadoria (`"0"` national … `"8"` imported) — the DANFE's "O" column. base: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. rate: type: number description: >- A **percentage**, not a fraction — `5` means 5%, as printed on the DANFE/DANFSE. amount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. stBase: type: number description: >- Substituição tributária — the tax the issuer collected on the chain's behalf. stRate: type: number description: >- A **percentage**, not a fraction — `5` means 5%, as printed on the DANFE/DANFSE. stAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. fcpBase: type: number description: Fundo de Combate à Pobreza. fcpRate: type: number description: >- A **percentage**, not a fraction — `5` means 5%, as printed on the DANFE/DANFSE. fcpAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. exemptAmount: type: number description: >- Desoneração — tax that was NOT charged, plus the legal reason code. exemptionReasonCode: type: string destinationStateAmount: type: number description: >- DIFAL split on an interstate sale to a final consumer. originStateAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. description: >- A per-item tax block. Every amount is cents; every rate is a percentage. `cst`/`csosn` are the tributary-situation codes that decide whether an item was taxed, exempt, deferred or substituted — a designer needs them only to show a badge, but an accountant needs them exactly. ipi: type: object properties: cst: type: string legalFrameworkCode: type: string description: Código de enquadramento legal. base: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. rate: type: number description: >- A **percentage**, not a fraction — `5` means 5%, as printed on the DANFE/DANFSE. amount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. pis: type: object properties: cst: type: string base: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. rate: type: number description: >- A **percentage**, not a fraction — `5` means 5%, as printed on the DANFE/DANFSE. amount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. description: >- PIS and COFINS share a layout, so they share a type. cofins: type: object properties: cst: type: string base: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. rate: type: number description: >- A **percentage**, not a fraction — `5` means 5%, as printed on the DANFE/DANFSE. amount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. description: >- PIS and COFINS share a layout, so they share a type. importDuty: type: number description: Imposto de Importação. issBase: type: number description: >- ISS, for a service line inside an NF-e (or any NFS-e line). issRate: type: number description: >- A **percentage**, not a fraction — `5` means 5%, as printed on the DANFE/DANFSE. issAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. ibsCbs: type: object properties: cst: type: string classificationCode: type: string description: >- cClassTrib — the tributary classification code that qualifies the CST. base: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. ibsStateRate: type: number description: IBS estadual. ibsStateAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. ibsMunicipalRate: type: number description: IBS municipal. ibsMunicipalAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. ibsAmount: type: number description: >- IBS total (state + municipal), when the source reports it directly. cbsRate: type: number description: CBS federal. cbsAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. description: >- The consumption-tax reform block (EC 132/2023): IBS (state + municipal) and CBS (federal), phasing in from 2026 alongside ICMS/ISS/PIS/COFINS and replacing them by 2033. Present because it is **already in consultation payloads today**, not as speculation — at least one source returns an `ibs_cbs` object on both NF-e items and NFS-e services. A shape with nowhere to put it would need redesigning within a year, and the numbers would silently vanish from screens in the meantime. Only the aggregate fields are modelled; the reform's long tail (monophasic retention, presumed credits, ZFM credits, competence adjustments) belongs in `raw` until a screen needs it. currency: type: string enum: - '784' - '971' - '008' - '051' - '973' - '032' - '036' - '533' - '944' - '977' - '052' - '050' - '048' - '108' - '060' - '096' - '068' - '984' - '986' - '044' - '064' - '072' - '933' - '084' - '124' - '976' - '947' - '756' - '948' - '990' - '152' - '156' - '170' - '970' - '188' - '192' - '132' - '203' - '262' - '208' - '214' - '012' - '818' - '232' - '230' - '978' - '242' - '238' - '826' - '981' - '936' - '292' - '270' - '324' - '320' - '328' - '344' - '340' - '332' - '348' - '360' - '376' - '356' - '368' - '364' - '352' - '388' - '400' - '392' - '404' - '417' - '116' - '174' - '408' - '410' - '414' - '136' - '398' - '418' - '422' - '144' - '430' - '426' - '434' - '504' - '498' - '969' - '807' - '104' - '496' - '446' - '929' - '480' - '462' - '454' - '484' - '979' - '458' - '943' - '516' - '566' - '558' - '578' - '524' - '554' - '512' - '590' - '604' - '598' - '608' - '586' - '985' - '600' - '634' - '946' - '941' - '643' - '646' - '682' - '090' - '690' - '938' - '752' - '702' - '654' - '925' - '706' - '968' - '728' - '930' - '222' - '760' - '748' - '764' - '972' - '934' - '788' - '776' - '949' - '780' - '901' - '834' - '980' - '800' - '840' - '997' - '940' - '858' - '927' - '860' - '926' - '928' - '704' - '548' - '882' - '396' - '950' - '961' - '959' - '955' - '956' - '957' - '958' - '951' - '532' - '960' - '952' - '964' - '953' - '962' - '994' - '963' - '965' - '999' - '886' - '710' - '967' - '924' description: >- Overrides the document-level `currency` for this entry only. Normally unset. additionalInfo: type: string description: >- Free text the issuer attached to the line (`infAdProd`). description: >- One line of the document. The tax codes (`ncm`, `cfop`, `cest`) are what make an items table useful beyond a receipt photo, and `approximateTax` is the per-line `vTotTrib` that Brazilian law requires a receipt to disclose — worth showing, and easy to mistake for a tax we charged. itemCount: type: number description: >- Reported item count, when the source gives one — may exceed `items.length` on a summary read. service: type: object properties: serviceListItemLC116: type: string description: >- Item da lista de serviços, LC 116 — `"01.05"`. Dotted format. serviceMunicipalCode: type: string description: >- The municipality's own tributary code for the service (`codigo_tributacao_municipio`). serviceMunicipalDescription: type: string description: >- That code's label, when the source prints one. cnae: type: string description: >- CNAE, digits only — sources report it both masked (`"8211-3/00"`) and unmasked (`"6311900"`). description: type: string description: >- Discriminação — the free-text description of what was actually done. Usually the useful field. serviceProvisionState: type: string description: >- Where the service was rendered — two-letter UF. serviceProvisionCity: type: string description: Where the service was rendered — city name. serviceProvisionCityCode: type: number description: >- IBGE code for that city — the half that joins reliably. description: >- NFS-e service classification (single-service documents; per-line data lives on `items`). rpsNumber: type: string description: >- Number and series of the RPS an NFS-e was converted from. rpsSeries: type: string rpsIssuedAt: type: string description: When the RPS itself was emitted (ISO 8601). replacesDocumentNumber: type: string description: >- Number of the NFS-e this one replaces (`nfse_substituida`). operationNature: type: string description: >- Natureza da operação, free text (`"VENDA"`, `"Compra para industrialização"`). operationDirection: type: string enum: - INBOUND - OUTBOUND description: Direction from the issuer's side. purpose: type: string enum: - NORMAL - COMPLEMENTARY - ADJUSTMENT - RETURN description: >- Why the document exists: `NORMAL`, `COMPLEMENTARY`, `ADJUSTMENT` or `RETURN`. An `ADJUSTMENT` or `COMPLEMENTARY` document must not be summed into an expense total alongside the one it adjusts, and a `RETURN` offsets one. cfops: type: array items: type: string description: >- Distinct CFOPs used across the lines — a cheap operation summary without walking `items`. isFinalConsumer: type: boolean description: >- `indFinal` — whether the buyer is the final consumer. buyerPresence: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- `indPres` — how the buyer was present (in person, online, by phone, …). purchaseOrderNumber: type: string description: >- Purchase-order references the issuer echoed back (`xPed`/`nItemPed`, `compra`). purchaseContractNumber: type: string taxRegime: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- Regime especial de tributação, as the municipality reports it. issRequirement: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- Exigibilidade do ISS — taxable, exempt, suspended by court order, … A coded value because the printed labels do not form a vocabulary: the stored bodies contain `"Exigível"`, `"EXIGÍVEL"`, `"Incidente"`, `"Operação Tributável"` and `"Exigível em Caldas Novas"` for what is a 1-digit code (`indISS`). simplesNacional: type: boolean description: >- Whether the provider is under Simples Nacional (changes who owes the ISS). culturalIncentive: type: boolean description: Incentivador cultural. issuerSystem: type: string description: >- Which municipal/national NFS-e system issued it (`"PadraoNacional"`, `"IPM2"`, …). freightService: type: object properties: modal: type: string enum: - ROAD - AIR - WATER - RAIL - PIPELINE - MULTIMODAL serviceType: type: string enum: - NORMAL - SUBCONTRACTING - REDISPATCH - INTERMEDIATE_REDISPATCH - MULTIMODAL_LINKED origin: type: object properties: city: type: string cityCode: type: number description: >- IBGE municipality code — `number`, like every IBGE code here. state: type: string description: Two-letter UF. description: >- Origin and destination of the HAUL — not of the parties. destination: type: object properties: city: type: string cityCode: type: number description: >- IBGE municipality code — `number`, like every IBGE code here. state: type: string description: Two-letter UF. description: >- A place a freight document loads at or unloads at. payer: type: object properties: type: type: string enum: - PERSON - COMPANY description: >- `PERSON` or `COMPANY` — how to read `federalDocument`. name: type: string description: >- Razão social, or an individual's full name — one field for both. tradeName: type: string description: >- Nome fantasia — the trading name, usually the one a user recognises. federalDocument: type: string description: >- CPF (`PERSON`) or CNPJ (`COMPANY`), unmasked. A CPF is 11 digits. A CNPJ is 14 characters and, from 2026, **may contain letters** — accept it as an opaque string and never strip non-digits or validate it as numeric. stateDocument: type: string description: >- Inscrição estadual (state tax registration) — relevant to ICMS. municipalDocument: type: string description: >- Inscrição municipal — relevant to ISS, so usually present on an NFS-e provider. suframaRegistration: type: string description: >- SUFRAMA registration (Manaus free-trade-zone incentives). cnae: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- CNAE — the party's primary economic-activity code. Providers disagree on FORMAT, not just value (`"6311900"` vs `"8211-3/00"` both occur in the stored bodies), so normalise to digits-only in `code` and keep whatever was printed in `description`. taxRegime: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- Tax regime, from the NF-e `CRT` table: `1` Simples Nacional, `2` Simples Nacional with a sublimit, `3` Regime Normal, `4` MEI. `code` carries that digit; `description` carries whatever the document printed, which varies in wording between issuers. email: type: string phone: type: string description: >- Contact phone exactly as the document carried it — an unnormalised national number (`"11999999999"`), not E.164. Display only. address: type: object properties: street: type: string number: type: string description: >- House/building number. A string, not a number — a real NF-e carries `"."`, `"S/N"`, `"KM 50"`. complement: type: string neighbourhood: type: string description: Bairro. city: type: string cityCode: type: number description: >- IBGE municipality code (7 digits, e.g. `3550308` = São Paulo) — the reliable city join key. state: type: string description: Two-letter UF (`"SP"`). stateCode: type: number description: IBGE state code (2 digits, `35` = SP). postalCode: type: string description: >- Postal code, unmasked but otherwise **verbatim**. A Brazilian CEP is 8 digits and sources report it both masked (`"12345-678"`) and unmasked, so strip the punctuation. ⚠️ Do NOT strip non-digits generally: a non-Brazilian invoice carries a postal code that is legitimately alphanumeric (`"SW1A 1AA"`, `"K1A 0B1"`, `"1012 AB"`), and digit-normalising one destroys it irreversibly. Key the normalisation on `country`. country: type: string countryCode: type: string description: >- BACEN/SEFAZ country code — `"1058"` is Brazil. description: >- A postal address. `cityCode`/`stateCode` are IBGE codes. description: >- Tomador — who owes the freight. Often, but not always, the sender or the recipient. sender: type: object properties: type: type: string enum: - PERSON - COMPANY description: >- `PERSON` or `COMPANY` — how to read `federalDocument`. name: type: string description: >- Razão social, or an individual's full name — one field for both. tradeName: type: string description: >- Nome fantasia — the trading name, usually the one a user recognises. federalDocument: type: string description: >- CPF (`PERSON`) or CNPJ (`COMPANY`), unmasked. A CPF is 11 digits. A CNPJ is 14 characters and, from 2026, **may contain letters** — accept it as an opaque string and never strip non-digits or validate it as numeric. stateDocument: type: string description: >- Inscrição estadual (state tax registration) — relevant to ICMS. municipalDocument: type: string description: >- Inscrição municipal — relevant to ISS, so usually present on an NFS-e provider. suframaRegistration: type: string description: >- SUFRAMA registration (Manaus free-trade-zone incentives). cnae: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- CNAE — the party's primary economic-activity code. Providers disagree on FORMAT, not just value (`"6311900"` vs `"8211-3/00"` both occur in the stored bodies), so normalise to digits-only in `code` and keep whatever was printed in `description`. taxRegime: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- Tax regime, from the NF-e `CRT` table: `1` Simples Nacional, `2` Simples Nacional with a sublimit, `3` Regime Normal, `4` MEI. `code` carries that digit; `description` carries whatever the document printed, which varies in wording between issuers. email: type: string phone: type: string description: >- Contact phone exactly as the document carried it — an unnormalised national number (`"11999999999"`), not E.164. Display only. address: type: object properties: street: type: string number: type: string description: >- House/building number. A string, not a number — a real NF-e carries `"."`, `"S/N"`, `"KM 50"`. complement: type: string neighbourhood: type: string description: Bairro. city: type: string cityCode: type: number description: >- IBGE municipality code (7 digits, e.g. `3550308` = São Paulo) — the reliable city join key. state: type: string description: Two-letter UF (`"SP"`). stateCode: type: number description: IBGE state code (2 digits, `35` = SP). postalCode: type: string description: >- Postal code, unmasked but otherwise **verbatim**. A Brazilian CEP is 8 digits and sources report it both masked (`"12345-678"`) and unmasked, so strip the punctuation. ⚠️ Do NOT strip non-digits generally: a non-Brazilian invoice carries a postal code that is legitimately alphanumeric (`"SW1A 1AA"`, `"K1A 0B1"`, `"1012 AB"`), and digit-normalising one destroys it irreversibly. Key the normalisation on `country`. country: type: string countryCode: type: string description: >- BACEN/SEFAZ country code — `"1058"` is Brazil. description: >- A postal address. `cityCode`/`stateCode` are IBGE codes. description: Remetente — who handed the cargo over. dispatcher: type: object properties: type: type: string enum: - PERSON - COMPANY description: >- `PERSON` or `COMPANY` — how to read `federalDocument`. name: type: string description: >- Razão social, or an individual's full name — one field for both. tradeName: type: string description: >- Nome fantasia — the trading name, usually the one a user recognises. federalDocument: type: string description: >- CPF (`PERSON`) or CNPJ (`COMPANY`), unmasked. A CPF is 11 digits. A CNPJ is 14 characters and, from 2026, **may contain letters** — accept it as an opaque string and never strip non-digits or validate it as numeric. stateDocument: type: string description: >- Inscrição estadual (state tax registration) — relevant to ICMS. municipalDocument: type: string description: >- Inscrição municipal — relevant to ISS, so usually present on an NFS-e provider. suframaRegistration: type: string description: >- SUFRAMA registration (Manaus free-trade-zone incentives). cnae: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- CNAE — the party's primary economic-activity code. Providers disagree on FORMAT, not just value (`"6311900"` vs `"8211-3/00"` both occur in the stored bodies), so normalise to digits-only in `code` and keep whatever was printed in `description`. taxRegime: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- Tax regime, from the NF-e `CRT` table: `1` Simples Nacional, `2` Simples Nacional with a sublimit, `3` Regime Normal, `4` MEI. `code` carries that digit; `description` carries whatever the document printed, which varies in wording between issuers. email: type: string phone: type: string description: >- Contact phone exactly as the document carried it — an unnormalised national number (`"11999999999"`), not E.164. Display only. address: type: object properties: street: type: string number: type: string description: >- House/building number. A string, not a number — a real NF-e carries `"."`, `"S/N"`, `"KM 50"`. complement: type: string neighbourhood: type: string description: Bairro. city: type: string cityCode: type: number description: >- IBGE municipality code (7 digits, e.g. `3550308` = São Paulo) — the reliable city join key. state: type: string description: Two-letter UF (`"SP"`). stateCode: type: number description: IBGE state code (2 digits, `35` = SP). postalCode: type: string description: >- Postal code, unmasked but otherwise **verbatim**. A Brazilian CEP is 8 digits and sources report it both masked (`"12345-678"`) and unmasked, so strip the punctuation. ⚠️ Do NOT strip non-digits generally: a non-Brazilian invoice carries a postal code that is legitimately alphanumeric (`"SW1A 1AA"`, `"K1A 0B1"`, `"1012 AB"`), and digit-normalising one destroys it irreversibly. Key the normalisation on `country`. country: type: string countryCode: type: string description: >- BACEN/SEFAZ country code — `"1058"` is Brazil. description: >- A postal address. `cityCode`/`stateCode` are IBGE codes. description: >- Expedidor / recebedor, on a redespacho chain. receiver: type: object properties: type: type: string enum: - PERSON - COMPANY description: >- `PERSON` or `COMPANY` — how to read `federalDocument`. name: type: string description: >- Razão social, or an individual's full name — one field for both. tradeName: type: string description: >- Nome fantasia — the trading name, usually the one a user recognises. federalDocument: type: string description: >- CPF (`PERSON`) or CNPJ (`COMPANY`), unmasked. A CPF is 11 digits. A CNPJ is 14 characters and, from 2026, **may contain letters** — accept it as an opaque string and never strip non-digits or validate it as numeric. stateDocument: type: string description: >- Inscrição estadual (state tax registration) — relevant to ICMS. municipalDocument: type: string description: >- Inscrição municipal — relevant to ISS, so usually present on an NFS-e provider. suframaRegistration: type: string description: >- SUFRAMA registration (Manaus free-trade-zone incentives). cnae: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- CNAE — the party's primary economic-activity code. Providers disagree on FORMAT, not just value (`"6311900"` vs `"8211-3/00"` both occur in the stored bodies), so normalise to digits-only in `code` and keep whatever was printed in `description`. taxRegime: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- Tax regime, from the NF-e `CRT` table: `1` Simples Nacional, `2` Simples Nacional with a sublimit, `3` Regime Normal, `4` MEI. `code` carries that digit; `description` carries whatever the document printed, which varies in wording between issuers. email: type: string phone: type: string description: >- Contact phone exactly as the document carried it — an unnormalised national number (`"11999999999"`), not E.164. Display only. address: type: object properties: street: type: string number: type: string description: >- House/building number. A string, not a number — a real NF-e carries `"."`, `"S/N"`, `"KM 50"`. complement: type: string neighbourhood: type: string description: Bairro. city: type: string cityCode: type: number description: >- IBGE municipality code (7 digits, e.g. `3550308` = São Paulo) — the reliable city join key. state: type: string description: Two-letter UF (`"SP"`). stateCode: type: number description: IBGE state code (2 digits, `35` = SP). postalCode: type: string description: >- Postal code, unmasked but otherwise **verbatim**. A Brazilian CEP is 8 digits and sources report it both masked (`"12345-678"`) and unmasked, so strip the punctuation. ⚠️ Do NOT strip non-digits generally: a non-Brazilian invoice carries a postal code that is legitimately alphanumeric (`"SW1A 1AA"`, `"K1A 0B1"`, `"1012 AB"`), and digit-normalising one destroys it irreversibly. Key the normalisation on `country`. country: type: string countryCode: type: string description: >- BACEN/SEFAZ country code — `"1058"` is Brazil. description: >- A postal address. `cityCode`/`stateCode` are IBGE codes. description: >- A party to the document — issuer, recipient, carrier or intermediary. A party is identified by ONE `federalDocument` (a CPF or a CNPJ) plus `type` saying which it is. Never assume 11 characters means CPF without reading `type`. totalValue: type: number description: >- Total freight charged, in integer **cents** (`vPrest.vTPrest`). receivableValue: type: number description: >- Of that total, the amount receivable, in integer **cents** (`vPrest.vRec`). components: type: array items: type: object properties: name: type: string value: type: number description: Integer **cents**. description: >- One priced component of a freight charge (CT-e `vPrest.Comp` — "frete peso", "pedágio", …). description: >- The breakdown that sums to `totalValue` — this is what a freight invoice actually itemises. cargoValue: type: number description: >- Declared value of the goods being carried, in integer **cents** — **not** the freight charge. Showing this next to `totalValue` without labelling both invites a serious misread. predominantProduct: type: string description: >- Produto predominante (`proPred`) — the one-line answer to "what was in the truck". cargoQuantities: type: array items: type: object properties: unit: type: string description: >- Unit as the document codes it — `"KG"`, `"M3"`, `"UNIDADE"`, `"LITRAGEM"`, `"AMT"`. quantity: type: number measure: type: string description: >- The measure being counted (`tpMed`) — free text, e.g. `"PESO BRUTO"`. description: >- A measured quantity of the cargo (CT-e `infCarga.infQ`). rntrc: type: string description: >- ANTT carrier registration (`infModal.rodo.RNTRC`). currency: type: string enum: - '784' - '971' - '008' - '051' - '973' - '032' - '036' - '533' - '944' - '977' - '052' - '050' - '048' - '108' - '060' - '096' - '068' - '984' - '986' - '044' - '064' - '072' - '933' - '084' - '124' - '976' - '947' - '756' - '948' - '990' - '152' - '156' - '170' - '970' - '188' - '192' - '132' - '203' - '262' - '208' - '214' - '012' - '818' - '232' - '230' - '978' - '242' - '238' - '826' - '981' - '936' - '292' - '270' - '324' - '320' - '328' - '344' - '340' - '332' - '348' - '360' - '376' - '356' - '368' - '364' - '352' - '388' - '400' - '392' - '404' - '417' - '116' - '174' - '408' - '410' - '414' - '136' - '398' - '418' - '422' - '144' - '430' - '426' - '434' - '504' - '498' - '969' - '807' - '104' - '496' - '446' - '929' - '480' - '462' - '454' - '484' - '979' - '458' - '943' - '516' - '566' - '558' - '578' - '524' - '554' - '512' - '590' - '604' - '598' - '608' - '586' - '985' - '600' - '634' - '946' - '941' - '643' - '646' - '682' - '090' - '690' - '938' - '752' - '702' - '654' - '925' - '706' - '968' - '728' - '930' - '222' - '760' - '748' - '764' - '972' - '934' - '788' - '776' - '949' - '780' - '901' - '834' - '980' - '800' - '840' - '997' - '940' - '858' - '927' - '860' - '926' - '928' - '704' - '548' - '882' - '396' - '950' - '961' - '959' - '955' - '956' - '957' - '958' - '951' - '532' - '960' - '952' - '964' - '953' - '962' - '994' - '963' - '965' - '999' - '886' - '710' - '967' - '924' description: >- Overrides the document-level `currency` for this block only. Normally unset. description: >- CT-e only: the freight service being invoiced — route, parties, charge breakdown and cargo. manifest: type: object properties: modal: type: string enum: - ROAD - AIR - WATER - RAIL - PIPELINE - MULTIMODAL tractionVehicle: type: object properties: plate: type: string state: type: string description: UF the plate is registered in. renavam: type: string description: RENAVAM. tareKg: type: number description: Tara — unladen weight, kg. capacityKg: type: number description: Load capacity, kg. capacityM3: type: number description: Load capacity, m³. description: >- A vehicle on a freight document (MDF-e `veicTracao`/`veicReboque`). trailers: type: array items: type: object properties: plate: type: string state: type: string description: UF the plate is registered in. renavam: type: string description: RENAVAM. tareKg: type: number description: Tara — unladen weight, kg. capacityKg: type: number description: Load capacity, kg. capacityM3: type: number description: Load capacity, m³. description: >- A vehicle on a freight document (MDF-e `veicTracao`/`veicReboque`). drivers: type: array items: type: string description: >- Condutores — names only; a CPF belongs in `raw` rather than being stored per driver. origin: type: object properties: city: type: string cityCode: type: number description: >- IBGE municipality code — `number`, like every IBGE code here. state: type: string description: Two-letter UF. description: >- Where the trip starts and ends, plus the UFs crossed (`infPercurso`). destination: type: object properties: city: type: string cityCode: type: number description: >- IBGE municipality code — `number`, like every IBGE code here. state: type: string description: Two-letter UF. description: >- A place a freight document loads at or unloads at. loadingStops: type: array items: type: object properties: city: type: string cityCode: type: number description: >- IBGE municipality code — `number`, like every IBGE code here. state: type: string description: Two-letter UF. description: >- A place a freight document loads at or unloads at. unloadingStops: type: array items: type: object properties: city: type: string cityCode: type: number description: >- IBGE municipality code — `number`, like every IBGE code here. state: type: string description: Two-letter UF. description: >- A place a freight document loads at or unloads at. routeStates: type: array items: type: string tripStartedAt: type: string description: >- ISO 8601. `closedAt` is set by the encerramento event (110112), not at emission. closedAt: type: string closingLocation: type: object properties: city: type: string cityCode: type: number description: >- IBGE municipality code — `number`, like every IBGE code here. state: type: string description: Two-letter UF. description: >- A place a freight document loads at or unloads at. seals: type: array items: type: string description: Lacres — seal numbers. cteCount: type: number description: >- Cargo totals (`tot`). Counts of the documents manifested, and the cargo itself. nfeCount: type: number mdfeCount: type: number cargoValue: type: number description: >- Declared value of the manifested cargo, in integer **cents**. cargoWeight: type: number cargoWeightUnit: type: string description: >- Unit of `cargoWeight` (`cUnid`): `"01"` KG, `"02"` TON. currency: type: string enum: - '784' - '971' - '008' - '051' - '973' - '032' - '036' - '533' - '944' - '977' - '052' - '050' - '048' - '108' - '060' - '096' - '068' - '984' - '986' - '044' - '064' - '072' - '933' - '084' - '124' - '976' - '947' - '756' - '948' - '990' - '152' - '156' - '170' - '970' - '188' - '192' - '132' - '203' - '262' - '208' - '214' - '012' - '818' - '232' - '230' - '978' - '242' - '238' - '826' - '981' - '936' - '292' - '270' - '324' - '320' - '328' - '344' - '340' - '332' - '348' - '360' - '376' - '356' - '368' - '364' - '352' - '388' - '400' - '392' - '404' - '417' - '116' - '174' - '408' - '410' - '414' - '136' - '398' - '418' - '422' - '144' - '430' - '426' - '434' - '504' - '498' - '969' - '807' - '104' - '496' - '446' - '929' - '480' - '462' - '454' - '484' - '979' - '458' - '943' - '516' - '566' - '558' - '578' - '524' - '554' - '512' - '590' - '604' - '598' - '608' - '586' - '985' - '600' - '634' - '946' - '941' - '643' - '646' - '682' - '090' - '690' - '938' - '752' - '702' - '654' - '925' - '706' - '968' - '728' - '930' - '222' - '760' - '748' - '764' - '972' - '934' - '788' - '776' - '949' - '780' - '901' - '834' - '980' - '800' - '840' - '997' - '940' - '858' - '927' - '860' - '926' - '928' - '704' - '548' - '882' - '396' - '950' - '961' - '959' - '955' - '956' - '957' - '958' - '951' - '532' - '960' - '952' - '964' - '953' - '962' - '994' - '963' - '965' - '999' - '886' - '710' - '967' - '924' description: >- Overrides the document-level `currency` for this block only. Normally unset. description: >- MDF-e only: the trip — vehicles, drivers, route, stops and cargo totals. An MDF-e is not an invoice and has no payable total, so `amounts` is empty on one by design. transport: type: object properties: freightModality: type: string enum: - SENDER - RECIPIENT - THIRD_PARTY - OWN_BY_SENDER - OWN_BY_RECIPIENT - NONE description: Normalised, for branching. freightModalityRaw: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- The source's own `modFrete`, preserved. A coded value rather than a bare code because the stored bodies show all four shapes of the same concept — `"9"`, `"0"`, `"0-Emitente"`, `"9-SEM FRETE"` — so the code and the label have to be separable. carrier: type: object properties: type: type: string enum: - PERSON - COMPANY description: >- `PERSON` or `COMPANY` — how to read `federalDocument`. name: type: string description: >- Razão social, or an individual's full name — one field for both. tradeName: type: string description: >- Nome fantasia — the trading name, usually the one a user recognises. federalDocument: type: string description: >- CPF (`PERSON`) or CNPJ (`COMPANY`), unmasked. A CPF is 11 digits. A CNPJ is 14 characters and, from 2026, **may contain letters** — accept it as an opaque string and never strip non-digits or validate it as numeric. stateDocument: type: string description: >- Inscrição estadual (state tax registration) — relevant to ICMS. municipalDocument: type: string description: >- Inscrição municipal — relevant to ISS, so usually present on an NFS-e provider. suframaRegistration: type: string description: >- SUFRAMA registration (Manaus free-trade-zone incentives). cnae: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- CNAE — the party's primary economic-activity code. Providers disagree on FORMAT, not just value (`"6311900"` vs `"8211-3/00"` both occur in the stored bodies), so normalise to digits-only in `code` and keep whatever was printed in `description`. taxRegime: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- Tax regime, from the NF-e `CRT` table: `1` Simples Nacional, `2` Simples Nacional with a sublimit, `3` Regime Normal, `4` MEI. `code` carries that digit; `description` carries whatever the document printed, which varies in wording between issuers. email: type: string phone: type: string description: >- Contact phone exactly as the document carried it — an unnormalised national number (`"11999999999"`), not E.164. Display only. address: type: object properties: street: type: string number: type: string description: >- House/building number. A string, not a number — a real NF-e carries `"."`, `"S/N"`, `"KM 50"`. complement: type: string neighbourhood: type: string description: Bairro. city: type: string cityCode: type: number description: >- IBGE municipality code (7 digits, e.g. `3550308` = São Paulo) — the reliable city join key. state: type: string description: Two-letter UF (`"SP"`). stateCode: type: number description: IBGE state code (2 digits, `35` = SP). postalCode: type: string description: >- Postal code, unmasked but otherwise **verbatim**. A Brazilian CEP is 8 digits and sources report it both masked (`"12345-678"`) and unmasked, so strip the punctuation. ⚠️ Do NOT strip non-digits generally: a non-Brazilian invoice carries a postal code that is legitimately alphanumeric (`"SW1A 1AA"`, `"K1A 0B1"`, `"1012 AB"`), and digit-normalising one destroys it irreversibly. Key the normalisation on `country`. country: type: string countryCode: type: string description: >- BACEN/SEFAZ country code — `"1058"` is Brazil. description: >- A postal address. `cityCode`/`stateCode` are IBGE codes. anttCode: type: string description: ANTT registration code. vehiclePlate: type: string vehicleState: type: string description: UF the plate is registered in. description: >- The transporter — a party, plus the vehicle and ANTT registration that only a carrier has. volumes: type: array items: type: object properties: quantity: type: number kind: type: string description: >- Espécie — `"CAIXA"`, `"RESMAS"`, `"PALLET"`. brand: type: string numbering: type: string grossWeightKg: type: number netWeightKg: type: number description: >- How the goods on an NF-e travelled. A CT-e uses `freightService` instead. deliveryLocation: type: object properties: type: type: string enum: - PERSON - COMPANY description: >- `PERSON` or `COMPANY` — how to read `federalDocument`. name: type: string description: >- Razão social, or an individual's full name — one field for both. tradeName: type: string description: >- Nome fantasia — the trading name, usually the one a user recognises. federalDocument: type: string description: >- CPF (`PERSON`) or CNPJ (`COMPANY`), unmasked. A CPF is 11 digits. A CNPJ is 14 characters and, from 2026, **may contain letters** — accept it as an opaque string and never strip non-digits or validate it as numeric. stateDocument: type: string description: >- Inscrição estadual (state tax registration) — relevant to ICMS. municipalDocument: type: string description: >- Inscrição municipal — relevant to ISS, so usually present on an NFS-e provider. suframaRegistration: type: string description: >- SUFRAMA registration (Manaus free-trade-zone incentives). cnae: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- CNAE — the party's primary economic-activity code. Providers disagree on FORMAT, not just value (`"6311900"` vs `"8211-3/00"` both occur in the stored bodies), so normalise to digits-only in `code` and keep whatever was printed in `description`. taxRegime: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- Tax regime, from the NF-e `CRT` table: `1` Simples Nacional, `2` Simples Nacional with a sublimit, `3` Regime Normal, `4` MEI. `code` carries that digit; `description` carries whatever the document printed, which varies in wording between issuers. email: type: string phone: type: string description: >- Contact phone exactly as the document carried it — an unnormalised national number (`"11999999999"`), not E.164. Display only. address: type: object properties: street: type: string number: type: string description: >- House/building number. A string, not a number — a real NF-e carries `"."`, `"S/N"`, `"KM 50"`. complement: type: string neighbourhood: type: string description: Bairro. city: type: string cityCode: type: number description: >- IBGE municipality code (7 digits, e.g. `3550308` = São Paulo) — the reliable city join key. state: type: string description: Two-letter UF (`"SP"`). stateCode: type: number description: IBGE state code (2 digits, `35` = SP). postalCode: type: string description: >- Postal code, unmasked but otherwise **verbatim**. A Brazilian CEP is 8 digits and sources report it both masked (`"12345-678"`) and unmasked, so strip the punctuation. ⚠️ Do NOT strip non-digits generally: a non-Brazilian invoice carries a postal code that is legitimately alphanumeric (`"SW1A 1AA"`, `"K1A 0B1"`, `"1012 AB"`), and digit-normalising one destroys it irreversibly. Key the normalisation on `country`. country: type: string countryCode: type: string description: >- BACEN/SEFAZ country code — `"1058"` is Brazil. description: >- A postal address. `cityCode`/`stateCode` are IBGE codes. description: >- Endereço de entrega / retirada, when different from the recipient's own address. pickupLocation: type: object properties: type: type: string enum: - PERSON - COMPANY description: >- `PERSON` or `COMPANY` — how to read `federalDocument`. name: type: string description: >- Razão social, or an individual's full name — one field for both. tradeName: type: string description: >- Nome fantasia — the trading name, usually the one a user recognises. federalDocument: type: string description: >- CPF (`PERSON`) or CNPJ (`COMPANY`), unmasked. A CPF is 11 digits. A CNPJ is 14 characters and, from 2026, **may contain letters** — accept it as an opaque string and never strip non-digits or validate it as numeric. stateDocument: type: string description: >- Inscrição estadual (state tax registration) — relevant to ICMS. municipalDocument: type: string description: >- Inscrição municipal — relevant to ISS, so usually present on an NFS-e provider. suframaRegistration: type: string description: >- SUFRAMA registration (Manaus free-trade-zone incentives). cnae: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- CNAE — the party's primary economic-activity code. Providers disagree on FORMAT, not just value (`"6311900"` vs `"8211-3/00"` both occur in the stored bodies), so normalise to digits-only in `code` and keep whatever was printed in `description`. taxRegime: type: object properties: code: type: string description: >- The authority's code, verbatim and as a string (leading zeros are significant). description: type: string description: >- The human label. May be the only half present on an AI-extracted body. description: >- Tax regime, from the NF-e `CRT` table: `1` Simples Nacional, `2` Simples Nacional with a sublimit, `3` Regime Normal, `4` MEI. `code` carries that digit; `description` carries whatever the document printed, which varies in wording between issuers. email: type: string phone: type: string description: >- Contact phone exactly as the document carried it — an unnormalised national number (`"11999999999"`), not E.164. Display only. address: type: object properties: street: type: string number: type: string description: >- House/building number. A string, not a number — a real NF-e carries `"."`, `"S/N"`, `"KM 50"`. complement: type: string neighbourhood: type: string description: Bairro. city: type: string cityCode: type: number description: >- IBGE municipality code (7 digits, e.g. `3550308` = São Paulo) — the reliable city join key. state: type: string description: Two-letter UF (`"SP"`). stateCode: type: number description: IBGE state code (2 digits, `35` = SP). postalCode: type: string description: >- Postal code, unmasked but otherwise **verbatim**. A Brazilian CEP is 8 digits and sources report it both masked (`"12345-678"`) and unmasked, so strip the punctuation. ⚠️ Do NOT strip non-digits generally: a non-Brazilian invoice carries a postal code that is legitimately alphanumeric (`"SW1A 1AA"`, `"K1A 0B1"`, `"1012 AB"`), and digit-normalising one destroys it irreversibly. Key the normalisation on `country`. country: type: string countryCode: type: string description: >- BACEN/SEFAZ country code — `"1058"` is Brazil. description: >- A postal address. `cityCode`/`stateCode` are IBGE codes. description: >- A party to the document — issuer, recipient, carrier or intermediary. A party is identified by ONE `federalDocument` (a CPF or a CNPJ) plus `type` saying which it is. Never assume 11 characters means CPF without reading `type`. payments: type: array items: type: object properties: method: type: string enum: - CASH - CHECK - CREDIT_CARD - DEBIT_CARD - STORE_CREDIT - VOUCHER - BOLETO - BANK_DEPOSIT - PIX - BANK_TRANSFER - LOYALTY - NO_PAYMENT - OTHER description: Normalised means of payment. rawCode: type: string description: >- The source's own code (NF-e `tPag`, e.g. `"17"`), kept so normalising is never lossy. label: type: string description: >- The source's own label, when it gives one (`"Pagamento Digital"`). amount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. change: type: number description: Troco — change given, on an NFC-e. cardBrand: type: string description: >- Card brand as reported (`"Visa"`, or the raw two-digit `bandeira` code in `cardBrandCode`). cardBrandCode: type: string authorizationCode: type: string description: >- The acquirer's authorization code — a reconciliation key against a card transaction. acquirerFederalDocument: type: string description: CNPJ of the credenciadora/acquirer. installmentCount: type: number description: >- Number of card instalments, when the payment was split at the terminal. currency: type: string enum: - '784' - '971' - '008' - '051' - '973' - '032' - '036' - '533' - '944' - '977' - '052' - '050' - '048' - '108' - '060' - '096' - '068' - '984' - '986' - '044' - '064' - '072' - '933' - '084' - '124' - '976' - '947' - '756' - '948' - '990' - '152' - '156' - '170' - '970' - '188' - '192' - '132' - '203' - '262' - '208' - '214' - '012' - '818' - '232' - '230' - '978' - '242' - '238' - '826' - '981' - '936' - '292' - '270' - '324' - '320' - '328' - '344' - '340' - '332' - '348' - '360' - '376' - '356' - '368' - '364' - '352' - '388' - '400' - '392' - '404' - '417' - '116' - '174' - '408' - '410' - '414' - '136' - '398' - '418' - '422' - '144' - '430' - '426' - '434' - '504' - '498' - '969' - '807' - '104' - '496' - '446' - '929' - '480' - '462' - '454' - '484' - '979' - '458' - '943' - '516' - '566' - '558' - '578' - '524' - '554' - '512' - '590' - '604' - '598' - '608' - '586' - '985' - '600' - '634' - '946' - '941' - '643' - '646' - '682' - '090' - '690' - '938' - '752' - '702' - '654' - '925' - '706' - '968' - '728' - '930' - '222' - '760' - '748' - '764' - '972' - '934' - '788' - '776' - '949' - '780' - '901' - '834' - '980' - '800' - '840' - '997' - '940' - '858' - '927' - '860' - '926' - '928' - '704' - '548' - '882' - '396' - '950' - '961' - '959' - '955' - '956' - '957' - '958' - '951' - '532' - '960' - '952' - '964' - '953' - '962' - '994' - '963' - '965' - '999' - '886' - '710' - '967' - '924' description: >- The currency this payment SETTLED in, when it differs from the document's. The one override that is genuinely common — a USD invoice paid on a BRL card. Normally unset. billing: type: object properties: number: type: string originalAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. discount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. netAmount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. installments: type: array items: type: object properties: number: type: string description: >- The issuer's own instalment label (`"015430/A"`, `"001"`). dueDate: type: string description: '`YYYY-MM-DD`.' amount: type: number description: >- An integer number of **cents** — `18990` is R$ 189,90. The denomination is `currency`. The one monetary value that is NOT cents is an item's `unitPrice`, a decimal string, because the NF-e layout allows up to 10 decimal places there. currency: type: string enum: - '784' - '971' - '008' - '051' - '973' - '032' - '036' - '533' - '944' - '977' - '052' - '050' - '048' - '108' - '060' - '096' - '068' - '984' - '986' - '044' - '064' - '072' - '933' - '084' - '124' - '976' - '947' - '756' - '948' - '990' - '152' - '156' - '170' - '970' - '188' - '192' - '132' - '203' - '262' - '208' - '214' - '012' - '818' - '232' - '230' - '978' - '242' - '238' - '826' - '981' - '936' - '292' - '270' - '324' - '320' - '328' - '344' - '340' - '332' - '348' - '360' - '376' - '356' - '368' - '364' - '352' - '388' - '400' - '392' - '404' - '417' - '116' - '174' - '408' - '410' - '414' - '136' - '398' - '418' - '422' - '144' - '430' - '426' - '434' - '504' - '498' - '969' - '807' - '104' - '496' - '446' - '929' - '480' - '462' - '454' - '484' - '979' - '458' - '943' - '516' - '566' - '558' - '578' - '524' - '554' - '512' - '590' - '604' - '598' - '608' - '586' - '985' - '600' - '634' - '946' - '941' - '643' - '646' - '682' - '090' - '690' - '938' - '752' - '702' - '654' - '925' - '706' - '968' - '728' - '930' - '222' - '760' - '748' - '764' - '972' - '934' - '788' - '776' - '949' - '780' - '901' - '834' - '980' - '800' - '840' - '997' - '940' - '858' - '927' - '860' - '926' - '928' - '704' - '548' - '882' - '396' - '950' - '961' - '959' - '955' - '956' - '957' - '958' - '951' - '532' - '960' - '952' - '964' - '953' - '962' - '994' - '963' - '965' - '999' - '886' - '710' - '967' - '924' description: >- Overrides the document-level `currency` for this entry only. Normally unset. description: >- A duplicata/parcela — one scheduled payment of the document's billing plan. currency: type: string enum: - '784' - '971' - '008' - '051' - '973' - '032' - '036' - '533' - '944' - '977' - '052' - '050' - '048' - '108' - '060' - '096' - '068' - '984' - '986' - '044' - '064' - '072' - '933' - '084' - '124' - '976' - '947' - '756' - '948' - '990' - '152' - '156' - '170' - '970' - '188' - '192' - '132' - '203' - '262' - '208' - '214' - '012' - '818' - '232' - '230' - '978' - '242' - '238' - '826' - '981' - '936' - '292' - '270' - '324' - '320' - '328' - '344' - '340' - '332' - '348' - '360' - '376' - '356' - '368' - '364' - '352' - '388' - '400' - '392' - '404' - '417' - '116' - '174' - '408' - '410' - '414' - '136' - '398' - '418' - '422' - '144' - '430' - '426' - '434' - '504' - '498' - '969' - '807' - '104' - '496' - '446' - '929' - '480' - '462' - '454' - '484' - '979' - '458' - '943' - '516' - '566' - '558' - '578' - '524' - '554' - '512' - '590' - '604' - '598' - '608' - '586' - '985' - '600' - '634' - '946' - '941' - '643' - '646' - '682' - '090' - '690' - '938' - '752' - '702' - '654' - '925' - '706' - '968' - '728' - '930' - '222' - '760' - '748' - '764' - '972' - '934' - '788' - '776' - '949' - '780' - '901' - '834' - '980' - '800' - '840' - '997' - '940' - '858' - '927' - '860' - '926' - '928' - '704' - '548' - '882' - '396' - '950' - '961' - '959' - '955' - '956' - '957' - '958' - '951' - '532' - '960' - '952' - '964' - '953' - '962' - '994' - '963' - '965' - '999' - '886' - '710' - '967' - '924' description: >- Overrides the document-level `currency` for this entry only. Normally unset. description: >- The `fatura` header that the instalments belong to. referencedDocuments: type: array items: type: object properties: type: type: string description: >- What kind of document is referenced (`"nfe"`, `"cte"`, a legacy paper note, …). accessKey: type: string description: >- 44-character access key, when the reference is a modern electronic document. model: type: string description: >- SEFAZ model code (`"55"`, `"65"`, `"57"`, `"01"` for a paper note). series: type: string number: type: string issuerFederalDocument: type: string description: >- The referenced document's issuer — a CPF or CNPJ, unmasked and possibly alphanumeric. yearMonth: type: string description: >- `AAMM` competence of a referenced legacy document. description: >- Another fiscal document this one refers to — the chain that makes a return note, an adjustment note or a freight document interpretable. Also what lets a UI link two attachments together. events: type: array items: type: object properties: kind: type: string enum: - CANCELLATION - CORRECTION_LETTER - RECIPIENT_CONFIRMED - RECIPIENT_ACKNOWLEDGED - RECIPIENT_DENIED - OPERATION_NOT_PERFORMED - DELIVERY_PROOF - TRANSIT_PASSAGE - ENDORSEMENT - OTHER code: type: string description: >- Raw SEFAZ event code — `"110111"`, `"210200"`. description: type: string description: >- The authority's description (`"Cancelamento"`, `"Confirmacao da Operacao"`). occurredAt: type: string description: When the event happened (ISO 8601). registeredAt: type: string description: >- When the authority registered it (ISO 8601) — usually the legally-operative moment. protocol: type: string authorFederalDocument: type: string description: >- Who requested it — issuer, recipient or the fisco. CPF or CNPJ. sequence: type: number description: >- Sequence number, for event types that can repeat (a second carta de correção supersedes the first). correctionText: type: string description: >- The amendment text of a carta de correção (110110) — the only place the correction exists. reason: type: string description: >- Cancellation/denial justification, when the event carries one. description: >- One registered event in the document's life. `kind` is the normalised handle to branch on; `code`/`description` are the authority's own words, which a fiscal user will expect to see verbatim. description: >- Registered events, newest-relevant first is a UI choice — store them as the source ordered them. documents: type: object properties: xmlAttachmentId: type: string description: Attachment id of the stored authorized XML. pdfAttachmentId: type: string description: >- Attachment id of the stored DANFE/DANFSE PDF. xmlProviderLink: type: string description: >- A provider-hosted URL, if one exists. Usually short-lived — do not treat as durable. pdfProviderLink: type: string qrCodeUrl: type: string description: >- The NFC-e QR-code payload/URL printed on the receipt (`qrCodeUrl` in the legacy shape). publicQueryUrl: type: string description: >- The public SEFAZ/municipal page where a human can verify the document (`queryUrl`). xmlVersion: type: string description: >- XML layout version the source reported (`"4.00"`). description: >- Pointers to the document's own artefacts — the authorized XML and the printable PDF. notes: type: object properties: additionalInfo: type: string description: >- `infCpl` — complementary information; in practice where issuers put anything unstructured. fiscalInfo: type: string description: >- `infAdFisco` — information addressed to the tax authority. observation: type: string description: >- Taxpayer observations (an NFS-e `observacoes`/`observacoes_contribuinte`). otherInfo: type: array items: type: string description: >- Any further labelled notes the source returned as a list. description: >- Free-text blocks. Kept together because they are all "render as a paragraph, don't parse". source: type: object properties: provider: type: string enum: - AI_EXTRACTION - TAX_AUTHORITY - FISCAL_MONITOR - XML_UPLOAD - MANUAL providerId: type: string description: >- The source's own identifier for the record — its document id, or a request id. retrievedAt: type: string description: >- When we fetched/produced this body (ISO 8601). Distinct from the document's own dates. completeness: type: string enum: - FULL - SUMMARY - PARTIAL confidence: type: number description: >- Extraction confidence, 0–1. Meaningful ONLY for `AI_EXTRACTION`; an authority-sourced body is not "confident", it is authoritative, and should leave this unset rather than report `1`. modelId: type: string description: >- Opaque identifier of the model that produced an `AI_EXTRACTION` body. warnings: type: array items: type: string description: >- Non-fatal problems the source or the connector reported — show these; don't swallow them. description: >- Where this body came from, and how complete it is. **Read it before trusting anything else here:** an `AI_EXTRACTION` is a model's reading of a file and can be wrong, while `TAX_AUTHORITY` and `FISCAL_MONITOR` are the authority's own record. `completeness` separates "the document has no items" from "this source did not return the items". raw: type: object additionalProperties: {} description: >- The source payload, for diagnostics and for fields no screen consumes yet. **Bounded and sanitised, not literally everything the source returned.** Binary artefacts are excluded: a source that returns the XML or PDF inline as base64 has those stripped and stored as their own attachments, referenced from `documents`. Expect a few kilobytes at most — these bodies ride inside every list response, which returns up to 100 of them. Never render it and never branch on it. description: >- The fiscal document this file represents — a nota fiscal or an invoice. Absent unless the file is one and its details are known. Every field inside is optional: null-check your way in, and read `status` before rendering any amount. example: type: NFCE accessKey: '35261011222333000181650010000042131384617292' model: '65' number: '4213' series: '1' environment: LIVE currency: '986' status: UNKNOWN issuedAt: '2026-10-15T08:47:12-03:00' issuer: type: COMPANY name: Posto Exemplo Ltda. tradeName: Posto Exemplo Centro federalDocument: '11222333000181' stateDocument: '123456789110' address: street: Avenida Exemplo number: '1000' neighbourhood: Bela Vista city: São Paulo cityCode: 3550308 state: SP stateCode: 35 postalCode: '01310100' country: Brasil countryCode: '1058' recipientRole: CONSUMER isFinalConsumer: true amounts: totalValue: 25000 productsValue: 25000 discounts: 0 approximateTax: 8130 taxes: approximateFederal: 2950 approximateState: 5180 items: - sequence: 1 code: '1' description: GASOLINA COMUM ncm: '27101259' cfop: '5656' unit: L quantity: 40 unitPrice: '6.25' total: 25000 itemCount: 1 payments: - method: CREDIT_CARD label: Cartão de crédito amount: 25000 cardBrand: Visa source: provider: AI_EXTRACTION retrievedAt: '2026-10-15T14:32:58.000Z' completeness: FULL confidence: 0.93 modelId: doc-analysis-2026-09 fiscal: type: object properties: status: type: string enum: - PENDING - PROCESSING - DONE - FAILED - SKIPPED description: >- Progress of the attachment's fiscal-data extraction. `PENDING` and `PROCESSING` are transient — a fiscal document's structured data is read asynchronously shortly after upload, so a freshly created attachment reports one of them until it settles on `DONE` (`extractedReceipt` is populated), `SKIPPED` (the file is not a fiscal document, or nothing could be read from it) or `FAILED`. example: DONE executedAt: type: string description: When the extraction ran. example: '2026-10-15T14:32:58.000Z' format: date-time modelId: type: string description: >- Identifier of the model that produced `extractedReceipt`. Opaque, and absent when no model ran (an authorized XML is read directly). example: doc-analysis-2026-09 error: type: string description: >- Why no fiscal data was produced. Absent when `DONE`. A `SKIPPED` status reports one of: `NOT_A_FISCAL_DOCUMENT` (the file is not an invoice — the ordinary outcome for most attachments), `NOTHING_EXTRACTED` (it looked like one, but no usable field could be read), `UNSUPPORTED_CONTENT_TYPE` (the file is not a PDF, a JPEG/PNG image or an XML document), `UNSUPPORTED_FISCAL_XML()` (an XML fiscal ARTIFACT that is not a document body — an event registration, a submission batch or a distribution summary) or `FILE_TOO_LARGE`. A `FAILED` status reports the underlying error instead, and its text is not a stable token — **branch on `status`, never on this string.** required: - status description: >- Progress of the fiscal-data extraction that fills `extractedReceipt`. Always present; a `PENDING`/`PROCESSING` status means the file has not been read yet, which is why an `extractedReceipt` can be absent from a document that does have one. createdBy: type: string description: >- ID of the user (or API client) who created the attachment. example: e3553bc1-5e20-4e17-b22a-a796fda0aa99 createdAt: type: string description: When the attachment was created. example: '2026-10-15T14:31:05.000Z' format: date-time updatedAt: type: string description: >- When the attachment last changed — its upload being confirmed or an analysis finishing. example: '2026-10-15T14:32:58.000Z' format: date-time deletedAt: type: string description: >- When the attachment was deleted. Present only on a `DELETED` attachment. format: date-time deletedBy: type: string description: >- ID of the user who deleted the attachment. Present only on a `DELETED` attachment. required: - id - realmId - organizationId - status - name - contentType - ai - thumbnail - fiscal - createdBy description: A stored file and what was read from it. description: The attachments of this page, newest first. next: type: string nullable: true description: >- Cursor for the next page — send it back as `next`. `null` on the last page. example: NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy required: - items - next description: A page of attachments, newest first. '403': description: >- `ATTACHMENT_REALM_ADMIN_REQUIRED` — Only admins of the realm can list its attachments. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - ATTACHMENT_REALM_ADMIN_REQUIRED description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - ATTACHMENT description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: ATTACHMENT_REALM_ADMIN_REQUIRED origin: ATTACHMENT message: Realm admin required '422': description: >- `BAD_REQUEST` — The realm ID or a query parameter is invalid; `fields` lists each one. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - BAD_REQUEST description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - ATTACHMENT description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. fields: type: array description: >- One entry per invalid request field (validation errors only). items: type: object properties: field: type: string description: >- Path of the invalid field, e.g. `label` or `values[0].value`. example: label message: type: string description: Why the field was rejected. example: label is required code: type: string description: >- `_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`. example: LABEL_REQUIRED values: type: array items: type: string description: >- The accepted values, when the field is an enumeration. required: - field - message - code required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BAD_REQUEST origin: ATTACHMENT message: >- Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields. fields: - field: ids message: 'Too big: expected array to have <=100 items' code: IDS_MAX ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.