Models and payload schemas

A user account on the platform — the human who logs in via email/password and owns one or more Businesses.

Represents a person authenticated through the access service. Holds personal data (name, email, phone, locale), authentication state (has-password, is-validated) and is the root of permission grants for every Business the user belongs to.

Resource of type AccountFiscalEntity.

Resource of type AccountType.

Physical address with country, state, city, neighborhood, street, number, zipcode, and complement.

Used as an embedded object in FiscalEntity schemas (e.g. address field on ProfessionalFiscalEntity, BusinessFiscalEntity). Fields: country (2-letter ISO), state, city, neighborhood, street, street-number, zipcode, complement. The Go struct is SimpleAddress from go-common/models/address.go.

A salon or beauty business owned by an Account — the tenant boundary identified by the ilm-business header.

Represents a salon, studio, or independent professional registered as a tenant. Almost every other resource (Professionals, Invoices, Schedules, Fiscal Entities) is scoped to a Business. The numeric id appears in the ilm-business header and in nested URLs like /businesses/{businessId}/….

Resource of type BusinessCategory.

The fiscal entity (CNPJ/CPF) owned by a Business — the issuer of invoices on the salon's behalf.

A SellerFiscalEntity scoped to a Business. Holds the salon's CNPJ, address, MEI registration data, digital certificate, and PassGov credentials used to talk to government services. The certificate_expiration_date attribute is sourced from the linked fiscal-entity-certificates.expiration_date row (single source of truth — updated automatically on certificate upload, absent when no active certificate is on file).

Tracks one asynchronous workflow, from creation to its final status.

Each schema belongs to BusinessRequest. The workflow is selected by attributes.type; the fields below describe attributes.data.

Resource of type BusinessSetting.

A CNAE (Classificação Nacional de Atividades Econômicas) code and description.

Embedded within ExtraData.all-cnae. Each item pairs a CNAE code with its human-readable description. CNAE codes classify the economic activities of the business.

An API key for external app integrations — scoped access without user credentials.

Allows third-party systems to call the API using a static key instead of user JWTs. The gateway validates the key, generates a short-lived external-app JWT, and caches it for 5 minutes. Managed by admins via /external-app-tokens CRUD.

Additional fiscal entity data — CNAE list and partner info.

Embedded within TaxData. Contains the primary CNAE code, the full list of CNAE items (all-cnae), the main partner name, and the municipal jurisdiction code.

Cartão CNPJ do MEI (CCMEI) — MEI card document for a fiscal entity.

Stores the CCMEI (MEI card) document data for a fiscal entity. The CCMEI is an official document proving MEI registration. Status tracks the document state; details and extra contain the government response data. Linked to a parent MEI entity.

A line item within a ProfessionalInvoice — description, quantity, unit value, and total.

Embedded within ProfessionalInvoice.items. Each item has: description (string), quantity (integer), unit-value-cents (integer, in centavos), total-value-cents (integer, in centavos). The sum of all items' total-value-cents should equal the invoice's total-value-cents.

Resource of type PaymentsRecipient.

Resource of type Permission.

An identity or supporting document attached to a Professional or Account.

Stores uploaded identity documents (RG, CNH, CPF, address proof, etc.) required for compliance checks, contract approval, or fiscal entity registration. Each document has a type, file URL, and validation status.

Resource of type Phone.

Resource of type PinCred.

A beauty professional (hairdresser, manicurist, esthetician, …) working under a Business.

A worker who renders services and may issue invoices through the platform. Linked to a ProfessionalContract with the Business and to a ProfessionalFiscalEntity (their MEI / CNPJ) used for invoice emission.

Resource of type ProfessionalCategory.

The contractual relationship between a Business and a Professional.

Tracks the agreement that authorizes a Professional to operate under a Business. Status flows: filling → approved → (active) → terminated. Two PDF slots: pdf_url for the signed contract (set by new_contract_pdf) and termination_pdf_url for the signed distrato (set by terminate_contract — either at create time via data.pdf_url, or at the status→closed transition via a top-level termination_pdf_url field). The termination-business-request relationship identifies the BusinessRequest that initiated termination. 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.

The fiscal entity (CPF/CNPJ, usually a MEI) belonging to a Professional — the issuer of their invoices.

A SellerFiscalEntity owned by a Professional. Stores CNPJ (when MEI), CPF, digital certificate, MEI registration data, and PassGov credentials needed to query Receita Federal services on the Professional's behalf. The certificate_expiration_date attribute is sourced from the linked fiscal-entity-certificates.expiration_date row (single source of truth — updated automatically on certificate upload, absent when no active certificate is on file).

A NFS-e (electronic service invoice) issued for services rendered by a Professional.

Represents a Brazilian electronic service invoice (NFS-e) emitted through the eNotas integration on behalf of a Professional. Lifecycle: pending → requested → succeeded | failed. Cancellation lifecycle: pending-cancelation → requested-cancelation → canceled | failed-cancelation.

Resource of type ProfessionalService.

The legal representative (Person) registered for a Business.

Stores the responsible person's identification (name, CPF, contact). Required by eNotas / Serpro when issuing invoices on the Business's behalf.

An uploaded blob (PDF, image, certificate) referenced from other resources by id.

Generic file upload. The response returns an id used to attach the blob to other resources (e.g. contract PDFs, certificate files).

Resource of type ServiceCategory.

An authenticated session — credentials traded for a short-lived JWT bearer token.

Created via POST /sessions with email/password. The response carries the bearer token used in Authorization: Bearer … for every subsequent call. Sessions can be listed and revoked.

Tax and fiscal configuration data for a seller fiscal entity — enterprise info, tax system, rules, and municipal parameters.

Embedded object on SellerFiscalEntity and BusinessFiscalEntity containing the fiscal entity's tax registration data: enterprise type/name, tax system (MEI/Simples Nacional status), CNAE codes, municipal jurisdiction, ISS aliquota, and regime especial tributacao. The enterprise-tax-system sub-object tracks MEI and Simples Nacional status with optional date intervals. The rules sub-object indicates which fields are active for this entity (e.g. whether descricao_servico or item_lista_servico are used). The extra sub-object contains CNAE list and partner info. Sourced from InfoSimples and updated on revalidation.

Flags indicating which tax fields are active for a fiscal entity.

Embedded within TaxData. Boolean flags that control which fields are relevant for this entity's tax regime: uses-descricao-servico, uses-item-lista-servico, uses-codigo-servico-municipal, uses-regime-especial-tributacao. These flags drive form visibility in the UI.

MEI and Simples Nacional tax regime status for a fiscal entity.

Embedded within TaxData. Tracks whether the entity is MEI (is-mei), enrolled in Simples Nacional (is-simples), and the date intervals for Simples participation (is-simples-intervals). The situacao-cadastral object holds the Receita Federal cadastral situation.

Weekly working hours for a Business or Professional.

Holds the recurring weekly availability used by booking flows: open/close time per weekday, breaks, and exceptions.