{ "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" } ], "x-p3-surface": "public", "tags": [ { "name": "Attachments" } ], "components": {}, "paths": { "/realms/{realmId}/attachments": { "get": { "operationId": "getRealmsByRealmIdAttachments", "summary": "List realm attachments", "tags": [ "Attachments" ], "x-p3-sidebar-order": 1, "description": "Lists the attachments of every organization in your realm, newest first.", "x-mint": { "content": "Only realm admins can list them. Any other caller gets a 403 — including an organization admin and an API client, which are scoped to their organizations: they list each organization's attachments with the organization route instead. Each attachment carries the `organizationId` it belongs to.\n\nDeleted attachments are left out unless `status` asks for them. Filter by ID, by name or by the automatic summary; a list parameter takes comma-separated values (`?status=AVAILABLE,DELETED`). Paginated — see [Pagination](/api-reference/pagination)." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "ids", "in": "query", "required": false, "description": "Only the attachments with these IDs. Sent but empty, it matches no attachment.\n\n---\n\nExample (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.\n\n---\n\nExample (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.\n\nA `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 —\n**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.\n\n⚠️ `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`.\n\n---\n\nExample: `[\"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.**\n\nNothing 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.\n\nFor 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.\n**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).\n\n`\"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.\n\n⚠️ 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.\n\n`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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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.\n\n`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.\n\n**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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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.\n\nNot 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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.\n\nPresent 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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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.\n\nA 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.\n\nAn 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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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.\n\nA 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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.\n\n**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`.\n\nA `SKIPPED` status reports one of: `NOT_A_FISCAL_DOCUMENT` (the file is not an invoice — the ordinary outcome for most attachments), `NOTHING_EXTRACTED` (it looked like one, but no usable field could be read), `UNSUPPORTED_CONTENT_TYPE` (the file is not a PDF, a JPEG/PNG image or an XML document), `UNSUPPORTED_FISCAL_XML()` (an XML fiscal ARTIFACT that is not a document body — an event registration, a submission batch or a distribution summary) or `FILE_TOO_LARGE`. A `FAILED` status reports the underlying error instead, and its text is not a stable token — **branch on `status`, never on this string.**" } }, "required": [ "status" ], "description": "Progress of the fiscal-data extraction that fills `extractedReceipt`. Always present; a `PENDING`/`PROCESSING` status means the file has not been read yet, which is why an `extractedReceipt` can be absent from a document that does have one." }, "createdBy": { "type": "string", "description": "ID of the user (or API client) who created the attachment.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99" }, "createdAt": { "type": "string", "description": "When the attachment was created.", "example": "2026-10-15T14:31:05.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the attachment last changed — its upload being confirmed or an analysis finishing.", "example": "2026-10-15T14:32:58.000Z", "format": "date-time" }, "deletedAt": { "type": "string", "description": "When the attachment was deleted. Present only on a `DELETED` attachment.", "format": "date-time" }, "deletedBy": { "type": "string", "description": "ID of the user who deleted the attachment. Present only on a `DELETED` attachment." } }, "required": [ "id", "realmId", "organizationId", "status", "name", "contentType", "ai", "thumbnail", "fiscal", "createdBy" ], "description": "A stored file and what was read from it." }, "description": "The attachments of this page, newest first." }, "next": { "type": "string", "nullable": true, "description": "Cursor for the next page — send it back as `next`. `null` on the last page.", "example": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy" } }, "required": [ "items", "next" ], "description": "A page of attachments, newest first." } } } }, "403": { "description": "`ATTACHMENT_REALM_ADMIN_REQUIRED` — Only admins of the realm can list its attachments.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "ATTACHMENT_REALM_ADMIN_REQUIRED" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ATTACHMENT" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "ATTACHMENT_REALM_ADMIN_REQUIRED", "origin": "ATTACHMENT", "message": "Realm admin required" } } } }, "422": { "description": "`BAD_REQUEST` — The realm ID or a query parameter is invalid; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ATTACHMENT" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "BAD_REQUEST", "origin": "ATTACHMENT", "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.", "fields": [ { "field": "ids", "message": "Too big: expected array to have <=100 items", "code": "IDS_MAX" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/attachments": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdAttachments", "summary": "List attachments", "tags": [ "Attachments" ], "x-p3-sidebar-order": 2, "description": "Lists the organization's attachments, newest first.", "x-mint": { "content": "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.\n\nDeleted attachments are left out unless `status` asks for them. You can also filter by name or by the automatic summary. Paginated — see [Pagination](/api-reference/pagination)." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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.\n\nFormat: `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.\n\n---\n\nExample (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.\n\n---\n\nExample (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.\n\nA `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 —\n**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.\n\n⚠️ `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`.\n\n---\n\nExample: `[\"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.**\n\nNothing 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.\n\nFor 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.\n**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).\n\n`\"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.\n\n⚠️ 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.\n\n`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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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.\n\n`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.\n\n**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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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.\n\nNot 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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.\n\nPresent 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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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.\n\nA 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.\n\nAn 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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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.\n\nA 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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.\n\n**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`.\n\nA `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" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } }, "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdAttachments", "summary": "Create an attachment", "tags": [ "Attachments" ], "x-p3-sidebar-order": 3, "description": "Registers a file and returns the URL to upload its bytes to.", "x-mint": { "content": "Uploading a file takes two requests:\n\n1. Call this endpoint with the file's `name`, `contentType`, `sizeBytes` and `checksumSha256`\n — the SHA-256 digest of the file's bytes, base64-encoded (44 characters). It answers `201` with the new attachment, in `PENDING_UPLOAD`, and an `uploadUrl`.\n2. Send the file's bytes to `uploadUrl` with a `PUT`, within 25 minutes. Send exactly the\n `Content-Type` you declared and an `x-amz-checksum-sha256` header holding the `checksumSha256` you declared, with a body of exactly `sizeBytes` bytes and no `Authorization` header. An upload whose type, size or content differs is rejected.\n\nOnce the upload lands, the attachment becomes `AVAILABLE`, usually within seconds — read it again to know when; until then a download answers `409 ATTACHMENT_NOT_AVAILABLE`. The summary, the preview image and the fiscal data are then filled in on their own: follow `ai.status`, `thumbnail.status` and `fiscal.status`.\n\nFiles can be up to 25 MiB of any type. The automatic analysis covers PDFs, JPEG and PNG images and XML documents, up to 3.7 MB for an image and 4 MB for a PDF or XML; the preview covers JPEG, PNG, GIF, BMP and TIFF images and the first page of a PDF. An uploaded file can't be replaced — create a new attachment for a new version." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the file belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Name of the file, returned as sent.", "example": "cupom-fiscal-posto.jpg" }, "contentType": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Media type of the file. The upload must send exactly this value as its `Content-Type` header.", "example": "image/jpeg" }, "checksumSha256": { "type": "string", "minLength": 44, "maxLength": 44, "pattern": "^[A-Za-z0-9+/]{43}=$", "description": "SHA-256 digest of the file's bytes, base64-encoded (44 characters). The upload must send exactly this value as its `x-amz-checksum-sha256` header.", "example": "mAvD2GDNsz9cDoFtpN+2TKBKtAMo+ZngJoUAsEf7eWs=" }, "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 26214400, "description": "Size of the file in bytes, up to 25 MiB (26,214,400 bytes). The upload must be exactly this long.", "example": 2457600 } }, "required": [ "name", "contentType", "checksumSha256", "sizeBytes" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the new 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": "`PENDING_UPLOAD` until the file is uploaded to `uploadUrl`.", "example": "PENDING_UPLOAD" }, "name": { "type": "string", "description": "Name of the file, as sent.", "example": "cupom-fiscal-posto.jpg" }, "contentType": { "type": "string", "description": "Media type of the file, as declared. The upload must send it as `Content-Type`.", "example": "image/jpeg" }, "sizeBytes": { "type": "number", "description": "Size of the file in bytes, as declared. The upload must be exactly this long.", "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": "PENDING" } }, "required": [ "status" ], "description": "The content analysis, which starts once the file is uploaded." }, "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": "PENDING" } }, "required": [ "status" ], "description": "The preview image, generated once the file is uploaded." }, "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": "PENDING" } }, "required": [ "status" ], "description": "The fiscal-data extraction, which starts once the file is uploaded." }, "contents": { "type": "array", "items": { "type": "string" }, "description": "Facts read from the file — empty until the analysis has run.\n\n---\n\nExample: `[]`", "example": [] }, "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.", "example": "2026-10-15T14:31:05.000Z", "format": "date-time" }, "uploadUrl": { "type": "string", "description": "Pre-signed URL to `PUT` the file's bytes to, valid for 25 minutes. Send exactly the declared `Content-Type`, an `x-amz-checksum-sha256` header with the declared `checksumSha256`, and a body of exactly `sizeBytes` bytes — and no `Authorization` header. (The example is shortened.)", "example": "https://files.example.com/3f6c2a1e-8b4d-4f7a-9c2e-5d1b7a9e4c60.jpg?signature=…" } }, "required": [ "id", "realmId", "organizationId", "status", "name", "contentType", "ai", "thumbnail", "fiscal", "createdBy", "uploadUrl" ], "description": "A just-created attachment, waiting for its file. It carries only what exists at creation time: no analysis has run yet, so `summary`, `image` and `extractedReceipt` are absent and each status block is `PENDING`." } } } }, "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 parameter is not a valid ID or the body failed validation; `fields` lists each offending field.", "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": "name", "message": "Invalid input: expected string, received undefined", "code": "NAME_REQUIRED" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/attachments/{attachmentId}": { "delete": { "operationId": "deleteRealmsByRealmIdOrganizationsByOrganizationIdAttachmentsByAttachmentId", "summary": "Delete an attachment", "tags": [ "Attachments" ], "x-p3-sidebar-order": 5, "description": "Deletes an attachment.", "x-mint": { "content": "Only admins of the organization (or of the realm) can delete one. Deleting is permanent — there is no undo — and no new download link is issued for the file afterwards; a link issued before stays valid until it expires, at most 10 minutes later. The attachment itself stays readable, with `status: DELETED`.\n\nDeleting an attachment that is already deleted succeeds again (`204`), so a retry is safe." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the attachment belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "attachmentId", "in": "path", "required": true, "description": "ID of the attachment, as returned when it was created.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "3f6c2a1e-8b4d-4f7a-9c2e-5d1b7a9e4c60" } ], "responses": { "204": { "description": "No Content. The operation succeeded and the response has no body." }, "403": { "description": "`ATTACHMENT_ADMIN_REQUIRED` — Only admins of the organization or of the realm can delete attachments.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "ATTACHMENT_ADMIN_REQUIRED" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ATTACHMENT" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "ATTACHMENT_ADMIN_REQUIRED", "origin": "ATTACHMENT", "message": "Organization admin required" } } } }, "404": { "description": "`ATTACHMENT_NOT_FOUND` — No attachment with this ID exists in 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_NOT_FOUND" ], "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_NOT_FOUND", "origin": "ATTACHMENT", "message": "Attachment not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID; `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": "attachmentId", "message": "Invalid UUID", "code": "ATTACHMENTID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } }, "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdAttachmentsByAttachmentId", "summary": "Get an attachment", "tags": [ "Attachments" ], "x-p3-sidebar-order": 4, "description": "Returns an attachment and what was read from it, whatever its status.", "x-mint": { "content": "Any member of the organization can read it. A deleted attachment is still returned, with `status: DELETED`, so you can tell it apart from an ID that never existed.\n\nThe automatic analysis fills four fields after the upload, each on its own: `summary` and `contents` (in Portuguese), the preview image in `thumbnail`, the file's dimensions in `image` and — when the file is a nota fiscal or an invoice — the structured `extractedReceipt`. Check the matching status block (`ai`, `thumbnail`, `fiscal`) before reading one: `PENDING` and `PROCESSING` mean the file hasn't been read yet." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the attachment belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "attachmentId", "in": "path", "required": true, "description": "ID of the attachment, as returned when it was created.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "3f6c2a1e-8b4d-4f7a-9c2e-5d1b7a9e4c60" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "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.\n\nA `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 —\n**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.\n\n⚠️ `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`.\n\n---\n\nExample: `[\"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.**\n\nNothing 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.\n\nFor 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.\n**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).\n\n`\"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.\n\n⚠️ 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.\n\n`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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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.\n\n`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.\n\n**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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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.\n\nNot 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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.\n\nPresent 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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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.\n\nA 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.\n\nAn 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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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.\n\nA 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**.\n\nA 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.\n\nA 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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`.\n\nThe 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.\n\n**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`.\n\nA `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." } } } }, "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" } } } }, "404": { "description": "`ATTACHMENT_NOT_FOUND` — No attachment with this ID exists in 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_NOT_FOUND" ], "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_NOT_FOUND", "origin": "ATTACHMENT", "message": "Attachment not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID; `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": "attachmentId", "message": "Invalid UUID", "code": "ATTACHMENTID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/attachments/{attachmentId}/download": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdAttachmentsByAttachmentIdDownload", "summary": "Download an attachment", "tags": [ "Attachments" ], "x-p3-sidebar-order": 6, "description": "Returns a short-lived URL to download the attachment's file.", "x-mint": { "content": "Any member of the organization can download it. The `url` works for 10 minutes: fetch it with a plain `GET`, without an `Authorization` header, and ask for a new one whenever you need the file — don't store it. It always serves the file exactly as it was uploaded.\n\nOnly an `AVAILABLE` attachment can be downloaded. Right after the upload, while it is still `PENDING_UPLOAD`, this answers `409 ATTACHMENT_NOT_AVAILABLE` — retry shortly. A `DELETED` attachment answers the same `409`, for good." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the attachment belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "attachmentId", "in": "path", "required": true, "description": "ID of the attachment, as returned when it was created.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "3f6c2a1e-8b4d-4f7a-9c2e-5d1b7a9e4c60" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Pre-signed URL that serves the file for 10 minutes. Fetch it with a plain `GET` and no `Authorization` header; request a new one when it expires instead of storing it. (The example is shortened.)", "example": "https://files.example.com/3f6c2a1e-8b4d-4f7a-9c2e-5d1b7a9e4c60.jpg?signature=…" }, "name": { "type": "string", "description": "Name of the file, as sent when the attachment was created.", "example": "cupom-fiscal-posto.jpg" }, "contentType": { "type": "string", "description": "Media type of the file, as declared when the attachment was created.", "example": "image/jpeg" } }, "required": [ "url", "name", "contentType" ], "description": "A short-lived link to the attachment's file." } } } }, "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" } } } }, "404": { "description": "`ATTACHMENT_NOT_FOUND` — No attachment with this ID exists in 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_NOT_FOUND" ], "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_NOT_FOUND", "origin": "ATTACHMENT", "message": "Attachment not found" } } } }, "409": { "description": "`ATTACHMENT_NOT_AVAILABLE` — The file hasn't been uploaded yet (`PENDING_UPLOAD` — retry shortly) or the attachment was deleted.", "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_NOT_AVAILABLE" ], "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_NOT_AVAILABLE", "origin": "ATTACHMENT", "message": "Attachment is not available for download yet" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID; `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": "attachmentId", "message": "Invalid UUID", "code": "ATTACHMENTID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } } } } }