Swagger UI openapi.json openapi.yaml

Changelog

Recent changes to the Contabeleza API. Source: public/openapi.yaml.

Service Commit Index

ServiceCommitDate
api-docs-contabeleza05ec82c2026-07-20
core-contabelezae605c1e2026-07-20
accounting9bdfcd72026-07-20
accessf4955852026-07-20

> Future endpoint updates should diff against these commits to generate changelogs automatically.

---

2026-10-07

  • Changed GET /business-requests/catalog: the manual catalog (Google Sheet) is now cached in Redis for 24 hours instead of 5 minutes per server, so sheet edits can take up to a day to appear.
  • Added force=true query parameter on GET /business-requests/catalog (admin accounts only; ignored for others) to re-read the sheet and refresh the cache immediately.
  • Improved catalog availability: if the sheet is unreachable, the last known copy (up to 30 days) is served; 503 CatalogUnavailable is only returned when no copy exists.

2026-10-06

  • Changed GET /accounting/search/fiscal-info: CPF lookups (tax-number-type=cpf) now require the holder's birth-date (YYYY-MM-DD), following the Serpro Consulta CPF v3 migration (RFB Ordinance 667/2026). CNPJ lookups are unchanged.
  • Added CPF lookup errors: 400 BirthDateRequired, 400 InvalidBirthDate, 422 BirthDateMismatch (birth date differs from the Receita Federal record) and 404 CPFNotFound.
  • Changed CPF lookups now also return data for minors, and the lookup result is cached per CPF and birth date.

2026-09-22

  • Added the new_certificate BusinessRequest workflow, with complete on-demand service, owner, business, and representative payload context.
  • Changed on-demand BusinessRequest payload context: both on-demand types now require owner and business at the data root. professional_on_demand_service also requires root-level professional and fiscal_entity, using fiscal_entity.tax_number.
  • Changed on-demand owner context: only owner.professional_id and owner.name are required; owner email and phone fields are optional.
  • Improved endpoint filtering: matched text is highlighted and URL matches are shown before title, group, description, and use-case matches.
  • Improved the Models reference with complete, namespaced payload schemas and a wider, scrollable layout.

2026-09-17

  • Added append-only BusinessRequest.statuses audit trail. Each transition now records its value, timestamp, and available author metadata; status remains the latest history value.
  • Changed GET /business-requests/catalog now returns a unified catalog: manually requestable services (service_mode: manual) and display-only automatic workflows (service_mode: auto). Items now include service_tag and service_department.
  • Changed generated BusinessRequest.tags now contains the normalized service tag, department, and service key, in that order. Direct cancellation is limited to draft and open; requests in open, processing, waiting, or closed can enter cancel_requested.
  • Added departments and business_request_services to GET /constants and GET /businesses/{id}/constants.
  • Added the termination-business-request relationship to ProfessionalContract responses.

2026-09-15

  • Added is_featured to every service returned by GET /business-requests/catalog. This boolean identifies services promoted in the on-demand catalog.
  • Added server-generated BusinessRequest.tags, containing normalized service and department tags for searchable workflow lists. Use filter[tags][ilike]=%fragment% for partial text search.

2026-09-14

  • Added GET /business-requests/catalog — lists the current server-managed on-demand service catalog, including service key, description, price in centavos, optional SLA, and scope.
  • Added on_demand_service and professional_on_demand_service BusinessRequest types. Select a service from the catalog first; the server resolves the submitted service_key to its authoritative service data. Professional-scoped requests require an owned professional_id.

2026-07-28

  • Changed emission validation endpoints now return emission-validations JSON:API resource instead of flat ValidationStatus object. Affected endpoints:
  • POST /fiscal-entities/{id}/invoices-emission/validate
  • GET /fiscal-entities/{id}/invoices-emission/validate
  • POST /fiscal-entities/{id}/validate-emission
  • GET /fiscal-entities/{id}/validation-status
  • Added new emission-validations resource type with relationship invoice (HasOne) and attributes: status, author, author_type, authentication_type, attempted_at, completed_at, canceled_at, invoice_status, error, municipal_data, is_valid
  • Added canceled_at — timestamp set when the validation invoice is queued for cancellation
  • Added authentication_type — which auth method was used (pass_only, token, user_and_pass, or certificate)
  • Added author and author_type — who requested the validation, captured from the request context
  • Removed certificate_expired field from the validation status response

2026-07-22

  • Added internal ★ group — ~71 accounting service endpoints (fiscal entities, MEI, revenue, pass-govs, pass-invoices, certificates, invoices, search, callbacks, diagnosis)
  • Added 6 internal model schemas — SellerFiscalEntity, FiscalEntityRequest, FiscalEntityMei, FiscalEntityMeiCnd, FiscalEntityMeiDasn, FiscalEntityMeiCcmei
  • Added tech guide /guides/tech/internal-endpoints — admin-only routes, direct accounting service, proxy vs direct, JSON:API types, deprecated/broken routes
  • Improved endpoints page — red ★ badge on internal group header, red dot on endpoint rows, red-tinted left border on group block
  • Improved models page — collapsed ★ Internal section in sidebar, red warning bar + red left border on internal model cards
  • Fixed 2 broken routes excluded (no handler): PUT /fiscal-entities/{id}/certificate, POST /fiscal-entities/{id}/mei/cnpj

