> ## 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. # Create the NFSe configuration > Turns on automatic NFSe issuance for the organization: from now on, each `event` you choose issues a service invoice (NFSe) through your tax issuer. Only admins of the organization or of the realm can create it. The organization needs an active tax issuer in the Accounting service first (`POST /realms/{realmId}/organizations/{organizationId}/tax-issuer`, with its test and live configurations), and it has at most one NFSe configuration: to change it, delete it and create a new one. The configuration is read when each event is processed, shortly after it happens, so an event processed while the organization has no configuration issues no NFSe, and it is not issued later. Each NFSe is issued in the background, after its event, and appears in the Accounting service's tax document list (`GET /realms/{realmId}/organizations/{organizationId}/tax-document`). It is issued to the invoice's payer: the CPF or CNPJ comes from the invoice, and the name, e-mail and address from the contract's buyer when it has them. An invoice whose payer has no CPF or CNPJ issues none. The service data (city, ISS rate, municipal service code, LC 116 item, CNAE) comes from your tax issuer's live configuration, also when `environment` is `TEST`, and the service description is the invoice's description. With `PAYMENT_RECEIVED`, each payment settled on an invoice issues its own NFSe, for the amount of that payment. Payments you record by hand (`POST .../invoices/{invoiceId}/statements` and `POST .../invoices/{invoiceId}/statements/settlement`) issue none. Answers the configuration it created. ## OpenAPI ````yaml /api-reference/billing.openapi.json post /realms/{realmId}/organizations/{organizationId}/nfse-configs openapi: 3.0.3 info: title: Billing version: 1.0.0 description: >- Portão 3 billing 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). Full billing surface — contracts, deals, invoices, statements, payment links, checkout and NFSe orchestration. (The product/supplier catalog moved to registry.) Confidence tiers: generated:typed=74 copied:manual=0 unknown=5. servers: - url: https://api.billing.v2.portao3.com.br/ description: production - url: https://api.billing.dev.3pers.com.br/ description: development security: [] tags: - name: Contracts - name: Deals - name: Invoices - name: Invoice Entries - name: Invoice Statements - name: NFSe Configuration - name: Payment Links paths: /realms/{realmId}/organizations/{organizationId}/nfse-configs: post: tags: - NFSe Configuration summary: Create the NFSe configuration description: >- Turns on automatic NFSe issuance for the organization: from now on, each `event` you choose issues a service invoice (NFSe) through your tax issuer. operationId: postRealmsByRealmIdOrganizationsByOrganizationIdNfseConfigs 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 NFSe. It needs an active tax issuer. Format: `UUID` schema: type: string format: uuid example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 requestBody: required: true content: application/json: schema: type: object properties: event: type: string enum: - INVOICE_PAID - INVOICE_CLOSED - PAYMENT_RECEIVED description: >- Which billing event issues an NFSe. `INVOICE_CLOSED`: one NFSe for the whole invoice, for its amount, when the invoice closes. `INVOICE_PAID`: one NFSe for the whole invoice, for its amount, when the invoice is paid. `PAYMENT_RECEIVED`: one NFSe for each payment settled on an invoice, for the amount of that payment. example: INVOICE_PAID issWithheldAtSource: type: boolean description: >- Whether the customer withholds the ISS at source. Sent on every NFSe this configuration issues. example: false environment: type: string enum: - TEST - LIVE description: >- `LIVE` issues real NFSe. `TEST` issues homologation documents, which have no fiscal value; they carry the same service data, from your tax issuer's live configuration. example: LIVE competence: type: string enum: - EVENT_DATE - CREATED_AT - CLOSED_AT - DUE_AT - PAID_AT - EFFECTIVE_AT description: >- Which date becomes the competence date of each NFSe (the date the service refers to), as a UTC calendar day. `EVENT_DATE`: the day the event happened. `CREATED_AT`: the day the invoice was created, or, with `PAYMENT_RECEIVED`, the day the payment was recorded. `CLOSED_AT`, `DUE_AT`, `PAID_AT`: the invoice's closing, due and payment dates (an invoice with no payment date uses the event date). `EFFECTIVE_AT`: the day the payment took effect. `INVOICE_CLOSED` and `INVOICE_PAID` accept `EVENT_DATE`, `CREATED_AT`, `CLOSED_AT`, `DUE_AT` and `PAID_AT`; `PAYMENT_RECEIVED` accepts `EVENT_DATE`, `CREATED_AT` and `EFFECTIVE_AT`. Any other combination is rejected. example: PAID_AT observation: type: string description: >- Free text printed on every NFSe this configuration issues. Send an empty string to print none. example: Serviços prestados conforme contrato. operationNature: type: string description: >- Nature of the operation, stored with every NFSe this configuration issues but not printed on it. An empty string is accepted. example: Prestação de Serviços required: - event - issWithheldAtSource - environment - competence - observation - operationNature responses: '201': description: Successful response content: application/json: schema: type: object properties: event: type: string enum: - INVOICE_PAID - INVOICE_CLOSED - PAYMENT_RECEIVED description: >- Which billing event issues an NFSe: `INVOICE_CLOSED` (one per invoice, when it closes), `INVOICE_PAID` (one per invoice, when it is paid) or `PAYMENT_RECEIVED` (one per payment settled on an invoice). example: INVOICE_PAID issWithheldAtSource: type: boolean description: Whether the customer withholds the ISS at source. example: false environment: type: string enum: - TEST - LIVE description: >- `LIVE` for real NFSe, `TEST` for homologation documents with no fiscal value. example: LIVE competence: type: string enum: - EVENT_DATE - CREATED_AT - CLOSED_AT - DUE_AT - PAID_AT - EFFECTIVE_AT description: >- Which date becomes the competence date of each NFSe: `EVENT_DATE`, `CREATED_AT`, `CLOSED_AT`, `DUE_AT`, `PAID_AT` or `EFFECTIVE_AT`. Absent on a configuration created before this field existed: its NFSe take the day the invoice was last updated. example: PAID_AT observation: type: string description: >- Free text printed on every NFSe. Absent on a configuration created before this field existed, which prints none. example: Serviços prestados conforme contrato. operationNature: type: string description: >- Nature of the operation, stored with every NFSe but not printed on it. Absent on a configuration created before this field existed, which stores `Prestação de Serviços`. example: Prestação de Serviços createdAt: type: string description: When the configuration was created. example: '2026-08-07T19:45:17.204Z' format: date-time required: - event - issWithheldAtSource - environment - createdAt description: The organization's NFSe configuration. '403': description: >- `INSUFFICIENT_PERMISSIONS` — You are not an admin of the organization or of the 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: - INSUFFICIENT_PERMISSIONS description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BILLING 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: INSUFFICIENT_PERMISSIONS origin: BILLING message: insufficient permissions '404': description: >- `TAX_ISSUER_NOT_FOUND` — The organization has no active tax issuer, its tax issuer is missing its test or its live configuration, or 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 description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BILLING 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: BILLING message: Tax issuer not found '409': description: >- `RESOURCE_CONFLICT` — The organization already has an NFSe configuration. Delete it first to replace 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: - RESOURCE_CONFLICT description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BILLING 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: RESOURCE_CONFLICT origin: BILLING message: NFSE_CONFIG already exist '422': description: >- `BAD_REQUEST` — The body is invalid, such as a missing field, an unknown `event`, `environment` or `competence`, or a `competence` the `event` does not accept, or 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: - BILLING 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: BILLING message: >- Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields. fields: - field: event message: >- Invalid option: expected one of "INVOICE_PAID"|"INVOICE_CLOSED"|"PAYMENT_RECEIVED" code: EVENT_ONE_OF values: - INVOICE_PAID - INVOICE_CLOSED - PAYMENT_RECEIVED ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.