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