2026-07-20

  • Added GET /AI_INDEX.md — compact API reference for AI agents (~272 lines)
  • Improved GET /accounts/{id} — added Account response schema and example
  • Improved GET /external-app-tokens/{tokenId} — added ExternalAppToken response schema and example
  • Improved GET /accounts/{id}/professional-contracts/{contractId} — added ProfessionalContract response schema and example
  • Improved GET /accounts/{id}/professional-invoices/{invoiceId} — added ProfessionalInvoice response schema and example
  • Fixed POST /accounts/{id}/invoices/{invoiceId}/emit and POST /accounts/{id}/invoices/{invoiceId}/cancel — mapped response to Invoice model (was ProfessionalInvoice)
  • Fixed businesses > invoices tag → businesses > professional invoices
  • Fixed accounts > invoices descriptions — removed "personal invoice" terminology
  • Fixed generateJsonApiExample() type values — now uses real JSON:API types from schema (not derived placeholders)
  • Fixed accordion close-others behavior — only one expansion open at a time
  • Fixed migration parser — handles bare ALTER COLUMN in multi-column statements
  • Fixed models page type display — suppresses | null when field has required badge

2026-07-13 (2)

  • Added ~58 endpoints across core-contabeleza and access:
  • CRUD /businesses, /businesses/{id}
  • CRUD /business-categories, /business-categories/{id}
  • CRUD /week-schedules/{id}
  • CRUD /professional-categories, /professional-categories/{id}
  • CRUD /professional-services, /professional-services/{id}
  • CRUD /business-requests, /business-requests/{id}
  • CRUD /representatives, /representatives/{id}
  • GET /professional-contracts, GET /professional-contracts/{id}
  • GET /professional-invoices, GET /professional-invoices/{id}, PATCH /professional-invoices/{id}
  • GET /constants
  • CRUD /accounts, /accounts/{id}
  • GET /accounts/{id}/professional-contracts, GET /accounts/{id}/professional-contracts/{contractId}
  • GET /accounts/{id}/professional-invoices, GET /accounts/{id}/professional-invoices/{invoiceId}
  • Deprecated 6 endpoints with Obsoleto tag:
  • PATCH /professional-contracts/{id}/status
  • PATCH /professional-contracts/{id}/in-approval
  • PATCH /professional-contracts/{id}/cancellation-request
  • DELETE /professional-contracts/{id}
  • GET /businesses/{id}/settings/status
  • PATCH /businesses/{id}/settings/status
  • Tagged GET /constants, GET /professionals/{id}/is-owned-by-account, GET /professional-fiscal-entities with Privado
  • Tagged POST /accounts/{id}/impersonate, POST /accounts/{id}/fiscal-entity/mei/cnpj with Admin

2026-07-13

  • Added has_pass_gov, has_pass_invoices, has_certificate booleans to GET responses of /professional-fiscal-entities, /business-fiscal-entities, /account-fiscal-entities

