openapi: 3.0.3 info: title: Contabeleza API — generated from HAR version: 0.1.0 description: |- Generated from MANUAL_OPERATIONS on 2026-07-27T15:47:14.112Z. ### Conventions - All requests and responses follow [JSON:API v1.1](/jsonapi). Content type: `application/vnd.api+json`. - Authentication: `Authorization: Bearer ` — see the [authentication guide](/auth). - Business context: `ilm-business: ` — see the [ilm-business guide](/headers). ### Base URL Pick the target environment from the **Servers** dropdown above (production / staging / qa / local mock). servers: - url: https://api.contabeleza.com.br description: production - url: https://api.staging.contabeleza.com.br description: staging - url: https://api.qa.contabeleza.com.br description: qa - url: http://localhost:4321 description: local mock tags: - name: access > sessions description: Login, logout, token refresh, password reset — the authentication gateway. - name: accounts description: Account creation, profile management, phone updates, impersonation, terms, external sign-up. - name: accounts > recipient description: Payout recipient and PIX key management. - name: accounts > resources description: Profile image upload and account document attachments. - name: access > external-app-tokens description: Admin API key management for external integrations. - name: businesses > professional invoices description: Operations on **professional invoices** resources. - name: professionals > fiscal entities description: Professional fiscal entity CRUD, emission setup. - name: businesses > fiscal entities > certificate description: Digital certificate management for business fiscal entities. - name: professionals > fiscal entities > certificate description: Digital certificate management for professional fiscal entities. - name: professionals > documents description: Professional-scoped identity and supporting documents. - name: businesses > documents description: Identity and supporting document uploads (RG, CNH, CPF, address proof). - name: businesses > representatives description: Legal representative management for businesses. - name: businesses description: Business catalog, settings, week schedules, municipal details. - name: accounts > professional contracts description: Account-scoped professional contract listing. - name: accounts > professional invoices description: Account-scoped professional invoice listing. - name: platform > resources description: File upload and management. - name: businesses > requests description: 'Workflow orchestration: contract creation, batch emission, termination.' - name: professionals > requests description: Professional-scoped business request history. - name: professionals > contracts description: Professional-scoped contract active status. - name: professionals > fiscal entities > revenue description: Revenue resumes and limits tracking for professional fiscal entities. - name: businesses > fiscal entities > revenue description: Revenue resumes and limits tracking for business fiscal entities. - name: businesses > fiscal entities > diagnosis description: MEI compliance diagnosis for business fiscal entities. - name: professionals > fiscal entities > diagnosis description: MEI compliance diagnosis for professional fiscal entities. - name: businesses > fiscal entities description: Business fiscal entity CRUD, emission setup. - name: businesses > fiscal entities > pass-gov description: Gov.br credential management for business fiscal entities. - name: businesses > fiscal entities > pass-invoices description: Prefeitura portal credential management for business fiscal entities. - name: businesses > fiscal entities > invoices-emission description: eNotas invoice emission setup and validation for businesses. - name: professionals > fiscal entities > pass-gov description: Gov.br credential management for professional fiscal entities. - name: professionals > fiscal entities > pass-invoices description: Prefeitura portal credential management for professional fiscal entities. - name: professionals > fiscal entities > invoices-emission description: eNotas invoice emission setup and validation for professionals. - name: accounts > fiscal entities description: Personal fiscal entity CRUD and CPF revalidation. - name: accounts > fiscal entities > certificate description: Digital certificate management for personal fiscal entities. - name: accounts > fiscal entities > pass-gov description: Gov.br credential management for personal fiscal entities. - name: accounts > fiscal entities > pass-invoices description: Prefeitura portal credential management for personal fiscal entities. - name: accounts > fiscal entities > mei description: 'MEI-specific operations: DAS, DASN, CND, diagnosis, CNPJ management.' - name: accounts > invoices description: Invoice creation, emission, and cancellation. - name: businesses > categories description: Business-level category management. - name: businesses > settings description: Business configuration settings. - name: platform > constants description: Platform-wide lookup tables and enumerations. - name: businesses > professional categories description: Professional category classification within a business. - name: businesses > services description: Professional service catalog with pricing. - name: professionals description: Professional catalog, ownership checks, personal documents. - name: businesses > schedules description: Weekly working hours for businesses and professionals. - name: internal ★ > fiscal entities description: >- Fiscal entity CRUD, MEI data, certificates, credentials, revenue, and requests — direct accounting service endpoints. - name: internal ★ > fiscal entities > mei description: 'MEI-specific data: DAS payments, DASN declarations, CND certificates, and compliance diagnosis.' - name: internal ★ > fiscal entities > revenue description: Revenue records and aggregated resume per fiscal entity. - name: internal ★ > fiscal entities > pass-gov description: Gov.br credential management for fiscal entities — create, update, validate, clear. - name: internal ★ > fiscal entities > pass-invoices description: Prefeitura portal credential management for fiscal entities — create, update, validate, clear. - name: internal ★ > fiscal entities > certificate description: Digital certificate management for fiscal entities — upload, validate, clear. - name: internal ★ > fiscal entities > requests description: Fiscal entity workflow requests — create, track, and update async operations. - name: internal ★ > fiscal entities > invoices description: 'Invoice lifecycle: create, emit, cancel, re-emit, upload NFS-e — direct accounting service endpoints.' - name: internal ★ > fiscal entities > invoices-emission description: eNotas invoice emission setup, validation, and deactivation for fiscal entities. - name: internal ★ > buyer fiscal entities description: Customer fiscal entity (CPF/CNPJ) CRUD for invoice addressing. - name: internal ★ > search description: CNPJ, CPF, address, and municipal details lookup via InfoSimples integration. - name: internal ★ > callbacks description: Webhook receivers for eNotas, Serpro, and InfoSimples async callbacks. x-tagGroups: - name: ACCESS tags: - access > external-app-tokens - access > sessions - name: ACCOUNTS tags: - accounts - accounts > fiscal entities - accounts > fiscal entities > certificate - accounts > fiscal entities > mei - accounts > fiscal entities > pass-gov - accounts > fiscal entities > pass-invoices - accounts > invoices - accounts > professional contracts - accounts > professional invoices - accounts > recipient - accounts > resources - name: BUSINESSES tags: - businesses - businesses > categories - businesses > documents - businesses > fiscal entities - businesses > fiscal entities > certificate - businesses > fiscal entities > diagnosis - businesses > fiscal entities > invoices-emission - businesses > fiscal entities > pass-gov - businesses > fiscal entities > pass-invoices - businesses > fiscal entities > revenue - businesses > professional categories - businesses > professional invoices - businesses > representatives - businesses > requests - businesses > schedules - businesses > services - businesses > settings - name: PROFESSIONALS tags: - professionals - professionals > contracts - professionals > documents - professionals > fiscal entities - professionals > fiscal entities > certificate - professionals > fiscal entities > diagnosis - professionals > fiscal entities > invoices-emission - professionals > fiscal entities > pass-gov - professionals > fiscal entities > pass-invoices - professionals > fiscal entities > revenue - professionals > requests - name: INTERNAL ★ tags: - internal ★ > buyer fiscal entities - internal ★ > callbacks - internal ★ > fiscal entities - internal ★ > fiscal entities > certificate - internal ★ > fiscal entities > invoices - internal ★ > fiscal entities > invoices-emission - internal ★ > fiscal entities > mei - internal ★ > fiscal entities > pass-gov - internal ★ > fiscal entities > pass-invoices - internal ★ > fiscal entities > requests - internal ★ > fiscal entities > revenue - internal ★ > search - name: PLATFORM tags: - platform > constants - platform > resources components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT bearer token. See `/auth`. schemas: Account: title: Account description: >- A user account on the platform — the human who logs in via email/password and owns one or more Businesses. Represents a person authenticated through the **access** service. Holds personal data (name, email, phone, locale), authentication state (`has-password`, `is-validated`) and is the root of permission grants for every Business the user belongs to. type: object properties: id: type: string type: type: string enum: - accounts attributes: type: object properties: email: type: string name: type: string phone-number: type: string nullable: true phone-country: type: string nullable: true tax-number: type: string nullable: true locale: type: string example: pt-BR has-password: type: boolean is-validated: type: boolean mobile-token: type: string nullable: true birthday: type: string format: date nullable: true extra: type: object nullable: true source: type: string nullable: true terms: type: object nullable: true personal-data: type: object nullable: true account-type: type: string nullable: true created-at: type: string format: date-time updated-at: type: string format: date-time relationships: type: object properties: businesses: type: object properties: data: type: array items: type: object properties: id: type: string type: type: string enum: - businesses AccountType: title: AccountType description: Resource of type `AccountType`. type: object properties: id: type: string type: type: string enum: - account-types attributes: type: object properties: name: type: string AccountFiscalEntity: title: AccountFiscalEntity description: Resource of type `AccountFiscalEntity`. type: object properties: id: type: string type: type: string enum: - account-fiscal-entities attributes: type: object properties: name: type: string email: type: string nullable: true address: type: string nullable: true status: type: string document-type: type: string tax-number: type: string tax-country: type: string tax-data: type: object nullable: true emission-status: type: string nullable: true certificate-expiration-date: type: string format: date nullable: true das-paid-by: type: string nullable: true status-pass-govs: type: string example: missing_setup status-pass-invoices: type: string example: missing_setup status-certificate: type: string example: missing_setup has-pass-gov: type: boolean has-pass-invoices: type: boolean has-certificate: type: boolean created-at: type: string format: date-time updated-at: type: string format: date-time created-by: type: string nullable: true updated-by: type: string nullable: true relationships: type: object properties: account: type: object properties: data: type: object properties: id: type: string type: type: string enum: - accounts PaymentsRecipient: title: PaymentsRecipient description: Resource of type `PaymentsRecipient`. type: object properties: id: type: string type: type: string enum: - billing-recipients attributes: type: object properties: bank-account: type: object nullable: true providers: type: object nullable: true pix-info: type: object nullable: true created-at: type: string format: date-time updated-at: type: string format: date-time relationships: type: object properties: business: type: object properties: data: type: object properties: id: type: string type: type: string enum: - businesses Permission: title: Permission description: Resource of type `Permission`. type: object properties: id: type: string type: type: string enum: - permissions attributes: type: object properties: name: type: string Phone: title: Phone description: Resource of type `Phone`. type: object properties: id: type: string type: type: string enum: - phones attributes: type: object properties: country: type: string number: type: string PinCred: title: PinCred description: Resource of type `PinCred`. type: object properties: id: type: string type: type: string enum: - pin-creds attributes: type: object properties: pin: type: string Session: title: Session description: >- An authenticated session — credentials traded for a short-lived JWT bearer token. Created via `POST /sessions` with email/password. The response carries the bearer token used in `Authorization: Bearer …` for every subsequent call. Sessions can be listed and revoked. type: object properties: id: type: string type: type: string enum: - sessions attributes: type: object properties: token: type: string email: type: string type: type: string example: email created-at: type: string format: date-time Business: title: Business description: >- A salon or beauty business owned by an Account — the tenant boundary identified by the `ilm-business` header. Represents a salon, studio, or independent professional registered as a tenant. Almost every other resource (Professionals, Invoices, Schedules, Fiscal Entities) is scoped to a Business. The numeric id appears in the `ilm-business` header and in nested URLs like `/businesses/{businessId}/…`. type: object properties: id: type: string type: type: string enum: - businesses attributes: type: object properties: name: type: string trading-name: type: string nullable: true document: type: string document-type: type: string example: cnpj brand: type: string nullable: true culture: type: string nullable: true locale: type: string example: pt-BR timezone: type: string nullable: true permalink: type: string nullable: true country-iso: type: string nullable: true created-at: type: string format: date-time updated-at: type: string format: date-time relationships: type: object properties: account: type: object properties: data: type: object properties: id: type: string type: type: string enum: - accounts category: type: object properties: data: type: object properties: id: type: string type: type: string enum: - business-categories week-schedule: type: object properties: data: type: object properties: id: type: string type: type: string enum: - week-schedules professionals: type: object properties: data: type: array items: type: object properties: id: type: string type: type: string enum: - professionals professional-categories: type: object properties: data: type: array items: type: object properties: id: type: string type: type: string enum: - professional-categories settings: type: object properties: data: type: array items: type: object properties: id: type: string type: type: string enum: - business-settings Professional: title: Professional description: >- A beauty professional (hairdresser, manicurist, esthetician, …) working under a Business. A worker who renders services and may issue invoices through the platform. Linked to a ProfessionalContract with the Business and to a ProfessionalFiscalEntity (their MEI / CNPJ) used for invoice emission. type: object properties: id: type: string type: type: string enum: - professionals attributes: type: object properties: name: type: string initials: type: string nullable: true email: type: string phone-number: type: string nullable: true phone-country: type: string nullable: true phone-composed: type: string nullable: true individual-tax-number: type: string nullable: true birth-date: type: string format: date nullable: true address: type: object nullable: true gender: type: string nullable: true marital-status: type: string nullable: true rg: type: string nullable: true issuing-organization: type: string nullable: true shipping-date: type: string format: date nullable: true national-identification-data: type: object nullable: true is-active: type: boolean category-key: type: string nullable: true created-at: type: string format: date-time updated-at: type: string format: date-time relationships: type: object properties: account: type: object properties: data: type: object properties: id: type: string type: type: string enum: - accounts business: type: object properties: data: type: object properties: id: type: string type: type: string enum: - businesses category: type: object properties: data: type: object properties: id: type: string type: type: string enum: - professional-categories permissions-group: type: object properties: data: type: object properties: id: type: string type: type: string enum: - permissions-groups ProfessionalFiscalEntity: title: ProfessionalFiscalEntity description: >- The fiscal entity (CPF/CNPJ, usually a MEI) belonging to a Professional — the issuer of their invoices. A SellerFiscalEntity owned by a Professional. Stores CNPJ (when MEI), CPF, digital certificate, MEI registration data, and PassGov credentials needed to query Receita Federal services on the Professional's behalf. The `certificate_expiration_date` attribute is sourced from the linked `fiscal-entity-certificates.expiration_date` row (single source of truth — updated automatically on certificate upload, absent when no active certificate is on file). type: object properties: id: type: string type: type: string enum: - professional-fiscal-entities attributes: type: object properties: name: type: string email: type: string nullable: true address: $ref: '#/components/schemas/Address' status: type: string document-type: type: string tax-number: type: string tax-country: type: string tax-data: $ref: '#/components/schemas/TaxData' emission-status: type: string example: missing_setup certificate-expiration-date: type: string format: date nullable: true das-paid-by: type: string nullable: true status-pass-govs: type: string example: missing_setup status-pass-invoices: type: string example: missing_setup status-certificate: type: string example: missing_setup has-pass-gov: type: boolean has-pass-invoices: type: boolean has-certificate: type: boolean created-at: type: string format: date-time updated-at: type: string format: date-time created-by: type: string nullable: true updated-by: type: string nullable: true relationships: type: object properties: professional: type: object properties: data: type: object properties: id: type: string type: type: string enum: - professionals BusinessFiscalEntity: title: BusinessFiscalEntity description: >- The fiscal entity (CNPJ/CPF) owned by a Business — the issuer of invoices on the salon's behalf. A SellerFiscalEntity scoped to a Business. Holds the salon's CNPJ, address, MEI registration data, digital certificate, and PassGov credentials used to talk to government services. The `certificate_expiration_date` attribute is sourced from the linked `fiscal-entity-certificates.expiration_date` row (single source of truth — updated automatically on certificate upload, absent when no active certificate is on file). type: object properties: id: type: string type: type: string enum: - business-fiscal-entities attributes: type: object properties: name: type: string email: type: string nullable: true address: $ref: '#/components/schemas/Address' status: type: string document-type: type: string tax-number: type: string tax-country: type: string tax-data: $ref: '#/components/schemas/TaxData' emission-status: type: string example: missing_setup certificate-expiration-date: type: string format: date nullable: true status-pass-govs: type: string example: missing_setup status-pass-invoices: type: string example: missing_setup status-certificate: type: string example: missing_setup has-pass-gov: type: boolean has-pass-invoices: type: boolean has-certificate: type: boolean created-at: type: string format: date-time updated-at: type: string format: date-time created-by: type: string nullable: true updated-by: type: string nullable: true relationships: type: object properties: business: type: object properties: data: type: object properties: id: type: string type: type: string enum: - businesses ProfessionalContract: title: ProfessionalContract description: >- The contractual relationship between a Business and a Professional. Tracks the agreement that authorizes a Professional to operate under a Business. Status flows: `filling` → `approved` → (active) → `terminated`. Two PDF slots: `pdf_url` for the signed contract (set by `new_contract_pdf`) and `termination_pdf_url` for the signed distrato (set by `terminate_contract` — either at create time via `data.pdf_url`, or at the status→closed transition via a top-level `termination_pdf_url` field). When `terminate_contract` is created with `data.pdf_url`, the contract is driven directly `approved` → `terminated` (skipping `termination_requested`) and the BusinessRequest goes directly to `closed` (skipping `open`) — mirrors the `new_contract_pdf` flow. The `termination_pdf_url` column can only be set while the contract is in `termination_requested` or `terminated` and is locked once populated; further attempts error with `422 TerminationPdfUrlAlreadySet`. type: object properties: id: type: string type: type: string enum: - professional-contracts attributes: type: object properties: status: type: string example: approved contract-status: type: string example: approved pdf-url: type: string format: uri nullable: true termination-pdf-url: type: string format: uri nullable: true termination-business-request-id: type: string nullable: true partnership-start-date: type: string format: date nullable: true partnership-end-date: type: string format: date nullable: true created-at: type: string format: date-time updated-at: type: string format: date-time relationships: type: object properties: business: type: object properties: data: type: object properties: id: type: string type: type: string enum: - businesses professional: type: object properties: data: type: object properties: id: type: string type: type: string enum: - professionals business-request: type: object properties: data: type: object properties: id: type: string type: type: string enum: - business-requests ProfessionalInvoice: title: ProfessionalInvoice description: >- A NFS-e (electronic service invoice) issued for services rendered by a Professional. Represents a Brazilian electronic service invoice (NFS-e) emitted through the eNotas integration on behalf of a Professional. Lifecycle: `pending → requested → succeeded | failed`. Cancellation lifecycle: `pending-cancelation → requested-cancelation → canceled | failed-cancelation`. type: object properties: id: type: string type: type: string enum: - professional-invoices attributes: type: object properties: invoice-type: type: string nullable: true items: type: array items: type: object nullable: true buyer-id: type: string nullable: true buyer-type: type: string nullable: true buyer-data: type: object nullable: true status: type: string example: succeeded cancel-status: type: string nullable: true status-reason: type: string nullable: true cancel-reason: type: string nullable: true emission-date: type: string format: date nullable: true fiscal-date: type: string format: date nullable: true nfse-url: type: string format: uri nullable: true total-value-cents: type: integer nullable: true source: type: string nullable: true invoice-id: type: string nullable: true created-at: type: string format: date-time updated-at: type: string format: date-time created-by: type: string nullable: true updated-by: type: string nullable: true relationships: type: object properties: business: type: object properties: data: type: object properties: id: type: string type: type: string enum: - businesses professional: type: object properties: data: type: object properties: id: type: string type: type: string enum: - professionals professional-fiscal-entity: type: object properties: data: type: object properties: id: type: string type: type: string enum: - professional-fiscal-entities business-request: type: object properties: data: type: object properties: id: type: string type: type: string enum: - business-requests Invoice: title: Invoice description: >- An invoice record managed by the accounting service — tracks NFS-e emission, tax breakdown, and provider status. The accounting-side invoice record created when a ProfessionalInvoice is emitted. Stores tax breakdown (IRRF, PIS, COFINS, CSLL, ISS), NFS-e number/verification code, and the external provider status. Linked to a SellerFiscalEntity (issuer) and BuyerFiscalEntity (receiver). Status follows the accounting service lifecycle: `pending → requested → succeeded | failed`. Cancellation: `pending-cancelation → requested-cancelation → canceled | failed-cancelation`. type: object properties: id: type: string type: type: string enum: - invoices attributes: type: object properties: competency-date: type: string format: date nfse-number: type: string nullable: true nfse-verification-code: type: string nullable: true nfse-url: type: string format: uri nullable: true amount-cents: type: integer tax-irrf-cents: type: integer tax-pis-cents: type: integer tax-cofins-cents: type: integer tax-csll-cents: type: integer tax-iss-cents: type: integer status: type: string example: succeeded cancel-status: type: string nullable: true provider-id: type: string nullable: true provider-status: type: string nullable: true emission-date: type: string format: date nullable: true fiscal-date: type: string format: date nullable: true created-at: type: string format: date-time updated-at: type: string format: date-time relationships: type: object properties: seller-fiscal-entity: type: object properties: data: type: object properties: id: type: string type: type: string enum: - seller-fiscal-entities buyer-fiscal-entity: type: object properties: data: type: object properties: id: type: string type: type: string enum: - buyer-fiscal-entities BuyerFiscalEntity: title: BuyerFiscalEntity description: >- A customer fiscal entity (CPF/CNPJ) — the receiver named on invoices issued by Professionals. Stores the tax data required to address an NFS-e to a customer (individual or company). Reused across many ProfessionalInvoices. type: object properties: id: type: string type: type: string enum: - buyer-fiscal-entities attributes: type: object properties: tax-number: type: string tax-type: type: string example: cpf name: type: string email: type: string nullable: true phone: type: string nullable: true address: $ref: '#/components/schemas/Address' created-at: type: string format: date-time updated-at: type: string format: date-time BusinessRequest: title: BusinessRequest description: >- A workflow envelope for asynchronous business operations (contract creation, batch invoice emission, contract termination, …). Wraps multi-step operations whose progress is tracked separately from a normal CRUD response. Known kinds: `new_contract`, `new_contract_pdf`, `professional_invoice_emission`, `terminate_contract`. Status flows: `draft → open → closed` (with `processing`/`waiting` in between) and a side `canceled` branch. The `data` JSON payload is validated against the kind-specific schema in `Schemas::BusinessRequestSchemas` (e.g. `TERMINATE_CONTRACT` for termination requests). For `terminate_contract`, an optional `data.pdf_url` field can carry a signed distrato PDF at create time; alternatively, a top-level `termination_pdf_url` can be sent in the status-update payload when transitioning the request to `closed` — this writes to `ProfessionalContract.termination_pdf_url` directly, bypassing the `data` immutability guard. type: object properties: id: type: string type: type: string enum: - business-requests attributes: type: object properties: type: type: string example: new_contract status: type: string example: open data: type: object artifacts: type: object nullable: true created-at: type: string format: date-time created-by: type: string nullable: true updated-at: type: string format: date-time updated-by: type: string nullable: true submitted-at: type: string format: date-time nullable: true submitted-by: type: string nullable: true canceled-at: type: string format: date-time nullable: true canceled-by: type: string nullable: true relationships: type: object properties: business: type: object properties: data: type: object properties: id: type: string type: type: string enum: - businesses Resource: title: Resource description: >- An uploaded blob (PDF, image, certificate) referenced from other resources by id. Generic file upload. The response returns an id used to attach the blob to other resources (e.g. contract PDFs, certificate files). type: object properties: id: type: string type: type: string enum: - resources attributes: type: object properties: url: type: string format: uri content-type: type: string filename: type: string byte-size: type: integer created-at: type: string format: date-time Representative: title: Representative description: >- The legal representative (Person) registered for a Business. Stores the responsible person's identification (name, CPF, contact). Required by eNotas / Serpro when issuing invoices on the Business's behalf. type: object properties: id: type: string type: type: string enum: - representatives attributes: type: object properties: name: type: string surname: type: string nullable: true gender: type: string nullable: true email: type: string nullable: true contact: type: string nullable: true cpf: type: string rg: type: string nullable: true issuing-organization: type: string nullable: true shipping-date: type: string format: date nullable: true address-postal: type: string nullable: true address-street: type: string nullable: true address-neighborhood: type: string nullable: true address-number: type: string nullable: true address-complement: type: string nullable: true address-city: type: string nullable: true address-state: type: string nullable: true marital-status: type: string nullable: true birthday: type: string format: date nullable: true business-id: type: string nullable: true created-at: type: string format: date-time updated-at: type: string format: date-time relationships: type: object properties: businesses: type: object properties: data: type: array items: type: object properties: id: type: string type: type: string enum: - businesses ExternalAppToken: title: ExternalAppToken description: >- An API key for external app integrations — scoped access without user credentials. Allows third-party systems to call the API using a static key instead of user JWTs. The gateway validates the key, generates a short-lived `external-app` JWT, and caches it for 5 minutes. Managed by admins via `/external-app-tokens` CRUD. type: object properties: id: type: string type: type: string enum: - external-app-tokens attributes: type: object properties: name: type: string key: type: string scopes: type: array items: type: string expires-at: type: string format: date-time nullable: true created-at: type: string format: date-time PassGov: title: PassGov description: >- Gov.br credentials (CPF + password) stored for automated government service access. Stores the gov.br login used to query Receita Federal on the FiscalEntity's behalf — e.g., to fetch DAS, diagnoses, and CND documents. Credentials are encrypted at rest. `PATCH .../pass-gov/validate` tests the credentials live against the government portal and updates `validation_status`. On `PATCH .../pass-gov`, sending `password: ""` clears the stored password, sets `status` to `inactive` and `validation_status` to `none`. The create endpoint requires a non-empty password. Validation runs automatically when credentials are saved or updated. type: object properties: id: type: string type: type: string enum: - fiscal-entity-pass-govs attributes: type: object properties: cpf: type: string password: type: string status: type: string example: active validation-status: type: string example: none validation-errors: type: array items: type: string nullable: true validation-at: type: string format: date-time nullable: true validation-by-id: type: string nullable: true created-at: type: string format: date-time created-by: type: string nullable: true updated-at: type: string format: date-time updated-by: type: string nullable: true relationships: type: object properties: business: type: object properties: data: type: object properties: id: type: string type: type: string enum: - businesses professional: type: object properties: data: type: object properties: id: type: string type: type: string enum: - professionals PassInvoice: title: PassInvoice description: >- Prefeitura NFS-e portal credentials for a FiscalEntity. Stores the login/password for the municipal NFS-e issuing system (prefeitura). Required when the municipality does not support direct integration via eNotas and invoices must be issued through the city portal. Managed separately from PassGov. `PATCH .../pass-invoices/validate` tests the credentials live against the external revenue API and updates `validation_status`. On `PATCH .../pass-invoices`, sending `password: ""` clears the stored password, sets `status` to `inactive` and `validation_status` to `none`. The create endpoint requires a non-empty password. Validation runs automatically when credentials are saved or updated. type: object properties: id: type: string type: type: string enum: - fiscal-entity-pass-invoices attributes: type: object properties: authentication-type: type: string example: pass_only username: type: string nullable: true login: type: string password: type: string status: type: string example: active validation-status: type: string example: none validation-errors: type: array items: type: string nullable: true validation-at: type: string format: date-time nullable: true validation-by-id: type: string nullable: true created-at: type: string format: date-time created-by: type: string nullable: true updated-at: type: string format: date-time updated-by: type: string nullable: true relationships: type: object properties: business: type: object properties: data: type: object properties: id: type: string type: type: string enum: - businesses professional: type: object properties: data: type: object properties: id: type: string type: type: string enum: - professionals FiscalEntityCertificate: title: FiscalEntityCertificate description: >- Digital certificate (PKCS#12) stored for a FiscalEntity, used to authenticate with the NFS-e issuing portal. Stores the PKCS#12 (.pfx) digital certificate bytes (in S3) and the encrypted password. `PATCH .../certificate/validate` downloads the .pfx from S3, decrypts the password, and tests the certificate against the external revenue API. Validation runs automatically when a new file or password is saved. Setting `password: ""` deactivates the certificate, clears the stored password and S3 key, and resets `validation_status` to `none`. The upload endpoints require a non-empty password. type: object properties: id: type: string type: type: string enum: - fiscal-entity-certificates attributes: type: object properties: expiration-date: type: string format: date nullable: true status: type: string example: active validation-status: type: string example: none validation-errors: type: array items: type: string nullable: true validation-at: type: string format: date-time nullable: true validation-by-id: type: string nullable: true s3-key: type: string nullable: true created-at: type: string format: date-time created-by: type: string nullable: true updated-at: type: string format: date-time updated-by: type: string nullable: true relationships: type: object properties: business: type: object properties: data: type: object properties: id: type: string type: type: string enum: - businesses professional: type: object properties: data: type: object properties: id: type: string type: type: string enum: - professionals WeekSchedule: title: WeekSchedule description: >- Weekly working hours for a Business or Professional. Holds the recurring weekly availability used by booking flows: open/close time per weekday, breaks, and exceptions. type: object properties: id: type: string type: type: string enum: - week-schedules attributes: type: object properties: time-intervals: type: array items: type: array items: type: string nullable: true created-at: type: string format: date-time updated-at: type: string format: date-time relationships: type: object properties: business: type: object properties: data: type: object properties: id: type: string type: type: string enum: - businesses BusinessCategory: title: BusinessCategory description: Resource of type `BusinessCategory`. type: object properties: id: type: string type: type: string enum: - business-categories attributes: type: object properties: name: type: string professional-categories: type: array items: type: object nullable: true BusinessSetting: title: BusinessSetting description: Resource of type `BusinessSetting`. type: object properties: id: type: string type: type: string enum: - business-settings attributes: type: object properties: group-name: type: string name: type: string value: type: string nullable: true relationships: type: object properties: business: type: object properties: data: type: object properties: id: type: string type: type: string enum: - businesses ProfessionalCategory: title: ProfessionalCategory description: Resource of type `ProfessionalCategory`. type: object properties: id: type: string type: type: string enum: - professional-categories attributes: type: object properties: name: type: string color: type: string nullable: true translation-key: type: string nullable: true sort-weight: type: integer nullable: true is-locked: type: boolean nullable: true created-at: type: string format: date-time updated-at: type: string format: date-time relationships: type: object properties: permissions-group: type: object properties: data: type: object properties: id: type: string type: type: string enum: - permissions-groups ProfessionalService: title: ProfessionalService description: Resource of type `ProfessionalService`. type: object properties: id: type: string type: type: string enum: - professional-services attributes: type: object properties: services: type: array items: type: object nullable: true pay-periodicity: type: string nullable: true created-at: type: string format: date-time updated-at: type: string format: date-time relationships: type: object properties: business: type: object properties: data: type: object properties: id: type: string type: type: string enum: - businesses professional: type: object properties: data: type: object properties: id: type: string type: type: string enum: - professionals PersonalDocument: title: PersonalDocument description: >- An identity or supporting document attached to a Professional or Account. Stores uploaded identity documents (RG, CNH, CPF, address proof, etc.) required for compliance checks, contract approval, or fiscal entity registration. Each document has a type, file URL, and validation status. type: object properties: id: type: string type: type: string enum: - personal-documents attributes: type: object properties: document-type: type: string data: type: object nullable: true front-url: type: string format: uri nullable: true back-url: type: string format: uri nullable: true foreign-type: type: string nullable: true foreign-id: type: string nullable: true created-at: type: string format: date-time updated-at: type: string format: date-time relationships: type: object properties: account: type: object properties: data: type: object properties: id: type: string type: type: string enum: - accounts ServiceCategory: title: ServiceCategory description: Resource of type `ServiceCategory`. type: object properties: id: type: string type: type: string enum: - service-categories attributes: type: object properties: translation-key: type: string nullable: true level: type: integer nullable: true service-category-id: type: string nullable: true Diagnosis: title: Diagnosis description: >- A fiscal compliance diagnostic result for a MEI FiscalEntity. Captures the result of querying Receita Federal / government services for pending issues (debts, certificate problems, registration inconsistencies) that would block NFS-e emission. A diagnosis is triggered on demand and may contain multiple issue entries. type: object properties: id: type: string type: type: string enum: - fiscal-entity-diagnoses attributes: type: object properties: status: type: string result: type: object nullable: true checked-at: type: string format: date-time nullable: true created-at: type: string format: date-time updated-at: type: string format: date-time relationships: type: object properties: fiscal-entity: type: object properties: data: type: object properties: id: type: string type: type: string enum: - professional-fiscal-entities - business-fiscal-entities - account-fiscal-entities Das: title: Das description: >- A monthly DAS (Documento de Arrecadação do Simples Nacional) record for a MEI. The monthly tax payment slip mandatory for MEI companies. Fetched from Serpro/InfoSimples for each month of the year. Status indicates whether the DAS has been paid, is overdue, or is pending fetch. The `PATCH` endpoint requests an update from the government source. type: object properties: id: type: string type: type: string enum: - fiscal-entity-dases attributes: type: object properties: competence: type: string nullable: true due-date: type: string format: date nullable: true amount-cents: type: integer nullable: true status: type: string barcode: type: string nullable: true created-at: type: string format: date-time updated-at: type: string format: date-time relationships: type: object properties: fiscal-entity: type: object properties: data: type: object properties: id: type: string type: type: string enum: - professional-fiscal-entities - business-fiscal-entities - account-fiscal-entities FiscalEntityRevenue: title: FiscalEntityRevenue description: >- Monthly fiscal entity gross revenue record used for annual limits tracking. Stores the declared monthly revenue for a seller fiscal entity. For MEI entities, the annual limit is R$81k/year (sum of current year). For non-MEI entities, the limit is platform-configurable and uses trailing-12-month calculation. The `PATCH` endpoint triggers an asynchronous refresh from the revenue provider. When refresh is in flight, the record `data` JSONB may carry a `revenue_job_id` (string) pointing to the async job on the external revenue API; on completion the poller removes the field and writes the final `succeeded`/`errored` status. type: object properties: id: type: string type: type: string enum: - fiscal-entity-revenues attributes: type: object properties: month: type: string nullable: true gross-amount: type: number nullable: true tax-number: type: string nullable: true tax-country: type: string nullable: true created-at: type: string format: date-time updated-at: type: string format: date-time relationships: type: object properties: professional: type: object properties: data: type: object properties: id: type: string type: type: string enum: - professionals FiscalEntityRevenueResume: title: FiscalEntityRevenueResume description: >- Revenue resume aggregated per fiscal entity across a business. Returned by `GET /professional-fiscal-entities/revenue`, `GET /businesses/{businessId}/revenue`, and `GET /fiscal-entities/revenue` (proxied from the accounting service). One entry per seller fiscal entity of the business, with the sum of succeeded monthly revenue records for the relevant period (yearly for MEI, trailing 12 months for non-MEI). The `api_status` reflects the aggregated health of the underlying monthly records (`errored` > `processing` > `succeeded`). The `total_revenue_status` compares actual total revenue against the annual limit (`ok`/`nok`). The `projected_revenue_status` projects current revenue forward using two configurable thresholds (`ok`/`warning_low`/`warning_high`). The `calculation_type` distinguishes `yearly` (MEI, calendar-year sum) from `trailing` (non-MEI, rolling 12-month sum). Errored and processing months are listed in `errored_months` and `processing_months` respectively. A `last_updated_at` field (RFC 3339) reflects the most recent update timestamp across all underlying revenue records. The response is JSON:API with a `fiscal-entity` relationship. type: object properties: id: type: string type: type: string enum: - fiscal-entity-revenue-resumes attributes: type: object properties: year: type: integer nullable: true total-gross-amount: type: number nullable: true total-months: type: integer nullable: true limit-amount: type: number nullable: true created-at: type: string format: date-time updated-at: type: string format: date-time relationships: type: object properties: fiscal-entity: type: object properties: data: type: object properties: id: type: string type: type: string enum: - professional-fiscal-entities - business-fiscal-entities - account-fiscal-entities SellerFiscalEntity: title: SellerFiscalEntity description: >- A seller fiscal entity (CPF/CNPJ) in the accounting service — the issuer of invoices. Represents a fiscal entity registered in the accounting service for invoice emission. Stores tax number, address, certificate expiration, MEI registration, and emission status. Linked to an Account and optionally to a parent fiscal entity and MEI data. The `certificate_expiration_date` is sourced from the linked `fiscal-entity-certificates.expiration_date` row. The `emission_status` tracks whether the entity can emit invoices (`missing_setup` → `missing_auth` → `missing_validation` → `active` | `inactive`); `missing_auth` means the eNotas company account exists but no credentials have been sent yet. The `status_pass_govs`, `status_pass_invoices`, and `status_certificate` fields expose the current state of linked credentials and certificates. type: object properties: id: type: string type: type: string enum: - fiscal-entities attributes: type: object properties: name: type: string email: type: string nullable: true address: $ref: '#/components/schemas/Address' status: type: string emission-status: type: string certificate-expiration-date: type: string format: date-time nullable: true das-paid-by: type: integer nullable: true status-pass-govs: type: string status-pass-invoices: type: string status-certificate: type: string has-pass-gov: type: boolean has-pass-invoices: type: boolean has-certificate: type: boolean document-type: type: string tax-number: type: string tax-country: type: string tax-data: $ref: '#/components/schemas/TaxData' extra: $ref: '#/components/schemas/ExtraData' emission-validated-at: type: string format: date-time nullable: true last-emission-validation: $ref: '#/components/schemas/EmissionValidation' nullable: true foreign-id: type: integer nullable: true foreign-type: type: string nullable: true created-at: type: string format: date-time created-by: type: integer nullable: true updated-at: type: string format: date-time updated-by: type: integer nullable: true relationships: type: object properties: parent-fiscal-entity: type: object properties: data: type: object properties: id: type: string type: type: string enum: - fiscal-entities account: type: object properties: data: type: object properties: id: type: string type: type: string enum: - accounts fiscal-entity-mei: type: object properties: data: type: object properties: id: type: string type: type: string enum: - fiscal-entity-meis EmissionValidation: title: EmissionValidation description: >- The result of a test-invoice emission validation attempt for a seller fiscal entity. Returned by the emission validation endpoints (`POST/GET /invoices-emission/validate`, `POST /validate-emission`, `GET /validation-status`). Each record represents one validation attempt: a zero-value test NFS-e is emitted through eNotas, and the callback updates the status to `succeeded` or `failed`. The `status` field is the last entry of the internal `statuses` audit trail (`none` → `validating` → `succeeded` / `failed`). `author` and `author_type` identify who requested the validation, captured from the request context. `authentication_type` records which credential was used (`pass_only`, `token`, `user_and_pass`, or `certificate`). `canceled_at` is set when the test invoice is queued for cancellation after a successful validation. `is_valid` reflects whether the seller fiscal entity is currently emission-validated. The `invoice` relationship points to the test invoice created for this validation. type: object properties: id: type: string type: type: string enum: - emission-validations attributes: type: object properties: status: type: string enum: - none - validating - succeeded - failed author: type: string nullable: true author-type: type: string nullable: true authentication-type: type: string enum: - pass_only - token - user_and_pass - certificate nullable: true attempted-at: type: string format: date-time completed-at: type: string format: date-time nullable: true canceled-at: type: string format: date-time nullable: true invoice-status: type: string nullable: true error: type: object nullable: true municipal-data: type: object nullable: true is-valid: type: boolean relationships: type: object properties: invoice: type: object properties: data: type: object properties: id: type: string type: type: string enum: - invoices FiscalEntityRequest: title: FiscalEntityRequest description: >- A request record for fiscal entity operations (CNPJ validation, document uploads, government service queries). Tracks asynchronous fiscal entity operations such as CNPJ validation, document fetch, or government service queries. Each request has a category, processing status, and optional error details. Linked to a parent fiscal entity. type: object properties: id: type: string type: type: string enum: - fiscal-entity-requests attributes: type: object properties: category: type: string details: type: object process-status: type: string status: type: string error-status: type: string nullable: true created-at: type: string format: date-time updated-at: type: string format: date-time relationships: type: object properties: fiscal-entity: type: object properties: data: type: object properties: id: type: string type: type: string enum: - fiscal-entities FiscalEntityMei: title: FiscalEntityMei description: >- MEI (Microempreendedor Individual) registration data for a fiscal entity — CNPJ details, CCMEI number, and compliance status. Stores the MEI-specific registration data for a fiscal entity including CNPJ details (situation, update timestamp), CCMEI number and situation, and overall MEI status. Linked to a parent fiscal entity. The CNPJ and CCMEI sub-objects track the raw government data and when it was last refreshed. type: object properties: id: type: string type: type: string enum: - fiscal-entity-meis attributes: type: object properties: tax-number: type: string cnpj: type: object properties: cnpj: type: string situation: type: string updated-at: type: string format: date-time ccmei: type: object properties: ccmei-number: type: string situation: type: string updated-at: type: string format: date-time status: type: string relationships: type: object properties: fiscal-entity: type: object properties: data: type: object properties: id: type: string type: type: string enum: - fiscal-entities FiscalEntityMeiCnd: title: FiscalEntityMeiCnd description: >- Certidão Negativa de Débitos (CND) — tax clearance certificate for a MEI fiscal entity. Stores the CND (negative tax certificate) for a MEI fiscal entity. The CND confirms the entity has no outstanding tax debts. Status tracks the validation state; details and extra contain the government response data. Linked to a parent MEI entity. type: object properties: id: type: string type: type: string enum: - fiscal-entity-mei-cnds attributes: type: object properties: updated-at: type: string format: date-time status: type: string details: type: object extra: type: object relationships: type: object properties: fiscal-entity-mei: type: object properties: data: type: object properties: id: type: string type: type: string enum: - fiscal-entity-meis FiscalEntityMeiDasn: title: FiscalEntityMeiDasn description: >- Declaração Anual do Simples Nacional (DASN) — annual MEI revenue declaration. Stores the annual DASN declaration for a MEI fiscal entity. The DASN is the yearly revenue declaration required for MEI companies. Status tracks the declaration state. Linked to an account and a fiscal entity. type: object properties: id: type: string type: type: string enum: - fiscal-entity-mei-dasns attributes: type: object properties: status: type: string relationships: type: object properties: account: type: object properties: data: type: object properties: id: type: string type: type: string enum: - accounts fiscal-entity: type: object properties: data: type: object properties: id: type: string type: type: string enum: - fiscal-entities FiscalEntityMeiCcmei: title: FiscalEntityMeiCcmei description: >- Cartão CNPJ do MEI (CCMEI) — MEI card document for a fiscal entity. Stores the CCMEI (MEI card) document data for a fiscal entity. The CCMEI is an official document proving MEI registration. Status tracks the document state; details and extra contain the government response data. Linked to a parent MEI entity. type: object properties: id: type: string type: type: string enum: - fiscal-entity-mei-ccmeis attributes: type: object properties: updated-at: type: string format: date-time status: type: string details: type: object extra: type: object relationships: type: object properties: fiscal-entity-mei: type: object properties: data: type: object properties: id: type: string type: type: string enum: - fiscal-entity-meis TaxData: title: TaxData description: >- Tax and fiscal configuration data for a seller fiscal entity — enterprise info, tax system, rules, and municipal parameters. Embedded object on SellerFiscalEntity and BusinessFiscalEntity containing the fiscal entity's tax registration data: enterprise type/name, tax system (MEI/Simples Nacional status), CNAE codes, municipal jurisdiction, ISS aliquota, and regime especial tributacao. The `enterprise-tax-system` sub-object tracks MEI and Simples Nacional status with optional date intervals. The `rules` sub-object indicates which fields are active for this entity (e.g. whether `descricao_servico` or `item_lista_servico` are used). The `extra` sub-object contains CNAE list and partner info. Sourced from InfoSimples and updated on revalidation. type: object properties: fantasy-name: type: string enterprise-type: type: string enterprise-name: type: string enterprise-tax-system: $ref: '#/components/schemas/TaxSystem' phone-country: type: string phone-number: type: string extra: $ref: '#/components/schemas/ExtraData' cnae: type: string rules: $ref: '#/components/schemas/TaxRules' serie-nfe: type: string codigo-nbs: type: string aliquota-iss: type: number razao-social: type: string nome-fantasia: type: string codigo-ibge-uf: type: string sequencial-nfe: type: string tipo-autenticacao: type: integer codigo-ibge-cidade: type: string inscricao-estadual: type: string telefone-comercial: type: string inscricao-municipal: type: string sequencial-lote-nfe: type: string item-lista-servico-lc: type: string municipal-jurisdiction: type: string codigo-servico-municipal: type: string optante-simples-nacional: type: boolean codigo-tributacao-nacional: type: string regime-especial-tributacao: type: string regime-especial-tributacao-label: type: string TaxSystem: title: TaxSystem description: >- MEI and Simples Nacional tax regime status for a fiscal entity. Embedded within TaxData. Tracks whether the entity is MEI (`is-mei`), enrolled in Simples Nacional (`is-simples`), and the date intervals for Simples participation (`is-simples-intervals`). The `situacao-cadastral` object holds the Receita Federal cadastral situation. type: object properties: country: type: string is-mei: type: boolean is-simples: type: boolean is-simples-intervals: type: array items: type: object properties: data-inicio: type: string data-fim: type: string situacao-cadastral: type: object is-simples-start-date: type: string format: date is-simples-end-date: type: string format: date TaxRules: title: TaxRules description: >- Flags indicating which tax fields are active for a fiscal entity. Embedded within TaxData. Boolean flags that control which fields are relevant for this entity's tax regime: `uses-descricao-servico`, `uses-item-lista-servico`, `uses-codigo-servico-municipal`, `uses-regime-especial-tributacao`. These flags drive form visibility in the UI. type: object properties: uses-descricao-servico: type: boolean uses-item-lista-servico: type: boolean uses-codigo-servico-municipal: type: boolean uses-regime-especial-tributacao: type: boolean ExtraData: title: ExtraData description: >- Additional fiscal entity data — CNAE list and partner info. Embedded within TaxData. Contains the primary CNAE code, the full list of CNAE items (`all-cnae`), the main partner name, and the municipal jurisdiction code. type: object properties: cnae: type: string all-cnae: type: array items: $ref: '#/components/schemas/CnaeItem' main-partner-name: type: string municipal-jurisdiction: type: string CnaeItem: title: CnaeItem description: >- A CNAE (Classificação Nacional de Atividades Econômicas) code and description. Embedded within ExtraData.all-cnae. Each item pairs a CNAE code with its human-readable description. CNAE codes classify the economic activities of the business. type: object properties: cnae: type: string description: type: string Address: title: Address description: >- Physical address with country, state, city, neighborhood, street, number, zipcode, and complement. Used as an embedded object in FiscalEntity schemas (e.g. `address` field on ProfessionalFiscalEntity, BusinessFiscalEntity). Fields: country (2-letter ISO), state, city, neighborhood, street, street-number, zipcode, complement. The Go struct is `SimpleAddress` from `go-common/models/address.go`. type: object properties: country: type: string minLength: 2 maxLength: 2 state: type: string city: type: string neighborhood: type: string street: type: string street-number: type: string zipcode: type: string complement: type: string InvoiceItem: title: InvoiceItem description: >- A line item within a ProfessionalInvoice — description, quantity, unit value, and total. Embedded within ProfessionalInvoice.items. Each item has: `description` (string), `quantity` (integer), `unit-value-cents` (integer, in centavos), `total-value-cents` (integer, in centavos). The sum of all items' total-value-cents should equal the invoice's total-value-cents. type: object properties: description: type: string quantity: type: integer unit-value-cents: type: integer total-value-cents: type: integer security: - bearerAuth: [] paths: /sessions: post: summary: Login description: >- Authenticate and obtain a bearer JWT. Send `type: "email"` with `email` + `password` for the standard flow. Alternative types: `"phone"` (SMS OTP), `"link"` (magic link), `"token"` (pre-issued token), `"external"` / `"beauty-fair"` (partner integrations). The response carries `data.token` — pass it as `Authorization: Bearer ` on every subsequent call. operationId: post_sessions tags: - access > sessions x-use-cases: - Standard email + password login to obtain a bearer token - Phone OTP / magic-link passwordless login - External partner (Beauty Fair, OAuth) login - API key exchange for external app integrations requestBody: required: true content: application/json: example: type: email: password: schema: type: object responses: '200': description: OK content: application/json: example: success: true data: token: eyJhbGciOiJIUzI1NiJ9… token-type: user account: id: '3' type: personal email: user@example.com locale: pt-BR businesses: - id: '900001' brand: contabeleza permissions: - invoices:read - invoices:write professional-id: '901162' '401': description: Unauthorized — invalid or expired token. content: &ref_0 application/json: example: success: false errors: - title: UnauthorizedError detail: Token expired or invalid code: auth.unauthorized status: 401 security: &ref_1 - bearerAuth: [] delete: summary: Logout description: >- Log out and revoke the current session. Removes the token's JTI from the Redis whitelist so it is rejected on future requests, even if it hasn't expired yet. operationId: delete_sessions tags: - access > sessions x-use-cases: - Log out on user sign-out action - Forced session termination from admin tooling responses: '204': description: No content — session revoked. '401': description: Unauthorized — invalid or expired token. content: *ref_0 security: *ref_1 /sessions/token-refresh: post: summary: Refresh token description: >- Issue a fresh bearer token before the current one expires. Call this proactively (e.g. when `exp` is < 5 minutes away) to keep the user signed in without prompting for credentials again. operationId: post_sessions_token-refresh tags: - access > sessions x-use-cases: - Proactive refresh before token expiry to keep user signed in - Silent background refresh in mobile/SPA clients responses: '200': description: OK content: application/json: example: success: true data: token: eyJhbGci… token-type: user '401': description: Unauthorized — invalid or expired token. content: *ref_0 security: *ref_1 /sessions/request: post: summary: Magic link / OTP request description: >- Initiate a passwordless login flow — generates and sends a magic link or OTP via the channel configured for the account (email or SMS). The client then completes login by calling `POST /sessions` with `type: "link"` or `"phone"` and the received code. operationId: post_sessions_request tags: - access > sessions x-use-cases: - Send magic link to user's email before calling POST /sessions with type "link" - Trigger SMS OTP before calling POST /sessions with type "phone" requestBody: required: true content: application/json: example: email: type: schema: type: object responses: '200': description: OK — link or OTP sent. '422': description: Unprocessable Entity — validation error. content: &ref_2 application/json: example: success: false errors: - title: InvalidType detail: 'Type must be one of: new_contract, terminate_contract' code: business_request.invalid_type status: 422 meta: source: pointer: data.type security: [] /sessions/password/forgot: post: summary: Forgot password description: >- Initiate the password-reset flow. Sends a reset token to the account's email. Call `POST /sessions/password/validate-token` to verify the token, then `POST /sessions/password/reset` to set the new password. operationId: post_sessions_password_forgot tags: - access > sessions x-use-cases: - Initiate "forgot password" flow from login screen - First step of the forgot → validate-token → reset sequence requestBody: required: true content: application/json: example: email: schema: type: object responses: '200': description: OK — reset email sent. '422': description: Unprocessable Entity — validation error. content: *ref_2 security: [] /sessions/password/reset: post: summary: Reset password description: >- Complete a password reset using the token received by email. The request must include `reset-token` and `password`. On success, the account's password is updated and existing sessions are invalidated. operationId: post_sessions_password_reset tags: - access > sessions x-use-cases: - Complete password reset after user clicks the emailed link - Third step of the forgot → validate-token → reset sequence requestBody: required: true content: application/json: example: reset-token: password: schema: type: object responses: '200': description: OK — password updated. '422': description: Unprocessable Entity — validation error. content: *ref_2 security: [] /sessions/password/change: post: summary: Change password description: >- Change the authenticated account's password. Requires the current `password` and the desired `new-password`. Unlike reset, this flow requires a valid bearer token. operationId: post_sessions_password_change tags: - access > sessions requestBody: required: true content: application/json: example: password: new-password: schema: type: object responses: '200': description: OK. '401': description: Unauthorized — invalid or expired token. content: *ref_0 '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /accounts/beauty-fair: post: summary: Beauty Fair signup description: >- Create a new account via the Beauty Fair partner flow. Non-authenticated. Produces an Account and returns a session token ready to use. operationId: post_accounts_beauty-fair tags: - accounts requestBody: required: true content: application/json: example: name: email: phone: schema: type: object responses: '201': description: Created — account and session token returned. security: [] /accounts/external: post: summary: External provider signup description: >- Create an account via external provider (e.g. Google OAuth or partner SSO). Non-authenticated. Returns an account and session token. operationId: post_accounts_external tags: - accounts requestBody: required: true content: application/json: example: provider: token: schema: type: object responses: '201': description: Created — account and session token returned. security: [] /accounts/accept-terms: post: summary: Accept Terms of Service description: >- Record that the authenticated account has accepted the current version of the platform Terms of Service. Required before certain platform features are unlocked. operationId: post_accounts_accept-terms tags: - accounts responses: '200': description: OK — terms acceptance recorded. '401': description: Unauthorized — invalid or expired token. content: *ref_0 security: *ref_1 /accounts/{accountId}/impersonate: post: summary: Admin impersonation description: >- Admin: create a session token that acts as the target account. The resulting JWT carries `assumedBy` / `impersonatedBy` claims identifying the admin. **Restricted to internal tooling.** operationId: post_accounts_accountId_impersonate tags: - accounts parameters: - name: accountId in: path required: true description: The account id to impersonate. schema: type: string responses: '200': description: OK — returns a JWT with `assumedBy` claim. '403': description: Forbidden — insufficient permissions. content: &ref_4 application/json: example: success: false errors: - title: PermissionDenied detail: You do not have permission to access this resource code: auth.permission_denied status: 403 security: *ref_1 /accounts/phone/request: post: summary: Request phone change OTP description: >- Request a phone number change — sends a verification OTP to the new number. Follow up with `PATCH /accounts/phone` to confirm. operationId: post_accounts_phone_request tags: - accounts requestBody: required: true content: application/json: example: phone: phone-country: schema: type: object responses: '200': description: OK — OTP sent to new phone. '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /accounts/phone: patch: summary: Confirm phone change description: Confirm a phone number change by submitting the OTP received at the new number. operationId: patch_accounts_phone tags: - accounts requestBody: required: true content: application/json: example: otp: phone: phone-country: schema: type: object responses: '200': description: OK — phone updated. '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /accounts/{accountId}/recipient: post: summary: Create payout recipient description: >- Create or update the payout **Recipient** for the account — the bank account or PIX key where revenue will be transferred. operationId: post_accounts_accountId_recipient tags: - accounts > recipient parameters: - name: accountId in: path required: true description: The account id. schema: type: string requestBody: required: true content: application/json: example: data: type: billing-recipients attributes: bank-account: {} providers: {} pix-info: {} relationships: business: data: type: businesses id: schema: type: object responses: '200': description: OK — recipient created or updated. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PaymentsRecipient' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /accounts/{accountId}/recipient/pix/authorization: post: summary: Request PIX authorization description: >- Request PIX authorization for the account's recipient. Triggers an ownership verification step with the payment provider before the PIX key is confirmed. operationId: post_accounts_accountId_recipient_pix_authorization tags: - accounts > recipient parameters: - name: accountId in: path required: true description: The account id. schema: type: string requestBody: required: true content: application/json: example: pix-key: pix-key-type: schema: type: object responses: '200': description: OK — authorization request submitted. '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /accounts/{accountId}/recipient/pix: patch: summary: Confirm PIX key description: Confirm and set the PIX key for the account's recipient after the authorization step. operationId: patch_accounts_accountId_recipient_pix tags: - accounts > recipient parameters: - name: accountId in: path required: true description: The account id. schema: type: string requestBody: required: true content: application/json: example: data: type: billing-recipients attributes: bank-account: {} providers: {} pix-info: {} relationships: business: data: type: businesses id: schema: type: object responses: '200': description: OK — PIX key set. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PaymentsRecipient' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 delete: summary: Remove PIX key description: Remove the PIX key from the account's recipient. operationId: delete_accounts_accountId_recipient_pix tags: - accounts > recipient parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '204': description: No content — PIX key removed. '401': description: Unauthorized — invalid or expired token. content: *ref_0 security: *ref_1 /accounts/{accountId}/resources: put: summary: Upload profile resource description: >- Upload a profile photo, avatar, or supporting document for the account. Accepts JPEG, PNG, or PDF up to 5 MB. Returns the uploaded resource URL. operationId: put_accounts_accountId_resources tags: - accounts > resources parameters: - name: accountId in: path required: true description: The account id. schema: type: string requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary responses: '200': description: OK — resource URL returned. '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /accounts/{accountId}/documents: post: summary: Attach document description: >- Attach a compliance document to the account (e.g. ID, address proof). Links the uploaded resource to the account record. operationId: post_accounts_accountId_documents tags: - accounts > resources parameters: - name: accountId in: path required: true description: The account id. schema: type: string requestBody: required: true content: application/json: example: data: type: personal-documents attributes: document-type: data: {} front-url: back-url: foreign-type: foreign-id: relationships: account: data: type: accounts id: schema: type: object responses: '201': description: Created — document attached. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PersonalDocument' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 get: summary: List documents description: List all documents attached to the account, with type, status, and URL. operationId: get_accounts_accountId_documents tags: - accounts > resources parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK content: application/vnd.api+json: example: data: - id: '1' type: personal-documents attributes: type: rg status: approved url: https://… schema: type: object properties: data: type: array items: $ref: '#/components/schemas/PersonalDocument' security: *ref_1 /accounts/{accountId}/documents/{documentId}: delete: summary: Remove document description: Remove a previously attached document from the account. operationId: delete_accounts_accountId_documents_documentId tags: - accounts > resources parameters: - name: accountId in: path required: true description: The account id. schema: type: string - name: documentId in: path required: true description: The document id. schema: type: string responses: '204': description: No content. '404': description: Not found. security: *ref_1 /external-app-tokens: get: summary: List API tokens description: List all external app API tokens. Admin-only. Returns token metadata (name, scope, expiry) but not the raw key. operationId: get_external-app-tokens tags: - access > external-app-tokens x-use-cases: - 'Admin: list all API keys for an external partner integration audit' - Check which external apps have active access before a platform change responses: '200': description: OK content: application/vnd.api+json: example: data: - id: '1' type: external-app-tokens attributes: name: n8n Integration scope: business created-at: '2026-01-01T00:00:00Z' schema: type: object properties: data: type: array items: $ref: '#/components/schemas/ExternalAppToken' security: *ref_1 post: summary: Create API token description: >- Create a new external app API token. Specify `name`, `scope` (platform or business), and `permissions`. The raw key is returned only once in the response — store it securely. operationId: post_external-app-tokens tags: - access > external-app-tokens x-use-cases: - Generate an API key for a new n8n automation or integration - Create a scoped read-only key for a reporting dashboard requestBody: required: true content: application/json: example: data: type: external-app-tokens attributes: name: key: scopes: [] schema: type: object responses: '201': description: Created — raw API key returned once in `data.attributes.key`. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ExternalAppToken' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /external-app-tokens/{tokenId}: get: summary: Get token metadata description: Retrieve metadata for a specific external app token. operationId: get_external-app-tokens_tokenId tags: - access > external-app-tokens parameters: - name: tokenId in: path required: true description: The external app token id. schema: type: string responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: external-app-tokens attributes: name: n8n Integration scope: business created-at: '2026-01-01T00:00:00Z' schema: type: object properties: data: $ref: '#/components/schemas/ExternalAppToken' '404': description: Not found. security: *ref_1 patch: summary: Update token description: Update the name, permissions, or expiry of an external app token. operationId: patch_external-app-tokens_tokenId tags: - access > external-app-tokens parameters: - name: tokenId in: path required: true description: The external app token id. schema: type: string requestBody: required: true content: application/json: example: data: type: external-app-tokens attributes: name: key: scopes: [] schema: type: object responses: '200': description: OK. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ExternalAppToken' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 delete: summary: Revoke token description: Revoke and permanently delete an external app token. Any API key derived from it will be rejected immediately. operationId: delete_external-app-tokens_tokenId tags: - access > external-app-tokens parameters: - name: tokenId in: path required: true description: The external app token id. schema: type: string responses: '204': description: No content — token revoked. security: *ref_1 /professional-invoices/{professionalinvoiceId}/emit: patch: summary: Emit NFS-e description: >- Trigger emission of the NFS-e (electronic service invoice) via the eNotas integration. Transitions the invoice from `pending` to `requested`; the async integration then drives it to `succeeded` or `failed`. Call only after the buyer fiscal entity and competency date are set. operationId: patch_professional-invoices_professionalinvoiceId_emit tags: - businesses > professional invoices x-use-cases: - Issue the NFS-e after confirming the competency date and buyer fiscal entity - Emit after a business-request emission workflow approves the invoice parameters: - name: professionalinvoiceId in: path required: true description: The professional invoice id. schema: type: string - &ref_3 name: ilm-business in: header required: true description: Business context id (see /headers). schema: type: string responses: '200': description: OK — invoice transitioned to `requested`. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalInvoice' '400': description: Bad Request — invoice validation error. content: application/json: example: success: false errors: - title: InvoiceAlreadyEmitted detail: Invoice must not be in success or canceled to be emitted code: invoices.is_final status: 400 meta: status: succeeded '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /professional-invoices/{professionalinvoiceId}/cancel/confirmation: patch: summary: Confirm cancellation description: >- Confirm that a cancellation request was processed successfully by the prefeitura. Call after the external webhook confirms the cancellation, transitioning the invoice from `requested-cancelation` to `canceled`. operationId: patch_professional-invoices_professionalinvoiceId_cancel_confirmation tags: - businesses > professional invoices x-use-cases: - Called by the webhook handler after the prefeitura confirms cancellation - Confirm cancel after polling for status change parameters: - name: professionalinvoiceId in: path required: true description: The professional invoice id. schema: type: string - *ref_3 responses: '200': description: OK — invoice transitioned to `canceled`. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalInvoice' '400': description: Bad Request — invoice cannot be canceled. content: application/json: example: success: false errors: - title: InvoiceAlreadyCanceled detail: Invoice must not be in canceled to be cancel code: invoices.is_canceled status: 400 '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /professional-invoices/{professionalinvoiceId}/reemit: post: summary: Re-emit invoice description: >- Re-attempt emission for an invoice that previously reached `failed` status. Resets the lifecycle back to `requested` and retries the eNotas call with the same parameters. operationId: post_professional-invoices_professionalinvoiceId_reemit tags: - businesses > professional invoices x-use-cases: - Re-emit an invoice after fixing the root cause of a previous `failed` status - Retry after a transient prefeitura API error parameters: - name: professionalinvoiceId in: path required: true description: The professional invoice id. schema: type: string - *ref_3 responses: '200': description: OK — invoice queued for re-emission. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalInvoice' '400': description: Bad Request — invoice cannot be re-emitted. content: application/json: example: success: false errors: - title: NotPendingOrFailedInvoice detail: Invoice must be in pending or failed status to re-emit code: invoices.emissions.not_pending_or_failed status: 400 '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /professional-invoices/{professionalinvoiceId}/nfse: put: summary: Upload NFS-e file description: >- Upload the NFS-e PDF or XML file returned by the prefeitura for an issued invoice. Accepts PDF or XML up to 10 MB. Attaches the file URL to the invoice record. operationId: put_professional-invoices_professionalinvoiceId_nfse tags: - businesses > professional invoices x-use-cases: - Attach the NFS-e PDF returned by the municipality after successful emission - Store the XML file for compliance archiving parameters: - name: professionalinvoiceId in: path required: true description: The professional invoice id. schema: type: string - *ref_3 requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary description: PDF or XML NFS-e file, max 10 MB. responses: '200': description: OK — file attached to invoice. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalInvoice' '404': description: Not Found — invoice not found. content: application/json: example: success: false errors: - title: ProfessionalInvoiceNotFound detail: Professional invoice not found code: professional_invoice.not_found status: 404 '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /professionals/{professionalId}/fiscal-entity/revalidate: patch: summary: Revalidate CPF/CNPJ description: >- Trigger a CPF/CNPJ revalidation for the Professional's fiscal entity via Serpro. Use when the entity's status is stale or validation previously failed. Refreshes `validation-status` and surfaces any registration inconsistencies. operationId: patch_professionals_professionalId_fiscal-entity_revalidate tags: - professionals > fiscal entities x-use-cases: - Refresh CPF/CNPJ validation after data correction - Revalidate after a previously failed MEI registration check parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 responses: '200': description: OK — validation-status refreshed. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalFiscalEntity' '400': description: Bad Request — CPF validation error. content: application/json: example: success: false errors: - title: CpfValidationError detail: Could not validate CPF with Serpro code: fiscal_entities.cpf_validation_error status: 400 '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /businesses/{businessId}/fiscal-entity/certificate: put: summary: Upload business certificate description: >- Upload a new PKCS12 digital certificate for the Business's fiscal entity. Required by the eNotas integration to sign NFS-e on the Business's behalf. Accepts `.pfx` / `.p12` files up to 3 MB. operationId: put_businesses_businessId_fiscal-entity_certificate tags: - businesses > fiscal entities > certificate x-use-cases: - Upload the Business's new digital certificate annually when it expires - Initial setup of the certificate before the Business can issue NFS-e parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary description: PKCS12 (.pfx/.p12) file, max 3 MB. password: type: string responses: '200': description: OK — certificate stored. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/FiscalEntityCertificate' '400': description: Bad Request — certificate validation error. content: application/json: example: success: false errors: - title: CertificateExpired detail: Digital certificate has expired code: fiscal_entity_certificate.expired status: 400 '422': description: Unprocessable Entity — missing CNPJ or validation error. content: application/json: example: success: false errors: - title: CnpjRequired detail: Fiscal entity has no CNPJ code: fiscal_entity_certificate.cnpj_required status: 422 security: *ref_1 get: summary: Get business certificate metadata description: Get metadata about the Business's digital certificate — issuer, subject, expiration date, and validation status. operationId: get_businesses_businessId_fiscal-entity_certificate tags: - businesses > fiscal entities > certificate parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: fiscal-entity-certificates attributes: issuer: AC Certisign subject: CN=MINHA EMPRESA LTDA expiration-date: '2027-06-01' status: valid schema: type: object properties: data: $ref: '#/components/schemas/FiscalEntityCertificate' '404': description: Certificate not found. security: *ref_1 delete: summary: Remove business certificate description: >- Remove the Business's digital certificate. Sets `status_certificate` to `none` and prevents invoice emission until a new certificate is uploaded. operationId: delete_businesses_businessId_fiscal-entity_certificate tags: - businesses > fiscal entities > certificate parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 responses: '204': description: No content — certificate removed. security: *ref_1 /professionals/{professionalId}/fiscal-entity/certificate: put: summary: Upload professional certificate description: >- Upload a new PKCS12 digital certificate for the Professional's fiscal entity (their MEI CNPJ). Same semantics as the Business-scoped endpoint. operationId: put_professionals_professionalId_fiscal-entity_certificate tags: - professionals > fiscal entities > certificate parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary password: type: string responses: '200': description: OK. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/FiscalEntityCertificate' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 delete: summary: Remove professional certificate description: Remove the Professional's digital certificate. operationId: delete_professionals_professionalId_fiscal-entity_certificate tags: - professionals > fiscal entities > certificate parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 responses: '204': description: No content — certificate removed. security: *ref_1 get: summary: Get professional certificate metadata description: Get metadata about the Professional's digital certificate. operationId: get_professionals_professionalId_fiscal-entity_certificate tags: - professionals > fiscal entities > certificate parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: fiscal-entity-certificates attributes: issuer: AC Certisign subject: CN=MARIA SILVA expiration-date: '2027-06-01' status: valid schema: type: object properties: data: $ref: '#/components/schemas/FiscalEntityCertificate' '404': description: Certificate not found. security: *ref_1 /professionals/{professionalId}/personal-documents: get: summary: List personal documents description: Fetch the personal documents (identity, address proof, certificates) attached to the Professional. operationId: get_professionals_professionalId_personal-documents tags: - professionals > documents parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: example: data: - id: '1' type: personal-documents attributes: type: rg status: approved url: https://… schema: type: object properties: data: type: array items: $ref: '#/components/schemas/PersonalDocument' security: *ref_1 post: summary: Attach document description: >- Attach a personal document (RG, CNH, CPF copy, address proof) to the Professional. Required before contract approval for some business configurations. operationId: post_professionals_professionalId_personal-documents tags: - professionals > documents x-use-cases: - Attach RG or CPF copy before contract approval - Upload address proof required for fiscal entity registration parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 requestBody: required: true content: application/json: example: data: type: personal-documents attributes: document-type: data: {} front-url: back-url: foreign-type: foreign-id: relationships: account: data: type: accounts id: schema: type: object responses: '201': description: Created. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PersonalDocument' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /professionals/{professionalId}/personal-documents/{documentId}: delete: summary: Remove document description: Remove a personal document from the Professional. operationId: delete_professionals_professionalId_personal-documents_documentId tags: - professionals > documents parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - name: documentId in: path required: true description: The document id. schema: type: string - *ref_3 responses: '204': description: No content. '404': description: Not found. security: *ref_1 /personal-documents: get: summary: List personal documents description: List all personal documents across the business. Supports filtering by professional or document type. operationId: get_personal-documents tags: - businesses > documents parameters: - *ref_3 responses: '200': description: OK content: application/vnd.api+json: example: data: - id: '1' type: personal-documents attributes: type: rg status: approved url: https://… schema: type: object properties: data: type: array items: $ref: '#/components/schemas/PersonalDocument' security: *ref_1 post: summary: Upload personal document description: Upload a personal document (RG, CNH, CPF copy, address proof) for identity verification. operationId: post_personal-documents tags: - businesses > documents parameters: - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: personal-documents attributes: document-type: data: {} front-url: back-url: foreign-type: foreign-id: relationships: account: data: type: accounts id: schema: type: object responses: '201': description: Created. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PersonalDocument' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /personal-documents/{id}: get: summary: Get personal document description: Fetch a single personal document by id. operationId: get_personal-documents_id tags: - businesses > documents parameters: - name: id in: path required: true description: The document id. schema: type: string - *ref_3 responses: '200': description: OK. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PersonalDocument' '404': description: Not found. security: *ref_1 delete: summary: Remove personal document description: Delete a personal document by id. operationId: delete_personal-documents_id tags: - businesses > documents parameters: - name: id in: path required: true description: The document id. schema: type: string - *ref_3 responses: '204': description: No content. '404': description: Not found. security: *ref_1 /representatives: get: summary: List representatives description: List all **Representatives** registered under the current Business context. operationId: get_representatives tags: - businesses > representatives parameters: - *ref_3 responses: '200': description: OK content: application/vnd.api+json: example: data: - id: '1' type: businesses > representatives attributes: name: João Silva cpf: 123.456.789-00 email: joao@example.com schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Representative' security: *ref_1 post: summary: Create representative description: >- Create a new **Representative** for the Business. The representative is the legally responsible person (CPF, name, contact) required by eNotas and Serpro for invoice-related operations. operationId: post_representatives tags: - businesses > representatives x-use-cases: - Register the Business's legal representative before configuring fiscal entity - Update after a change of responsible person parameters: - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: representatives attributes: name: surname: gender: email: contact: cpf: rg: issuing-organization: shipping-date: address-postal: address-street: address-neighborhood: address-number: address-complement: address-city: address-state: marital-status: birthday: relationships: businesses: data: - type: businesses id: schema: type: object responses: '201': description: Created. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/Representative' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /representatives/{representativeId}: get: summary: Get representative description: Retrieve a single **Representative** by id. operationId: get_representatives_representativeId tags: - businesses > representatives parameters: - name: representativeId in: path required: true description: The representative id. schema: type: string - *ref_3 responses: '200': description: OK. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/Representative' '404': description: Not found. security: *ref_1 patch: summary: Update representative description: Update the **Representative**'s personal data — typically name, CPF, or contact information. operationId: patch_representatives_representativeId tags: - businesses > representatives parameters: - name: representativeId in: path required: true description: The representative id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: representatives attributes: name: surname: gender: email: contact: cpf: rg: issuing-organization: shipping-date: address-postal: address-street: address-neighborhood: address-number: address-complement: address-city: address-state: marital-status: birthday: relationships: businesses: data: - type: businesses id: schema: type: object responses: '200': description: OK. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/Representative' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /professional-contracts/{professionalcontractId}/update-status: patch: summary: Advance contract status description: >- Advance a **ProfessionalContract** through its status workflow (e.g. `filling → approved`, `approved → terminated`). The target status is passed in the request body. When transitioning directly to `terminated` and a top-level `termination_pdf_url` field is present in the body, the service writes it to `ProfessionalContract.termination_pdf_url` after the AASM event (the linked BusinessRequest closes via the AASM after-callback as usual). Ignored for other target statuses. operationId: patch_professional-contracts_professionalcontractId_update-status tags: - businesses x-use-cases: - Move a contract from `in_approval` to `approved` once the approval decision is made - >- Drive a `termination_requested` contract to `terminated` and optionally attach a signed distrato PDF via the top-level `termination_pdf_url` field - Cancel a contract in `filling` or `in_approval` (see also PATCH /professional-contracts/{id}/cancel) parameters: - name: professionalcontractId in: path required: true description: The professional contract id. schema: type: string - *ref_3 requestBody: required: true content: application/json: example: data: type: professional-contracts attributes: status: contract-status: pdf-url: termination-pdf-url: termination-business-request-id: partnership-start-date: partnership-end-date: relationships: business: data: type: businesses id: professional: data: type: professionals id: business-request: data: type: business-requests id: schema: type: object responses: '200': description: OK — status updated. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalContract' '422': description: Unprocessable Entity — invalid state transition or validation error. content: application/json: example: success: false errors: - title: InvalidTransition detail: fiscal_entity_id must be present before requesting approval code: professional_contract.invalid_transition status: 422 security: *ref_1 /professional-contracts/{professionalcontractId}/cancel: patch: summary: Cancel contract description: >- Cancel a **ProfessionalContract**, transitioning it to `terminated` and ending the working relationship between the Professional and the Business. operationId: patch_professional-contracts_professionalcontractId_cancel tags: - businesses parameters: - name: professionalcontractId in: path required: true description: The professional contract id. schema: type: string - *ref_3 responses: '200': description: OK — contract terminated. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalContract' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /accounts/{accountId}/professional-contracts: get: summary: List account contracts description: >- List all **ProfessionalContracts** associated with the given Account across any Business. Useful for account-level dashboards. operationId: get_accounts_accountId_professional-contracts tags: - accounts > professional contracts x-use-cases: - List all contracts across all professionals for an account - Account-level dashboard for contract management - Retrieve contracts without knowing specific professional IDs parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK content: application/vnd.api+json: example: data: [] schema: type: object properties: data: type: array items: $ref: '#/components/schemas/ProfessionalContract' security: *ref_1 /accounts/{accountId}/professional-invoices: get: summary: List account invoices description: >- List all **ProfessionalInvoices** for all professionals associated with the account via the fiscal entity owner relationship. Returns invoices from all professionals with `professional-id` and `tenant-id` fields. operationId: get_accounts_accountId_professional-invoices tags: - accounts > professional invoices x-use-cases: - List all invoices across all professionals for an account - Account-level dashboard for invoice management - Retrieve invoices without knowing specific professional IDs parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK content: application/vnd.api+json: example: data: [] schema: type: object properties: data: type: array items: $ref: '#/components/schemas/ProfessionalInvoice' security: *ref_1 /resources: post: summary: Upload file description: >- Upload a file (PDF, JPG, PNG, XML) and receive a resource id for attachment to other entities (e.g. contract PDFs, certificate files). Max 10MB. operationId: post_resources tags: - platform > resources parameters: - *ref_3 requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary responses: '201': description: Created — resource id returned. content: application/vnd.api+json: example: data: id: '42' type: resources attributes: url: https://… content-type: application/pdf filename: contract.pdf byte-size: 102400 schema: type: object properties: data: $ref: '#/components/schemas/Resource' '400': description: Bad Request — missing file. content: application/json: example: success: false errors: - title: FileMissing detail: No file provided code: resource.file_missing status: 400 '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 delete: summary: Delete resource description: Delete a previously uploaded **Resource** blob. Pass the resource id in the request body. operationId: delete_resources tags: - platform > resources parameters: - *ref_3 requestBody: required: true content: application/json: example: id: '42' responses: '204': description: No content. '404': description: Not found. security: *ref_1 /postbacks/n8n/business-requests: post: summary: n8n webhook description: >- Webhook endpoint called by n8n automations when a **BusinessRequest** status changes externally (e.g. PDF generation complete, signature received). No `ilm-business` header required — n8n uses a separate auth mechanism. operationId: post_postbacks_n8n_business-requests tags: - businesses > requests x-use-cases: - Receive n8n notification that a PDF was generated for a new_contract_pdf request - Receive async status update for a professional_invoice_emission workflow requestBody: required: true content: application/json: example: data: {} schema: type: object responses: '200': description: OK — event processed. security: [] /business-requests/{businessrequestId}/update-status: patch: summary: Advance status description: >- Transition a **BusinessRequest** through its AASM workflow. Accepts `status` values: `open`, `processing`, `waiting`, `closed`, `canceled`. The `call_status_update_webhook` runs on transition and cascades status to the linked `ProfessionalContract` and/or `ProfessionalInvoice` rows. The id can be provided as a path parameter or in `data.business_request_id` (useful for n8n callers). For a `TerminateContract` being transitioned to `closed`, the payload may also include a top-level `termination_pdf_url` — the URL of a signed distrato PDF (already uploaded to S3 via `POST /resources`). The service writes it to `ProfessionalContract.termination_pdf_url` for the linked contract. Ignored for other BR types and other transitions. operationId: patch_business-requests_businessrequestId_update-status tags: - businesses > requests x-use-cases: - Advance a `new_contract` BusinessRequest from `open` to `closed` once the contract is approved - Cancel a `professional_invoice_emission` workflow before all invoices are processed - Trigger n8n status callbacks for a BusinessRequest from any client - >- Attach a signed distrato PDF when closing a `terminate_contract` request via the top-level `termination_pdf_url` field parameters: - name: businessrequestId in: path required: true description: The business request id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: business-requests attributes: type: status: data: {} artifacts: {} relationships: business: data: type: businesses id: schema: type: object responses: '200': description: OK — status transitioned; downstream resources updated. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/BusinessRequest' '404': description: Not found — no business request with this id for the current business. '422': description: Unprocessable Entity — invalid state transition or validation error. content: application/json: example: success: false errors: - title: InvalidTransition detail: 'Unknown event: closed' code: business_request.invalid_transition status: 422 security: *ref_1 post: summary: Advance status (POST alias) description: >- POST alias of PATCH /business-requests/{id}/update-status, kept for n8n clients and any consumer that only supports POST. Body shape and behavior are identical to the PATCH version — including the optional top-level `termination_pdf_url` field for `TerminateContract` + `closed` transitions. operationId: post_business-requests_businessrequestId_update-status tags: - businesses > requests x-use-cases: - n8n HTTP Request node that defaults to POST - Clients behind firewalls that block PATCH - Attach a signed distrato PDF via the POST alias variant parameters: - name: businessrequestId in: path required: true description: The business request id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: business-requests attributes: type: status: data: {} artifacts: {} relationships: business: data: type: businesses id: schema: type: object responses: '200': description: OK — status transitioned. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/BusinessRequest' '404': description: Not found. '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /business-requests/update-status: patch: summary: Advance status (id in body) description: >- Same as PATCH /business-requests/{id}/update-status but reads the id from `data.business_request_id`. Used by the n8n postback flow and any client that prefers to send the id in the body. Body shape: `{ data: { business_request_id: "42", payload: { status: "closed", termination_pdf_url: "https://…" } } }`. The `termination_pdf_url` field follows the same rules as the path-based variant (only honored on `TerminateContract` + `closed`). operationId: patch_business-requests_update-status tags: - businesses > requests x-use-cases: - n8n postback alternative when the id is not in the URL - Programmatic status updates from internal services - Attach a signed distrato PDF via the body-based `termination_pdf_url` field parameters: - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: business-requests attributes: type: status: data: {} artifacts: {} relationships: business: data: type: businesses id: schema: type: object responses: '200': description: OK — status transitioned. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/BusinessRequest' '404': description: Not found. '422': description: Unprocessable Entity — invalid state transition or validation error. content: application/json: example: success: false errors: - title: InvalidTransition detail: 'Unknown event: closed' code: business_request.invalid_transition status: 422 security: *ref_1 /professionals/{professionalId}/business-requests/history: get: summary: History description: >- List all BusinessRequest rows for the given professional, ordered by `created_at` desc. Useful for showing the full history of contract creations, terminations, and invoice emissions for a specific professional. operationId: get_professionals_professionalId_business-requests_history tags: - professionals > requests x-use-cases: - Show the full workflow history of a specific professional - Audit which BusinessRequests were triggered for a given professional parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: example: data: [] schema: type: object properties: data: type: array items: $ref: '#/components/schemas/BusinessRequest' security: *ref_1 /professionals/{professionalId}/professional-contracts/active: get: summary: Active contract description: >- Returns the currently active `ProfesionalContract` for the given professional, if any. Backed by the latest `BusinessRequest::NewContract` row. Returns an empty data object if the professional has no active contract. operationId: get_professionals_professionalId_professional-contracts_active tags: - professionals > contracts x-use-cases: - Check whether a professional has an active contract before creating a new one - Get the active contract id to attach new invoices to parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: example: data: null schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalContract' security: *ref_1 /professional-fiscal-entities/revenue: get: summary: Revenue resumes per fiscal entity description: >- List the **FiscalEntityRevenueResumes** — one entry per seller fiscal entity of the business — aggregating monthly revenue records into a summary with status, projection, and errored/processing month lists. Each resume declares a `calculation_type`: `"yearly"` for MEI entities (calendar-year sum against R$81k limit) or `"trailing"` for non-MEI entities (rolling 12-month sum against a configurable limit). The `api_status` reflects the underlying monthly records (`errored` > `processing` > `succeeded`), `total_revenue_status` compares actual total against the limit (`ok`/`nok`), and `projected_revenue_status` projects current revenue forward against configurable thresholds (`ok`/`warning_low`/`warning_high`). Fiscal entities without an active owner are still listed with their stored data but are not refreshed. For each entity that needs refresh, the service submits one async **lote** (batch) request to the external revenue API and returns immediately with the stored (possibly stale) resume; a singleton poller tracks the resulting job_ids in the background and writes the final results to the DB when the upstream returns. The response is JSON:API with a `fiscal-entity` relationship. See the **Revenue** tech guide for the full data flow, authentication, and refresh rules. operationId: get_professional-fiscal-entities_revenue tags: - professionals > fiscal entities > revenue x-use-cases: - >- Show a "faturamento por fiscal entity" card on the Business dashboard, highlighting fiscal entities approaching the revenue cap - >- Identify fiscal entities whose `api_status` is `errored` so an admin can fix credentials (certificate expired, portal password changed) - >- Cross-check projected annual revenue (`projected_revenue_status: "warning_high"`) against commissions before issuing a contract update - >- Trigger a background refresh by calling the endpoint when records are missing, errored, or from a previous month parameters: - name: businessId in: path required: true description: The business id. schema: type: string - name: year in: query required: false schema: type: integer example: 2026 description: >- Calendar year for MEI yearly aggregation. Defaults to the current year when omitted. Trailing-12-month calculation ignores this parameter. responses: '200': description: OK — list of fiscal-entity-revenue-resumes for the business. content: application/vnd.api+json: example: data: - id: fe-456 type: fiscal-entity-revenue-resumes attributes: calculation-type: yearly initial-month: '202601' last-month: '202606' api-status: errored api-status-reason: no_credentials_available revenue-status: warning is-mei: true total-revenue-cents: 4500000 avg-month-revenue-cents: 750000 invoice-count: 12 total-limit-cents: 8100000 total-limit-percentage: 5556 errored-months: - '202603' processing-months: [] relationships: fiscal-entity: data: type: fiscal-entities id: fe-456 schema: type: object properties: data: type: array items: $ref: '#/components/schemas/FiscalEntityRevenueResume' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /businesses/{businessId}/revenue: get: summary: Revenue resumes per fiscal entity (path-scoped) description: >- Business-scoped revenue resume list. Same shape as `GET /professional-fiscal-entities/revenue` but the business is taken from the path parameter `{businessId}` instead of the `ilm-business` header. operationId: get_businesses_businessId_revenue tags: - businesses > fiscal entities > revenue x-use-cases: - >- Same use cases as `GET /professional-fiscal-entities/revenue` but scoped via the URL path instead of the `ilm-business` header - Convenience route when the client already has the business ID from a resource URL parameters: - name: businessId in: path required: true description: The business id. schema: type: string - name: year in: query required: false schema: type: integer example: 2026 description: >- Calendar year for MEI yearly aggregation. Defaults to the current year when omitted. Trailing-12-month calculation ignores this parameter. responses: '200': description: OK — list of fiscal-entity-revenue-resumes for the business. content: application/vnd.api+json: example: data: [] schema: type: object properties: data: type: array items: $ref: '#/components/schemas/FiscalEntityRevenueResume' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /businesses/{businessId}/fiscal-entity/diagnosis: get: summary: Latest diagnosis description: >- Get the most recent MEI compliance diagnosis for the Business's fiscal entity. Returns the last diagnosis result (status, issues) without triggering a new check. For a fresh diagnosis, use `POST /businesses/{businessId}/fiscal-entity/diagnosis`. operationId: get_businesses_businessId_fiscal-entity_diagnosis tags: - businesses > fiscal entities > diagnosis x-use-cases: - Show the last MEI diagnosis result on the Business dashboard before attempting invoice emission - >- Check whether the fiscal entity has any pending issues (debts, certificate problems) without triggering a new check parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: fiscal-entity-diagnoses attributes: status: ok issues: [] checked-at: '2026-04-29T00:00:00Z' schema: type: object properties: data: $ref: '#/components/schemas/Diagnosis' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 post: summary: Trigger diagnosis description: >- Trigger a new MEI compliance diagnosis for the Business's fiscal entity. Runs a fresh check against Receita Federal / government services and returns the result. The diagnosis surfaces pending issues (debts, certificate problems, registration inconsistencies) that would block NFS-e emission. operationId: post_businesses_businessId_fiscal-entity_diagnosis tags: - businesses > fiscal entities > diagnosis x-use-cases: - Trigger a fresh MEI compliance diagnosis before a critical workflow (invoice emission, contract signing) - Re-validate after fixing a credential or paying a debt to confirm the issue is resolved parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 responses: '200': description: OK — diagnosis triggered and result returned content: application/vnd.api+json: example: data: id: '1' type: fiscal-entity-diagnoses attributes: status: processing issues: [] checked-at: '2026-04-29T00:00:00Z' schema: type: object properties: data: $ref: '#/components/schemas/Diagnosis' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /professionals/{professionalId}/fiscal-entity/revenue: get: summary: Revenue for a professional's fiscal entity description: >- Fetch per-month revenue records for the fiscal entity linked to this professional. Delegates to the accounting service's `GET /fiscal-entities/:id/revenue`. operationId: get_professionals_professionalId_fiscal-entity_revenue tags: - professionals > fiscal entities > revenue parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - name: year in: query required: false schema: type: integer - name: month in: query required: false schema: type: integer responses: '200': description: OK content: application/vnd.api+json: example: {} schema: type: object properties: data: type: array items: $ref: '#/components/schemas/FiscalEntityRevenue' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /professionals/{professionalId}/fiscal-entity/diagnosis: get: summary: Latest diagnosis for a professional's fiscal entity description: >- Get the most recent MEI compliance diagnosis for the fiscal entity linked to this professional. Returns the last result without triggering a new check. operationId: get_professionals_professionalId_fiscal-entity_diagnosis tags: - professionals > fiscal entities > diagnosis parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: fiscal-entity-diagnoses attributes: status: ok issues: [] checked-at: '2026-04-29T00:00:00Z' schema: type: object properties: data: $ref: '#/components/schemas/Diagnosis' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 post: summary: Trigger diagnosis for a professional's fiscal entity description: >- Trigger a new MEI compliance diagnosis for the fiscal entity linked to this professional. Runs a fresh check against Receita Federal and returns the result. operationId: post_professionals_professionalId_fiscal-entity_diagnosis tags: - professionals > fiscal entities > diagnosis parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 responses: '200': description: OK — diagnosis triggered content: application/vnd.api+json: example: data: id: '1' type: fiscal-entity-diagnoses attributes: status: processing issues: [] checked-at: '2026-04-29T00:00:00Z' schema: type: object properties: data: $ref: '#/components/schemas/Diagnosis' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /businesses/{businessId}/fiscal-entity/certificate/validate: post: summary: Validate business certificate description: >- Test the stored digital certificate for the Business's fiscal entity against the external revenue API. Updates `validation-status` accordingly. operationId: post_businesses_businessId_fiscal-entity_certificate_validate tags: - businesses > fiscal entities > certificate x-use-cases: - Test a newly uploaded digital certificate - Re-validate after a failed revenue refresh to confirm the certificate and its password still work parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 responses: '200': description: OK — validation-status updated. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/FiscalEntityCertificate' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /businesses/{businessId}/fiscal-entity: get: summary: Get business fiscal entity description: >- Fetch the **FiscalEntity** (CNPJ/CPF, certificates, MEI data) tied to the given Business. This is the entity that issues invoices on behalf of the Business itself. operationId: get_businesses_businessId_fiscal-entity tags: - businesses > fiscal entities parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 responses: '200': description: OK. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/BusinessFiscalEntity' '404': description: Not found. security: *ref_1 patch: summary: Update business fiscal entity description: >- Update the Business's **FiscalEntity** — typically to change tax number, address, or upload a new digital certificate. operationId: patch_businesses_businessId_fiscal-entity tags: - businesses > fiscal entities parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: business-fiscal-entities attributes: name: email: address: status: document-type: tax-number: tax-country: tax-data: emission-status: certificate-expiration-date: status-pass-govs: status-pass-invoices: status-certificate: has-pass-gov: has-pass-invoices: has-certificate: relationships: business: data: type: businesses id: schema: type: object responses: '200': description: OK — fiscal entity updated. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/BusinessFiscalEntity' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 post: summary: Create business fiscal entity description: >- Create a new **FiscalEntity** for the Business — registers the tax number (CNPJ/CPF), address, and initial configuration. operationId: post_businesses_businessId_fiscal-entity tags: - businesses > fiscal entities x-use-cases: - >- Register a new Business fiscal entity with CNPJ/CPF as the first step before configuring certificates and credentials parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: business-fiscal-entities attributes: name: email: address: status: document-type: tax-number: tax-country: tax-data: emission-status: certificate-expiration-date: status-pass-govs: status-pass-invoices: status-certificate: has-pass-gov: has-pass-invoices: has-certificate: relationships: business: data: type: businesses id: schema: type: object responses: '201': description: Created — fiscal entity registered. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/BusinessFiscalEntity' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 delete: summary: Destroy business fiscal entity description: >- Remove the Business's **FiscalEntity** record. Irreversible — all linked certificates, credentials, and revenue records are also removed. operationId: delete_businesses_businessId_fiscal-entity tags: - businesses > fiscal entities parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 responses: '204': description: No content — fiscal entity removed. '404': description: Not found. security: *ref_1 /businesses/{businessId}/fiscal-entity/pass-gov: get: summary: Get business PassGov credentials description: >- Retrieve the stored **gov.br** credentials (PassGov) used to access government services on behalf of the Business's fiscal entity. operationId: get_businesses_businessId_fiscal-entity_pass-gov tags: - businesses > fiscal entities > pass-gov parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: pass-govs attributes: cpf: '***.456.789-**' status: valid validation-status: valid schema: type: object properties: data: $ref: '#/components/schemas/PassGov' '404': description: Not found. security: *ref_1 post: summary: Create business PassGov credentials description: Create **gov.br** credentials for the Business's fiscal entity. operationId: post_businesses_businessId_fiscal-entity_pass-gov tags: - businesses > fiscal entities > pass-gov parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 requestBody: required: true content: application/json: example: data: type: fiscal-entity-pass-govs attributes: cpf: password: status: validation-status: validation-errors: [] validation-by-id: relationships: business: data: type: businesses id: professional: data: type: professionals id: schema: type: object responses: '201': description: Created. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PassGov' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 patch: summary: Update business PassGov credentials description: Update the **gov.br** credentials for the Business's fiscal entity. operationId: patch_businesses_businessId_fiscal-entity_pass-gov tags: - businesses > fiscal entities > pass-gov parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 requestBody: required: true content: application/json: example: data: type: fiscal-entity-pass-govs attributes: cpf: password: status: validation-status: validation-errors: [] validation-by-id: relationships: business: data: type: businesses id: professional: data: type: professionals id: schema: type: object responses: '200': description: OK. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PassGov' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /businesses/{businessId}/fiscal-entity/pass-gov/validate: post: summary: Validate business gov.br credentials description: Test the stored gov.br credentials for the Business's fiscal entity against the live government portal. operationId: post_businesses_businessId_fiscal-entity_pass-gov_validate tags: - businesses > fiscal entities > pass-gov x-use-cases: - Test new gov.br credentials immediately after saving them - Re-validate after a failed DAS or diagnosis fetch to confirm credentials are still valid parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 responses: '200': description: OK — validation-status updated. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PassGov' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /businesses/{businessId}/fiscal-entity/pass-invoices: get: summary: Get business pass-invoices credentials description: Retrieve the credentials used to access the prefeitura's NFS-e portal for the Business's fiscal entity. operationId: get_businesses_businessId_fiscal-entity_pass-invoices tags: - businesses > fiscal entities > pass-invoices parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: pass-invoices attributes: login: prefeitura_user status: valid validation-status: valid schema: type: object properties: data: $ref: '#/components/schemas/PassInvoice' '404': description: Not found. security: *ref_1 post: summary: Create business pass-invoices credentials description: Create prefeitura portal credentials for the Business's fiscal entity. operationId: post_businesses_businessId_fiscal-entity_pass-invoices tags: - businesses > fiscal entities > pass-invoices parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 requestBody: required: true content: application/json: example: data: type: fiscal-entity-pass-invoices attributes: authentication-type: username: login: password: status: validation-status: validation-errors: [] validation-by-id: relationships: business: data: type: businesses id: professional: data: type: professionals id: schema: type: object responses: '201': description: Created. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PassInvoice' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 patch: summary: Update business pass-invoices credentials description: Update the prefeitura portal credentials for the Business's fiscal entity. operationId: patch_businesses_businessId_fiscal-entity_pass-invoices tags: - businesses > fiscal entities > pass-invoices parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 requestBody: required: true content: application/json: example: data: type: fiscal-entity-pass-invoices attributes: authentication-type: username: login: password: status: validation-status: validation-errors: [] validation-by-id: relationships: business: data: type: businesses id: professional: data: type: professionals id: schema: type: object responses: '200': description: OK. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PassInvoice' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /businesses/{businessId}/fiscal-entity/pass-invoices/validate: post: summary: Validate business portal credentials description: Test the stored pass-invoices credentials for the Business's fiscal entity against the external revenue API. operationId: post_businesses_businessId_fiscal-entity_pass-invoices_validate tags: - businesses > fiscal entities > pass-invoices x-use-cases: - Test new portal credentials immediately after saving them - Re-validate after a failed revenue refresh to confirm credentials are still valid parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 responses: '200': description: OK — validation-status updated. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PassInvoice' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /businesses/{businessId}/fiscal-entity/invoices-emission: post: summary: Setup business invoice emission description: Set up invoice emission for the Business's fiscal entity via eNotas. operationId: post_businesses_businessId_fiscal-entity_invoices-emission tags: - businesses > fiscal entities > invoices-emission parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 responses: '200': description: OK — emission setup initiated. '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 delete: summary: Deactivate business invoice emission description: Deactivate invoice emission for the Business's fiscal entity. operationId: delete_businesses_businessId_fiscal-entity_invoices-emission tags: - businesses > fiscal entities > invoices-emission parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 responses: '204': description: No content — emission deactivated. security: *ref_1 /businesses/{businessId}/fiscal-entity/invoices-emission/validate: post: summary: Validate business emission setup description: Trigger a test-invoice emission to validate the Business's emission setup. operationId: post_businesses_businessId_fiscal-entity_invoices-emission_validate tags: - businesses > fiscal entities > invoices-emission parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 responses: '200': description: OK — validation triggered. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/EmissionValidation' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 get: summary: Get business emission validation status description: Get the current validation status of the Business's emission setup. operationId: get_businesses_businessId_fiscal-entity_invoices-emission_validate tags: - businesses > fiscal entities > invoices-emission parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: emission-validations attributes: status: succeeded author: '123' author-type: admin authentication-type: pass_only attempted-at: '2026-07-28T10:30:00Z' completed-at: '2026-07-28T10:30:05Z' canceled-at: '2026-07-28T10:30:06Z' invoice-status: succeeded is-valid: true relationships: invoice: data: id: inv_abc123 type: invoices schema: type: object properties: data: $ref: '#/components/schemas/EmissionValidation' '404': description: No validation found. security: *ref_1 /businesses/{businessId}/municipal-details: get: summary: Municipal details for a business description: Fetch municipal tax details for the Business — city registration, taxation regime, and service codes. operationId: get_businesses_businessId_municipal-details tags: - businesses parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: municipal-details attributes: city: São Paulo municipal-registration: '12345' taxation-regime: simples-nacional '404': description: Not found. security: *ref_1 /businesses/{businessId}/professionals-fiscal-details: get: summary: Fiscal details of professionals for a business description: List fiscal details for all Professionals linked to the Business. operationId: get_businesses_businessId_professionals-fiscal-details tags: - businesses parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: example: data: - id: '1' type: professional-fiscal-details attributes: professional-name: Maria Silva certificate-status: valid emission-status: active security: *ref_1 /professionals/{professionalId}/fiscal-entity: get: summary: Get professional fiscal entity description: Retrieve the **ProfessionalFiscalEntity** (MEI/CPF) belonging to the given Professional. operationId: get_professionals_professionalId_fiscal-entity tags: - professionals > fiscal entities parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 responses: '200': description: OK. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalFiscalEntity' '404': description: Not found. security: *ref_1 post: summary: Create professional fiscal entity description: Create a **ProfessionalFiscalEntity** for the given Professional. operationId: post_professionals_professionalId_fiscal-entity tags: - professionals > fiscal entities x-use-cases: - Create a fiscal entity for a Professional — first step before they can issue invoices parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: professional-fiscal-entities attributes: name: email: address: status: document-type: tax-number: tax-country: tax-data: emission-status: certificate-expiration-date: status-pass-govs: status-pass-invoices: status-certificate: has-pass-gov: has-pass-invoices: has-certificate: relationships: professional: data: type: professionals id: schema: type: object responses: '201': description: Created. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalFiscalEntity' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 patch: summary: Update professional fiscal entity (via proxy) description: Update the **ProfessionalFiscalEntity** (proxied to the accounting service). operationId: patch_professionals_professionalId_fiscal-entity tags: - professionals > fiscal entities parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: professional-fiscal-entities attributes: name: email: address: status: document-type: tax-number: tax-country: tax-data: emission-status: certificate-expiration-date: status-pass-govs: status-pass-invoices: status-certificate: has-pass-gov: has-pass-invoices: has-certificate: relationships: professional: data: type: professionals id: schema: type: object responses: '200': description: OK. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalFiscalEntity' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /professionals/{professionalId}/fiscal-entity/certificate/validate: post: summary: Validate professional certificate description: Test the stored digital certificate for the Professional's fiscal entity. operationId: post_professionals_professionalId_fiscal-entity_certificate_validate tags: - professionals > fiscal entities > certificate x-use-cases: - Test a newly uploaded digital certificate - Re-validate after a failed revenue refresh to confirm the certificate and its password still work parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 responses: '200': description: OK — validation-status updated. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/FiscalEntityCertificate' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /professionals/{professionalId}/fiscal-entity/pass-gov: get: summary: Get professional PassGov description: Retrieve the stored **gov.br** credentials for the Professional's fiscal entity. operationId: get_professionals_professionalId_fiscal-entity_pass-gov tags: - professionals > fiscal entities > pass-gov parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: pass-govs attributes: cpf: '***.456.789-**' status: valid validation-status: valid schema: type: object properties: data: $ref: '#/components/schemas/PassGov' '404': description: Not found. security: *ref_1 post: summary: Create professional PassGov description: Create **gov.br** credentials for the Professional's fiscal entity. operationId: post_professionals_professionalId_fiscal-entity_pass-gov tags: - professionals > fiscal entities > pass-gov parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 requestBody: required: true content: application/json: example: data: type: fiscal-entity-pass-govs attributes: cpf: password: status: validation-status: validation-errors: [] validation-by-id: relationships: business: data: type: businesses id: professional: data: type: professionals id: schema: type: object responses: '201': description: Created. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PassGov' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 patch: summary: Update professional PassGov description: Update the **gov.br** credentials for the Professional's fiscal entity. operationId: patch_professionals_professionalId_fiscal-entity_pass-gov tags: - professionals > fiscal entities > pass-gov parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 requestBody: required: true content: application/json: example: data: type: fiscal-entity-pass-govs attributes: cpf: password: status: validation-status: validation-errors: [] validation-by-id: relationships: business: data: type: businesses id: professional: data: type: professionals id: schema: type: object responses: '200': description: OK. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PassGov' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /professionals/{professionalId}/fiscal-entity/pass-gov/validate: post: summary: Validate professional gov.br credentials description: Test the stored gov.br credentials for the Professional's fiscal entity. operationId: post_professionals_professionalId_fiscal-entity_pass-gov_validate tags: - professionals > fiscal entities > pass-gov x-use-cases: - Test new gov.br credentials immediately after saving them - Re-validate after a failed DAS or diagnosis fetch to confirm credentials are still valid parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 responses: '200': description: OK — validation-status updated. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PassGov' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /professionals/{professionalId}/fiscal-entity/pass-invoices: get: summary: Get professional pass-invoices description: Retrieve the prefeitura portal credentials for the Professional's fiscal entity. operationId: get_professionals_professionalId_fiscal-entity_pass-invoices tags: - professionals > fiscal entities > pass-invoices parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: pass-invoices attributes: login: maria_user status: valid validation-status: valid schema: type: object properties: data: $ref: '#/components/schemas/PassInvoice' '404': description: Not found. security: *ref_1 post: summary: Create professional pass-invoices description: Create prefeitura portal credentials for the Professional's fiscal entity. operationId: post_professionals_professionalId_fiscal-entity_pass-invoices tags: - professionals > fiscal entities > pass-invoices parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 requestBody: required: true content: application/json: example: data: type: fiscal-entity-pass-invoices attributes: authentication-type: username: login: password: status: validation-status: validation-errors: [] validation-by-id: relationships: business: data: type: businesses id: professional: data: type: professionals id: schema: type: object responses: '201': description: Created. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PassInvoice' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 patch: summary: Update professional pass-invoices description: Update the prefeitura portal credentials for the Professional's fiscal entity. operationId: patch_professionals_professionalId_fiscal-entity_pass-invoices tags: - professionals > fiscal entities > pass-invoices parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 requestBody: required: true content: application/json: example: data: type: fiscal-entity-pass-invoices attributes: authentication-type: username: login: password: status: validation-status: validation-errors: [] validation-by-id: relationships: business: data: type: businesses id: professional: data: type: professionals id: schema: type: object responses: '200': description: OK. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PassInvoice' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /professionals/{professionalId}/fiscal-entity/pass-invoices/validate: post: summary: Validate professional portal credentials description: Test the stored pass-invoices credentials for the Professional's fiscal entity. operationId: post_professionals_professionalId_fiscal-entity_pass-invoices_validate tags: - professionals > fiscal entities > pass-invoices x-use-cases: - Test new portal credentials immediately after saving them - Re-validate after a failed revenue refresh to confirm credentials are still valid parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 responses: '200': description: OK — validation-status updated. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PassInvoice' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /professionals/{professionalId}/fiscal-entity/invoices-emission: post: summary: Setup professional invoice emission description: Set up invoice emission for the Professional's fiscal entity. operationId: post_professionals_professionalId_fiscal-entity_invoices-emission tags: - professionals > fiscal entities > invoices-emission parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 responses: '200': description: OK — emission setup initiated. content: application/vnd.api+json: example: data: id: '1' type: professional-fiscal-entities attributes: cnpj: 12.345.678/0001-90 company-name: Maria Silva MEI emission-status: missing_validation status: active '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 delete: summary: Deactivate professional invoice emission description: Deactivate invoice emission for the Professional's fiscal entity. operationId: delete_professionals_professionalId_fiscal-entity_invoices-emission tags: - professionals > fiscal entities > invoices-emission parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 responses: '204': description: No content — emission deactivated. security: *ref_1 /professionals/{professionalId}/fiscal-entity/invoices-emission/validate: post: summary: Validate professional emission setup description: Trigger a test-invoice emission to validate the Professional's emission setup. operationId: post_professionals_professionalId_fiscal-entity_invoices-emission_validate tags: - professionals > fiscal entities > invoices-emission parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 requestBody: content: application/vnd.api+json: example: data: type: emission-validations attributes: status: author: author-type: authentication-type: invoice-status: error: {} municipal-data: {} is-valid: relationships: invoice: data: type: invoices id: schema: type: object responses: '200': description: OK — validation triggered. Returns the validation status. content: application/vnd.api+json: example: data: id: '1' type: emission-validations attributes: status: validating author: '123' author-type: admin authentication-type: pass_only attempted-at: '2026-07-28T10:30:00Z' invoice-status: pending is-valid: false relationships: invoice: data: id: inv_abc123 type: invoices schema: type: object properties: data: $ref: '#/components/schemas/EmissionValidation' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 get: summary: Get professional emission validation status description: Get the current validation status of the Professional's emission setup. operationId: get_professionals_professionalId_fiscal-entity_invoices-emission_validate tags: - professionals > fiscal entities > invoices-emission parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: emission-validations attributes: status: succeeded author: '123' author-type: admin authentication-type: pass_only attempted-at: '2026-07-28T10:30:00Z' completed-at: '2026-07-28T10:30:05Z' canceled-at: '2026-07-28T10:30:06Z' invoice-status: succeeded is-valid: true relationships: invoice: data: id: inv_abc123 type: invoices schema: type: object properties: data: $ref: '#/components/schemas/EmissionValidation' '404': description: No validation found. security: *ref_1 /accounts/{accountId}/fiscal-entity: get: summary: Show personal fiscal entity description: Retrieve the personal **FiscalEntity** for the given Account — CPF, address, and fiscal registration data. operationId: get_accounts_accountId_fiscal-entity tags: - accounts > fiscal entities x-use-cases: - Show personal fiscal entity for the account - Retrieve CPF/address for the user's dashboard parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: fiscal-entities attributes: cpf: 123.456.789-00 name: Maria Silva emission-status: active schema: type: object properties: data: $ref: '#/components/schemas/AccountFiscalEntity' '404': description: Not found. security: *ref_1 post: summary: Create personal fiscal entity description: >- Create a personal **FiscalEntity** for the Account — registers the CPF, address, and initial fiscal configuration. operationId: post_accounts_accountId_fiscal-entity tags: - accounts > fiscal entities x-use-cases: - Create personal fiscal entity for a new account - Register CPF and address for the user parameters: - name: accountId in: path required: true description: The account id. schema: type: string requestBody: required: true content: application/vnd.api+json: example: data: type: account-fiscal-entities attributes: name: email: address: status: document-type: tax-number: tax-country: tax-data: {} emission-status: certificate-expiration-date: status-pass-govs: status-pass-invoices: status-certificate: has-pass-gov: has-pass-invoices: has-certificate: relationships: account: data: type: accounts id: schema: type: object responses: '201': description: Created. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/AccountFiscalEntity' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 patch: summary: Update personal fiscal entity description: Update the personal **FiscalEntity** — correct CPF, address, or other fiscal registration data. operationId: patch_accounts_accountId_fiscal-entity tags: - accounts > fiscal entities x-use-cases: - Update personal fiscal entity details - Correct CPF or address information parameters: - name: accountId in: path required: true description: The account id. schema: type: string requestBody: required: true content: application/vnd.api+json: example: data: type: account-fiscal-entities attributes: name: email: address: status: document-type: tax-number: tax-country: tax-data: {} emission-status: certificate-expiration-date: status-pass-govs: status-pass-invoices: status-certificate: has-pass-gov: has-pass-invoices: has-certificate: relationships: account: data: type: accounts id: schema: type: object responses: '200': description: OK. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/AccountFiscalEntity' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /accounts/{accountId}/fiscal-entity/revalidate: patch: summary: Revalidate personal CPF description: >- Trigger a CPF revalidation for the Account's fiscal entity via Serpro. Refreshes `validation-status` and surfaces any registration inconsistencies. operationId: patch_accounts_accountId_fiscal-entity_revalidate tags: - accounts > fiscal entities x-use-cases: - Revalidate personal CPF after correction - Fix stale validation status parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK — revalidation triggered. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/AccountFiscalEntity' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /accounts/{accountId}/fiscal-entity/certificate: put: summary: Upload personal certificate description: Upload a new PKCS12 digital certificate for the Account's fiscal entity. operationId: put_accounts_accountId_fiscal-entity_certificate tags: - accounts > fiscal entities > certificate x-use-cases: - Upload a digital certificate for the personal account - Initial certificate setup for personal invoice emission parameters: - name: accountId in: path required: true description: The account id. schema: type: string requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary password: type: string responses: '200': description: OK — certificate stored. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/FiscalEntityCertificate' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 get: summary: Get personal certificate description: Get metadata about the Account's digital certificate. operationId: get_accounts_accountId_fiscal-entity_certificate tags: - accounts > fiscal entities > certificate parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: fiscal-entity-certificates attributes: issuer: AC Certisign expiration-date: '2027-06-01' status: valid schema: type: object properties: data: $ref: '#/components/schemas/FiscalEntityCertificate' '404': description: Not found. security: *ref_1 post: summary: Create personal certificate description: Create a new digital certificate record for the Account's fiscal entity. operationId: post_accounts_accountId_fiscal-entity_certificate tags: - accounts > fiscal entities > certificate x-use-cases: - Create a new certificate record for personal account - Register certificate metadata parameters: - name: accountId in: path required: true description: The account id. schema: type: string requestBody: required: true content: application/json: example: data: type: fiscal-entity-certificates attributes: expiration-date: status: validation-status: validation-errors: [] validation-by-id: s3-key: relationships: business: data: type: businesses id: professional: data: type: professionals id: schema: type: object responses: '201': description: Created. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/FiscalEntityCertificate' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 delete: summary: Remove personal certificate description: Remove the Account's digital certificate. operationId: delete_accounts_accountId_fiscal-entity_certificate tags: - accounts > fiscal entities > certificate x-use-cases: - Remove expired or invalid personal certificate - Clear certificate before uploading a new one parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '204': description: No content — certificate removed. security: *ref_1 /accounts/{accountId}/fiscal-entity/certificate/validate: post: summary: Validate personal certificate description: Test the stored digital certificate for the Account's fiscal entity. operationId: post_accounts_accountId_fiscal-entity_certificate_validate tags: - accounts > fiscal entities > certificate x-use-cases: - Test a newly uploaded personal certificate - Re-validate after a certificate upload parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK — validation-status updated. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/FiscalEntityCertificate' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /accounts/{accountId}/fiscal-entity/pass-gov: get: summary: Get personal PassGov description: Retrieve the stored **gov.br** credentials for the Account's fiscal entity. operationId: get_accounts_accountId_fiscal-entity_pass-gov tags: - accounts > fiscal entities > pass-gov x-use-cases: - Check stored gov.br credentials for personal account - View masked credential status parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: pass-govs attributes: cpf: '***.456.789-**' status: valid schema: type: object properties: data: $ref: '#/components/schemas/PassGov' '404': description: Not found. security: *ref_1 post: summary: Create personal PassGov description: Create **gov.br** credentials for the Account's fiscal entity. operationId: post_accounts_accountId_fiscal-entity_pass-gov tags: - accounts > fiscal entities > pass-gov x-use-cases: - Save gov.br credentials for personal account - Configure government portal access parameters: - name: accountId in: path required: true description: The account id. schema: type: string requestBody: required: true content: application/json: example: data: type: fiscal-entity-pass-govs attributes: cpf: password: status: validation-status: validation-errors: [] validation-by-id: relationships: business: data: type: businesses id: professional: data: type: professionals id: schema: type: object responses: '201': description: Created. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PassGov' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 patch: summary: Update personal PassGov description: Update the **gov.br** credentials for the Account's fiscal entity. operationId: patch_accounts_accountId_fiscal-entity_pass-gov tags: - accounts > fiscal entities > pass-gov x-use-cases: - Update gov.br credentials for personal account - Refresh expired or changed credentials parameters: - name: accountId in: path required: true description: The account id. schema: type: string requestBody: required: true content: application/json: example: data: type: fiscal-entity-pass-govs attributes: cpf: password: status: validation-status: validation-errors: [] validation-by-id: relationships: business: data: type: businesses id: professional: data: type: professionals id: schema: type: object responses: '200': description: OK. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PassGov' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /accounts/{accountId}/fiscal-entity/pass-gov/validate: post: summary: Validate personal gov.br description: Test the stored gov.br credentials for the Account's fiscal entity against the live government portal. operationId: post_accounts_accountId_fiscal-entity_pass-gov_validate tags: - accounts > fiscal entities > pass-gov x-use-cases: - Test gov.br credentials against the live portal - Confirm credentials work before fetching DAS/CND parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK — validation-status updated. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PassGov' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /accounts/{accountId}/fiscal-entity/pass-invoices: get: summary: Get personal pass-invoices description: Retrieve the prefeitura portal credentials for the Account's fiscal entity. operationId: get_accounts_accountId_fiscal-entity_pass-invoices tags: - accounts > fiscal entities > pass-invoices x-use-cases: - Check stored prefeitura portal credentials - View masked pass-invoices status parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: pass-invoices attributes: login: maria_user status: valid schema: type: object properties: data: $ref: '#/components/schemas/PassInvoice' '404': description: Not found. security: *ref_1 post: summary: Create personal pass-invoices description: Create prefeitura portal credentials for the Account's fiscal entity. operationId: post_accounts_accountId_fiscal-entity_pass-invoices tags: - accounts > fiscal entities > pass-invoices x-use-cases: - Save prefeitura portal credentials for personal account - Configure municipal invoice portal access parameters: - name: accountId in: path required: true description: The account id. schema: type: string requestBody: required: true content: application/json: example: data: type: fiscal-entity-pass-invoices attributes: authentication-type: username: login: password: status: validation-status: validation-errors: [] validation-by-id: relationships: business: data: type: businesses id: professional: data: type: professionals id: schema: type: object responses: '201': description: Created. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PassInvoice' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 patch: summary: Update personal pass-invoices description: Update the prefeitura portal credentials for the Account's fiscal entity. operationId: patch_accounts_accountId_fiscal-entity_pass-invoices tags: - accounts > fiscal entities > pass-invoices x-use-cases: - Update prefeitura portal credentials - Refresh expired or changed municipal credentials parameters: - name: accountId in: path required: true description: The account id. schema: type: string requestBody: required: true content: application/json: example: data: type: fiscal-entity-pass-invoices attributes: authentication-type: username: login: password: status: validation-status: validation-errors: [] validation-by-id: relationships: business: data: type: businesses id: professional: data: type: professionals id: schema: type: object responses: '200': description: OK. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PassInvoice' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /accounts/{accountId}/fiscal-entity/pass-invoices/validate: post: summary: Validate personal pass-invoices description: Test the stored pass-invoices credentials for the Account's fiscal entity. operationId: post_accounts_accountId_fiscal-entity_pass-invoices_validate tags: - accounts > fiscal entities > pass-invoices x-use-cases: - Test pass-invoices credentials against the revenue API - Confirm credentials work before attempting revenue refreshes parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK — validation-status updated. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PassInvoice' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /accounts/{accountId}/fiscal-entity/mei: get: summary: Get personal MEI data description: Retrieve the MEI registration data for the Account's fiscal entity — CNPJ, occupation, status. operationId: get_accounts_accountId_fiscal-entity_mei tags: - accounts > fiscal entities > mei x-use-cases: - View personal MEI registration data - Check MEI status on the user dashboard parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: fiscal-entity-meis attributes: cnpj: 12.345.678/0001-90 status: active occupation: Cabeleireiro '404': description: Not found. security: *ref_1 /accounts/{accountId}/fiscal-entity/mei/diagnosis: get: summary: Get personal MEI diagnosis description: Get the most recent MEI compliance diagnosis for the Account's fiscal entity. operationId: get_accounts_accountId_fiscal-entity_mei_diagnosis tags: - accounts > fiscal entities > mei x-use-cases: - Check latest MEI diagnosis without triggering a new check - View compliance status parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: fiscal-entity-diagnoses attributes: status: ok issues: [] checked-at: '2026-06-01T00:00:00Z' schema: type: object properties: data: $ref: '#/components/schemas/Diagnosis' '404': description: Not found. security: *ref_1 post: summary: Trigger personal MEI diagnosis description: Trigger a new MEI compliance diagnosis for the Account's fiscal entity. operationId: post_accounts_accountId_fiscal-entity_mei_diagnosis tags: - accounts > fiscal entities > mei x-use-cases: - Trigger a fresh MEI compliance check - Re-validate after fixing reported issues parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK — diagnosis triggered. content: application/vnd.api+json: example: data: id: '1' type: fiscal-entity-diagnoses attributes: status: processing issues: [] checked-at: '2026-06-01T00:00:00Z' schema: type: object properties: data: $ref: '#/components/schemas/Diagnosis' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /accounts/{accountId}/fiscal-entity/mei/cnd: get: summary: Get personal CND description: Get the CND (Certidão Negativa de Débitos) for the Account's MEI entity. operationId: get_accounts_accountId_fiscal-entity_mei_cnd tags: - accounts > fiscal entities > mei x-use-cases: - Download the CND certificate for personal account - Check tax clearance status parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: fiscal-entity-cnds attributes: status: clean url: https://... updated-at: '2026-06-01T00:00:00Z' '404': description: Not found. security: *ref_1 patch: summary: Update personal CND description: Request an update of the CND for the Account's MEI entity. Triggers an async fetch from Serpro. operationId: patch_accounts_accountId_fiscal-entity_mei_cnd tags: - accounts > fiscal entities > mei x-use-cases: - Request a CND update from Serpro - Refresh after resolving a tax debt parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '202': description: Accepted — CND fetch queued. '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /accounts/{accountId}/fiscal-entity/mei/cnd/notify: post: summary: Notify CND update description: Notify the Account about a CND update. operationId: post_accounts_accountId_fiscal-entity_mei_cnd_notify tags: - accounts > fiscal entities > mei parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK — notification sent. security: *ref_1 /accounts/{accountId}/fiscal-entity/mei/das: get: summary: Get personal DAS description: List the DAS (monthly MEI tax slip) records for the Account's fiscal entity. operationId: get_accounts_accountId_fiscal-entity_mei_das tags: - accounts > fiscal entities > mei x-use-cases: - View monthly DAS records for personal account - Check which months are paid or overdue parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK content: application/vnd.api+json: example: data: - id: '1' type: fiscal-entity-dases attributes: month: 6 year: 2026 amount_cents: 70000 status: paid schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Das' security: *ref_1 patch: summary: Update personal DAS description: Request a refresh of DAS data for the Account's fiscal entity. operationId: patch_accounts_accountId_fiscal-entity_mei_das tags: - accounts > fiscal entities > mei x-use-cases: - Request DAS refresh from Serpro - Update payment status after making a payment parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '202': description: Accepted — DAS refresh queued. content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Das' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /accounts/{accountId}/fiscal-entity/mei/das/notify: post: summary: Notify DAS update description: Notify the Account about a DAS update. operationId: post_accounts_accountId_fiscal-entity_mei_das_notify tags: - accounts > fiscal entities > mei parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK — notification sent. security: *ref_1 /accounts/{accountId}/fiscal-entity/mei/das/pdf: get: summary: Get personal DAS PDF description: Get the DAS PDF document for the Account's fiscal entity. operationId: get_accounts_accountId_fiscal-entity_mei_das_pdf tags: - accounts > fiscal entities > mei x-use-cases: - Download DAS PDF for a specific month - Print or save the payment slip parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK content: application/pdf: schema: type: string format: binary '404': description: Not found. security: *ref_1 /accounts/{accountId}/fiscal-entity/mei/ccmei/notify: post: summary: Notify CCMEI update description: Notify the Account about a CCMEI update. operationId: post_accounts_accountId_fiscal-entity_mei_ccmei_notify tags: - accounts > fiscal entities > mei parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK — notification sent. security: *ref_1 /accounts/{accountId}/fiscal-entity/mei/dasn: get: summary: Get personal DASN description: Get the DASN (annual MEI declaration) for the Account's fiscal entity. operationId: get_accounts_accountId_fiscal-entity_mei_dasn tags: - accounts > fiscal entities > mei x-use-cases: - View the annual DASN declaration - Check last declared amount parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: fiscal-entity-dasns attributes: year: 2025 status: submitted total-revenue-cents: 4500000 '404': description: Not found. security: *ref_1 patch: summary: Update personal DASN description: Update the DASN for the Account's fiscal entity. operationId: patch_accounts_accountId_fiscal-entity_mei_dasn tags: - accounts > fiscal entities > mei x-use-cases: - Update the annual DASN declaration - Submit corrected annual revenue parameters: - name: accountId in: path required: true description: The account id. schema: type: string requestBody: required: true content: application/json: example: total-revenue-cents: schema: type: object responses: '200': description: OK — DASN updated. '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /accounts/{accountId}/fiscal-entity/mei/cnpj: post: summary: Update personal CNPJ (admin) description: Update the CNPJ for the Account's fiscal entity (admin only). operationId: post_accounts_accountId_fiscal-entity_mei_cnpj tags: - accounts > fiscal entities > mei parameters: - name: accountId in: path required: true description: The account id. schema: type: string requestBody: required: true content: application/json: example: cnpj: schema: type: object responses: '200': description: OK — CNPJ updated. '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /accounts/{accountId}/invoices: post: summary: Create invoice description: Create a new invoice under the Account. operationId: post_accounts_accountId_invoices tags: - accounts > invoices x-use-cases: - Create a new invoice - Record a sale as an individual MEI parameters: - name: accountId in: path required: true description: The account id. schema: type: string requestBody: required: true content: application/vnd.api+json: example: data: type: invoices attributes: competency-date: nfse-number: nfse-verification-code: nfse-url: amount-cents: tax-irrf-cents: tax-pis-cents: tax-cofins-cents: tax-csll-cents: tax-iss-cents: status: cancel-status: provider-id: provider-status: emission-date: fiscal-date: relationships: seller-fiscal-entity: data: type: seller-fiscal-entities id: buyer-fiscal-entity: data: type: buyer-fiscal-entities id: schema: type: object responses: '201': description: Created. content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Invoice' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 get: summary: List invoices description: List invoices for the Account. operationId: get_accounts_accountId_invoices tags: - accounts > invoices x-use-cases: - List invoices - Filter by status, date range parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK content: application/vnd.api+json: example: data: - id: '1' type: invoices attributes: status: pending competency-date: '2026-06-01' amount_cents: 150000 schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Invoice' security: *ref_1 /accounts/{accountId}/invoices/{invoiceId}: get: summary: Get invoice description: Retrieve a single invoice by id. operationId: get_accounts_accountId_invoices_invoiceId tags: - accounts > invoices x-use-cases: - View a single invoice - Check emission status and details parameters: - name: accountId in: path required: true description: The account id. schema: type: string - name: invoiceId in: path required: true description: The invoice id. schema: type: string responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: invoices attributes: status: succeeded competency-date: '2026-06-01' amount_cents: 150000 nfse-number: '12345' schema: type: object properties: data: $ref: '#/components/schemas/Invoice' '404': description: Not found. security: *ref_1 /accounts/{accountId}/invoices/{invoiceId}/emit: post: summary: Emit invoice description: Emit an invoice. operationId: post_accounts_accountId_invoices_invoiceId_emit tags: - accounts > invoices x-use-cases: - Emit an invoice to the municipality - Submit NFS-e for a pending invoice parameters: - name: accountId in: path required: true description: The account id. schema: type: string - name: invoiceId in: path required: true description: The invoice id. schema: type: string responses: '200': description: OK — emission queued. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/Invoice' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /accounts/{accountId}/invoices/{invoiceId}/cancel: post: summary: Cancel invoice description: Cancel an invoice. operationId: post_accounts_accountId_invoices_invoiceId_cancel tags: - accounts > invoices x-use-cases: - Cancel an issued invoice - Request NFS-e cancellation from the municipality parameters: - name: accountId in: path required: true description: The account id. schema: type: string - name: invoiceId in: path required: true description: The invoice id. schema: type: string responses: '200': description: OK — cancellation queued. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/Invoice' '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /accounts/{accountId}: get: summary: Show account description: >- Retrieve the **Account** by id — personal profile, email, phone, locale, validation state, and the list of **Businesses** the account belongs to. operationId: get_accounts_accountId tags: - accounts x-use-cases: - View account profile and linked businesses - Bootstrap app state from account id parameters: - name: accountId in: path required: true description: The account id. schema: type: string responses: '200': description: OK content: application/vnd.api+json: example: data: id: '42' type: accounts attributes: name: Maria Santos email: maria@example.com phone: '11912345678' locale: pt-BR validation-state: pending created-at: '2026-01-01T00:00:00Z' schema: type: object properties: data: $ref: '#/components/schemas/Account' '404': description: Not found. security: *ref_1 patch: summary: Update account description: Update the **Account** profile — name, locale, or phone number. Only the supplied attributes are written. operationId: patch_accounts_accountId tags: - accounts x-use-cases: - Update account name, locale, or phone - Correct profile information after onboarding parameters: - name: accountId in: path required: true description: The account id. schema: type: string requestBody: required: true content: application/vnd.api+json: example: data: type: accounts attributes: email: name: phone-number: phone-country: tax-number: locale: has-password: is-validated: mobile-token: birthday: extra: {} source: terms: {} personal-data: {} account-type: relationships: businesses: data: - type: businesses id: schema: type: object responses: '200': description: OK — account updated. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/Account' '404': description: Not found. '422': description: Unprocessable Entity — validation error. security: *ref_1 /accounts/{accountId}/professional-contracts/{contractId}: get: summary: Get account contract description: >- Retrieve a single **ProfessionalContract** by id, scoped to the given Account. Returns the contract with full status, attached PDFs, and linked BusinessRequest. operationId: get_accounts_accountId_professional-contracts_contractId tags: - accounts > professional contracts x-use-cases: - View a single contract by account scope - Check contract status and attached PDFs parameters: - name: accountId in: path required: true description: The account id. schema: type: string - name: contractId in: path required: true description: The professional contract id. schema: type: string responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: professional-contracts attributes: status: approved partnership-start-date: '2026-01-01' partnership-end-date: '2026-12-31' pdf-url: https://cdn.example.com/contract.pdf created-at: '2026-01-01T00:00:00Z' schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalContract' '404': description: Not found. security: *ref_1 /accounts/{accountId}/professional-invoices/{invoiceId}: get: summary: Get account invoice description: >- Retrieve a single **ProfessionalInvoice** by id, scoped to the given Account. Returns the invoice with status, amounts, buyer fiscal entity, and emission details. operationId: get_accounts_accountId_professional-invoices_invoiceId tags: - accounts > professional invoices x-use-cases: - View a single invoice by account scope - Check emission status and amounts parameters: - name: accountId in: path required: true description: The account id. schema: type: string - name: invoiceId in: path required: true description: The professional invoice id. schema: type: string responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: professional-invoices attributes: status: succeeded invoice-type: services competency-date: '2026-01-15' amount: '150.00' buyer-name: João Silva created-at: '2026-01-01T00:00:00Z' schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalInvoice' '404': description: Not found. security: *ref_1 /accounts/{accountId}/professional-invoices/{invoiceId}/cancel: patch: summary: Cancel account invoice description: Request cancellation of a professional invoice scoped to the given Account. operationId: patch_accounts_accountId_professional-invoices_invoiceId_cancel tags: - accounts > professional invoices x-use-cases: - Cancel a professional invoice via account scope - Request NFS-e cancellation via account dashboard parameters: - name: accountId in: path required: true description: The account id. schema: type: string - name: invoiceId in: path required: true description: The professional invoice id. schema: type: string responses: '200': description: OK — cancellation queued. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalInvoice' '422': description: Unprocessable Entity — validation error. security: *ref_1 /accounts/{accountId}/professional-invoices/{invoiceId}/emit: patch: summary: Emit account invoice description: Emit a professional invoice scoped to the given Account. Triggers NFS-e emission via eNotas integration. operationId: patch_accounts_accountId_professional-invoices_invoiceId_emit tags: - accounts > professional invoices x-use-cases: - Emit a professional invoice via account scope - Trigger NFS-e emission without knowing the professional id parameters: - name: accountId in: path required: true description: The account id. schema: type: string - name: invoiceId in: path required: true description: The professional invoice id. schema: type: string responses: '200': description: OK — emission queued. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalInvoice' '422': description: Unprocessable Entity — validation error. security: *ref_1 /accounts/{accountId}/professional-invoices/{invoiceId}/reemit: post: summary: Reemit account invoice description: Re-attempt emission for a failed professional invoice scoped to the given Account. operationId: post_accounts_accountId_professional-invoices_invoiceId_reemit tags: - accounts > professional invoices x-use-cases: - Re-emit a failed professional invoice via account scope - Retry emission after fixing root cause parameters: - name: accountId in: path required: true description: The account id. schema: type: string - name: invoiceId in: path required: true description: The professional invoice id. schema: type: string responses: '200': description: OK — re-emission queued. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalInvoice' '422': description: Unprocessable Entity — validation error. security: *ref_1 /business-categories: get: summary: List business categories description: List **BusinessCategories** (occupation codes, service categories) available for the current Business. operationId: get_business-categories tags: - businesses > categories x-use-cases: - List available occupation categories - Populate category selector when creating professionals parameters: - *ref_3 responses: '200': description: OK — list of business categories. content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/BusinessCategory' security: *ref_1 post: summary: Create business category description: Create a new **BusinessCategory** for the current Business. operationId: post_business-categories tags: - businesses > categories x-use-cases: - Create a new category for the business - Define custom occupation codes parameters: - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: business-categories attributes: name: professional-categories: [] schema: type: object responses: '201': description: Created. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/BusinessCategory' '422': description: Unprocessable Entity — validation error. security: *ref_1 /business-categories/{businesscategoryId}: delete: summary: Delete business category description: Remove a **BusinessCategory**. Irreversible — linked professionals and services lose the category assignment. operationId: delete_business-categories_businesscategoryId tags: - businesses > categories x-use-cases: - Remove a category - Archive unused occupation codes parameters: - name: businesscategoryId in: path required: true description: The business category id. schema: type: string - *ref_3 responses: '204': description: No content — category deleted. '404': description: Not found. security: *ref_1 get: summary: Show business category description: Retrieve a single **BusinessCategory** by id. operationId: get_business-categories_businesscategoryId tags: - businesses > categories x-use-cases: - View a single category - Check category configuration parameters: - name: businesscategoryId in: path required: true description: The business category id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/BusinessCategory' '404': description: Not found. security: *ref_1 patch: summary: Update business category description: Update a **BusinessCategory** — name, status, or configuration. operationId: patch_business-categories_businesscategoryId tags: - businesses > categories x-use-cases: - Update category name or status - Correct category information parameters: - name: businesscategoryId in: path required: true description: The business category id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: business-categories attributes: name: professional-categories: [] schema: type: object responses: '200': description: OK — category updated. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/BusinessCategory' '404': description: Not found. '422': description: Unprocessable Entity — validation error. security: *ref_1 /business-requests: get: summary: List business requests description: >- List **BusinessRequests** for the current Business. Filter by status, type, or professional. Useful for dashboards showing pending workflows. operationId: get_business-requests tags: - businesses > requests x-use-cases: - List all workflows for the business - Dashboard view of pending and completed requests parameters: - *ref_3 responses: '200': description: OK — list of business requests. content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/BusinessRequest' security: *ref_1 /business-requests/{businessrequestId}: get: summary: Show business request description: Retrieve a single **BusinessRequest** by id — type, status, data payload, and linked resources. operationId: get_business-requests_businessrequestId tags: - businesses > requests x-use-cases: - View a single workflow request - Check status, type, and data payload parameters: - name: businessrequestId in: path required: true description: The business request id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/BusinessRequest' '404': description: Not found. security: *ref_1 /business-requests/{businessrequestId}/status: get: summary: Deprecated status endpoint description: '**Deprecated** — use `PATCH /business-requests/{id}/update-status` instead. Alias for status transition.' operationId: get_business-requests_businessrequestId_status tags: - businesses > requests - Obsoleto x-use-cases: - Advance workflow status (deprecated — use update-status) - Legacy status transition parameters: - name: businessrequestId in: path required: true description: The business request id. schema: type: string - *ref_3 responses: '200': description: OK — status returned. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/BusinessRequest' '404': description: Not found. security: *ref_1 deprecated: true /business-settings: get: summary: List business settings description: List **BusinessSettings** for the current Business — operating hours, notification preferences, feature flags. operationId: get_business-settings tags: - businesses > settings x-use-cases: - List business configuration settings - Review operating hours, notification preferences parameters: - *ref_3 responses: '200': description: OK — list of business settings. content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/BusinessSetting' security: *ref_1 post: summary: Create business setting description: Create a new **BusinessSettings** entry for the current Business. operationId: post_business-settings tags: - businesses > settings x-use-cases: - Create a new business setting - Configure feature flags or preferences parameters: - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: business-settings attributes: group-name: name: value: relationships: business: data: type: businesses id: schema: type: object responses: '201': description: Created. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/BusinessSetting' '422': description: Unprocessable Entity — validation error. security: *ref_1 /business-settings/{businesssettingId}: delete: summary: Delete business setting description: Remove a **BusinessSetting**. The setting reverts to its default value. operationId: delete_business-settings_businesssettingId tags: - businesses > settings x-use-cases: - Remove a business setting - Revert to default configuration parameters: - name: businesssettingId in: path required: true description: The business setting id. schema: type: string - *ref_3 responses: '204': description: No content — setting deleted. '404': description: Not found. security: *ref_1 get: summary: Show business setting description: Retrieve a single **BusinessSetting** by id. operationId: get_business-settings_businesssettingId tags: - businesses > settings x-use-cases: - View a single business setting - Check setting value and metadata parameters: - name: businesssettingId in: path required: true description: The business setting id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/BusinessSetting' '404': description: Not found. security: *ref_1 patch: summary: Update business setting description: Update a **BusinessSetting** value. operationId: patch_business-settings_businesssettingId tags: - businesses > settings x-use-cases: - Update a business setting value - Toggle feature flags or preferences parameters: - name: businesssettingId in: path required: true description: The business setting id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: business-settings attributes: group-name: name: value: relationships: business: data: type: businesses id: schema: type: object responses: '200': description: OK — setting updated. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/BusinessSetting' '404': description: Not found. '422': description: Unprocessable Entity — validation error. security: *ref_1 /businesses: get: summary: List businesses description: >- List **Businesses** the authenticated Account belongs to. Returns all businesses with their brand, status, and permissions. operationId: get_businesses tags: - businesses x-use-cases: - List all businesses the user belongs to - Bootstrap business selector on app load parameters: - *ref_3 responses: '200': description: OK — list of businesses. content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Business' security: *ref_1 post: summary: Create business description: Create a new **Business** under the current Account. Protected by Cloudflare Turnstile. operationId: post_businesses tags: - businesses x-use-cases: - Create a new business as a self-service signup - Register a salon or studio on the platform requestBody: required: true content: application/vnd.api+json: example: data: type: businesses attributes: name: trading-name: document: document-type: brand: culture: locale: timezone: permalink: country-iso: relationships: account: data: type: accounts id: category: data: type: business-categories id: week-schedule: data: type: week-schedules id: professionals: data: - type: professionals id: professional-categories: data: - type: professional-categories id: settings: data: - type: business-settings id: schema: type: object responses: '201': description: Created — business created. content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Business' '422': description: Unprocessable Entity — validation error. security: *ref_1 /businesses/{businessId}: get: summary: Show business description: Retrieve a single **Business** by id — name, brand, status, and configuration. operationId: get_businesses_businessId tags: - businesses x-use-cases: - View business details and configuration - Check business status before performing operations parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/Business' '404': description: Not found. security: *ref_1 patch: summary: Update business description: Update a **Business** profile — name, brand, or configuration settings. operationId: patch_businesses_businessId tags: - businesses x-use-cases: - Update business name, brand, or settings - Correct business information after onboarding parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: businesses attributes: name: trading-name: document: document-type: brand: culture: locale: timezone: permalink: country-iso: relationships: account: data: type: accounts id: category: data: type: business-categories id: week-schedule: data: type: week-schedules id: professionals: data: - type: professionals id: professional-categories: data: - type: professional-categories id: settings: data: - type: business-settings id: schema: type: object responses: '200': description: OK — business updated. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/Business' '404': description: Not found. '422': description: Unprocessable Entity — validation error. security: *ref_1 /businesses/{businessId}/constants: get: summary: Business constants description: Fetch platform-wide enumerations scoped to the given Business. Same data as `GET /constants` but business-aware. operationId: get_businesses_businessId_constants tags: - platform > constants x-use-cases: - Fetch business-scoped enumerations - Populate dropdowns with occupation codes and status values parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 responses: '200': description: OK security: *ref_1 /businesses/{businessId}/representative: get: summary: Get business representative description: >- Fetch the legal representative (a Person) registered for the Business. Required by the eNotas / Serpro integrations when issuing invoices. operationId: get_businesses_businessId_representative tags: - businesses > representatives x-use-cases: - View the legal representative for a business - Check representative before invoice emission parameters: - name: businessId in: path required: true description: The business id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/Representative' '404': description: Not found. security: *ref_1 /constants: get: summary: Platform constants description: >- Fetch the platform-wide enumerations (statuses, occupation codes, taxation regimes, …). Cache aggressively — the payload changes only with deploys. operationId: get_constants tags: - platform > constants x-use-cases: - Populate dropdowns for occupation codes and tax regimes on form load - Validate status values before submitting a business request responses: '200': description: OK security: *ref_1 /professional-categories: get: summary: List professional categories description: List **ProfessionalCategories** (specialization areas) available for the current Business. operationId: get_professional-categories tags: - businesses > professional categories x-use-cases: - List available professional specializations - Populate category selector for professional profiles parameters: - *ref_3 responses: '200': description: OK — list of professional categories. content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/ProfessionalCategory' security: *ref_1 post: summary: Create professional category description: Create a new **ProfessionalCategory** for the current Business. operationId: post_professional-categories tags: - businesses > professional categories x-use-cases: - Create a new professional category - Define custom specialization areas parameters: - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: professional-categories attributes: name: color: translation-key: sort-weight: is-locked: relationships: permissions-group: data: type: permissions-groups id: schema: type: object responses: '201': description: Created. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalCategory' '422': description: Unprocessable Entity — validation error. security: *ref_1 /professional-categories/{professionalcategoryId}: delete: summary: Delete professional category description: Remove a **ProfessionalCategory**. Irreversible — linked professionals lose the category assignment. operationId: delete_professional-categories_professionalcategoryId tags: - businesses > professional categories x-use-cases: - Remove a professional category - Archive unused specialization areas parameters: - name: professionalcategoryId in: path required: true description: The professional category id. schema: type: string - *ref_3 responses: '204': description: No content — category deleted. '400': description: Bad Request — category still has professionals. content: application/json: example: success: false errors: - title: CategoryHasProfessionals detail: Category still has professionals assigned code: professional_categories.delete.has_professionals status: 400 '404': description: Not found. security: *ref_1 get: summary: Show professional category description: Retrieve a single **ProfessionalCategory** by id. operationId: get_professional-categories_professionalcategoryId tags: - businesses > professional categories x-use-cases: - View a single professional category - Check category configuration parameters: - name: professionalcategoryId in: path required: true description: The professional category id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalCategory' '404': description: Not found. security: *ref_1 patch: summary: Update professional category description: Update a **ProfessionalCategory** — name, status, or configuration. operationId: patch_professional-categories_professionalcategoryId tags: - businesses > professional categories x-use-cases: - Update professional category name or status - Correct category information parameters: - name: professionalcategoryId in: path required: true description: The professional category id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: professional-categories attributes: name: color: translation-key: sort-weight: is-locked: relationships: permissions-group: data: type: permissions-groups id: schema: type: object responses: '200': description: OK — category updated. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalCategory' '404': description: Not found. '422': description: Unprocessable Entity — validation error. security: *ref_1 /professional-contracts: get: summary: List contracts description: List **ProfessionalContracts** between the current Business and its Professionals. operationId: get_professional-contracts tags: - businesses x-use-cases: - List all professional contracts for the business - Dashboard view of contract statuses parameters: - *ref_3 responses: '200': description: OK — list of professional contracts. content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/ProfessionalContract' security: *ref_1 /professional-contracts/{professionalcontractId}: delete: summary: Deprecated description: Terminate (soft-delete) a **ProfessionalContract**, ending the working relationship. operationId: delete_professional-contracts_professionalcontractId tags: - businesses - Obsoleto x-use-cases: - Delete a professional contract (deprecated — use terminate) - Legacy contract deletion parameters: - name: professionalcontractId in: path required: true description: The professional contract id. schema: type: string - *ref_3 responses: '200': description: OK — contract deleted. '404': description: Not found. security: *ref_1 deprecated: true get: summary: Show contract description: Retrieve a single **ProfessionalContract** with its full status and attached PDFs. operationId: get_professional-contracts_professionalcontractId tags: - businesses x-use-cases: - View a single contract - Check contract status, PDFs, and linked BusinessRequest parameters: - name: professionalcontractId in: path required: true description: The professional contract id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalContract' '404': description: Not found. security: *ref_1 /professional-contracts/{professionalcontractId}/cancellation-request: patch: summary: Deprecated description: >- **Deprecated** — use `PATCH /professional-contracts/{id}/cancel` instead. Requests cancellation of an approved contract. operationId: patch_professional-contracts_professionalcontractId_cancellation-request tags: - businesses - Obsoleto x-use-cases: - Request contract cancellation (deprecated — use cancel) - Legacy cancellation flow parameters: - name: professionalcontractId in: path required: true description: The professional contract id. schema: type: string - *ref_3 responses: '200': description: OK — cancellation requested. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalContract' '404': description: Not found. security: *ref_1 deprecated: true /professional-contracts/{professionalcontractId}/in-approval: patch: summary: Deprecated description: >- **Deprecated** — use `PATCH /professional-contracts/{id}/update-status` instead. Requests approval for a contract that is currently in `filling` status. operationId: patch_professional-contracts_professionalcontractId_in-approval tags: - businesses - Obsoleto x-use-cases: - Request approval for a filling contract (deprecated — use update-status) - Legacy approval request flow parameters: - name: professionalcontractId in: path required: true description: The professional contract id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: professional-contracts attributes: status: contract-status: pdf-url: termination-pdf-url: termination-business-request-id: partnership-start-date: partnership-end-date: relationships: business: data: type: businesses id: professional: data: type: professionals id: business-request: data: type: business-requests id: schema: type: object responses: '200': description: OK — status transitioned. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalContract' '404': description: Not found. '422': description: Unprocessable Entity — validation error. security: *ref_1 deprecated: true /professional-contracts/{professionalcontractId}/status: patch: summary: Deprecated status endpoint description: '**Deprecated** — use `PATCH /professional-contracts/{id}/update-status` instead. Alias for status transition.' operationId: patch_professional-contracts_professionalcontractId_status tags: - businesses - Obsoleto x-use-cases: - Advance contract status (deprecated — use update-status) - Legacy status transition parameters: - name: professionalcontractId in: path required: true description: The professional contract id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: professional-contracts attributes: status: contract-status: pdf-url: termination-pdf-url: termination-business-request-id: partnership-start-date: partnership-end-date: relationships: business: data: type: businesses id: professional: data: type: professionals id: business-request: data: type: business-requests id: schema: type: object responses: '200': description: OK — status transitioned. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalContract' '404': description: Not found. '422': description: Unprocessable Entity — validation error. security: *ref_1 deprecated: true /professional-contracts/update-status: patch: summary: Advance status (body-based) description: >- Advance a **ProfessionalContract** through its status workflow. The target status and optional `termination_pdf_url` are passed in the request body. Requires the `ilm-business` header. operationId: patch_professional-contracts_update-status tags: - businesses x-use-cases: - Advance contract status from the body-based endpoint - Used by n8n automations and internal tooling parameters: - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: professional-contracts attributes: status: contract-status: pdf-url: termination-pdf-url: termination-business-request-id: partnership-start-date: partnership-end-date: relationships: business: data: type: businesses id: professional: data: type: professionals id: business-request: data: type: business-requests id: schema: type: object responses: '200': description: OK — status transitioned. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalContract' '404': description: Not found. '422': description: Unprocessable Entity — validation error. security: *ref_1 /professional-fiscal-entities: get: summary: List professionals (Privado) description: >- List the **ProfessionalFiscalEntities** (each Professional's MEI / CNPJ / CPF) registered for the current Business. operationId: get_professional-fiscal-entities tags: - professionals > fiscal entities - Privado x-use-cases: - List all Professional MEI entities to show fiscal readiness on the business dashboard - Check which Professionals still need their fiscal entity configured before invoice emission parameters: - *ref_3 responses: '200': description: OK — list of professional fiscal entities. content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/ProfessionalFiscalEntity' security: *ref_1 /professional-invoices: get: summary: List professional invoices description: >- List **ProfessionalInvoices** (NFS-e) issued under the current Business. Filter by status to track pending, succeeded, or failed emissions. operationId: get_professional-invoices tags: - businesses > professional invoices x-use-cases: - List all professional invoices for the business - Filter by status to track emission progress parameters: - *ref_3 responses: '200': description: OK — list of professional invoices. content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/ProfessionalInvoice' security: *ref_1 /professional-invoices/{professionalinvoiceId}: get: summary: Show professional invoice description: >- Retrieve a single **ProfessionalInvoice** by id — status, amounts, buyer fiscal entity, competency date, and emission details. operationId: get_professional-invoices_professionalinvoiceId tags: - businesses > professional invoices x-use-cases: - View a single professional invoice - Check emission status, amounts, and buyer details parameters: - name: professionalinvoiceId in: path required: true description: The professional invoice id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalInvoice' '404': description: Not found. security: *ref_1 patch: summary: Update professional invoice description: >- Update a **ProfessionalInvoice** — typically to set or correct the buyer fiscal entity or competency date before emission. operationId: patch_professional-invoices_professionalinvoiceId tags: - businesses > professional invoices x-use-cases: - Update invoice details before emission - Set or correct buyer fiscal entity and competency date parameters: - name: professionalinvoiceId in: path required: true description: The professional invoice id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: professional-invoices attributes: invoice-type: items: [] buyer-id: buyer-type: buyer-data: {} status: cancel-status: status-reason: cancel-reason: emission-date: fiscal-date: nfse-url: total-value-cents: source: invoice-id: relationships: business: data: type: businesses id: professional: data: type: professionals id: professional-fiscal-entity: data: type: professional-fiscal-entities id: business-request: data: type: business-requests id: schema: type: object responses: '200': description: OK — invoice updated. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalInvoice' '404': description: Not found. '422': description: Unprocessable Entity — validation error. security: *ref_1 /professional-services: get: summary: List professional services description: List **ProfessionalServices** (service offerings) available for the current Business. operationId: get_professional-services tags: - businesses > services x-use-cases: - List available professional services - Populate service selector for booking flows parameters: - *ref_3 responses: '200': description: OK — list of professional services. content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/ProfessionalService' security: *ref_1 post: summary: Create professional service description: Create a new **ProfessionalService** for the current Business. operationId: post_professional-services tags: - businesses > services x-use-cases: - Create a new professional service - Define a service offering with name, duration, and price parameters: - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: professional-services attributes: services: [] pay-periodicity: relationships: business: data: type: businesses id: professional: data: type: professionals id: schema: type: object responses: '201': description: Created. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalService' '422': description: Unprocessable Entity — validation error. security: *ref_1 /professional-services/{professionalserviceId}: delete: summary: Delete professional service description: Remove a **ProfessionalService**. Irreversible — linked bookings lose the service. operationId: delete_professional-services_professionalserviceId tags: - businesses > services x-use-cases: - Remove a professional service - Archive discontinued offerings parameters: - name: professionalserviceId in: path required: true description: The professional service id. schema: type: string - *ref_3 responses: '204': description: No content — service deleted. '404': description: Not found. security: *ref_1 get: summary: Show professional service description: Retrieve a single **ProfessionalService** by id. operationId: get_professional-services_professionalserviceId tags: - businesses > services x-use-cases: - View a single professional service - Check service details and pricing parameters: - name: professionalserviceId in: path required: true description: The professional service id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalService' '404': description: Not found. security: *ref_1 patch: summary: Update professional service description: Update a **ProfessionalService** — name, duration, price, or category. operationId: patch_professional-services_professionalserviceId tags: - businesses > services x-use-cases: - Update service name, duration, or price - Correct service information parameters: - name: professionalserviceId in: path required: true description: The professional service id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: professional-services attributes: services: [] pay-periodicity: relationships: business: data: type: businesses id: professional: data: type: professionals id: schema: type: object responses: '200': description: OK — service updated. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/ProfessionalService' '404': description: Not found. '422': description: Unprocessable Entity — validation error. security: *ref_1 /professionals: get: summary: List professionals description: List **Professionals** linked to the current Business. operationId: get_professionals tags: - professionals x-use-cases: - List all professionals for the business - Dashboard view of professional profiles parameters: - *ref_3 responses: '200': description: OK — list of professionals. content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Professional' security: *ref_1 post: summary: Create professional description: >- Create a new **Professional** under the current Business. Triggers a welcome email when the Professional is created with an email address. operationId: post_professionals tags: - professionals x-use-cases: - Onboard a new beauty professional to the Business - Create a Professional record as the first step before issuing contracts or invoices parameters: - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: professionals attributes: name: initials: email: phone-number: phone-country: phone-composed: individual-tax-number: birth-date: address: {} gender: marital-status: rg: issuing-organization: shipping-date: national-identification-data: {} is-active: category-key: relationships: account: data: type: accounts id: business: data: type: businesses id: category: data: type: professional-categories id: permissions-group: data: type: permissions-groups id: schema: type: object responses: '201': description: Created — professional created. content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Professional' '422': description: Unprocessable Entity — validation error. security: *ref_1 /professionals/{professionalId}: delete: summary: Delete professional description: >- Remove a **Professional** from the Business. Irreversible — linked contracts, invoices, and fiscal entities are also affected. operationId: delete_professionals_professionalId tags: - professionals x-use-cases: - Remove a professional who no longer works at the business - Archive inactive professional profiles parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 responses: '204': description: No content — professional deleted. '404': description: Not found. security: *ref_1 get: summary: Show professional description: Retrieve a single **Professional** with personal data and links to their contract and fiscal entity. operationId: get_professionals_professionalId tags: - professionals x-use-cases: - View a single professional profile - Check professional details before creating a contract parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/Professional' '404': description: Not found. security: *ref_1 patch: summary: Update professional description: Update a **Professional** — name, email, or other profile attributes. operationId: patch_professionals_professionalId tags: - professionals x-use-cases: - Update professional name or contact - Correct profile information parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: professionals attributes: name: initials: email: phone-number: phone-country: phone-composed: individual-tax-number: birth-date: address: {} gender: marital-status: rg: issuing-organization: shipping-date: national-identification-data: {} is-active: category-key: relationships: account: data: type: accounts id: business: data: type: businesses id: category: data: type: professional-categories id: permissions-group: data: type: permissions-groups id: schema: type: object responses: '200': description: OK — professional updated. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/Professional' '404': description: Not found. '422': description: Unprocessable Entity — validation error. security: *ref_1 /professionals/{professionalId}/is-owned-by-account: get: summary: Ownership check (Privado) description: Check whether the authenticated Account owns/manages the given Professional. Used to gate edit UIs. operationId: get_professionals_professionalId_is-owned-by-account tags: - professionals - Privado x-use-cases: - Check if the authenticated account owns the professional - Gate edit UIs for professional profiles parameters: - name: professionalId in: path required: true description: The professional id. schema: type: string - *ref_3 responses: '200': description: OK — ownership status returned. security: *ref_1 /week-schedules: get: summary: List week schedules description: List **WeekSchedules** for the current Business — recurring weekly working hours. operationId: get_week-schedules tags: - businesses > schedules x-use-cases: - List weekly schedules for the business - View configured operating hours parameters: - *ref_3 responses: '200': description: OK — list of week schedules. content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/WeekSchedule' security: *ref_1 post: summary: Create week schedule description: Create a new **WeekSchedule** for the current Business. operationId: post_week-schedules tags: - businesses > schedules x-use-cases: - Create a new weekly schedule - Set up operating hours for a business parameters: - *ref_3 requestBody: required: true content: application/vnd.api+json: example: data: type: week-schedules attributes: time-intervals: [] relationships: business: data: type: businesses id: schema: type: object responses: '201': description: Created. content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/WeekSchedule' '422': description: Unprocessable Entity — validation error. security: *ref_1 /week-schedules/{weekscheduleId}: delete: summary: Delete week schedule description: Remove a **WeekSchedule**. The Business loses its configured weekly hours. operationId: delete_week-schedules_weekscheduleId tags: - businesses > schedules x-use-cases: - Remove a weekly schedule - Clear configured operating hours parameters: - name: weekscheduleId in: path required: true description: The week schedule id. schema: type: string - *ref_3 responses: '204': description: No content — schedule deleted. '404': description: Not found. security: *ref_1 get: summary: Show week schedule description: Retrieve a single **WeekSchedule** by id — weekday open/close times and breaks. operationId: get_week-schedules_weekscheduleId tags: - businesses > schedules x-use-cases: - View a single weekly schedule - Check weekday open/close times and breaks parameters: - name: weekscheduleId in: path required: true description: The week schedule id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/WeekSchedule' '404': description: Not found. security: *ref_1 /fiscal-entities: get: summary: List fiscal entities description: >- List all **FiscalEntities** accessible to the current Business. Returns CPF/CNPJ entities with their validation status, emission status, and linked sub-resource indicators. operationId: get_fiscal-entities tags: - internal ★ > fiscal entities x-use-cases: - List all fiscal entities for the business to show on the dashboard - Check which fiscal entities still need configuration before invoice emission parameters: - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/SellerFiscalEntity' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 post: summary: Create a fiscal entity description: >- Create a new **FiscalEntity** — registers a CPF or CNPJ with address and initial configuration. After creation, attach certificates, PassGov, and PassInvoice credentials. operationId: post_fiscal-entities tags: - internal ★ > fiscal entities x-use-cases: - Register a new CPF or CNPJ as the first step before configuring certificates and credentials - Add a new professional's fiscal entity to the business parameters: - *ref_3 requestBody: required: true content: application/vnd.api+json: schema: type: object example: data: type: fiscal-entities attributes: name: email: address: status: emission-status: certificate-expiration-date: status-pass-govs: status-pass-invoices: status-certificate: has-pass-gov: has-pass-invoices: has-certificate: document-type: tax-number: tax-country: tax-data: extra: last-emission-validation: foreign-id: foreign-type: relationships: parent-fiscal-entity: data: type: fiscal-entities id: account: data: type: accounts id: fiscal-entity-mei: data: type: fiscal-entity-meis id: responses: '201': description: Created content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/SellerFiscalEntity' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /fiscal-entities/{fiscalEntityId}: get: summary: Get a fiscal entity description: >- Retrieve a single **FiscalEntity** by id, including tax data, validation status, emission status, and sub-resource indicators. operationId: get_fiscal-entities_fiscalEntityId tags: - internal ★ > fiscal entities x-use-cases: - View full fiscal entity details including validation and emission status - Check certificate expiration and sub-resource status before emitting invoices parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/SellerFiscalEntity' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '404': description: Not Found — resource does not exist. content: &ref_5 application/json: example: success: false errors: - title: NotFound detail: Resource not found code: resource.not_found status: 404 security: *ref_1 patch: summary: Update a fiscal entity description: Update a **FiscalEntity** — correct tax number, address, or other fiscal attributes. operationId: patch_fiscal-entities_fiscalEntityId tags: - internal ★ > fiscal entities x-use-cases: - Correct tax number or address after a data entry error - Update fiscal entity attributes after a government status change parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: schema: type: object example: data: type: fiscal-entities attributes: name: email: address: status: emission-status: certificate-expiration-date: status-pass-govs: status-pass-invoices: status-certificate: has-pass-gov: has-pass-invoices: has-certificate: document-type: tax-number: tax-country: tax-data: extra: last-emission-validation: foreign-id: foreign-type: relationships: parent-fiscal-entity: data: type: fiscal-entities id: account: data: type: accounts id: fiscal-entity-mei: data: type: fiscal-entity-meis id: responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/SellerFiscalEntity' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 delete: summary: Delete a fiscal entity description: >- Remove a **FiscalEntity** and all linked sub-resources (certificates, credentials, revenue records). Irreversible. operationId: delete_fiscal-entities_fiscalEntityId tags: - internal ★ > fiscal entities x-use-cases: - Remove a fiscal entity that is no longer associated with the business - Clean up test or duplicate fiscal entity records parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '204': description: No Content '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '404': description: Not Found — resource does not exist. content: *ref_5 security: *ref_1 /fiscal-entities/{fiscalEntityId}/revalidate: post: summary: Revalidate a fiscal entity description: >- Trigger revalidation of the **FiscalEntity** against government services (Receita Federal / Serpro). Refreshes tax data, MEI status, and CNAE codes. operationId: post_fiscal-entities_fiscalEntityId_revalidate tags: - internal ★ > fiscal entities x-use-cases: - Refresh CPF/CNPJ validation after data correction - Revalidate after a previously failed government check parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /fiscal-entities/{fiscalEntityId}/validate-emission: post: summary: Validate emission (deprecated) description: >- Validate the emission setup for a **FiscalEntity** by sending a test invoice through eNotas. **Deprecated** — use `POST /fiscal-entities/{fiscalEntityId}/invoices-emission/validate` instead. operationId: post_fiscal-entities_fiscalEntityId_validate-emission tags: - internal ★ > fiscal entities x-use-cases: - Test emission setup by sending a zero-value NFS-e through eNotas (deprecated) - Use invoices-emission/validate instead parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK — returns emission-validations resource. content: application/vnd.api+json: example: data: id: '1' type: emission-validations attributes: status: succeeded author: '123' author-type: admin authentication-type: pass_only attempted-at: '2026-07-28T10:30:00Z' completed-at: '2026-07-28T10:30:05Z' is-valid: true schema: type: object properties: data: $ref: '#/components/schemas/EmissionValidation' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 deprecated: true /fiscal-entities/{fiscalEntityId}/validation-status: get: summary: Get validation status (deprecated) description: >- Get the current emission validation status for a **FiscalEntity**. **Deprecated** — use `GET /fiscal-entities/{fiscalEntityId}/invoices-emission/validate` instead. operationId: get_fiscal-entities_fiscalEntityId_validation-status tags: - internal ★ > fiscal entities x-use-cases: - Check whether emission validation passed or failed (deprecated) - Use invoices-emission/validate instead parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK — returns emission-validations resource. content: application/vnd.api+json: example: data: id: '1' type: emission-validations attributes: status: succeeded author: '123' author-type: admin authentication-type: pass_only attempted-at: '2026-07-28T10:30:00Z' completed-at: '2026-07-28T10:30:05Z' is-valid: true schema: type: object properties: data: $ref: '#/components/schemas/EmissionValidation' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '404': description: Not Found — resource does not exist. content: *ref_5 security: *ref_1 deprecated: true /fiscal-entities/{fiscalEntityId}/mei: get: summary: Get MEI data description: >- Retrieve MEI (Microempreendedor Individual) registration data for a **FiscalEntity** — MEI number, CNAE codes, opening date, and Simples Nacional status. operationId: get_fiscal-entities_fiscalEntityId_mei tags: - internal ★ > fiscal entities > mei x-use-cases: - View MEI registration details on the fiscal entity dashboard - Check MEI status before attempting invoice emission parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/FiscalEntityMei' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '404': description: Not Found — resource does not exist. content: *ref_5 security: *ref_1 patch: summary: Update MEI data description: Update MEI registration data for a **FiscalEntity**. operationId: patch_fiscal-entities_fiscalEntityId_mei tags: - internal ★ > fiscal entities > mei x-use-cases: - Update MEI registration data after a government change - Correct MEI information parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/FiscalEntityMei' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /fiscal-entities/{fiscalEntityId}/mei/das: get: summary: List DAS records description: >- List monthly DAS (Documento de Arrecadação do Simples Nacional) records for the **FiscalEntity**. Shows payment status for each month. operationId: get_fiscal-entities_fiscalEntityId_mei_das tags: - internal ★ > fiscal entities > mei x-use-cases: - View monthly DAS payment status for the fiscal entity - Check which months are paid or overdue parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Das' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 patch: summary: Refresh DAS records description: >- Request a refresh of DAS records from Serpro. Asynchronously fetches updated payment status for the fiscal entity's DAS history. operationId: patch_fiscal-entities_fiscalEntityId_mei_das tags: - internal ★ > fiscal entities > mei x-use-cases: - Request DAS refresh from Serpro after a payment - Update payment status to reflect recent DAS payments parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/Das' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /fiscal-entities/{fiscalEntityId}/mei/das/pdf: get: summary: Get DAS PDF description: Download the DAS PDF payment slip for a specific month. Returns the PDF document for printing or archiving. operationId: get_fiscal-entities_fiscalEntityId_mei_das_pdf tags: - internal ★ > fiscal entities > mei x-use-cases: - Download DAS PDF payment slip for a specific month - Print or archive the payment document parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '404': description: Not Found — resource does not exist. content: *ref_5 security: *ref_1 /fiscal-entities/{fiscalEntityId}/mei/dasn: get: summary: Get DASN declaration description: Get the annual DASN (Declaração Anual do Simples Nacional) declaration for the **FiscalEntity**. operationId: get_fiscal-entities_fiscalEntityId_mei_dasn tags: - internal ★ > fiscal entities > mei x-use-cases: - View the annual DASN declaration - Check last declared revenue amount parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/FiscalEntityMeiDasn' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 patch: summary: Update DASN description: Update the annual DASN declaration for the **FiscalEntity** — submit corrected annual revenue data. operationId: patch_fiscal-entities_fiscalEntityId_mei_dasn tags: - internal ★ > fiscal entities > mei x-use-cases: - Submit corrected annual revenue in the DASN declaration - Update DASN after discovering an error parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/FiscalEntityMeiDasn' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /fiscal-entities/{fiscalEntityId}/mei/cnd: get: summary: Get CND certificate description: Get the CND (Certidão Negativa de Débitos) tax clearance certificate for the **FiscalEntity**. operationId: get_fiscal-entities_fiscalEntityId_mei_cnd tags: - internal ★ > fiscal entities > mei x-use-cases: - Download the CND tax clearance certificate - Check whether the entity has pending tax debts parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/FiscalEntityMeiCnd' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 patch: summary: Refresh CND description: Request a CND refresh from Serpro. Asynchronously fetches an updated tax clearance certificate. operationId: patch_fiscal-entities_fiscalEntityId_mei_cnd tags: - internal ★ > fiscal entities > mei x-use-cases: - Request a CND refresh from Serpro - Re-validate after resolving a tax debt parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/FiscalEntityMeiCnd' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /fiscal-entities/{fiscalEntityId}/mei/diagnosis: get: summary: Get MEI diagnosis description: Get the latest MEI compliance diagnosis result for the **FiscalEntity** without triggering a new check. operationId: get_fiscal-entities_fiscalEntityId_mei_diagnosis tags: - internal ★ > fiscal entities > mei x-use-cases: - Check the latest MEI diagnosis without triggering a new check - View compliance status before a critical workflow parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: fiscal-entity-diagnoses attributes: status: ok issues: [] checked-at: '2026-04-29T00:00:00Z' schema: type: object properties: data: $ref: '#/components/schemas/Diagnosis' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 post: summary: Trigger MEI diagnosis description: >- Trigger a fresh MEI compliance diagnosis from government services. Checks for pending debts, certificate issues, and registration inconsistencies. operationId: post_fiscal-entities_fiscalEntityId_mei_diagnosis tags: - internal ★ > fiscal entities > mei x-use-cases: - Trigger a fresh MEI compliance diagnosis before invoice emission - Re-validate after fixing reported issues parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: fiscal-entity-diagnoses attributes: status: processing issues: [] checked-at: '2026-04-29T00:00:00Z' schema: type: object properties: data: $ref: '#/components/schemas/Diagnosis' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /fiscal-entities/{fiscalEntityId}/revenue: get: summary: List revenue records description: >- List monthly revenue records for the **FiscalEntity**. Shows declared revenue per month and status against annual limits. operationId: get_fiscal-entities_fiscalEntityId_revenue tags: - internal ★ > fiscal entities > revenue x-use-cases: - View monthly revenue records for the fiscal entity - Check revenue against annual limits parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/FiscalEntityRevenue' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /fiscal-entities/{fiscalEntityId}/revenue/resume: get: summary: Get revenue resume description: >- Get the revenue resume for the **FiscalEntity** — aggregated revenue totals, annual limit status, and projected revenue status. operationId: get_fiscal-entities_fiscalEntityId_revenue_resume tags: - internal ★ > fiscal entities > revenue x-use-cases: - Get aggregated revenue totals and annual limit status - Check projected revenue status for the fiscal entity parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/FiscalEntityRevenueResume' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /fiscal-entities/{fiscalEntityId}/pass-govs: get: summary: List pass-govs description: List stored **PassGov** (gov.br) credentials for the **FiscalEntity**. Passwords are masked. operationId: get_fiscal-entities_fiscalEntityId_pass-govs tags: - internal ★ > fiscal entities > pass-gov x-use-cases: - Check stored gov.br credentials status - View masked credential details parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/PassGov' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 post: summary: Create pass-gov description: >- Create **PassGov** (gov.br) credentials for the **FiscalEntity**. Requires a non-empty password. Credentials are encrypted at rest and validated automatically. operationId: post_fiscal-entities_fiscalEntityId_pass-govs tags: - internal ★ > fiscal entities > pass-gov x-use-cases: - Save gov.br credentials for automated government service access - Configure government portal credentials for the fiscal entity parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: schema: type: object example: data: type: fiscal-entity-pass-govs attributes: cpf: password: status: validation-status: validation-errors: [] validation-by-id: relationships: business: data: type: businesses id: professional: data: type: professionals id: responses: '201': description: Created content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PassGov' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /fiscal-entities/{fiscalEntityId}/pass-govs/{passGovId}: patch: summary: Update pass-gov description: >- Update **PassGov** credentials. Sending `password: ""` clears the stored password, sets status to `inactive` and validation_status to `none`. A non-empty password triggers automatic validation. operationId: patch_fiscal-entities_fiscalEntityId_pass-govs_passGovId tags: - internal ★ > fiscal entities > pass-gov x-use-cases: - Update gov.br credentials after a password change - Clear credentials by sending empty password parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - name: passGovId in: path required: true description: The pass-gov id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: schema: type: object example: data: type: fiscal-entity-pass-govs attributes: cpf: password: status: validation-status: validation-errors: [] validation-by-id: relationships: business: data: type: businesses id: professional: data: type: professionals id: responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PassGov' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 delete: summary: Delete pass-gov description: Delete **PassGov** credentials for the **FiscalEntity**. operationId: delete_fiscal-entities_fiscalEntityId_pass-govs_passGovId tags: - internal ★ > fiscal entities > pass-gov x-use-cases: - Remove gov.br credentials that are no longer needed - Delete compromised or outdated credentials parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - name: passGovId in: path required: true description: The pass-gov id. schema: type: string - *ref_3 responses: '204': description: No Content '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '404': description: Not Found — resource does not exist. content: *ref_5 security: *ref_1 /fiscal-entities/{fiscalEntityId}/pass-govs/{passGovId}/validate: post: summary: Validate pass-gov description: Test stored **PassGov** credentials against the live gov.br portal. Updates validation_status accordingly. operationId: post_fiscal-entities_fiscalEntityId_pass-govs_passGovId_validate tags: - internal ★ > fiscal entities > pass-gov x-use-cases: - Test gov.br credentials against the live portal - Confirm credentials work before attempting DAS/CND fetches parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - name: passGovId in: path required: true description: The pass-gov id. schema: type: string - *ref_3 responses: '200': description: OK '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /fiscal-entities/{fiscalEntityId}/pass-govs/{passGovId}/clear: delete: summary: Clear pass-gov description: >- Clear **PassGov** credentials — deactivates the record, clears stored password, and resets validation_status to `none`. operationId: delete_fiscal-entities_fiscalEntityId_pass-govs_passGovId_clear tags: - internal ★ > fiscal entities > pass-gov x-use-cases: - Clear stored gov.br credentials without deleting the record - Deactivate credentials and reset validation status parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - name: passGovId in: path required: true description: The pass-gov id. schema: type: string - *ref_3 responses: '200': description: OK '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '404': description: Not Found — resource does not exist. content: *ref_5 security: *ref_1 /fiscal-entities/{fiscalEntityId}/pass-invoices: get: summary: List pass-invoices description: List stored **PassInvoice** (prefeitura portal) credentials for the **FiscalEntity**. Passwords are masked. operationId: get_fiscal-entities_fiscalEntityId_pass-invoices tags: - internal ★ > fiscal entities > pass-invoices x-use-cases: - Check stored prefeitura portal credentials status - View masked pass-invoices details parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/PassInvoice' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 post: summary: Create pass-invoice description: >- Create **PassInvoice** (prefeitura portal) credentials for the **FiscalEntity**. Requires a non-empty password. Used when the municipality requires portal login instead of direct eNotas integration. operationId: post_fiscal-entities_fiscalEntityId_pass-invoices tags: - internal ★ > fiscal entities > pass-invoices x-use-cases: - Save prefeitura portal credentials for NFS-e portal access - Configure municipal invoice portal credentials parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: schema: type: object example: data: type: fiscal-entity-pass-invoices attributes: authentication-type: username: login: password: status: validation-status: validation-errors: [] validation-by-id: relationships: business: data: type: businesses id: professional: data: type: professionals id: responses: '201': description: Created content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PassInvoice' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /fiscal-entities/{fiscalEntityId}/pass-invoices/{passInvoiceId}: patch: summary: Update pass-invoice description: >- Update **PassInvoice** credentials. Sending `password: ""` clears the stored password, sets status to `inactive` and validation_status to `none`. A non-empty password triggers automatic validation. operationId: patch_fiscal-entities_fiscalEntityId_pass-invoices_passInvoiceId tags: - internal ★ > fiscal entities > pass-invoices x-use-cases: - Update prefeitura portal credentials after a password change - Clear credentials by sending empty password parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - name: passInvoiceId in: path required: true description: The pass-invoice id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: schema: type: object example: data: type: fiscal-entity-pass-invoices attributes: authentication-type: username: login: password: status: validation-status: validation-errors: [] validation-by-id: relationships: business: data: type: businesses id: professional: data: type: professionals id: responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/PassInvoice' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 delete: summary: Delete pass-invoice description: Delete **PassInvoice** credentials for the **FiscalEntity**. operationId: delete_fiscal-entities_fiscalEntityId_pass-invoices_passInvoiceId tags: - internal ★ > fiscal entities > pass-invoices x-use-cases: - Remove prefeitura portal credentials that are no longer needed - Delete compromised or outdated credentials parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - name: passInvoiceId in: path required: true description: The pass-invoice id. schema: type: string - *ref_3 responses: '204': description: No Content '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '404': description: Not Found — resource does not exist. content: *ref_5 security: *ref_1 /fiscal-entities/{fiscalEntityId}/pass-invoices/{passInvoiceId}/validate: post: summary: Validate pass-invoice description: Test stored **PassInvoice** credentials against the external revenue API. Updates validation_status accordingly. operationId: post_fiscal-entities_fiscalEntityId_pass-invoices_passInvoiceId_validate tags: - internal ★ > fiscal entities > pass-invoices x-use-cases: - Test pass-invoices credentials against the revenue API - Confirm credentials work before attempting revenue refreshes parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - name: passInvoiceId in: path required: true description: The pass-invoice id. schema: type: string - *ref_3 responses: '200': description: OK '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /fiscal-entities/{fiscalEntityId}/pass-invoices/{passInvoiceId}/clear: delete: summary: Clear pass-invoice description: >- Clear **PassInvoice** credentials — deactivates the record, clears stored password, and resets validation_status to `none`. operationId: delete_fiscal-entities_fiscalEntityId_pass-invoices_passInvoiceId_clear tags: - internal ★ > fiscal entities > pass-invoices x-use-cases: - Clear stored prefeitura portal credentials without deleting the record - Deactivate credentials and reset validation status parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - name: passInvoiceId in: path required: true description: The pass-invoice id. schema: type: string - *ref_3 responses: '200': description: OK '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '404': description: Not Found — resource does not exist. content: *ref_5 security: *ref_1 /fiscal-entities/{fiscalEntityId}/certificates: get: summary: List certificates description: List digital certificates (PKCS#12) stored for the **FiscalEntity**. operationId: get_fiscal-entities_fiscalEntityId_certificates tags: - internal ★ > fiscal entities > certificate x-use-cases: - List all digital certificates stored for the fiscal entity - Check which certificates are active or expired parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/FiscalEntityCertificate' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 post: summary: Create certificate description: >- Upload a new PKCS#12 digital certificate for the **FiscalEntity**. Required by eNotas to sign NFS-e. Accepts `.pfx`/`.p12` files up to 3 MB. operationId: post_fiscal-entities_fiscalEntityId_certificates tags: - internal ★ > fiscal entities > certificate x-use-cases: - Upload a new PKCS#12 certificate for invoice emission - Initial certificate setup before the fiscal entity can issue NFS-e parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: schema: type: object example: data: type: fiscal-entity-certificates attributes: expiration-date: status: validation-status: validation-errors: [] validation-by-id: s3-key: relationships: business: data: type: businesses id: professional: data: type: professionals id: responses: '201': description: Created content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/FiscalEntityCertificate' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /fiscal-entities/{fiscalEntityId}/certificates/{certificateId}: patch: summary: Update certificate description: Update a digital certificate — replace the certificate file or password. operationId: patch_fiscal-entities_fiscalEntityId_certificates_certificateId tags: - internal ★ > fiscal entities > certificate x-use-cases: - Update certificate file or password - Replace an expired certificate with a new one parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - name: certificateId in: path required: true description: The certificate id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/FiscalEntityCertificate' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 delete: summary: Delete certificate description: >- Delete a digital certificate. Sets status_certificate to `none` and prevents invoice emission until a new certificate is uploaded. operationId: delete_fiscal-entities_fiscalEntityId_certificates_certificateId tags: - internal ★ > fiscal entities > certificate x-use-cases: - Remove an expired or invalid certificate - Clear certificate before uploading a new one parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - name: certificateId in: path required: true description: The certificate id. schema: type: string - *ref_3 responses: '204': description: No Content '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '404': description: Not Found — resource does not exist. content: *ref_5 security: *ref_1 /fiscal-entities/{fiscalEntityId}/certificates/{certificateId}/validate: post: summary: Validate certificate description: >- Test the stored digital certificate against the external revenue API. Downloads the .pfx from S3, decrypts the password, and validates. operationId: post_fiscal-entities_fiscalEntityId_certificates_certificateId_validate tags: - internal ★ > fiscal entities > certificate x-use-cases: - Test a newly uploaded certificate against the revenue API - Re-validate after a failed emission to confirm certificate still works parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - name: certificateId in: path required: true description: The certificate id. schema: type: string - *ref_3 responses: '200': description: OK '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /fiscal-entities/{fiscalEntityId}/certificates/{certificateId}/clear: delete: summary: Clear certificate description: >- Clear the digital certificate — deactivates the record, clears stored password and S3 key, resets validation_status to `none`. operationId: delete_fiscal-entities_fiscalEntityId_certificates_certificateId_clear tags: - internal ★ > fiscal entities > certificate x-use-cases: - Clear certificate data without deleting the record - Deactivate certificate and reset validation status parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - name: certificateId in: path required: true description: The certificate id. schema: type: string - *ref_3 responses: '200': description: OK '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '404': description: Not Found — resource does not exist. content: *ref_5 security: *ref_1 /fiscal-entities/{fiscalEntityId}/requests: get: summary: List requests description: List fiscal entity requests (setup-emission, validation, etc.) for the **FiscalEntity**. operationId: get_fiscal-entities_fiscalEntityId_requests tags: - internal ★ > fiscal entities > requests x-use-cases: - List all fiscal entity workflow requests - Track progress of setup-emission or validation workflows parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/FiscalEntityRequest' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 post: summary: Create request description: Create a new fiscal entity request — e.g., setup emission workflow, validation trigger. operationId: post_fiscal-entities_fiscalEntityId_requests tags: - internal ★ > fiscal entities > requests x-use-cases: - Start a setup-emission workflow for the fiscal entity - Trigger a validation workflow parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: schema: type: object example: data: type: fiscal-entity-requests attributes: category: details: {} process-status: status: error-status: relationships: fiscal-entity: data: type: fiscal-entities id: responses: '201': description: Created content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/FiscalEntityRequest' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /fiscal-entities/{fiscalEntityId}/requests/{requestId}: get: summary: Get request description: Get a single fiscal entity request by id. operationId: get_fiscal-entities_fiscalEntityId_requests_requestId tags: - internal ★ > fiscal entities > requests x-use-cases: - Check the status and result of a specific request - Debug a failed or stuck workflow parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - name: requestId in: path required: true description: The request id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/FiscalEntityRequest' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '404': description: Not Found — resource does not exist. content: *ref_5 security: *ref_1 patch: summary: Update request description: Update a fiscal entity request — typically to advance status or update data. operationId: patch_fiscal-entities_fiscalEntityId_requests_requestId tags: - internal ★ > fiscal entities > requests x-use-cases: - Advance a request status - Update request data after partial completion parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - name: requestId in: path required: true description: The request id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/FiscalEntityRequest' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /fiscal-entities/{fiscalEntityId}/invoices: get: summary: List invoices description: List invoices created through the accounting service for the **FiscalEntity**. operationId: get_fiscal-entities_fiscalEntityId_invoices tags: - internal ★ > fiscal entities > invoices x-use-cases: - List all invoices for the fiscal entity - Track emission status across invoices parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Invoice' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 post: summary: Create invoice description: Create an invoice in the accounting service for the **FiscalEntity**. operationId: post_fiscal-entities_fiscalEntityId_invoices tags: - internal ★ > fiscal entities > invoices x-use-cases: - Create a new invoice for the fiscal entity - Record a service sale as an NFS-e parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: schema: type: object example: data: type: invoices attributes: competency-date: nfse-number: nfse-verification-code: nfse-url: amount-cents: tax-irrf-cents: tax-pis-cents: tax-cofins-cents: tax-csll-cents: tax-iss-cents: status: cancel-status: provider-id: provider-status: emission-date: fiscal-date: relationships: seller-fiscal-entity: data: type: seller-fiscal-entities id: buyer-fiscal-entity: data: type: buyer-fiscal-entities id: responses: '201': description: Created content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/Invoice' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /fiscal-entities/{fiscalEntityId}/invoices/{invoiceId}: get: summary: Get invoice description: Get a single invoice by id from the accounting service. operationId: get_fiscal-entities_fiscalEntityId_invoices_invoiceId tags: - internal ★ > fiscal entities > invoices x-use-cases: - View invoice details including tax breakdown and NFS-e number - Check emission status and verification code parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - name: invoiceId in: path required: true description: The invoice id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/Invoice' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '404': description: Not Found — resource does not exist. content: *ref_5 security: *ref_1 patch: summary: Update invoice description: Update invoice details before emission — set buyer, competency date, or items. operationId: patch_fiscal-entities_fiscalEntityId_invoices_invoiceId tags: - internal ★ > fiscal entities > invoices x-use-cases: - Update invoice details before emission - Set or correct buyer fiscal entity and competency date parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - name: invoiceId in: path required: true description: The invoice id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/Invoice' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /fiscal-entities/{fiscalEntityId}/invoices/{invoiceId}/emit: patch: summary: Emit invoice description: Emit the invoice through the eNotas integration. Transitions the invoice to `requested` status. operationId: patch_fiscal-entities_fiscalEntityId_invoices_invoiceId_emit tags: - internal ★ > fiscal entities > invoices x-use-cases: - Submit the invoice for emission through eNotas - Issue NFS-e after confirming all details parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - name: invoiceId in: path required: true description: The invoice id. schema: type: string - *ref_3 responses: '200': description: OK '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /fiscal-entities/{fiscalEntityId}/invoices/{invoiceId}/cancel: patch: summary: Cancel invoice description: Request cancellation of an emitted invoice. Transitions to `pending-cancelation`. operationId: patch_fiscal-entities_fiscalEntityId_invoices_invoiceId_cancel tags: - internal ★ > fiscal entities > invoices x-use-cases: - Request cancellation of an emitted invoice - Cancel NFS-e at the professional's request parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - name: invoiceId in: path required: true description: The invoice id. schema: type: string - *ref_3 responses: '200': description: OK '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /fiscal-entities/{fiscalEntityId}/invoices/{invoiceId}/reemit: post: summary: Re-emit invoice description: Re-emit a failed invoice after fixing the root cause. Only allowed for `pending` or `failed` invoices. operationId: post_fiscal-entities_fiscalEntityId_invoices_invoiceId_reemit tags: - internal ★ > fiscal entities > invoices x-use-cases: - Re-emit a failed invoice after fixing the root cause - Retry emission after a transient eNotas API error parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - name: invoiceId in: path required: true description: The invoice id. schema: type: string - *ref_3 responses: '200': description: OK '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /fiscal-entities/{fiscalEntityId}/invoices/{invoiceId}/nfse: put: summary: Upload NFS-e description: Upload the NFS-e PDF or XML returned by the municipality after successful emission. operationId: put_fiscal-entities_fiscalEntityId_invoices_invoiceId_nfse tags: - internal ★ > fiscal entities > invoices x-use-cases: - Upload the NFS-e PDF returned by the municipality - Store the XML file for compliance archiving parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - name: invoiceId in: path required: true description: The invoice id. schema: type: string - *ref_3 responses: '200': description: OK '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /fiscal-entities/{fiscalEntityId}/invoices-emission: post: summary: Setup emission description: >- Set up invoice emission for the **FiscalEntity** via eNotas. Registers the entity as a seller and configures the emission profile. operationId: post_fiscal-entities_fiscalEntityId_invoices-emission tags: - internal ★ > fiscal entities > invoices-emission x-use-cases: - Set up invoice emission via eNotas integration - Register the fiscal entity as a seller in eNotas parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '201': description: Created '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 delete: summary: Deactivate emission description: Deactivate invoice emission for the **FiscalEntity**. Removes the eNotas seller configuration. operationId: delete_fiscal-entities_fiscalEntityId_invoices-emission tags: - internal ★ > fiscal entities > invoices-emission x-use-cases: - Deactivate invoice emission for the fiscal entity - Remove eNotas seller configuration parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '204': description: No Content '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /fiscal-entities/{fiscalEntityId}/invoices-emission/validate: post: summary: Validate emission setup description: Trigger a test-invoice emission to validate the setup. Sends a zero-value test NFS-e through eNotas. operationId: post_fiscal-entities_fiscalEntityId_invoices-emission_validate tags: - internal ★ > fiscal entities > invoices-emission x-use-cases: - Send a test NFS-e to validate the emission setup - Confirm the full pipeline works before emitting real invoices parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 requestBody: required: false content: application/json: example: data: type: emission-validations attributes: status: author: author-type: authentication-type: invoice-status: error: {} municipal-data: {} is-valid: relationships: invoice: data: type: invoices id: schema: type: object responses: '200': description: >- Validation status returned. Triggers a test invoice emission (zero-value NFS-e via eNotas) and returns the current validation status. content: application/vnd.api+json: example: data: id: '1' type: emission-validations attributes: status: validating author: '123' author-type: admin authentication-type: pass_only attempted-at: '2026-07-28T10:30:00Z' invoice-status: pending is-valid: false relationships: invoice: data: id: inv_abc123 type: invoices schema: type: object properties: data: $ref: '#/components/schemas/EmissionValidation' '400': description: Bad Request — emission not active or missing validation. content: application/json: example: success: false errors: - title: EmissionNotActive detail: Seller fiscal entity emission is not active or missing validation code: invoices.emission_not_active status: 400 '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 get: summary: Get emission validation status description: Get the current emission validation status. Returns whether the last test emission succeeded or failed. operationId: get_fiscal-entities_fiscalEntityId_invoices-emission_validate tags: - internal ★ > fiscal entities > invoices-emission x-use-cases: - Check whether the last test emission succeeded - View emission validation status and error details parameters: - name: fiscalEntityId in: path required: true description: The fiscal entity id. schema: type: string - *ref_3 responses: '200': description: Current emission validation status. Returns whether the last test emission succeeded or failed. content: application/vnd.api+json: example: data: id: '1' type: emission-validations attributes: status: succeeded author: '123' author-type: admin authentication-type: pass_only attempted-at: '2026-07-28T10:30:00Z' completed-at: '2026-07-28T10:30:05Z' canceled-at: '2026-07-28T10:30:06Z' invoice-status: succeeded is-valid: true relationships: invoice: data: id: inv_abc123 type: invoices schema: type: object properties: data: $ref: '#/components/schemas/EmissionValidation' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /buyer-fiscal-entities: get: summary: List buyer fiscal entities description: List **BuyerFiscalEntities** (customers) the current Business has issued invoices to. operationId: get_buyer-fiscal-entities tags: - internal ★ > buyer fiscal entities x-use-cases: - Populate the buyer selector when creating a new invoice - Review existing customers before batch invoice emission parameters: - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/BuyerFiscalEntity' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 post: summary: Create buyer fiscal entity description: '' operationId: post_buyer-fiscal-entities tags: - internal ★ > buyer fiscal entities parameters: - *ref_3 requestBody: required: true content: application/vnd.api+json: schema: type: object example: data: type: buyer-fiscal-entities attributes: tax-number: tax-type: name: email: phone: address: responses: '201': description: Created content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/BuyerFiscalEntity' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '422': description: Unprocessable Entity — validation error. content: *ref_2 security: *ref_1 /buyer-fiscal-entities/{buyerFiscalEntityId}: get: summary: Get buyer fiscal entity description: '' operationId: get_buyer-fiscal-entities_buyerFiscalEntityId tags: - internal ★ > buyer fiscal entities parameters: - name: buyerFiscalEntityId in: path required: true description: The buyer fiscal entity id. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/BuyerFiscalEntity' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '404': description: Not Found — resource does not exist. content: *ref_5 security: *ref_1 patch: summary: Update buyer fiscal entity description: '' operationId: patch_buyer-fiscal-entities_buyerFiscalEntityId tags: - internal ★ > buyer fiscal entities parameters: - name: buyerFiscalEntityId in: path required: true description: The buyer fiscal entity id. schema: type: string - *ref_3 requestBody: required: true content: application/vnd.api+json: schema: type: object example: data: type: buyer-fiscal-entities attributes: tax-number: tax-type: name: email: phone: address: responses: '200': description: OK content: application/vnd.api+json: schema: type: object properties: data: $ref: '#/components/schemas/BuyerFiscalEntity' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 delete: summary: Delete buyer fiscal entity description: '' operationId: delete_buyer-fiscal-entities_buyerFiscalEntityId tags: - internal ★ > buyer fiscal entities parameters: - name: buyerFiscalEntityId in: path required: true description: The buyer fiscal entity id. schema: type: string - *ref_3 responses: '204': description: No Content '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '404': description: Not Found — resource does not exist. content: *ref_5 security: *ref_1 /accounting/search/cnpj/{cnpj}: get: summary: Search CNPJ description: >- Search CNPJ data via InfoSimples integration. Returns company name, trade name, address, CNAE codes, and MEI status. operationId: get_accounting_search_cnpj_cnpj tags: - internal ★ > search x-use-cases: - Look up company data before creating a fiscal entity - Auto-fill company name, address, and CNAE codes from CNPJ parameters: - name: cnpj in: path required: true description: The CNPJ to search. schema: type: string - *ref_3 responses: '200': description: OK '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '404': description: Not Found — resource does not exist. content: *ref_5 security: *ref_1 /accounting/search/cpf/{cpf}: get: summary: Search CPF description: Search CPF data via InfoSimples integration. Returns name, birth date, and validation status. operationId: get_accounting_search_cpf_cpf tags: - internal ★ > search x-use-cases: - Validate CPF data before creating a buyer or fiscal entity - Auto-fill person name from CPF lookup parameters: - name: cpf in: path required: true description: The CPF to search. schema: type: string - *ref_3 responses: '200': description: OK '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '404': description: Not Found — resource does not exist. content: *ref_5 security: *ref_1 /accounting/search/address/{address}: get: summary: Search address description: >- Search address data via InfoSimples integration. Returns structured address with CEP, street, neighborhood, city, and state. operationId: get_accounting_search_address_address tags: - internal ★ > search x-use-cases: - Search address by CEP or partial address for auto-fill - Validate address before creating a fiscal entity parameters: - name: address in: path required: true description: The address to search. schema: type: string - *ref_3 responses: '200': description: OK '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 security: *ref_1 /accounting/search/municipal-details/{taxNumber}: get: summary: Search municipal details description: >- Fetch municipal tax details for a tax number — city registration number, taxation regime, and municipal service codes required for NFS-e emission. operationId: get_accounting_search_municipal-details_taxNumber tags: - internal ★ > search x-use-cases: - Fetch municipal tax registration details for NFS-e setup - Check ISS regime and municipal service codes parameters: - name: taxNumber in: path required: true description: The tax number to look up. schema: type: string - *ref_3 responses: '200': description: OK '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '404': description: Not Found — resource does not exist. content: *ref_5 security: *ref_1 /accounting/callbacks/enotas: post: summary: eNotas callback description: >- Receive callback from eNotas when an invoice emission completes or fails. Updates invoice status in the accounting service. operationId: post_accounting_callbacks_enotas tags: - internal ★ > callbacks x-use-cases: - Receive async notification when eNotas invoice emission completes - Process eNotas webhook for invoice status updates parameters: - *ref_3 responses: '200': description: OK '401': description: Unauthorized — invalid or expired token. content: *ref_0 security: *ref_1 /accounting/callbacks/serpro: post: summary: Serpro callback description: Receive callback from Serpro when a government validation request completes. Updates fiscal entity status. operationId: post_accounting_callbacks_serpro tags: - internal ★ > callbacks x-use-cases: - Receive async notification from Serpro government validation - Process Serpro webhook for fiscal entity status updates parameters: - *ref_3 responses: '200': description: OK '401': description: Unauthorized — invalid or expired token. content: *ref_0 security: *ref_1 /accounting/callbacks/serpro-cnd: post: summary: Serpro CND callback description: Receive callback from Serpro when a CND (tax clearance) request completes. Updates the CND certificate data. operationId: post_accounting_callbacks_serpro-cnd tags: - internal ★ > callbacks x-use-cases: - Receive async notification from Serpro CND request - Process Serpro webhook for tax clearance certificate updates parameters: - *ref_3 responses: '200': description: OK '401': description: Unauthorized — invalid or expired token. content: *ref_0 security: *ref_1 /accounting/callbacks/serpro-das: post: summary: Serpro DAS callback description: Receive callback from Serpro when a DAS request completes. Updates DAS payment records. operationId: post_accounting_callbacks_serpro-das tags: - internal ★ > callbacks x-use-cases: - Receive async notification from Serpro DAS request - Process Serpro webhook for DAS payment record updates parameters: - *ref_3 responses: '200': description: OK '401': description: Unauthorized — invalid or expired token. content: *ref_0 security: *ref_1 /accounting/callbacks/serpro-dasn: post: summary: Serpro DASN callback description: Receive callback from Serpro when a DASN request completes. Updates the annual declaration data. operationId: post_accounting_callbacks_serpro-dasn tags: - internal ★ > callbacks x-use-cases: - Receive async notification from Serpro DASN request - Process Serpro webhook for annual declaration updates parameters: - *ref_3 responses: '200': description: OK '401': description: Unauthorized — invalid or expired token. content: *ref_0 security: *ref_1 /accounting/callbacks/serpro-diagnosis: post: summary: Serpro diagnosis callback description: Receive callback from Serpro when a MEI diagnosis request completes. Updates the diagnosis result. operationId: post_accounting_callbacks_serpro-diagnosis tags: - internal ★ > callbacks x-use-cases: - Receive async notification from Serpro diagnosis request - Process Serpro webhook for MEI diagnosis result updates parameters: - *ref_3 responses: '200': description: OK '401': description: Unauthorized — invalid or expired token. content: *ref_0 security: *ref_1 /accounting/diagnosis/{taxNumber}: get: summary: Get diagnosis by tax number description: >- Get the latest MEI compliance diagnosis for a given tax number (CNPJ/CPF). Returns pending issues, debts, and registration inconsistencies. operationId: get_accounting_diagnosis_taxNumber tags: - internal ★ > fiscal entities > mei x-use-cases: - Get the latest MEI diagnosis for a tax number without triggering a new check - View compliance status from a standalone endpoint parameters: - name: taxNumber in: path required: true description: The tax number (CNPJ/CPF) to diagnose. schema: type: string - *ref_3 responses: '200': description: OK content: application/vnd.api+json: example: data: id: '1' type: fiscal-entity-diagnoses attributes: status: ok issues: [] checked-at: '2026-04-29T00:00:00Z' schema: type: object properties: data: $ref: '#/components/schemas/Diagnosis' '401': description: Unauthorized — invalid or expired token. content: *ref_0 '403': description: Forbidden — insufficient permissions. content: *ref_4 '404': description: Not Found — resource does not exist. content: *ref_5 security: *ref_1