> ## Documentation Index > Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt > Use this file to discover all available pages before exploring further. # List tax documents > Lists the tax documents (NFSe) of your organization, newest first. 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. Every 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. Dates 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`. Results are paginated, newest first, 50 per page unless you send `limit` (1 to 100). See [Pagination](https://developers.portao3.com.br/api-reference/pagination.md). ## OpenAPI ````yaml /api-reference/accounting.openapi.json get /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: get: tags: - Tax Documents (NFSe) summary: List tax documents description: Lists the tax documents (NFSe) of your organization, newest first. operationId: getRealmsByRealmIdOrganizationsByOrganizationIdTaxDocument parameters: - name: realmId in: path required: true description: |- ID of your realm. Format: `UUID` schema: type: string format: uuid example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b - name: organizationId in: path required: true description: |- ID of the organization whose tax documents you want to list. Format: `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. --- Example (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. --- Example: `?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. `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 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.