2026-07-10 (4)

  • Removed /fiscal-entities/{id}/* (all direct accounting service paths)
  • Added proxy endpoints:
  • /businesses/{id}/fiscal-entity/* (certificate, PassGov, PassInvoices, invoices-emission)
  • /professionals/{id}/fiscal-entity/* (certificate, PassGov, PassInvoices, invoices-emission)
  • /accounts/{id}/fiscal-entity/* (CRUD, certificate, PassGov, PassInvoices, MEI sub-resources)
  • /accounts/{id}/invoices/* (create, list, get, emit, cancel)
  • GET /municipal-details, GET /professionals-fiscal-details
  • Added GET /accounts/{id}/professional-invoices and GET /accounts/{id}/professional-contracts (account-level lists)
  • Added GET|PATCH|POST /accounts/{id}/professional-invoices/{invoiceId}/* (account-scoped writes: cancel, emit, reemit)
  • Removed /fiscal-entity/authentication (split into pass-gov and pass-invoices)

2026-07-10 (3)

  • Renamed /businesses/{id}/professionals-revenue → /professional-fiscal-entities/revenue
  • Added GET /businesses/{id}/revenue, GET /professionals/{id}/fiscal-entity/revenue

2026-07-23

  • Added missing_auth to emission_status enum — represents provider account exists but no credentials sent yet
  • Changed POST /fiscal-entities/{id}/invoices-emission — now checks for existing credentials and sends them to eNotas; sets missing_auth if none exist, missing_validation if credentials were sent
  • Changed POST /fiscal-entities/{id}/pass-invoices — now sends credentials to eNotas when a provider account already exists (FLOW B); stores locally only when no provider exists (FLOW A)
  • Changed POST /fiscal-entities/{id}/certificate — no longer creates a provider account if none exists; only sends to eNotas when provider exists; stored locally otherwise

2026-07-10 (2)

  • Changed status_pass_govs, status_pass_invoices, status_certificate response values — added none (no record) vs inactive (record exists but inactive) distinction

2026-07-10

  • Changed status_pass_govs, status_pass_invoices, status_certificate — expanded values: valid, invalid, none, not-validated, processing-validation; status_certificate adds expired
  • Added emission_validation_statuses field to fiscal entity GET responses
  • Changed POST /fiscal-entities/{id}/invoices-emission — no longer sends certificate or pass_invoices; only creates eNotas company
  • Changed POST /fiscal-entities/{id}/invoices-emission/validate — now the explicit path to reach active emission_status
  • Removed missing_auth from emission_status enum
  • Changed validated_at and validation_history — now UI audit trail only; canonical state is emission_validation_statuses

2026-07-09

  • Changed status_pass_govs, status_pass_invoices, status_certificate values — none vs inactive distinction added

2026-07-09

  • Added PATCH /fiscal-entities/{id}/pass-invoices/validate and PATCH /fiscal-entities/{id}/certificate/validate
  • Changed pass-invoices and certificate create/update — automatic validation on non-empty credentials; clearing resets to none
  • Removed automatic emission validation on pass-invoices/certificate create/update
  • Deprecated PUT /fiscal-entities/{id}/certificate, POST /fiscal-entities/{id}/validate-emission, GET /fiscal-entities/{id}/validation-status

2026-07-08

  • Changed POST /fiscal-entities/{id}/certificate/validate — rejects expired certs immediately
  • Changed GET /fiscal-entities/{id} — auto-updates emission_status to missing_validation if certificate expired
  • Changed emission status enum — removed missing_auth; values now missing_setup, missing_validation, active, inactive
  • Changed has_pass_gov, has_pass_invoice, has_certificate booleans → status_pass_govs, status_pass_invoices, status_certificate strings

2026-07-07

  • Added PATCH /fiscal-entities/{id}/pass-invoices/validate and PATCH /fiscal-entities/{id}/certificate/validate

2026-07-06 (2)

  • Added last-updated-at attribute to GET /fiscal-entity-revenue-resumes responses

2026-06-16

  • Changed PATCH /fiscal-entities/{id}/pass-gov and PATCH /fiscal-entities/{id}/pass-invoices — clear/inactivate on empty password
  • Changed POST /fiscal-entities/{id}/pass-gov and POST /fiscal-entities/{id}/pass-invoices — reject empty password with 400 PasswordRequired

2026-06-15

  • Added data.pdf_url support to POST /business-requests for terminate_contract type
  • Added termination_pdf_url to PATCH /business-requests/{id}/update-status (body-based and n8n variants)
  • Added termination_pdf_url to PATCH /professional-contracts/{id}/update-status
  • Added termination_pdf_url to ProfessionalContract GET responses

2026-04-30

  • Added Test Battery runner at /tests/*
  • Added /tests/run and /tests/run/:runId endpoints

2026-04-29

  • Added 43 endpoints across api gateway, business-contabeleza, accounting, access services
  • Added session/auth surface, invoice lifecycle, fiscal entity management, MEI sub-resources, account management, external-app-tokens, representatives, partners, n8n webhook

2026-04-01

  • Initial release: 28 paths, 9 models from HAR capture

2026-09-18

  • Added PUT /professional-contracts/{id}/pdf to attach a signed contract PDF (multipart PDF up to 10 MB or an existing pdf_url) and approve contracts in filling or in_approval.

2026-09-21

  • Changed on-demand BusinessRequest payloads — data.service_data now documents representative (id, name, email, phone_country, phone_number), business (id, brand), fiscal_entity (id, cnpj), and, for MEI/professional services, professional (id, name).

2026-10-12

  • Added POST /sessions/api/handoff — external app gets a one-time token JWT (30 s, single use) for one of its linked users, exchanged via POST /sessions (loginType: "token") / mei-contabeleza /session/login-by-token/{token}
  • Added POST /sessions/external and POST /sessions/api to the reference; POST /sessions/external accepts handoff: true and returns data.url
  • Changed POST /accounts/external — documented as an external-app (API key) endpoint; links existing accounts only by phone with contacts_verified: true, never by email, and ignores account_id for external-app callers
  • Fixed API key docs — the key is sent raw in Authorization, without an ApiKey prefix
  • Added "Hand-off from ilove.me" to the authentication tech guide and "Entrar a partir do ilove.me" to the general login guide

2026-10-12 (2)

  • Added POST /sessions/api/business-access — external app checks whether one of its users belongs here to a business with the same CNPJ (has-access, business-id, reason)
  • Changed POST /accounts/external — existing accounts are linked only when phone AND email both match (with contacts_verified: true)
  • Changed POST /sessions/external — managers of the selected business get present-services instead of a URL when their business is not on Contabeleza or they are not in it