{ "openapi": "3.0.3", "info": { "title": "Accounting", "version": "1.0.0", "description": "Portão 3 accounting 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). NFSe issuance: the organization's tax issuer (setup, certificate, logo), its tax documents (issue, list, download, cancel, CSV batches) and the city special-tax-regime lookup. Every route validates path, query, body and multipart form through a zod Input class (`accounting/app/use-case/*/inputs`), which documents it; responses are the named interfaces in `accounting/app/use-case/*/outputs/*Response.ts`. Confidence tiers: generated:typed=24 copied:manual=0 unknown=0." }, "servers": [ { "url": "https://api.accounting.v2.portao3.com.br/", "description": "production" }, { "url": "https://api.accounting.dev.3pers.com.br/", "description": "development" } ], "x-p3-surface": "public", "tags": [ { "name": "Tax Issuers" }, { "name": "Tax Documents (NFSe)" }, { "name": "Tax Codes" } ], "components": {}, "paths": { "/realms/{realmId}/organizations/{organizationId}/tax-issuer": { "delete": { "operationId": "deleteRealmsByRealmIdOrganizationsByOrganizationIdTaxIssuer", "summary": "Deactivate your tax issuer", "tags": [ "Tax Issuers" ], "x-p3-sidebar-order": 4, "description": "Deactivates the tax issuer of the organization.", "x-mint": { "content": "The issuer is deactivated at the tax provider and marked inactive: no more documents can be issued from it, and getting it answers 404 until you create a new one. Documents you already issued are not touched.\n\nIf the tax provider cannot be reached, the issuer stays active and the request fails with a status of 400." }, "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.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "responses": { "204": { "description": "No Content. The operation succeeded and the response has no body." }, "404": { "description": "`TAX_ISSUER_NOT_FOUND` — The organization has no tax issuer.", "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": [ "TAX_ISSUER_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_ISSUER_NOT_FOUND", "origin": "ACCOUNTING", "message": "Tax issuer 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": [ "ACCOUNTING" ], "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": "ACCOUNTING", "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.", "fields": [ { "field": "organizationId", "message": "Invalid UUID", "code": "ORGANIZATIONID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } }, "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdTaxIssuer", "summary": "Get your tax issuer", "tags": [ "Tax Issuers" ], "x-p3-sidebar-order": 1, "description": "Returns the tax issuer of the organization, with its test and live configurations.", "x-mint": { "content": "The tax issuer is the registration of your organization that issues its service invoices (NFSe). The response carries the organization's registration data (name, CNPJ, address, taken from Portão 3), the `TEST` (homologation) and `LIVE` (production) configurations, and whether a digital certificate and a logotype have been uploaded. Use its `id` as `{taxIssuer}` in the upload routes.\n\nOnly an active tax issuer is returned: one you deactivated, or that never finished its creation, is answered as not found." }, "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.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the tax issuer. Use it as `{taxIssuer}` in the upload routes.", "example": "9b2f4c1e-7a3d-4e8b-b6f0-2d5c8a1e3f47", "format": "uuid" }, "realm": { "type": "string", "description": "ID of your realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "tradingName": { "type": "string", "description": "Trade name of the organization.", "example": "Acme Tecnologia" }, "legalName": { "type": "string", "description": "Legal name of the organization.", "example": "Acme Tecnologia Ltda" }, "document": { "type": "string", "description": "CNPJ of the organization, digits only.", "example": "12345678000195" }, "email": { "type": "string", "description": "E-mail of the organization.", "example": "fiscal@acme.com.br" }, "municipalDocument": { "type": "string", "description": "Municipal registration (`inscrição municipal`) of the organization.", "example": "123456" }, "stateDocument": { "type": "string", "description": "State registration (`inscrição estadual`) of the organization.", "example": "654321" }, "phoneNumber": { "type": "string", "description": "Phone number of the organization, in international format.", "example": "+5534984325252" }, "mainActivity": { "type": "string", "description": "Main business activity of the organization.", "example": "Desenvolvimento de programas de computador sob encomenda" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "ERROR" ], "description": "Status of the tax issuer. Only an `ACTIVE` issuer is returned.", "example": "ACTIVE" }, "hasLogotype": { "type": "boolean", "description": "Whether a logotype has been uploaded.", "example": true }, "address": { "type": "object", "properties": { "city": { "type": "string", "description": "City.", "example": "Uberlândia" }, "neighborhood": { "type": "string", "description": "Neighborhood.", "example": "Centro" }, "number": { "type": "string", "description": "Street number.", "example": "1000" }, "state": { "type": "string", "description": "State, as its two-letter code.", "example": "MG" }, "street": { "type": "string", "description": "Street name.", "example": "Avenida Getúlio Vargas" }, "postalCode": { "type": "string", "description": "Postal code (CEP).", "example": "38400-000" }, "complement": { "type": "string", "description": "Address complement, such as the floor or suite. Empty when there is none.", "example": "Sala 12" }, "stateCode": { "type": "number", "nullable": true, "description": "IBGE code of the state. `null` when the organization has none registered.", "example": 31 }, "cityCode": { "type": "number", "nullable": true, "description": "IBGE code of the city. `null` when the organization has none registered.", "example": 3170206 } }, "required": [ "city", "neighborhood", "number", "state", "street", "postalCode", "complement" ], "description": "Registered address of the organization." }, "homologationProperties": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of this configuration.", "example": "7c1e5a90-3b2d-4f68-8a14-d9e0b6c2f375", "format": "uuid" }, "environment": { "type": "string", "enum": [ "LIVE", "TEST" ], "description": "Environment this configuration is for: always `TEST`.", "example": "TEST" }, "specialTaxCode": { "type": "string", "description": "Code of the special taxation regime of the city.", "example": "1" }, "municipalServiceCode": { "type": "string", "description": "Municipal service code, as the city hall defines it. Used on every invoice that does not send its own.", "example": "0107" }, "serviceListItem": { "type": "string", "description": "Item of the federal service list (LC 116/2003), such as `1.07`. Empty when none was registered.", "example": "1.07" }, "cnae": { "type": "number", "description": "CNAE subclass code of the main activity, as a number.", "example": 6201501 }, "issTax": { "type": "number", "description": "ISS (municipal service tax) rate in percent: `2.5` means 2.5%.", "example": 2.5 }, "serviceDescription": { "type": "string", "description": "Description of the service provided.", "example": "Licenciamento de software como serviço (SaaS)" }, "hasCulturalIncentive": { "type": "boolean", "description": "Whether the organization is a cultural incentivizer (`incentivador cultural`).", "example": false }, "isSimplesNacional": { "type": "boolean", "description": "Whether the organization is under the Simples Nacional tax regime.", "example": true }, "nfeSequencialCode": { "type": "number", "description": "RPS (provisional service receipt) number set for this environment when the tax issuer was created or last updated: where the tax provider's numbering started. It is NOT advanced as documents are issued, so it is not the next number — never send it back unchanged in an update.", "example": 1 }, "nfeSeries": { "type": "string", "description": "Series of the RPS this environment issues.", "example": "1" }, "nfeSequencialBatch": { "type": "number", "description": "RPS batch number set for this environment when the tax issuer was created or last updated. Like `nfeSequencialCode`, it is not advanced as documents are issued.", "example": 1 }, "hasCertificate": { "type": "boolean", "description": "Whether a digital certificate has been uploaded (see Upload your digital certificate).", "example": true }, "taxConfiguration": { "type": "object", "properties": { "nbsCode": { "type": "string", "description": "NBS code (`Nomenclatura Brasileira de Serviços`) of the service.", "example": "115090000" }, "nationalTaxCode": { "type": "string", "description": "National tax code (`código de tributação nacional`) of the service.", "example": "010701" }, "taxClassification": { "type": "string", "description": "Tax classification (`classificação tributária`) of the operation.", "example": "000001" }, "operationIndicatorCode": { "type": "string", "description": "Operation indicator (`indicador de operação`) code.", "example": "100301" } }, "description": "National NFSe tax fields of the LC 214/2025 reform. Absent when none were registered." } }, "required": [ "cnae", "hasCertificate", "hasCulturalIncentive", "id", "isSimplesNacional", "issTax", "municipalServiceCode", "nfeSequencialBatch", "nfeSequencialCode", "nfeSeries", "serviceDescription", "serviceListItem", "specialTaxCode" ], "description": "Configuration of the test (homologation) environment: documents issued here have no fiscal value." }, "productionProperties": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of this configuration.", "example": "a4d8e2f1-6b3c-4e9a-8f05-1c7b9d2e6a30", "format": "uuid" }, "environment": { "type": "string", "enum": [ "LIVE", "TEST" ], "description": "Environment this configuration is for: always `LIVE`.", "example": "LIVE" }, "specialTaxCode": { "type": "string", "description": "Code of the special taxation regime of the city.", "example": "1" }, "municipalServiceCode": { "type": "string", "description": "Municipal service code, as the city hall defines it. Used on every invoice that does not send its own.", "example": "0107" }, "serviceListItem": { "type": "string", "description": "Item of the federal service list (LC 116/2003), such as `1.07`. Empty when none was registered.", "example": "1.07" }, "cnae": { "type": "number", "description": "CNAE subclass code of the main activity, as a number.", "example": 6201501 }, "issTax": { "type": "number", "description": "ISS (municipal service tax) rate in percent: `2.5` means 2.5%.", "example": 2.5 }, "serviceDescription": { "type": "string", "description": "Description of the service provided.", "example": "Licenciamento de software como serviço (SaaS)" }, "hasCulturalIncentive": { "type": "boolean", "description": "Whether the organization is a cultural incentivizer (`incentivador cultural`).", "example": false }, "isSimplesNacional": { "type": "boolean", "description": "Whether the organization is under the Simples Nacional tax regime.", "example": true }, "nfeSequencialCode": { "type": "number", "description": "RPS (provisional service receipt) number set for this environment when the tax issuer was created or last updated: where the tax provider's numbering started. It is NOT advanced as documents are issued, so it is not the next number — never send it back unchanged in an update.", "example": 1 }, "nfeSeries": { "type": "string", "description": "Series of the RPS this environment issues.", "example": "1" }, "nfeSequencialBatch": { "type": "number", "description": "RPS batch number set for this environment when the tax issuer was created or last updated. Like `nfeSequencialCode`, it is not advanced as documents are issued.", "example": 1 }, "hasCertificate": { "type": "boolean", "description": "Whether a digital certificate has been uploaded (see Upload your digital certificate).", "example": true }, "taxConfiguration": { "type": "object", "properties": { "nbsCode": { "type": "string", "description": "NBS code (`Nomenclatura Brasileira de Serviços`) of the service.", "example": "115090000" }, "nationalTaxCode": { "type": "string", "description": "National tax code (`código de tributação nacional`) of the service.", "example": "010701" }, "taxClassification": { "type": "string", "description": "Tax classification (`classificação tributária`) of the operation.", "example": "000001" }, "operationIndicatorCode": { "type": "string", "description": "Operation indicator (`indicador de operação`) code.", "example": "100301" } }, "description": "National NFSe tax fields of the LC 214/2025 reform. Absent when none were registered." } }, "required": [ "cnae", "hasCertificate", "hasCulturalIncentive", "id", "isSimplesNacional", "issTax", "municipalServiceCode", "nfeSequencialBatch", "nfeSequencialCode", "nfeSeries", "serviceDescription", "serviceListItem", "specialTaxCode" ], "description": "Configuration of the live (production) environment: documents issued here are legally valid." } }, "required": [ "id", "realm", "organization", "tradingName", "legalName", "document", "email", "status", "hasLogotype", "address", "homologationProperties", "productionProperties" ], "description": "The tax issuer of an organization: who issues its NFSe, and how, in the test and live environments." } } } }, "404": { "description": "`TAX_ISSUER_NOT_FOUND` — The organization has no active tax issuer.\n\n`ORGANIZATION_NOT_FOUND` — The organization does not exist in your realm.\n\n`ISSUER_PROPERTIES_NOT_FOUND` — The tax issuer is missing its test or its live configuration.", "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": [ "TAX_ISSUER_NOT_FOUND", "ORGANIZATION_NOT_FOUND", "ISSUER_PROPERTIES_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_ISSUER_NOT_FOUND", "origin": "ACCOUNTING", "message": "Tax issuer 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": [ "ACCOUNTING" ], "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": "ACCOUNTING", "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.", "fields": [ { "field": "organizationId", "message": "Invalid UUID", "code": "ORGANIZATIONID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } }, "patch": { "operationId": "patchRealmsByRealmIdOrganizationsByOrganizationIdTaxIssuer", "summary": "Update your tax issuer", "tags": [ "Tax Issuers" ], "x-p3-sidebar-order": 3, "description": "Updates the configuration of the tax issuer of the organization, in both environments.", "x-mint": { "content": "This replaces the configuration of the `TEST` (homologation) and the `LIVE` (production) environment, so send both `homologationProperties` and `productionProperties` in full. The organization's own data (CNPJ, legal name, address, phone) is taken again from its registration in Portão 3 and sent to the tax provider together with the new configuration. Omitting a `taxConfiguration` keeps the stored one.\n\nThe RPS numbers you send (`nfeSequencialCode`, `nfeSequencialBatch`) restart the tax provider's numbering for that environment. Get your tax issuer returns the numbers set last, not the current ones (they are not advanced as documents are issued), so send the number your city hall expects next — never the value read back unchanged.\n\nWhen `isSimplesNacional` is `false` in an environment, the `taxConfiguration` of that environment must carry `taxClassification`, `operationIndicatorCode` and `nationalTaxCode`. The value of `isSimplesNacional` in `productionProperties` is the one registered with the tax provider. The tax issuer must be active.\n\nIf the tax provider rejects the request, the error is returned with the provider's error `code` and a status of 400, 409, 422 or 502." }, "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.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "homologationProperties": { "type": "object", "properties": { "specialTaxCode": { "type": "integer", "description": "Code of the special taxation regime of your city: the `id` of one of the regimes `GET /taxCode/{specialTaxCode}` lists. Send it as the integer or as the string `GET` returns.", "example": 1 }, "municipalServiceCode": { "type": "string", "minLength": 1, "description": "Municipal service code, as your city hall defines it for the service you provide.", "example": "0107" }, "serviceListItem": { "type": "string", "minLength": 1, "description": "Item of the federal service list (LC 116/2003) that describes your service, such as `1.07`.", "example": "1.07" }, "issTax": { "type": "number", "description": "ISS (municipal service tax) rate in percent: `2.5` means 2.5%. Rounded to 2 decimal places.", "example": 2.5 }, "serviceDescription": { "type": "string", "minLength": 1, "description": "Description of the service you provide.", "example": "Licenciamento de software como serviço (SaaS)" }, "hasCulturalIncentive": { "type": "boolean", "description": "Whether your organization is a cultural incentivizer (`incentivador cultural`).", "example": false }, "isSimplesNacional": { "type": "boolean", "description": "Whether your organization is under the Simples Nacional tax regime. When `false`, `taxConfiguration` is required with `taxClassification`, `operationIndicatorCode` and `nationalTaxCode`, otherwise the request fails with `TAX_CONFIGURATION_INCOMPLETE`.", "example": true }, "nfeSequencialCode": { "type": "integer", "description": "RPS (provisional service receipt) number the tax provider continues from in the test environment. Integer. It RESETS the numbering: send the number your city hall expects next — the value in Get your tax issuer is the one set last, not the current one.", "example": 1 }, "nfeSeries": { "type": "string", "minLength": 1, "maxLength": 5, "description": "Series of the RPS issued in the test environment. Up to 5 characters.", "example": "1" }, "nfeSequencialBatch": { "type": "integer", "description": "RPS batch number the tax provider continues from in the test environment. Integer. It resets the batch numbering, like `nfeSequencialCode`.", "example": 1 }, "cnae": { "type": "integer", "description": "CNAE subclass code of your main activity. It must be an existing CNAE code, otherwise the request fails with `CNAE_NOT_FOUND`. Send it as the integer or as the string.", "example": 6201501 }, "taxConfiguration": { "description": "National NFSe tax fields of the LC 214/2025 reform. Required when `isSimplesNacional` is `false`. When omitted, the stored value is kept; when sent, it replaces the stored one.", "type": "object", "properties": { "nbsCode": { "description": "NBS code (`Nomenclatura Brasileira de Serviços`) of your service. Optional.", "example": "115090000", "type": "string" }, "nationalTaxCode": { "description": "National tax code (`código de tributação nacional`) of your service. Required when `isSimplesNacional` is `false`.", "example": "010701", "type": "string" }, "taxClassification": { "description": "Tax classification (`classificação tributária`) of the operation. Required when `isSimplesNacional` is `false`.", "example": "000001", "type": "string" }, "operationIndicatorCode": { "description": "Operation indicator (`indicador de operação`) code. Required when `isSimplesNacional` is `false`.", "example": "100301", "type": "string" } }, "additionalProperties": false } }, "required": [ "specialTaxCode", "municipalServiceCode", "serviceListItem", "issTax", "serviceDescription", "hasCulturalIncentive", "isSimplesNacional", "nfeSequencialCode", "nfeSeries", "nfeSequencialBatch", "cnae" ], "additionalProperties": false, "description": "Configuration of the test (homologation) environment: documents issued here have no fiscal value. Replaces the stored configuration, so send every field." }, "productionProperties": { "type": "object", "properties": { "specialTaxCode": { "type": "integer", "description": "Code of the special taxation regime of your city: the `id` of one of the regimes `GET /taxCode/{specialTaxCode}` lists. Send it as the integer or as the string `GET` returns.", "example": 1 }, "municipalServiceCode": { "type": "string", "minLength": 1, "description": "Municipal service code, as your city hall defines it for the service you provide.", "example": "0107" }, "serviceListItem": { "type": "string", "minLength": 1, "description": "Item of the federal service list (LC 116/2003) that describes your service, such as `1.07`.", "example": "1.07" }, "issTax": { "type": "number", "description": "ISS (municipal service tax) rate in percent: `2.5` means 2.5%. Rounded to 2 decimal places.", "example": 2.5 }, "serviceDescription": { "type": "string", "minLength": 1, "description": "Description of the service you provide.", "example": "Licenciamento de software como serviço (SaaS)" }, "hasCulturalIncentive": { "type": "boolean", "description": "Whether your organization is a cultural incentivizer (`incentivador cultural`).", "example": false }, "isSimplesNacional": { "type": "boolean", "description": "Whether your organization is under the Simples Nacional tax regime. When `false`, `taxConfiguration` is required with `taxClassification`, `operationIndicatorCode` and `nationalTaxCode`, otherwise the request fails with `TAX_CONFIGURATION_INCOMPLETE`. The value you send here is also the one registered with the tax provider.", "example": true }, "nfeSequencialCode": { "type": "integer", "description": "RPS (provisional service receipt) number the tax provider continues from in the live environment. Integer. It RESETS the numbering: send the number your city hall expects next — the value in Get your tax issuer is the one set last, not the current one.", "example": 1 }, "nfeSeries": { "type": "string", "minLength": 1, "maxLength": 5, "description": "Series of the RPS issued in the live environment. Up to 5 characters.", "example": "1" }, "nfeSequencialBatch": { "type": "integer", "description": "RPS batch number the tax provider continues from in the live environment. Integer. It resets the batch numbering, like `nfeSequencialCode`.", "example": 1 }, "cnae": { "type": "integer", "description": "CNAE subclass code of your main activity. It must be an existing CNAE code, otherwise the request fails with `CNAE_NOT_FOUND`. Send it as the integer or as the string.", "example": 6201501 }, "taxConfiguration": { "description": "National NFSe tax fields of the LC 214/2025 reform. Required when `isSimplesNacional` is `false`. When omitted, the stored value is kept; when sent, it replaces the stored one.", "type": "object", "properties": { "nbsCode": { "description": "NBS code (`Nomenclatura Brasileira de Serviços`) of your service. Optional.", "example": "115090000", "type": "string" }, "nationalTaxCode": { "description": "National tax code (`código de tributação nacional`) of your service. Required when `isSimplesNacional` is `false`.", "example": "010701", "type": "string" }, "taxClassification": { "description": "Tax classification (`classificação tributária`) of the operation. Required when `isSimplesNacional` is `false`.", "example": "000001", "type": "string" }, "operationIndicatorCode": { "description": "Operation indicator (`indicador de operação`) code. Required when `isSimplesNacional` is `false`.", "example": "100301", "type": "string" } }, "additionalProperties": false } }, "required": [ "specialTaxCode", "municipalServiceCode", "serviceListItem", "issTax", "serviceDescription", "hasCulturalIncentive", "isSimplesNacional", "nfeSequencialCode", "nfeSeries", "nfeSequencialBatch", "cnae" ], "additionalProperties": false, "description": "Configuration of the live (production) environment: documents issued here are legally valid. Replaces the stored configuration, so send every field." } }, "required": [ "homologationProperties", "productionProperties" ], "additionalProperties": false } } } }, "responses": { "204": { "description": "No Content. The operation succeeded and the response has no body." }, "400": { "description": "`TAX_CONFIGURATION_INCOMPLETE` — `isSimplesNacional` is `false` in an environment whose `taxConfiguration` is missing, or lacks `taxClassification`, `operationIndicatorCode` or `nationalTaxCode`.\n\n`TAX_ISSUER_PROVIDER_ID_NOT_FOUND` — The tax issuer is not registered with the tax provider yet.", "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": [ "TAX_CONFIGURATION_INCOMPLETE", "TAX_ISSUER_PROVIDER_ID_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_CONFIGURATION_INCOMPLETE", "origin": "ACCOUNTING", "message": "The fields `Tax Situation` and `Tax Classification` are mandatory for issuers that are not of the `Simples Nacional` type. The fields `codigoTributacaoNacional` and `codigoNBS` are optional." } } } }, "403": { "description": "`TAX_ISSUER_INACTIVE` — The tax issuer is not active.", "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": [ "TAX_ISSUER_INACTIVE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_ISSUER_INACTIVE", "origin": "ACCOUNTING", "message": "Tax issuer is deactivated. You do not have permission to perform this action." } } } }, "404": { "description": "`TAX_ISSUER_NOT_FOUND` — The organization has no tax issuer.\n\n`ORGANIZATION_NOT_FOUND` — The organization does not exist in your realm.\n\n`CNAE_NOT_FOUND` — The `cnae` of an environment is not an existing CNAE code.\n\n`ISSUER_PROPERTIES_NOT_FOUND` — The tax issuer is missing its test or its live configuration.", "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": [ "TAX_ISSUER_NOT_FOUND", "ORGANIZATION_NOT_FOUND", "CNAE_NOT_FOUND", "ISSUER_PROPERTIES_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_ISSUER_NOT_FOUND", "origin": "ACCOUNTING", "message": "Tax issuer not found" } } } }, "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": [ "ACCOUNTING" ], "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": "ACCOUNTING", "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.", "fields": [ { "field": "homologationProperties", "message": "Invalid input: expected object, received undefined", "code": "HOMOLOGATIONPROPERTIES_REQUIRED" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.transform(…)` constraint not represented (runtime-dependent value)" } }, "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdTaxIssuer", "summary": "Create your tax issuer", "tags": [ "Tax Issuers" ], "x-p3-sidebar-order": 2, "description": "Creates the tax issuer of the organization: the registration that lets it issue service invoices (NFSe).", "x-mint": { "content": "The CNPJ, legal name, address and phone of the organization are taken from its registration in Portão 3 and registered with the tax provider, together with the service data you send. Two configurations are created: `nfseHomologationConfigurations` for the `TEST` (homologation) environment, where documents have no fiscal value, and `nfseProductionConfigurations` for the `LIVE` (production) environment. Each has its own RPS numbering. Then upload your digital certificate, which cities generally require to issue invoices.\n\nWhen `isSimplesNacional` is `false`, the `taxConfiguration` of the live configuration is required and must carry `taxClassification` and `operationIndicatorCode`. The test configuration is not checked.\n\nAn organization has one active tax issuer: creating another answers 409. One you deactivated can be replaced by a new one.\n\nIf the tax provider rejects the request, the error is returned with the provider's error `code` and a status of 400, 409, 422 or 502." }, "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.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "specialTaxCode": { "type": "string", "minLength": 1, "maxLength": 2, "description": "Code of the special taxation regime of the city where your organization is registered: the `id` of one of the regimes `GET /taxCode/{specialTaxCode}` lists for that city. One or two characters.", "example": "1" }, "municipalServiceCode": { "type": "string", "minLength": 1, "maxLength": 4, "description": "Municipal service code, as your city hall defines it for the service you provide. Up to 4 characters. Used on every invoice that does not send its own.", "example": "0107" }, "serviceListItem": { "description": "Item of the federal service list (LC 116/2003) that describes your service, such as `1.07`. Up to 8 characters. Optional here, but required when you update the issuer. Used on every invoice that does not send its own.", "example": "1.07", "type": "string", "maxLength": 8 }, "cnae": { "type": "string", "minLength": 1, "maxLength": 10, "description": "CNAE subclass code of your main activity. It must be an existing CNAE code, otherwise the request fails with `CNAE_NOT_FOUND`. Used on every invoice that does not send its own.", "example": "6201501" }, "issTax": { "type": "number", "description": "ISS (municipal service tax) rate in percent: `2.5` means 2.5%. Rounded to 2 decimal places. Used on every invoice that does not send its own.", "example": 2.5 }, "serviceDescription": { "type": "string", "minLength": 1, "maxLength": 1500, "description": "Description of the service you provide. Up to 1500 characters.", "example": "Licenciamento de software como serviço (SaaS)" }, "hasCulturalIncentive": { "type": "boolean", "description": "Whether your organization is a cultural incentivizer (`incentivador cultural`).", "example": false }, "isSimplesNacional": { "type": "boolean", "description": "Whether your organization is under the Simples Nacional tax regime. When `false`, the live (production) `taxConfiguration` must carry `taxClassification` and `operationIndicatorCode`, otherwise the request fails with `TAX_CONFIGURATION_INCOMPLETE`.", "example": true }, "nfseHomologationConfigurations": { "type": "object", "properties": { "nfeSequencialCode": { "type": "integer", "description": "Number of the next RPS (provisional service receipt) issued in the test environment. Integer.", "example": 1 }, "nfeSeries": { "type": "string", "minLength": 1, "maxLength": 5, "description": "Series of the RPS issued in the test environment. Up to 5 characters.", "example": "1" }, "nfeSequencialBatch": { "type": "integer", "description": "Number of the next RPS batch sent in the test environment. Integer.", "example": 1 }, "taxConfiguration": { "description": "National NFSe tax fields of the LC 214/2025 reform for the test environment. The rules for `isSimplesNacional` `false` are checked on the live (production) configuration only; send the same values here so your tests are faithful.", "type": "object", "properties": { "nbsCode": { "description": "NBS code (`Nomenclatura Brasileira de Serviços`) of your service. Optional.", "example": "115090000", "type": "string" }, "nationalTaxCode": { "description": "National tax code (`código de tributação nacional`) of your service. Not required to create the issuer, but issuing an invoice or updating the issuer requires it when `isSimplesNacional` is `false`.", "example": "010701", "type": "string" }, "taxClassification": { "description": "Tax classification (`classificação tributária`) of the operation. Required for the live (production) configuration when `isSimplesNacional` is `false`.", "example": "000001", "type": "string" }, "operationIndicatorCode": { "description": "Operation indicator (`indicador de operação`) code. Required for the live (production) configuration when `isSimplesNacional` is `false`.", "example": "100301", "type": "string" } }, "additionalProperties": false } }, "required": [ "nfeSequencialCode", "nfeSeries", "nfeSequencialBatch" ], "additionalProperties": false, "description": "Configuration of the test (homologation) environment: documents issued here have no fiscal value." }, "nfseProductionConfigurations": { "type": "object", "properties": { "nfeSequencialCode": { "type": "integer", "minimum": 1, "description": "Number of the next RPS (provisional service receipt) issued in the live environment. Integer, at least 1: send the number your city hall expects next.", "example": 1 }, "nfeSeries": { "type": "string", "minLength": 1, "maxLength": 5, "pattern": "^\\d+$", "description": "Series of the RPS issued in the live environment. Digits only, up to 5.", "example": "1" }, "nfeSequencialBatch": { "type": "integer", "description": "Number of the next RPS batch sent in the live environment. Integer.", "example": 1 }, "taxConfiguration": { "description": "National NFSe tax fields of the LC 214/2025 reform for the live environment. Required when `isSimplesNacional` is `false`: `taxClassification` and `operationIndicatorCode` must be set, otherwise the request fails with `TAX_CONFIGURATION_INCOMPLETE`.", "type": "object", "properties": { "nbsCode": { "description": "NBS code (`Nomenclatura Brasileira de Serviços`) of your service. Optional.", "example": "115090000", "type": "string" }, "nationalTaxCode": { "description": "National tax code (`código de tributação nacional`) of your service. Not required to create the issuer, but issuing an invoice or updating the issuer requires it when `isSimplesNacional` is `false`.", "example": "010701", "type": "string" }, "taxClassification": { "description": "Tax classification (`classificação tributária`) of the operation. Required when `isSimplesNacional` is `false`.", "example": "000001", "type": "string" }, "operationIndicatorCode": { "description": "Operation indicator (`indicador de operação`) code. Required when `isSimplesNacional` is `false`.", "example": "100301", "type": "string" } }, "additionalProperties": false } }, "required": [ "nfeSequencialCode", "nfeSeries", "nfeSequencialBatch" ], "additionalProperties": false, "description": "Configuration of the live (production) environment: documents issued here are legally valid." } }, "required": [ "specialTaxCode", "municipalServiceCode", "cnae", "issTax", "serviceDescription", "hasCulturalIncentive", "isSimplesNacional", "nfseHomologationConfigurations", "nfseProductionConfigurations" ], "additionalProperties": false } } } }, "responses": { "204": { "description": "No Content. The operation succeeded and the response has no body." }, "400": { "description": "`TAX_CONFIGURATION_INCOMPLETE` — `isSimplesNacional` is `false` and the live `taxConfiguration` is missing, or lacks `taxClassification` or `operationIndicatorCode`.\n\n`INTEGRATION_ERROR` — The tax provider registered the issuer but did not activate it, so it cannot be used. Fix the data and create it again.", "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": [ "TAX_CONFIGURATION_INCOMPLETE", "INTEGRATION_ERROR" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_CONFIGURATION_INCOMPLETE", "origin": "ACCOUNTING", "message": "The fields `Tax Situation` and `Tax Classification` are mandatory for issuers that are not of the `Simples Nacional` type. The fields `codigoTributacaoNacional` and `codigoNBS` are optional." } } } }, "404": { "description": "`CNAE_NOT_FOUND` — `cnae` is not an existing CNAE code.\n\n`ORGANIZATION_NOT_FOUND` — The organization does not exist in your realm.", "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": [ "CNAE_NOT_FOUND", "ORGANIZATION_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "CNAE_NOT_FOUND", "origin": "ACCOUNTING", "message": "Cnae not found" } } } }, "409": { "description": "`TAX_ISSUER_CONFLICT` — The organization already has an active tax issuer.", "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": [ "TAX_ISSUER_CONFLICT" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_ISSUER_CONFLICT", "origin": "ACCOUNTING", "message": "Tax issuer already exists" } } } }, "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": [ "ACCOUNTING" ], "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": "ACCOUNTING", "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.", "fields": [ { "field": "specialTaxCode", "message": "Invalid input: expected string, received undefined", "code": "SPECIALTAXCODE_REQUIRED" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.transform(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/tax-issuer/{taxIssuer}/secrets": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdTaxIssuerByTaxIssuerSecrets", "summary": "Upload your digital certificate", "tags": [ "Tax Issuers" ], "x-p3-sidebar-order": 5, "description": "Uploads the digital certificate your organization uses to sign its service invoices (NFSe).", "x-mint": { "content": "Send the certificate as `multipart/form-data`: the file in the part `file` and its password in the part `pwsCertificate`. It is your organization's ICP-Brasil A1 certificate (a `.pfx` or `.p12` file of up to 1 MB), which signs each NFSe at the city hall. One certificate serves both the `TEST` and the `LIVE` environment, and uploading a new one replaces the previous. Once it is uploaded, `hasCertificate` is `true` on Get your tax issuer.\n\nIf the tax provider rejects the request, the error is returned with the provider's error `code` and a status of 400, 409, 422 or 502." }, "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.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "taxIssuer", "in": "path", "required": true, "description": "ID of your tax issuer — the `id` returned by Get your tax issuer.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "9b2f4c1e-7a3d-4e8b-b6f0-2d5c8a1e3f47" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Your digital certificate (ICP-Brasil A1), as a `multipart/form-data` file part. It must be a `.pfx` or `.p12` file (or be sent with the content type `application/x-pkcs12` or `application/pkcs12`) of up to 1 MB (1,048,576 bytes)." }, "pwsCertificate": { "type": "string", "minLength": 1, "description": "Password of the certificate file.", "example": "your-certificate-password" } }, "required": [ "file", "pwsCertificate" ], "additionalProperties": false } } } }, "responses": { "204": { "description": "No Content. The operation succeeded and the response has no body." }, "400": { "description": "`TAX_ISSUER_PROVIDER_ID_NOT_FOUND` — Your tax issuer is not registered with the tax provider yet.", "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": [ "TAX_ISSUER_PROVIDER_ID_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_ISSUER_PROVIDER_ID_NOT_FOUND", "origin": "ACCOUNTING", "message": "Tax issuer provider id not exists" } } } }, "404": { "description": "`TAX_ISSUER_NOT_FOUND` — No tax issuer 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": [ "TAX_ISSUER_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_ISSUER_NOT_FOUND", "origin": "ACCOUNTING", "message": "Tax issuer not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID, or the `file` part is missing, is not a `.pfx` or `.p12` certificate or is larger than 1 MB, or the `pwsCertificate` part is missing; `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": [ "ACCOUNTING" ], "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": "ACCOUNTING", "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.", "fields": [ { "field": "file", "message": "file is required", "code": "FILE_REQUIRED" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/tax-issuer/{taxIssuer}/logotype": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdTaxIssuerByTaxIssuerLogotype", "summary": "Upload your logo", "tags": [ "Tax Issuers" ], "x-p3-sidebar-order": 6, "description": "Uploads the logo printed on your service invoices (NFSe).", "x-mint": { "content": "Send the image as `multipart/form-data`, in the part `file`. The logo is printed on the NFSe PDF, so it must be a PNG or a JPEG (content type `image/png` or `image/jpeg`) of up to 1 MB. Uploading a new logo replaces the previous one.\n\nIf the tax provider rejects the request, the error is returned with the provider's error `code` and a status of 400, 409, 422 or 502." }, "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.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "taxIssuer", "in": "path", "required": true, "description": "ID of your tax issuer — the `id` returned by Get your tax issuer.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "9b2f4c1e-7a3d-4e8b-b6f0-2d5c8a1e3f47" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Your logo image, as a `multipart/form-data` file part. It must be a PNG or a JPEG (content type `image/png` or `image/jpeg`) of up to 1 MB (1,048,576 bytes)." } }, "required": [ "file" ], "additionalProperties": false } } } }, "responses": { "204": { "description": "No Content. The operation succeeded and the response has no body." }, "400": { "description": "`TAX_ISSUER_PROVIDER_ID_NOT_FOUND` — Your tax issuer is not registered with the tax provider yet.", "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": [ "TAX_ISSUER_PROVIDER_ID_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_ISSUER_PROVIDER_ID_NOT_FOUND", "origin": "ACCOUNTING", "message": "Tax issuer provider id not exists" } } } }, "404": { "description": "`TAX_ISSUER_NOT_FOUND` — No tax issuer 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": [ "TAX_ISSUER_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_ISSUER_NOT_FOUND", "origin": "ACCOUNTING", "message": "Tax issuer not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID, or the `file` part is missing, is not a PNG or JPEG image, or is larger than 1 MB; `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": [ "ACCOUNTING" ], "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": "ACCOUNTING", "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.", "fields": [ { "field": "file", "message": "file is required", "code": "FILE_REQUIRED" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/tax-document": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdTaxDocument", "summary": "List tax documents", "tags": [ "Tax Documents (NFSe)" ], "x-p3-sidebar-order": 1, "description": "Lists the tax documents (NFSe) of your organization, newest first.", "x-mint": { "content": "This is where you follow a document you issued: it appears with the status `WAITINGFORAUTHORIZATION` and moves on its own to `AUTHORIZED` or `DENIED`. Each item carries the `externalId` you sent when you issued it, so you can match it to your own record. Amounts are in reais.\n\nEvery filter is optional, and the filters you send combine: a document must match all of them. Send `status` and `type` as a comma-separated list (`status=AUTHORIZED,DENIED`) or by repeating the parameter. `customerName` matches any part of the customer's name, ignoring case, while `customerDocument` must match the whole CPF or CNPJ as it was written at issuance (your value is also tried without punctuation). Without `environment`, real (`LIVE`) and homologation (`TEST`) documents are listed together.\n\nDates compare full timestamps in UTC, so a date without a time (`2026-10-31`) means 00:00 UTC. To include the whole last day of a range, send the end bound as `2026-10-31T23:59:59.999Z`.\n\nResults are paginated, newest first, 50 per page unless you send `limit` (1 to 100). 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 tax documents you want to list.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "status", "in": "query", "required": false, "description": "Only documents in one of these statuses. Send several as a comma-separated list or by repeating the parameter. Matched case-insensitively.\n\n---\n\nExample (comma-separated list): `?status=AUTHORIZED,DENIED`", "schema": { "type": "array", "items": { "type": "string", "enum": [ "WAITINGFORAUTHORIZATION", "REQUESTINGAUTHORIZATION", "AUTHORIZATIONREQUESTED", "AUTHORIZATIONPROCESS", "AWAITINGFILEGENERATION", "AUTHORIZED", "DENIED", "REQUESTINGCANCELLATION", "CANCELLATIONREQUESTED", "CANCELLATIONPROCESS", "AWAITINGFILECANCELATION", "CANCELED", "CANCELLATIONDENIED" ] } }, "style": "form", "explode": false }, { "name": "type", "in": "query", "required": false, "description": "Only documents of one of these types. Send several as a comma-separated list or by repeating the parameter. Matched case-insensitively.\n\n---\n\nExample: `?type=NFSE`", "schema": { "type": "array", "items": { "type": "string", "enum": [ "NFSE" ] } }, "style": "form", "explode": false }, { "name": "environment", "in": "query", "required": false, "description": "`LIVE` for real documents, `TEST` for homologation documents (no fiscal value). Omit to list both.", "schema": { "type": "string", "enum": [ "LIVE", "TEST" ] }, "example": "LIVE" }, { "name": "issuedAtStart", "in": "query", "required": false, "description": "Only documents issued on or after this moment. A date without a time (`2026-10-01`) means 00:00 UTC.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00.000Z" }, { "name": "issuedAtEnd", "in": "query", "required": false, "description": "Only documents issued on or before this moment. Must not be before `issuedAtStart`. To include a whole day, send `T23:59:59.999Z` of that day.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-31T23:59:59.999Z" }, { "name": "competenceDateStart", "in": "query", "required": false, "description": "Only documents whose competence date is on or after this moment. A date without a time means 00:00 UTC.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00.000Z" }, { "name": "competenceDateEnd", "in": "query", "required": false, "description": "Only documents whose competence date is on or before this moment. Must not be before `competenceDateStart`. To include a whole day, send `T23:59:59.999Z` of that day.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-31T23:59:59.999Z" }, { "name": "rpsNumberStart", "in": "query", "required": false, "description": "Only documents whose RPS number is greater than or equal to this one.", "schema": { "type": "number" }, "example": 1000 }, { "name": "rpsNumberEnd", "in": "query", "required": false, "description": "Only documents whose RPS number is less than or equal to this one. Must not be less than `rpsNumberStart`.", "schema": { "type": "number" }, "example": 1100 }, { "name": "customerName", "in": "query", "required": false, "description": "Only documents whose customer name contains this text (case-insensitive).", "schema": { "type": "string", "maxLength": 200 }, "example": "acme" }, { "name": "customerDocument", "in": "query", "required": false, "description": "Only documents of the customer with this CPF or CNPJ. An exact match, not a partial one, against the document as it was written when the tax document was issued: your value is tried as you send it and also with its punctuation removed.", "schema": { "type": "string", "maxLength": 20 }, "example": "12345678000195" }, { "name": "next", "in": "query", "required": false, "description": "Cursor returned as `next` by the previous page. Omit for the first page; a value you did not get from the API is rejected.", "schema": { "type": "string" }, "example": "68a7c1f2a3b4c5d6e7f80912" }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "example": 20 } ], "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 tax document.", "example": "3d6f9a2b-1c4e-4f8a-9b7d-5e2c1a0f8b63", "format": "uuid" }, "realm": { "type": "string", "description": "ID of the realm the document belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization the document belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "taxIssuer": { "type": "string", "description": "ID of the tax issuer that issued the document.", "example": "9b2f4c1e-7a3d-4e8b-b6f0-2d5c8a1e3f47", "format": "uuid" }, "environment": { "type": "string", "enum": [ "LIVE", "TEST" ], "description": "`LIVE` for a real document, `TEST` for a homologation document with no fiscal value.", "example": "LIVE" }, "rpsNumber": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "Number of the RPS (provisional service receipt). A number once it has been assigned, and an empty string (`\"\"`) before that.", "example": 1042 }, "rpsSeries": { "type": "string", "description": "Series of the RPS. An empty string (`\"\"`) until it has been assigned.", "example": "1" }, "nfseNumber": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "Number of the NFSe given by the city hall. A number once the document is `AUTHORIZED`, and an empty string (`\"\"`) before that.", "example": 2874 }, "type": { "type": "string", "enum": [ "NFSE" ], "description": "Type of the document.", "example": "NFSE" }, "competenceDate": { "type": "string", "description": "Competence date of the document.", "example": "2026-10-01T00:00:00.000Z", "format": "date-time" }, "customer": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PERSON", "COMPANY" ], "description": "Whether the customer is a person (CPF) or a company (CNPJ).", "example": "COMPANY" }, "name": { "type": "string", "description": "Name of the customer.", "example": "Acme Tecnologia Ltda" }, "email": { "type": "string", "description": "E-mail of the customer.", "example": "financeiro@acme.com.br" }, "federalDocument": { "type": "string", "description": "CPF or CNPJ of the customer, as it was sent when the document was issued (digits only or with punctuation).", "example": "12345678000195" }, "municipalDocument": { "type": "string", "description": "Municipal registration (inscrição municipal) of the customer.", "example": "123456" }, "stateDocument": { "type": "string", "description": "State registration (inscrição estadual) of the customer.", "example": "123456789" }, "phone": { "type": "string", "description": "Phone of the customer in E.164 format. Omitted when none was sent.", "example": "+5534991234567" }, "addressStateCode": { "type": "number", "description": "IBGE code of the customer's state.", "example": 31 }, "addressCityCode": { "type": "number", "description": "IBGE code of the customer's city.", "example": 3170206 }, "addressState": { "type": "string", "description": "State of the customer's address (two letters).", "example": "MG" }, "addressCity": { "type": "string", "description": "City of the customer's address.", "example": "Uberlândia" }, "addressStreet": { "type": "string", "description": "Street of the customer's address.", "example": "Avenida João Naves de Ávila" }, "addressNumber": { "type": "string", "description": "Number of the customer's address.", "example": "2121" }, "addressComplement": { "type": "string", "description": "Complement of the customer's address.", "example": "Sala 101" }, "addressNeighbourhood": { "type": "string", "description": "Neighbourhood of the customer's address.", "example": "Santa Mônica" }, "addressPostalCode": { "type": "string", "description": "Postal code (CEP) of the customer's address.", "example": "38408100" } }, "description": "The customer (service taker) of the document. An empty object when there is none." }, "service": { "type": "object", "properties": { "serviceProvisionState": { "type": "string", "description": "State where the service was provided (two letters).", "example": "MG" }, "serviceProvisionCity": { "type": "string", "description": "City where the service was provided.", "example": "Uberlândia" }, "description": { "type": "string", "description": "Description of the service, printed on the document.", "example": "Licenciamento de software (SaaS)" }, "issRate": { "type": "number", "description": "ISS rate, as a percentage (`2` means 2%).", "example": 2 }, "issWithheldAtSource": { "type": "boolean", "description": "Whether the ISS is withheld at source by the customer.", "example": false }, "serviceMunicipalCode": { "type": "string", "description": "Municipal service code, as defined by the city hall.", "example": "0107" }, "serviceMunicipalDescription": { "type": "string", "description": "Description of the municipal service code.", "example": "Licenciamento ou cessão de direito de uso de programas de computação." }, "serviceListItemLC116": { "type": "string", "description": "Item of the LC 116 service list.", "example": "1.05" }, "cnae": { "type": "string", "description": "CNAE (national classification of economic activities) code.", "example": "6201501" }, "cofinsAmount": { "type": "number", "description": "COFINS amount, in reais.", "example": 0 }, "csllAmount": { "type": "number", "description": "CSLL amount, in reais.", "example": 0 }, "inssAmount": { "type": "number", "description": "INSS amount, in reais.", "example": 0 }, "irAmount": { "type": "number", "description": "IR amount, in reais.", "example": 0 }, "pisAmount": { "type": "number", "description": "PIS amount, in reais.", "example": 0 }, "taxConfiguration": { "type": "object", "properties": { "nbsCode": { "type": "string", "description": "NBS code (Nomenclatura Brasileira de Serviços) of the service.", "example": "115090000" }, "nationalTaxCode": { "type": "string", "description": "National tax code of the service.", "example": "010701" }, "taxClassification": { "type": "string", "description": "Tax classification applied to the operation.", "example": "000001" }, "operationIndicatorCode": { "type": "string", "description": "Operation indicator code.", "example": "100301" } }, "description": "Tax configuration applied to the service. An empty object when none was sent or defaulted." } }, "description": "The service the document bills. An empty object when there is none." }, "operationNature": { "type": "string", "description": "Nature of the operation, as sent when the document was issued.", "example": "Prestação de Serviços" }, "deductions": { "type": "number", "description": "Deductions, in reais.", "example": 0 }, "discounts": { "type": "number", "description": "Discounts, in reais.", "example": 0 }, "totalValue": { "type": "number", "description": "Total value of the document, in reais.", "example": 1500.5 }, "status": { "type": "string", "enum": [ "WAITINGFORAUTHORIZATION", "REQUESTINGAUTHORIZATION", "AUTHORIZATIONREQUESTED", "AUTHORIZATIONPROCESS", "AWAITINGFILEGENERATION", "AUTHORIZED", "DENIED", "REQUESTINGCANCELLATION", "CANCELLATIONREQUESTED", "CANCELLATIONPROCESS", "AWAITINGFILECANCELATION", "CANCELED", "CANCELLATIONDENIED" ], "description": "Current status of the document. A document is created as `WAITINGFORAUTHORIZATION` and moves on its own: the authorization states (`REQUESTINGAUTHORIZATION`, `AUTHORIZATIONREQUESTED`, `AUTHORIZATIONPROCESS`, `AWAITINGFILEGENERATION`) end in `AUTHORIZED` or `DENIED`; after you cancel it, the cancellation states (`REQUESTINGCANCELLATION`, `CANCELLATIONREQUESTED`, `CANCELLATIONPROCESS`, `AWAITINGFILECANCELATION`) end in `CANCELED` or `CANCELLATIONDENIED`.", "example": "AUTHORIZED" }, "errorMessage": { "type": "string", "description": "Reason the tax provider or the city hall gave when the document was denied. An empty string (`\"\"`) when there is none.", "example": "" }, "observation": { "type": "string", "description": "Free text printed on the document. Omitted when none was sent.", "example": "Referente ao contrato 1234" }, "issuedAt": { "type": "string", "description": "When the document was issued, that is, when your request created it.", "example": "2026-10-01T13:45:12.000Z", "format": "date-time" }, "issuedBy": { "type": "string", "description": "ID of the user, or of the API client, that issued the document.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99" }, "externalId": { "type": "string", "description": "The `externalId` you sent when you issued the document. Omitted when you sent none.", "example": "6f1b7c52-8a4e-4d3f-9c21-b0e5a7d84c19" } }, "required": [ "id", "realm", "organization", "taxIssuer", "environment", "rpsNumber", "rpsSeries", "nfseNumber", "type", "competenceDate", "customer", "service", "deductions", "discounts", "totalValue", "status", "errorMessage" ], "description": "A tax document (NFSe) of your organization." }, "description": "The tax documents of this page, newest first." }, "next": { "type": "string", "nullable": true, "description": "Cursor of the next page: send it as `next` to get the following page. `null` when this is the last page.", "example": "68a7c1f2a3b4c5d6e7f80912" } }, "required": [ "items", "next" ], "description": "A page of tax documents, newest first." } } } }, "404": { "description": "`TAX_ISSUER_NOT_FOUND` — The organization has no active tax issuer.\n\n`ORGANIZATION_NOT_FOUND` — The organization does not exist in your realm.", "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": [ "TAX_ISSUER_NOT_FOUND", "ORGANIZATION_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_ISSUER_NOT_FOUND", "origin": "ACCOUNTING", "message": "Tax issuer not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path or query parameter is invalid: an ID that is not a UUID, a `limit` outside 1 to 100, a `status` or `type` that does not exist, a `next` cursor you did not get from the API, or a range whose end is before its start; `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": [ "ACCOUNTING" ], "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": "ACCOUNTING", "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.", "fields": [ { "field": "environment", "message": "Invalid option: expected one of \"LIVE\"|\"TEST\"", "code": "ENVIRONMENT_ONE_OF" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed", "note": "`.superRefine(…)` constraint not represented (runtime-dependent value); `.refine(…)` constraint not represented (runtime-dependent value)" } }, "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdTaxDocument", "summary": "Issue a tax document", "tags": [ "Tax Documents (NFSe)" ], "x-p3-sidebar-order": 2, "description": "Issues a tax document (NFSe) for your organization.", "x-mint": { "content": "Issuance is asynchronous. The request answers `204` as soon as the tax provider has accepted the document, which is created with the status `WAITINGFORAUTHORIZATION` and later moves to `AUTHORIZED` or `DENIED`. Find it in List tax documents: each item carries the `externalId` you sent, and you can download its PDF and XML with Download a tax document once it is `AUTHORIZED`.\n\nSend `externalId` together with `externalParentId` (both or neither) to make the request safe to retry: while a document with that `externalId` exists and is not `DENIED` or `CANCELED`, issuing another one answers `409` `TAX_DOCUMENT_ALREADY_ISSUED`. Treat that answer as \"already issued\", not as a failure. After a `DENIED` or `CANCELED` document you can issue again with the same `externalId`.\n\nThe service code, CNAE and LC 116 item you omit are taken from the configuration of your tax issuer for the `environment` you choose. The NFSe is issued for `totalValue` with the ISS rate registered for your tax issuer; `issRate`, `deductions`, `discounts`, the place of service and the tax amounts you send are recorded with the document. Use `TEST` to issue homologation documents, which have no fiscal value. Every amount is in reais.\n\nIf the tax provider rejects the request, the error is returned with the provider's error `code` and a status of 400, 409, 422 or 502." }, "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 that issues the tax document.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "description": "Type of the document. `NFSE` is the only type, and the default.", "example": "NFSE", "type": "string", "enum": [ "NFSE" ] }, "environment": { "type": "string", "enum": [ "LIVE", "TEST" ], "description": "`LIVE` issues a real document. `TEST` issues a homologation document, which has no fiscal value. It also selects which configuration of your tax issuer fills in what you omit.", "example": "TEST" }, "competenceDate": { "description": "Competence date of the document: the date the service refers to. An ISO 8601 date or date-time.", "example": "2026-10-01T00:00:00.000Z", "type": "string", "format": "date-time" }, "operationNature": { "description": "Nature of the operation. It is stored with the document, but it is not printed on it.", "example": "Prestação de Serviços", "type": "string" }, "deductions": { "description": "Deductions, in reais (`150.5` is R$ 150.50). Recorded with the document; the NFSe is issued for `totalValue`.", "example": 0, "type": "number" }, "discounts": { "description": "Discounts, in reais (`150.5` is R$ 150.50). Recorded with the document; the NFSe is issued for `totalValue`.", "example": 0, "type": "number" }, "totalValue": { "description": "Total value of the document, in reais (`1500.5` is R$ 1,500.50).", "example": 1500.5, "type": "number" }, "observation": { "description": "Free text printed on the document.", "example": "Referente ao contrato 1234", "type": "string" }, "externalId": { "description": "Your own ID for what this document bills (an invoice, for example), a UUID v4. Send it together with `externalParentId`. While a document with this `externalId` exists and is not `DENIED` or `CANCELED`, issuing another one answers 409 `TAX_DOCUMENT_ALREADY_ISSUED`, so you can safely retry a request whose answer you lost. Each tax document you list carries it back as `externalId`.\n\nFormat: `UUID` (version 4)", "example": "6f1b7c52-8a4e-4d3f-9c21-b0e5a7d84c19", "type": "string", "format": "uuid" }, "externalParentId": { "description": "What `externalId` refers to: `INVOICE` or `INVOICE_STATEMENT`. Required when you send `externalId`, and not accepted without it.", "example": "INVOICE", "type": "string", "enum": [ "INVOICE", "INVOICE_STATEMENT" ] }, "taxDocumentCustomer": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PERSON", "COMPANY" ], "description": "`PERSON` for an individual (CPF), `COMPANY` for a legal entity (CNPJ).", "example": "COMPANY" }, "name": { "type": "string", "minLength": 1, "description": "Name of the customer.", "example": "Acme Tecnologia Ltda" }, "email": { "type": "string", "minLength": 1, "description": "E-mail of the customer.", "example": "financeiro@acme.com.br" }, "federalDocument": { "type": "string", "minLength": 1, "description": "CPF or CNPJ of the customer.", "example": "12345678000195" }, "municipalDocument": { "description": "Municipal registration (inscrição municipal) of the customer.", "example": "123456", "type": "string" }, "stateDocument": { "description": "State registration (inscrição estadual) of the customer.", "example": "123456789", "type": "string" }, "phone": { "description": "Phone of the customer, in E.164 format. An empty string is the same as not sending it.", "example": "+5534991234567", "type": "string" }, "addressState": { "type": "string", "minLength": 1, "description": "State of the customer's address, two letters.", "example": "MG" }, "addressCity": { "type": "string", "minLength": 1, "description": "City of the customer's address.", "example": "Uberlândia" }, "addressStreet": { "type": "string", "minLength": 1, "description": "Street of the customer's address.", "example": "Avenida João Naves de Ávila" }, "addressNumber": { "type": "string", "minLength": 1, "description": "Number of the customer's address.", "example": "2121" }, "addressComplement": { "description": "Complement of the customer's address. Only the first 30 characters are printed on the document.", "example": "Sala 101", "type": "string" }, "addressNeighbourhood": { "type": "string", "minLength": 1, "description": "Neighbourhood of the customer's address.", "example": "Santa Mônica" }, "addressPostalCode": { "type": "string", "minLength": 1, "description": "Postal code (CEP) of the customer's address.", "example": "38408100" } }, "required": [ "type", "name", "email", "federalDocument", "addressState", "addressCity", "addressStreet", "addressNumber", "addressNeighbourhood", "addressPostalCode" ], "additionalProperties": false, "description": "The customer (service taker) of the document." }, "taxDocumentServiceProperty": { "description": "The service the document bills. Send it: the state, the city, the description and the municipal description of the service have no default. The optional fields below fall back to your tax issuer's configuration for the environment.", "type": "object", "properties": { "serviceProvisionState": { "type": "string", "minLength": 1, "description": "State where the service was provided, two letters. Recorded with the document; it is not part of what is sent for issuance.", "example": "MG" }, "serviceProvisionCity": { "type": "string", "minLength": 1, "description": "City where the service was provided. Recorded with the document; it is not part of what is sent for issuance.", "example": "Uberlândia" }, "description": { "type": "string", "minLength": 1, "description": "Description of the service, printed on the document.", "example": "Licenciamento de software (SaaS)" }, "issRate": { "description": "ISS rate, as a percentage (`2` means 2%), recorded with the document. The NFSe itself is issued with the ISS rate registered for your tax issuer (`issTax`), not with this value. Omit it, or send 0, to record that configured rate.", "example": 2, "type": "number" }, "issWithheldAtSource": { "type": "boolean", "description": "Whether the customer withholds the ISS at source.", "example": false }, "serviceMunicipalCode": { "description": "Municipal service code. Omit it to use the one your tax issuer has configured for the environment.", "example": "0107", "type": "string" }, "serviceMunicipalDescription": { "type": "string", "minLength": 1, "description": "Description of the municipal service code.", "example": "Licenciamento ou cessão de direito de uso de programas de computação." }, "serviceListItemLC116": { "description": "Item of the LC 116 service list. Omit it to use the one your tax issuer has configured for the environment.", "example": "1.05", "type": "string" }, "cnae": { "description": "CNAE code, as a string. Omit it to use the one your tax issuer has configured for the environment.", "example": "6201501", "type": "string" }, "cofinsAmount": { "description": "COFINS amount, in reais. It is stored with the document.", "example": 0, "type": "number" }, "csllAmount": { "description": "CSLL amount, in reais. It is stored with the document.", "example": 0, "type": "number" }, "inssAmount": { "description": "INSS amount, in reais. It is stored with the document.", "example": 0, "type": "number" }, "irAmount": { "description": "IR amount, in reais. It is stored with the document.", "example": 0, "type": "number" }, "pisAmount": { "description": "PIS amount, in reais. It is stored with the document.", "example": 0, "type": "number" }, "taxConfiguration": { "description": "Tax configuration (tax-reform codes). When you send it, all four fields are required and not empty, and a partial object is rejected: do not forward a partial configuration, omit it instead. Omit it to use your tax issuer's configuration for the environment. If your tax issuer is not Simples Nacional, a tax classification and a national tax code must come from here or from that configuration, otherwise the request fails with `TAX_CONFIGURATION_INCOMPLETE`.", "type": "object", "properties": { "nbsCode": { "type": "string", "minLength": 1, "description": "NBS code (Nomenclatura Brasileira de Serviços) of the service.", "example": "115090000" }, "nationalTaxCode": { "type": "string", "minLength": 1, "description": "National tax code of the service.", "example": "010701" }, "taxClassification": { "type": "string", "minLength": 1, "description": "Tax classification applied to the operation.", "example": "000001" }, "operationIndicatorCode": { "type": "string", "minLength": 1, "description": "Operation indicator code.", "example": "100301" } }, "required": [ "nbsCode", "nationalTaxCode", "taxClassification", "operationIndicatorCode" ], "additionalProperties": false } }, "required": [ "serviceProvisionState", "serviceProvisionCity", "description", "issWithheldAtSource", "serviceMunicipalDescription" ], "additionalProperties": false } }, "required": [ "environment", "competenceDate", "taxDocumentCustomer" ], "additionalProperties": false } } } }, "responses": { "204": { "description": "No Content. The operation succeeded and the response has no body." }, "400": { "description": "`TAX_ISSUER_PROVIDER_ID_NOT_FOUND` — The tax issuer is not registered with the tax provider yet.\n\n`TAX_CONFIGURATION_INCOMPLETE` — The tax issuer is not Simples Nacional, and neither the request nor the tax issuer's configuration has a tax classification and a national tax code.", "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": [ "TAX_ISSUER_PROVIDER_ID_NOT_FOUND", "TAX_CONFIGURATION_INCOMPLETE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_ISSUER_PROVIDER_ID_NOT_FOUND", "origin": "ACCOUNTING", "message": "Tax issuer provider id not exists" } } } }, "404": { "description": "`TAX_ISSUER_NOT_FOUND` — The organization has no active tax issuer.\n\n`ISSUER_PROPERTIES_NOT_FOUND` — The tax issuer has no configuration for the `environment` you chose.", "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": [ "TAX_ISSUER_NOT_FOUND", "ISSUER_PROPERTIES_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_ISSUER_NOT_FOUND", "origin": "ACCOUNTING", "message": "Tax issuer not found" } } } }, "409": { "description": "`TAX_DOCUMENT_ALREADY_ISSUED` — A document with this `externalId` already exists and is not `DENIED` or `CANCELED`.", "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": [ "TAX_DOCUMENT_ALREADY_ISSUED" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_DOCUMENT_ALREADY_ISSUED", "origin": "ACCOUNTING", "message": "A tax document was already issued for this externalId" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID, the body is not a JSON object, or a field is missing or invalid, including an unknown field; `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": [ "ACCOUNTING" ], "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": "ACCOUNTING", "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.", "fields": [ { "field": "environment", "message": "Invalid option: expected one of \"LIVE\"|\"TEST\"", "code": "ENVIRONMENT_ONE_OF", "values": [ "LIVE", "TEST" ] } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.superRefine(…)` constraint not represented (runtime-dependent value); `.transform(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/tax-document/batch": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdTaxDocumentBatch", "summary": "Issue tax documents in batch", "tags": [ "Tax Documents (NFSe)" ], "x-p3-sidebar-order": 3, "description": "Issues a tax document (NFSe) for every row of an uploaded CSV file.", "x-mint": { "content": "Send a `multipart/form-data` request whose `file` part is a CSV file: comma-separated, with a header row and one row per tax document to issue. The header names are case-sensitive and the column order does not matter.\n\n| Column | Required | Meaning |\n|---|---|---|\n| `environment` | Yes | `LIVE` to issue a real tax document, `TEST` to issue a test one. Your tax issuer must be configured for that environment. |\n| `competenceDate` | Yes | Competence date of the service, for example `2026-10-31`. |\n| `totalValue` | Yes | Total value of the service in reais, for example `1500.50`. A comma is accepted as the decimal separator (`1500,50`); do not use thousands separators. |\n| `statementId` | Yes | ID of the invoice statement this tax document refers to. It is the idempotency key of the row: a statement that already has an active tax document is skipped. |\n| `customerName` | Yes | Name of the customer. |\n| `customerEmail` | Yes | E-mail address of the customer. |\n| `customerFederalDocument` | Yes | Federal document of the customer, digits only: the CNPJ (or the CPF). |\n| `customerMunicipalDocument` | No | Municipal registration of the customer. |\n| `customerstateDocument` | No | State registration of the customer. |\n| `customerphoneNumber` | Yes | Brazilian phone number of the customer with area code, for example `34984325252` or `+5534984325252`. A number that is not a valid Brazilian one is left off the tax document. |\n| `addressState` | Yes | State of the customer's address, for example `MG`. |\n| `addressCity` | Yes | City of the customer's address, for example `Uberlândia`. |\n| `addressStreet` | Yes | Street of the customer's address. |\n| `addressNumber` | Yes | Number of the customer's address. |\n| `addressComplement` | No | Complement of the customer's address. `N/A` is used when it is blank. |\n| `addressNeighborhood` | Yes | Neighborhood of the customer's address. |\n| `addressPostalCode` | Yes | Postal code (CEP) of the customer's address. |\n\nThe column names are exactly as listed, including the spelling of `customerstateDocument`, `customerphoneNumber` and `addressNeighborhood`. Any other column is rejected, and so is a row that misses a required column.\n\nEvery tax document is issued with fixed values. The customer is registered as a company, the service is provided in Uberlândia (MG), and its description is \"LICENCIAMENTO DE SOFTWARE - SAAS\". The document records an ISS rate of 2% (the NFSe itself is issued with the ISS rate registered for your tax issuer), not withheld at source. The municipal service description is \"Licenciamento ou cessão de direito de uso de programas de computação.\", the operation nature is \"Prestação de Serviços\", and there are no deductions, no discounts and no observation. The municipal service code, the service list item, the CNAE and the tax configuration come from your tax issuer's configuration for the row's `environment`.\n\nThe whole upload is validated first: if any row is invalid nothing is issued, and `fields` points at the row by its position, where `invoices[0]` is the first row after the header. When the upload is valid, the response only means the rows were accepted. Each row is then issued in the background, so a row can still fail later; a row whose statement already has an active tax document is skipped, which makes it safe to upload the same file again. A row the tax provider rejects for invalid data is skipped as well: fix its data and upload it again." }, "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.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The CSV file, with a header row and one row per tax document to issue. The columns are listed in the operation description. Required, not empty, at most 4 MB; its file name must end in `.csv`, or its content type be `text/csv`, `application/vnd.ms-excel` or `text/plain`." } }, "required": [ "file" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirms what was requested. It only means the rows were accepted, not that every document was already issued or cancelled.", "example": "Batch issuance requested." }, "count": { "type": "number", "description": "Number of CSV rows accepted for processing.", "example": 25 } }, "required": [ "message", "count" ], "description": "Acknowledgement that a CSV batch was accepted. Each row is processed in the background." } } } }, "400": { "description": "`TAX_ISSUER_PROVIDER_ID_NOT_FOUND` — The tax issuer is not registered with the tax provider yet.", "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": [ "TAX_ISSUER_PROVIDER_ID_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_ISSUER_PROVIDER_ID_NOT_FOUND", "origin": "ACCOUNTING", "message": "Tax issuer provider id not exists" } } } }, "404": { "description": "`TAX_ISSUER_NOT_FOUND` — The organization has no active tax issuer.\n\n`ISSUER_PROPERTIES_NOT_FOUND` — The tax issuer has no configuration for any environment.", "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": [ "TAX_ISSUER_NOT_FOUND", "ISSUER_PROPERTIES_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_ISSUER_NOT_FOUND", "origin": "ACCOUNTING", "message": "Tax issuer not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID, the request is not `multipart/form-data`, the `file` part is missing, empty, larger than 4 MB or not a readable CSV, or a row failed validation; `fields` lists each problem.", "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": [ "ACCOUNTING" ], "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": "ACCOUNTING", "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.", "fields": [ { "field": "file", "message": "file is required", "code": "FILE_REQUIRED" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/tax-document/download-batch": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdTaxDocumentDownloadBatch", "summary": "Download tax documents in batch", "tags": [ "Tax Documents (NFSe)" ], "x-p3-sidebar-order": 4, "description": "Bundles the XML or PDF files of several tax documents into one zip and returns a temporary download link.", "x-mint": { "content": "Say which documents to bundle with exactly one of `taxDocumentIds` and `filters`. With `taxDocumentIds` you choose the documents yourself; duplicate ids count once, and an id that is not one of your organization's is reported in `missing` as `NOT_FOUND`. With `filters` every document that matches is bundled, using the same filters as List tax documents (`environment` included); at least one filter is required, so an empty body is never read as \"everything\", and each range must end on or after its start.\n\n`type` chooses which file of each document goes in the zip: `XML` (the default) or `PDF`. A zip holds at most 1 000 XML files or 200 PDF files. A selection above the limit is rejected as a bad request, and a filter that matches more documents than the limit is rejected with `TAX_DOCUMENT_BATCH_DOWNLOAD_LIMIT_EXCEEDED`: narrow the filters, for example to a shorter date range, or select the documents yourself in smaller groups.\n\nThe zip has one file per document, named by its NFSe number (`NFSe-1042.xml`), or by its RPS number (`RPS-1-1042.xml`) before it is authorized, or by its ID. Test-environment documents are prefixed with `HOMOLOGACAO-`, and when two documents would share a name the document's ID is appended. It also holds `manifest.csv`, which lists every requested or matched document with its file name, IDs, NFSe and RPS numbers, status, environment, dates, customer, total value in reais and, for the ones left out, the reason.\n\nA document that has no file of the requested type yet, for example because it is not authorized yet, does not fail the request: it is left out of the zip and listed in `missing` with the reason `FILE_NOT_AVAILABLE`. The request fails only when no document has a file to include. The link in `url` expires after `expiresInSeconds` seconds (1 hour)." }, "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.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "description": "Which file of each tax document to bundle: `XML` or `PDF`. Defaults to `XML`. A zip holds at most 1 000 XML files or 200 PDF files.", "example": "XML", "type": "string", "enum": [ "PDF", "XML" ] }, "taxDocumentIds": { "description": "Selection mode: the `id` of each tax document to bundle. Duplicates count once. At most 1 000 distinct ids for `XML` and 200 for `PDF`. Send either this or `filters`, never both.\n\n---\n\nExample: `[\"3d6f9a2b-1c4e-4f8a-9b7d-5e2c1a0f8b63\",\"7a1c5e90-2b3d-4c6f-8e1a-9d4b0f2c7a35\"]`", "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "example": "3d6f9a2b-1c4e-4f8a-9b7d-5e2c1a0f8b63" } }, "filters": { "description": "Filter mode: bundle every tax document that matches, using the same filters as List tax documents. At least one filter is required, and a filter that matches more than 1 000 documents (200 for `PDF`) is rejected. Send either this or `taxDocumentIds`, never both.", "type": "object", "properties": { "status": { "description": "Only documents in one of these statuses.\n\n---\n\nExample: `[\"AUTHORIZED\",\"DENIED\"]`", "type": "array", "items": { "type": "string", "enum": [ "WAITINGFORAUTHORIZATION", "REQUESTINGAUTHORIZATION", "AUTHORIZATIONREQUESTED", "AUTHORIZATIONPROCESS", "AWAITINGFILEGENERATION", "AUTHORIZED", "DENIED", "REQUESTINGCANCELLATION", "CANCELLATIONREQUESTED", "CANCELLATIONPROCESS", "AWAITINGFILECANCELATION", "CANCELED", "CANCELLATIONDENIED" ], "example": "AUTHORIZED" } }, "type": { "description": "Only documents of one of these types.\n\n---\n\nExample: `[\"NFSE\"]`", "type": "array", "items": { "type": "string", "enum": [ "NFSE" ], "example": "NFSE" } }, "environment": { "description": "`LIVE` for real documents, `TEST` for homologation documents (no fiscal value). Omit to match both.", "example": "LIVE", "type": "string", "enum": [ "LIVE", "TEST" ] }, "issuedAtStart": { "description": "Only documents issued on or after this moment. A date without a time (`2026-10-01`) means 00:00 UTC.", "example": "2026-10-01T00:00:00.000Z", "type": "string", "format": "date-time" }, "issuedAtEnd": { "description": "Only documents issued on or before this moment. Must not be before `issuedAtStart`. To include a whole day, send `T23:59:59.999Z` of that day.", "example": "2026-10-31T23:59:59.999Z", "type": "string", "format": "date-time" }, "competenceDateStart": { "description": "Only documents whose competence date is on or after this moment. A date without a time means 00:00 UTC.", "example": "2026-10-01T00:00:00.000Z", "type": "string", "format": "date-time" }, "competenceDateEnd": { "description": "Only documents whose competence date is on or before this moment. Must not be before `competenceDateStart`. To include a whole day, send `T23:59:59.999Z` of that day.", "example": "2026-10-31T23:59:59.999Z", "type": "string", "format": "date-time" }, "rpsNumberStart": { "description": "Only documents whose RPS number is greater than or equal to this one.", "example": 1000, "type": "number" }, "rpsNumberEnd": { "description": "Only documents whose RPS number is less than or equal to this one. Must not be less than `rpsNumberStart`.", "example": 1100, "type": "number" }, "customerDocument": { "description": "Only documents of the customer with this CPF or CNPJ, with or without punctuation. An exact match, not a partial one.", "example": "12345678000195", "type": "string" }, "customerName": { "description": "Only documents whose customer name contains this text (case-insensitive).", "example": "acme", "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "fileName": { "type": "string", "description": "Suggested name of the zip file.", "example": "nfse-xml-2026-10-20_14-30-05.zip" }, "url": { "type": "string", "description": "Temporary link to download the zip. Opening it saves the file. It stops working after `expiresInSeconds` seconds.", "example": "https://downloads.example.com/nfse-xml-2026-10-20_14-30-05.zip?signature=abc123" }, "expiresInSeconds": { "type": "number", "description": "For how long `url` works, in seconds, counted from this response.", "example": 3600 }, "total": { "type": "number", "description": "Tax documents the request resolved to: the distinct ids you sent (selection mode), or the documents the filters matched (filter mode).", "example": 3 }, "included": { "type": "number", "description": "Files inside the zip, besides `manifest.csv`.", "example": 2 }, "missing": { "type": "array", "items": { "type": "object", "properties": { "taxDocumentId": { "type": "string", "description": "ID of the tax document. For `NOT_FOUND` it is the id exactly as you sent it.", "example": "7a1c5e90-2b3d-4c6f-8e1a-9d4b0f2c7a35" }, "reason": { "type": "string", "enum": [ "NOT_FOUND", "FILE_NOT_AVAILABLE" ], "description": "Why the document is not in the zip. `NOT_FOUND`: no tax document with that id belongs to your organization (selection mode only). `FILE_NOT_AVAILABLE`: the document exists but has no file of the requested type yet, for example because it is not authorized yet or was denied.", "example": "FILE_NOT_AVAILABLE" }, "nfseNumber": { "type": "string", "description": "NFSe number given by the city hall, as text. Present only for `FILE_NOT_AVAILABLE`, and only when the document already has one.", "example": "1042" }, "rpsNumber": { "type": "string", "description": "RPS number of the document, as text. Present only for `FILE_NOT_AVAILABLE`, and only when the document has one.", "example": "1042" }, "status": { "type": "string", "description": "Current status of the tax document. Present only for `FILE_NOT_AVAILABLE`.", "example": "AUTHORIZATIONPROCESS" } }, "required": [ "taxDocumentId", "reason" ], "description": "A tax document that was requested or matched but is not in the zip." }, "description": "Every requested or matched tax document that is not in the zip, and why. Empty when the zip holds all of them. They are also listed in the zip's `manifest.csv`.", "example": [ { "taxDocumentId": "7a1c5e90-2b3d-4c6f-8e1a-9d4b0f2c7a35", "reason": "FILE_NOT_AVAILABLE", "rpsNumber": "1042", "status": "AUTHORIZATIONPROCESS" } ] } }, "required": [ "fileName", "url", "expiresInSeconds", "total", "included", "missing" ], "description": "The zip with the files of the requested tax documents, and what was left out of it." } } } }, "404": { "description": "`TAX_DOCUMENT_BATCH_DOWNLOAD_EMPTY` — None of the requested or matched documents has a file of the requested type, so there is nothing to put in the zip.\n\n`TAX_ISSUER_NOT_FOUND` — Filter mode only: the organization has no active tax issuer.", "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": [ "TAX_DOCUMENT_BATCH_DOWNLOAD_EMPTY", "TAX_ISSUER_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_DOCUMENT_BATCH_DOWNLOAD_EMPTY", "origin": "ACCOUNTING", "message": "None of the requested tax documents has a file available for download" } } } }, "422": { "description": "`TAX_DOCUMENT_BATCH_DOWNLOAD_LIMIT_EXCEEDED` — Filter mode only: the filters match more documents than one zip can hold. The limit in the message is 1000 for `XML` and 200 for `PDF`.\n\n`BAD_REQUEST` — A path parameter is not a valid ID, the body is not a JSON object, it has neither `taxDocumentIds` nor a filter or has both, a field is invalid, or a selection is above the limit; `fields` lists each problem.", "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": [ "TAX_DOCUMENT_BATCH_DOWNLOAD_LIMIT_EXCEEDED", "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_DOCUMENT_BATCH_DOWNLOAD_LIMIT_EXCEEDED", "origin": "ACCOUNTING", "message": "Too many tax documents match this batch download; narrow the filters or select fewer documents (limit: 1000)" } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.superRefine(…)` constraint not represented (runtime-dependent value); `.transform(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/tax-document/batch-cancel": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdTaxDocumentBatchCancel", "summary": "Cancel tax documents in batch", "tags": [ "Tax Documents (NFSe)" ], "x-p3-sidebar-order": 5, "description": "Requests the cancellation of every tax document listed in an uploaded CSV file.", "x-mint": { "content": "Send a `multipart/form-data` request whose `file` part is a CSV file: comma-separated, with a header row and one row per tax document to cancel.\n\n| Column | Required | Meaning |\n|---|---|---|\n| `taxDocumentId` | Yes | ID of the tax document to cancel: the `id` of a document returned by the tax documents list. |\n\nOnly the `taxDocumentId` column is read; every other column is ignored, so the export of your tax documents can be uploaded as it is. A row without a valid `taxDocumentId` is rejected.\n\nThe whole upload is validated first: if any row is invalid nothing is cancelled, and `fields` points at the row by its position, where `taxDocuments[0]` is the first row after the header. When the upload is valid, the response only means the rows were accepted. The cancellation of each tax document is then requested in the background, so a row can still fail later: a tax document that is not one of your organization's is not cancelled, and one that cannot be cancelled in its current state, for example because it is not authorized yet, is skipped. Upload each tax document once, because asking again to cancel one that is already being cancelled fails." }, "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.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The CSV file, with a header row and one row per tax document to cancel. Only the `taxDocumentId` column is read; see the operation description. Required, not empty, at most 4 MB; its file name must end in `.csv`, or its content type be `text/csv`, `application/vnd.ms-excel` or `text/plain`." } }, "required": [ "file" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirms what was requested. It only means the rows were accepted, not that every document was already issued or cancelled.", "example": "Batch cancellation requested." }, "count": { "type": "number", "description": "Number of CSV rows accepted for processing.", "example": 25 } }, "required": [ "message", "count" ], "description": "Acknowledgement that a CSV batch was accepted. Each row is processed in the background." } } } }, "400": { "description": "`TAX_ISSUER_PROVIDER_ID_NOT_FOUND` — The tax issuer is not registered with the tax provider yet.", "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": [ "TAX_ISSUER_PROVIDER_ID_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_ISSUER_PROVIDER_ID_NOT_FOUND", "origin": "ACCOUNTING", "message": "Tax issuer provider id not exists" } } } }, "404": { "description": "`TAX_ISSUER_NOT_FOUND` — The organization has no active tax issuer.", "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": [ "TAX_ISSUER_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_ISSUER_NOT_FOUND", "origin": "ACCOUNTING", "message": "Tax issuer not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID, the request is not `multipart/form-data`, the `file` part is missing, empty, larger than 4 MB or not a readable CSV, or a row has no valid `taxDocumentId`; `fields` lists each problem.", "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": [ "ACCOUNTING" ], "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": "ACCOUNTING", "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.", "fields": [ { "field": "file", "message": "file is required", "code": "FILE_REQUIRED" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/tax-document/{taxDocumentId}/download": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdTaxDocumentByTaxDocumentIdDownload", "summary": "Download a tax document", "tags": [ "Tax Documents (NFSe)" ], "x-p3-sidebar-order": 6, "description": "Gets a temporary link to download the PDF or the XML of a tax document.", "x-mint": { "content": "Choose the file with `type`. The files exist only once the document is `AUTHORIZED`: before that, the request answers 404. Open the returned `url` within 1 hour, and the browser saves the file under the returned `fileName`." }, "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 that owns the tax document.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "taxDocumentId", "in": "path", "required": true, "description": "ID of the tax document to download.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "3d6f9a2b-1c4e-4f8a-9b7d-5e2c1a0f8b63" }, { "name": "type", "in": "query", "required": true, "description": "Which file to download: the `PDF` of the document or its `XML`.", "schema": { "type": "string", "enum": [ "PDF", "XML" ] }, "example": "XML" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "fileName": { "type": "string", "description": "Name of the file: `NFSe-` once the document has its NFSe number, else `RPS--`, else the ID of the document, followed by the extension (`.pdf` or `.xml`). Files of `TEST` documents are prefixed with `HOMOLOGACAO-`.", "example": "NFSe-2874.xml" }, "url": { "type": "string", "description": "Temporary download link, valid for 1 hour. Opening it makes the browser save the file.", "example": "https://files.example.com/nfse/xml/3d6f9a2b-1c4e-4f8a-9b7d-5e2c1a0f8b63.xml?X-Signature=abc123" } }, "required": [ "fileName", "url" ], "description": "A temporary link to one file of a tax document." } } } }, "404": { "description": "`TAX_DOCUMENT_NOT_FOUND` — No tax document with this ID exists in the organization.\n\n`TAX_DOCUMENT_PDF_NOT_FOUND` — The PDF is not available: it exists only once the document is `AUTHORIZED`.\n\n`TAX_DOCUMENT_XML_NOT_FOUND` — The XML is not available: it exists only once the document is `AUTHORIZED`.", "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": [ "TAX_DOCUMENT_NOT_FOUND", "TAX_DOCUMENT_PDF_NOT_FOUND", "TAX_DOCUMENT_XML_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_DOCUMENT_NOT_FOUND", "origin": "ACCOUNTING", "message": "Tax document not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID, or `type` is missing or is not `PDF` or `XML`; `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": [ "ACCOUNTING" ], "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": "ACCOUNTING", "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.", "fields": [ { "field": "type", "message": "Invalid option: expected one of \"PDF\"|\"XML\"", "code": "TYPE_ONE_OF", "values": [ "PDF", "XML" ] } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/tax-document/{taxDocumentId}": { "delete": { "operationId": "deleteRealmsByRealmIdOrganizationsByOrganizationIdTaxDocumentByTaxDocumentId", "summary": "Cancel a tax document", "tags": [ "Tax Documents (NFSe)" ], "x-p3-sidebar-order": 7, "description": "Requests the cancellation of a tax document and answers with the document.", "x-mint": { "content": "Cancellation is asynchronous. The document you get back has the status `REQUESTINGCANCELLATION`; it later moves to `CANCELED`, or to `CANCELLATIONDENIED` when the city hall refuses the cancellation (the document then stays valid). Follow it in List tax documents. A document that is still being authorized cannot be cancelled yet.\n\nIf the tax provider rejects the cancellation, the error is returned with the provider's error `code` and a status of 400, 409, 422 or 502." }, "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 that owns the tax document.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "taxDocumentId", "in": "path", "required": true, "description": "ID of the tax document to cancel.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "3d6f9a2b-1c4e-4f8a-9b7d-5e2c1a0f8b63" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the tax document.", "example": "3d6f9a2b-1c4e-4f8a-9b7d-5e2c1a0f8b63", "format": "uuid" }, "realm": { "type": "string", "description": "ID of the realm the document belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization the document belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "taxIssuer": { "type": "string", "description": "ID of the tax issuer that issued the document.", "example": "9b2f4c1e-7a3d-4e8b-b6f0-2d5c8a1e3f47", "format": "uuid" }, "environment": { "type": "string", "enum": [ "LIVE", "TEST" ], "description": "`LIVE` for a real document, `TEST` for a homologation document with no fiscal value.", "example": "LIVE" }, "rpsNumber": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "Number of the RPS (provisional service receipt). A number once it has been assigned, and an empty string (`\"\"`) before that.", "example": 1042 }, "rpsSeries": { "type": "string", "description": "Series of the RPS. An empty string (`\"\"`) until it has been assigned.", "example": "1" }, "nfseNumber": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "Number of the NFSe given by the city hall. A number once the document is `AUTHORIZED`, and an empty string (`\"\"`) before that.", "example": 2874 }, "type": { "type": "string", "enum": [ "NFSE" ], "description": "Type of the document.", "example": "NFSE" }, "competenceDate": { "type": "string", "description": "Competence date of the document.", "example": "2026-10-01T00:00:00.000Z", "format": "date-time" }, "customer": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PERSON", "COMPANY" ], "description": "Whether the customer is a person (CPF) or a company (CNPJ).", "example": "COMPANY" }, "name": { "type": "string", "description": "Name of the customer.", "example": "Acme Tecnologia Ltda" }, "email": { "type": "string", "description": "E-mail of the customer.", "example": "financeiro@acme.com.br" }, "federalDocument": { "type": "string", "description": "CPF or CNPJ of the customer, as it was sent when the document was issued (digits only or with punctuation).", "example": "12345678000195" }, "municipalDocument": { "type": "string", "description": "Municipal registration (inscrição municipal) of the customer.", "example": "123456" }, "stateDocument": { "type": "string", "description": "State registration (inscrição estadual) of the customer.", "example": "123456789" }, "phone": { "type": "string", "description": "Phone of the customer in E.164 format. Omitted when none was sent.", "example": "+5534991234567" }, "addressStateCode": { "type": "number", "description": "IBGE code of the customer's state.", "example": 31 }, "addressCityCode": { "type": "number", "description": "IBGE code of the customer's city.", "example": 3170206 }, "addressState": { "type": "string", "description": "State of the customer's address (two letters).", "example": "MG" }, "addressCity": { "type": "string", "description": "City of the customer's address.", "example": "Uberlândia" }, "addressStreet": { "type": "string", "description": "Street of the customer's address.", "example": "Avenida João Naves de Ávila" }, "addressNumber": { "type": "string", "description": "Number of the customer's address.", "example": "2121" }, "addressComplement": { "type": "string", "description": "Complement of the customer's address.", "example": "Sala 101" }, "addressNeighbourhood": { "type": "string", "description": "Neighbourhood of the customer's address.", "example": "Santa Mônica" }, "addressPostalCode": { "type": "string", "description": "Postal code (CEP) of the customer's address.", "example": "38408100" } }, "description": "The customer (service taker) of the document. An empty object when there is none." }, "service": { "type": "object", "properties": { "serviceProvisionState": { "type": "string", "description": "State where the service was provided (two letters).", "example": "MG" }, "serviceProvisionCity": { "type": "string", "description": "City where the service was provided.", "example": "Uberlândia" }, "description": { "type": "string", "description": "Description of the service, printed on the document.", "example": "Licenciamento de software (SaaS)" }, "issRate": { "type": "number", "description": "ISS rate, as a percentage (`2` means 2%).", "example": 2 }, "issWithheldAtSource": { "type": "boolean", "description": "Whether the ISS is withheld at source by the customer.", "example": false }, "serviceMunicipalCode": { "type": "string", "description": "Municipal service code, as defined by the city hall.", "example": "0107" }, "serviceMunicipalDescription": { "type": "string", "description": "Description of the municipal service code.", "example": "Licenciamento ou cessão de direito de uso de programas de computação." }, "serviceListItemLC116": { "type": "string", "description": "Item of the LC 116 service list.", "example": "1.05" }, "cnae": { "type": "string", "description": "CNAE (national classification of economic activities) code.", "example": "6201501" }, "cofinsAmount": { "type": "number", "description": "COFINS amount, in reais.", "example": 0 }, "csllAmount": { "type": "number", "description": "CSLL amount, in reais.", "example": 0 }, "inssAmount": { "type": "number", "description": "INSS amount, in reais.", "example": 0 }, "irAmount": { "type": "number", "description": "IR amount, in reais.", "example": 0 }, "pisAmount": { "type": "number", "description": "PIS amount, in reais.", "example": 0 }, "taxConfiguration": { "type": "object", "properties": { "nbsCode": { "type": "string", "description": "NBS code (Nomenclatura Brasileira de Serviços) of the service.", "example": "115090000" }, "nationalTaxCode": { "type": "string", "description": "National tax code of the service.", "example": "010701" }, "taxClassification": { "type": "string", "description": "Tax classification applied to the operation.", "example": "000001" }, "operationIndicatorCode": { "type": "string", "description": "Operation indicator code.", "example": "100301" } }, "description": "Tax configuration applied to the service. An empty object when none was sent or defaulted." } }, "description": "The service the document bills. An empty object when there is none." }, "operationNature": { "type": "string", "description": "Nature of the operation, as sent when the document was issued.", "example": "Prestação de Serviços" }, "deductions": { "type": "number", "description": "Deductions, in reais.", "example": 0 }, "discounts": { "type": "number", "description": "Discounts, in reais.", "example": 0 }, "totalValue": { "type": "number", "description": "Total value of the document, in reais.", "example": 1500.5 }, "status": { "type": "string", "enum": [ "WAITINGFORAUTHORIZATION", "REQUESTINGAUTHORIZATION", "AUTHORIZATIONREQUESTED", "AUTHORIZATIONPROCESS", "AWAITINGFILEGENERATION", "AUTHORIZED", "DENIED", "REQUESTINGCANCELLATION", "CANCELLATIONREQUESTED", "CANCELLATIONPROCESS", "AWAITINGFILECANCELATION", "CANCELED", "CANCELLATIONDENIED" ], "description": "Current status of the document. A document is created as `WAITINGFORAUTHORIZATION` and moves on its own: the authorization states (`REQUESTINGAUTHORIZATION`, `AUTHORIZATIONREQUESTED`, `AUTHORIZATIONPROCESS`, `AWAITINGFILEGENERATION`) end in `AUTHORIZED` or `DENIED`; after you cancel it, the cancellation states (`REQUESTINGCANCELLATION`, `CANCELLATIONREQUESTED`, `CANCELLATIONPROCESS`, `AWAITINGFILECANCELATION`) end in `CANCELED` or `CANCELLATIONDENIED`.", "example": "REQUESTINGCANCELLATION" }, "errorMessage": { "type": "string", "description": "Reason the tax provider or the city hall gave when the document was denied. An empty string (`\"\"`) when there is none.", "example": "" }, "observation": { "type": "string", "description": "Free text printed on the document. Omitted when none was sent.", "example": "Referente ao contrato 1234" }, "issuedAt": { "type": "string", "description": "When the document was issued, that is, when your request created it.", "example": "2026-10-01T13:45:12.000Z", "format": "date-time" }, "issuedBy": { "type": "string", "description": "ID of the user, or of the API client, that issued the document.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99" }, "externalId": { "type": "string", "description": "The `externalId` you sent when you issued the document. Omitted when you sent none.", "example": "6f1b7c52-8a4e-4d3f-9c21-b0e5a7d84c19" } }, "required": [ "id", "realm", "organization", "taxIssuer", "environment", "rpsNumber", "rpsSeries", "nfseNumber", "type", "competenceDate", "customer", "service", "deductions", "discounts", "totalValue", "status", "errorMessage" ], "description": "A tax document (NFSe) of your organization." } } } }, "400": { "description": "`TAX_ISSUER_PROVIDER_ID_NOT_FOUND` — The tax issuer is not registered with the tax provider yet.\n\n`PROVIDER_ID_NOT_FOUND` — The document never reached the tax provider, so there is nothing to cancel.", "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": [ "TAX_ISSUER_PROVIDER_ID_NOT_FOUND", "PROVIDER_ID_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_ISSUER_PROVIDER_ID_NOT_FOUND", "origin": "ACCOUNTING", "message": "Tax issuer provider id not exists" } } } }, "403": { "description": "`TAX_ISSUER_INACTIVE` — The organization has no active tax issuer.", "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": [ "TAX_ISSUER_INACTIVE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_ISSUER_INACTIVE", "origin": "ACCOUNTING", "message": "Tax issuer is deactivated. You do not have permission to perform this action." } } } }, "404": { "description": "`TAX_DOCUMENT_NOT_FOUND` — No tax document 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": [ "TAX_DOCUMENT_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "ACCOUNTING" ], "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": "TAX_DOCUMENT_NOT_FOUND", "origin": "ACCOUNTING", "message": "Tax document 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": [ "ACCOUNTING" ], "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": "ACCOUNTING", "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.", "fields": [ { "field": "taxDocumentId", "message": "Invalid UUID", "code": "TAXDOCUMENTID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/taxCode/{specialTaxCode}": { "get": { "operationId": "getTaxCodeBySpecialTaxCode", "summary": "List a city's special tax regimes", "tags": [ "Tax Codes" ], "x-p3-sidebar-order": 1, "description": "Lists the special taxation regimes a city hall supports for service invoice (NFSe) issuance.", "x-mint": { "content": "Send the 7-digit IBGE code of the city as `specialTaxCode`. Use the `id` of the regime that applies to your organization as `specialTaxCode` when you create your tax issuer. A city with no special regimes answers an empty list.\n\nThe regimes come from the tax provider. If the tax provider rejects the request, the error is returned with the provider's error `code` and a status of 400, 409, 422 or 502." }, "parameters": [ { "name": "specialTaxCode", "in": "path", "required": true, "description": "IBGE code of the city (7 digits). The path parameter keeps its historical name.", "schema": { "type": "string", "pattern": "^\\d{7}$" }, "example": "3170206" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Code of the special taxation regime — send it as `specialTaxCode` when you create your tax issuer.", "example": "1" }, "name": { "type": "string", "description": "Name of the regime, as the city hall calls it.", "example": "Microempresa municipal" } }, "required": [ "id", "name" ], "description": "A special taxation regime the city hall supports for service invoice (NFSe) issuance." } } } } }, "422": { "description": "`BAD_REQUEST` — `specialTaxCode` is not a 7-digit IBGE code; `fields` lists it.", "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": [ "ACCOUNTING" ], "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": "ACCOUNTING", "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.", "fields": [ { "field": "id", "message": "Invalid input: expected string, received undefined", "code": "ID_REQUIRED" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } } } } }