> ## 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. # /realms/{realmId}/organizations/{organizationId}/attachments/{attachmentId} ## OpenAPI ````yaml /api-reference/attachment.openapi.json get /realms/{realmId}/organizations/{organizationId}/attachments/{attachmentId} openapi: 3.0.3 info: title: Attachment version: 1.0.0 description: >- Portão 3 attachment API. Generated by tools/openapi from code (routes + security) and the hand-written spec (request/response bodies). Confidence tiers: generated:typed=2 copied:manual=0 unknown=5. servers: - url: https://api.attachment.v2.portao3.com.br/ description: production - url: https://api.attachment.dev.3pers.com.br/ description: development security: - bearerAuth: [] tags: - name: Attachments paths: /realms/{realmId}/organizations/{organizationId}/attachments/{attachmentId}: get: tags: - Attachments summary: >- /realms/{realmId}/organizations/{organizationId}/attachments/{attachmentId} operationId: getRealmsByRealmIdOrganizationsByOrganizationIdAttachmentsByAttachmentId parameters: - name: realmId in: path required: true schema: type: string - name: organizationId in: path required: true schema: type: string - name: attachmentId in: path required: true schema: type: string responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string realmId: type: string organizationId: type: string 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. name: type: string contentType: type: string sizeBytes: type: number 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`. executedAt: type: string modelId: type: string error: type: string required: - status description: >- The wire/event-payload shape — one mapper, shared by every HTTP response and event dispatch. 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`. data: type: string description: >- The preview image as base64-encoded JPEG, without a `data:` prefix — render it with `data:${contentType};base64,${data}`. Present only once `status` is `DONE`. contentType: type: string description: Media type of `data` (currently always `image/jpeg`). width: type: number description: Width of the preview image in pixels (square). height: type: number description: Height of the preview image in pixels (square). sizeBytes: type: number description: >- Size of the decoded preview in bytes (the base64 string is about a third larger). generatedAt: type: string description: When the preview was generated, ISO-8601. 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 height: type: number format: type: string description: >- The detected format: `jpg` | `png` | `gif` | `bmp` | `tiff` | `webp` | `pdf` | … 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 contents: type: array items: type: string 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. 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`. executedAt: type: string description: When the extraction ran, ISO-8601. modelId: type: string description: >- Identifier of the model that produced `extractedReceipt`. 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 createdAt: type: string updatedAt: type: string deletedAt: type: string deletedBy: type: string required: - id - realmId - organizationId - status - name - contentType - ai - thumbnail - fiscal - createdBy components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````