{ "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.\n\n### Conventions\n- All requests and responses follow [JSON:API v1.1](/jsonapi). Content type: `application/vnd.api+json`.\n- Authentication: `Authorization: Bearer ` — see the [authentication guide](/auth).\n- Business context: `ilm-business: ` — see the [ilm-business guide](/headers).\n\n### Base URL\nPick 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.\n\nRepresents 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.\n\nCreated 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.\n\nRepresents 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.\n\nA 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.\n\nA 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.\n\nA 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.\n\nTracks 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.\n\nRepresents 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.\n\nThe 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.\n\nStores 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, …).\n\nWraps 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.\n\nGeneric 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.\n\nStores 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.\n\nAllows 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.\n\nStores 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.\n\nStores 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.\n\nStores 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.\n\nHolds 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.\n\nStores 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.\n\nCaptures 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.\n\nThe 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.\n\nStores 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.\n\nReturned 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.\n\nRepresents 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.\n\nReturned 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).\n\nTracks 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.\n\nStores 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.\n\nStores 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.\n\nStores 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.\n\nStores 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.\n\nEmbedded 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.\n\nEmbedded 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.\n\nEmbedded 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.\n\nEmbedded 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.\n\nEmbedded 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.\n\nUsed 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.\n\nEmbedded 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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } } }, "security": [ { "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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": { "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": { "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/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": { "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/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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "422": { "description": "Unprocessable Entity — validation error.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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": { "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": [ { "bearerAuth": [] } ] } }, "/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": { "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": [ { "bearerAuth": [] } ] } }, "/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": { "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": [ { "bearerAuth": [] } ] } }, "/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": { "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": [ { "bearerAuth": [] } ] } }, "/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": { "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": [ { "bearerAuth": [] } ] } }, "/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": { "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": [ { "bearerAuth": [] } ] }, "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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": { "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": [ { "bearerAuth": [] } ] } }, "/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": { "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": [ { "bearerAuth": [] } ] }, "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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] }, "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": { "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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] }, "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": { "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": [ { "bearerAuth": [] } ] }, "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "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": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content — certificate removed." } }, "security": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FiscalEntityCertificate" } } } } } }, "422": { "description": "Unprocessable Entity — validation error.", "content": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content — certificate removed." } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PersonalDocument" } } } } } }, "422": { "description": "Unprocessable Entity — validation error.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content." }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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": [ { "bearerAuth": [] } ] }, "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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PersonalDocument" } } } } } }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content." }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/representatives": { "get": { "summary": "List representatives", "description": "List all **Representatives** registered under the current Business context.", "operationId": "get_representatives", "tags": [ "businesses > representatives" ], "parameters": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] }, "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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Representative" } } } } } }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] } }, "/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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "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": [ { "bearerAuth": [] } ] }, "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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "id": "42" } } } }, "responses": { "204": { "description": "No content." }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "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": [ { "bearerAuth": [] } ] } }, "/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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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/BusinessRequest" } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.api+json": { "example": { "data": null }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProfessionalContract" } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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-04-29T00:00:00Z" } } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Diagnosis" } } } } } }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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-04-29T00:00:00Z" } } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Diagnosis" } } } } } }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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-04-29T00:00:00Z" } } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Diagnosis" } } } } } }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BusinessFiscalEntity" } } } } } }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content — fiscal entity removed." }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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", "validation-status": "valid" } } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PassGov" } } } } } }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK — emission setup initiated." }, "422": { "description": "Unprocessable Entity — validation error.", "content": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content — emission deactivated." } }, "security": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProfessionalFiscalEntity" } } } } } }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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", "validation-status": "valid" } } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PassGov" } } } } } }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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", "validation-status": "valid" } } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PassInvoice" } } } } } }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content — emission deactivated." } }, "security": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] }, "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": { "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": [ { "bearerAuth": [] } ] }, "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": { "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": [ { "bearerAuth": [] } ] } }, "/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": { "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": [ { "bearerAuth": [] } ] } }, "/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": { "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": [ { "bearerAuth": [] } ] }, "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": [ { "bearerAuth": [] } ] }, "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": { "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": [ { "bearerAuth": [] } ] }, "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": [ { "bearerAuth": [] } ] } }, "/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": { "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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] }, "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": { "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": [ { "bearerAuth": [] } ] }, "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": { "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": [ { "bearerAuth": [] } ] } }, "/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": { "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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] }, "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": { "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": [ { "bearerAuth": [] } ] }, "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": { "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": [ { "bearerAuth": [] } ] } }, "/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": { "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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] }, "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": { "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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] }, "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": { "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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] }, "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": { "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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] }, "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": { "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": [ { "bearerAuth": [] } ] } }, "/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": { "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": [ { "bearerAuth": [] } ] } }, "/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": { "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": [ { "bearerAuth": [] } ] }, "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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] } }, "/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": { "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": [ { "bearerAuth": [] } ] } }, "/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": { "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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] }, "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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] } }, "/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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] }, "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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content — category deleted." }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BusinessCategory" } } } } } }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BusinessRequest" } } } } } }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ], "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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] }, "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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content — setting deleted." }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BusinessSetting" } } } } } }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] }, "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Business" } } } } } }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } }, "security": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Representative" } } } } } }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/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": [ { "bearerAuth": [] } ] } }, "/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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] }, "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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProfessionalCategory" } } } } } }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK — contract deleted." }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ], "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProfessionalContract" } } } } } }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ], "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ], "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ], "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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProfessionalInvoice" } } } } } }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] }, "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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content — service deleted." }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProfessionalService" } } } } } }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] }, "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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content — professional deleted." }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Professional" } } } } } }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK — ownership status returned." } }, "security": [ { "bearerAuth": [] } ] } }, "/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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] }, "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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content — schedule deleted." }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WeekSchedule" } } } } } }, "404": { "description": "Not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] }, "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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "422": { "description": "Unprocessable Entity — validation error.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "404": { "description": "Not Found — resource does not exist.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "NotFound", "detail": "Resource not found", "code": "resource.not_found", "status": 404 } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "422": { "description": "Unprocessable Entity — validation error.", "content": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "404": { "description": "Not Found — resource does not exist.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "NotFound", "detail": "Resource not found", "code": "resource.not_found", "status": 404 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "422": { "description": "Unprocessable Entity — validation error.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "422": { "description": "Unprocessable Entity — validation error.", "content": { "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": [ { "bearerAuth": [] } ], "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "404": { "description": "Not Found — resource does not exist.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "NotFound", "detail": "Resource not found", "code": "resource.not_found", "status": 404 } ] } } } } }, "security": [ { "bearerAuth": [] } ], "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "404": { "description": "Not Found — resource does not exist.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "NotFound", "detail": "Resource not found", "code": "resource.not_found", "status": 404 } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "404": { "description": "Not Found — resource does not exist.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "NotFound", "detail": "Resource not found", "code": "resource.not_found", "status": 404 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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-04-29T00:00:00Z" } } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Diagnosis" } } } } } }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "422": { "description": "Unprocessable Entity — validation error.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "422": { "description": "Unprocessable Entity — validation error.", "content": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "404": { "description": "Not Found — resource does not exist.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "NotFound", "detail": "Resource not found", "code": "resource.not_found", "status": 404 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "404": { "description": "Not Found — resource does not exist.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "NotFound", "detail": "Resource not found", "code": "resource.not_found", "status": 404 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "422": { "description": "Unprocessable Entity — validation error.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "422": { "description": "Unprocessable Entity — validation error.", "content": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "404": { "description": "Not Found — resource does not exist.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "NotFound", "detail": "Resource not found", "code": "resource.not_found", "status": 404 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "404": { "description": "Not Found — resource does not exist.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "NotFound", "detail": "Resource not found", "code": "resource.not_found", "status": 404 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "422": { "description": "Unprocessable Entity — validation error.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "404": { "description": "Not Found — resource does not exist.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "NotFound", "detail": "Resource not found", "code": "resource.not_found", "status": 404 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "404": { "description": "Not Found — resource does not exist.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "NotFound", "detail": "Resource not found", "code": "resource.not_found", "status": 404 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "404": { "description": "Not Found — resource does not exist.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "NotFound", "detail": "Resource not found", "code": "resource.not_found", "status": 404 } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "422": { "description": "Unprocessable Entity — validation error.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "404": { "description": "Not Found — resource does not exist.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "NotFound", "detail": "Resource not found", "code": "resource.not_found", "status": 404 } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Created" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "422": { "description": "Unprocessable Entity — validation error.", "content": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] }, "post": { "summary": "Create buyer fiscal entity", "description": "", "operationId": "post_buyer-fiscal-entities", "tags": [ "internal ★ > buyer fiscal entities" ], "parameters": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "422": { "description": "Unprocessable Entity — validation error.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "404": { "description": "Not Found — resource does not exist.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "NotFound", "detail": "Resource not found", "code": "resource.not_found", "status": 404 } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "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": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] }, "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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "404": { "description": "Not Found — resource does not exist.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "NotFound", "detail": "Resource not found", "code": "resource.not_found", "status": 404 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "404": { "description": "Not Found — resource does not exist.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "NotFound", "detail": "Resource not found", "code": "resource.not_found", "status": 404 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "404": { "description": "Not Found — resource does not exist.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "NotFound", "detail": "Resource not found", "code": "resource.not_found", "status": 404 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "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": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "404": { "description": "Not Found — resource does not exist.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "NotFound", "detail": "Resource not found", "code": "resource.not_found", "status": 404 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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": [ { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/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" } }, { "name": "ilm-business", "in": "header", "required": true, "description": "Business context id (see /headers).", "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-04-29T00:00:00Z" } } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Diagnosis" } } } } } }, "401": { "description": "Unauthorized — invalid or expired token.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "UnauthorizedError", "detail": "Token expired or invalid", "code": "auth.unauthorized", "status": 401 } ] } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "PermissionDenied", "detail": "You do not have permission to access this resource", "code": "auth.permission_denied", "status": 403 } ] } } } }, "404": { "description": "Not Found — resource does not exist.", "content": { "application/json": { "example": { "success": false, "errors": [ { "title": "NotFound", "detail": "Resource not found", "code": "resource.not_found", "status": 404 } ] } } } } }, "security": [ { "bearerAuth": [] } ] } } } }