> ## Documentation Index > Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Issue a tax document > Issues a tax document (NFSe) for your organization. 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`. Send `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`. The 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. 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. ## OpenAPI ````yaml /api-reference/accounting.openapi.json post /realms/{realmId}/organizations/{organizationId}/tax-document 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 security: [] tags: - name: Tax Issuers - name: Tax Documents (NFSe) - name: Tax Codes paths: /realms/{realmId}/organizations/{organizationId}/tax-document: post: tags: - Tax Documents (NFSe) summary: Issue a tax document description: Issues a tax document (NFSe) for your organization. operationId: postRealmsByRealmIdOrganizationsByOrganizationIdTaxDocument parameters: - name: realmId in: path required: true description: |- ID of your realm. Format: `UUID` schema: type: string format: uuid example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b - name: organizationId in: path required: true description: |- ID of the organization that issues the tax document. Format: `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`. Format: `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: 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: 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. `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. `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 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.