Step 1.5 — Check the Changelog at /changelog

Before you write code, check if anything related to your task has changed recently. The changelog lists recent additions, changes, and removals.

2. Understand the API conventions

These apply to every endpoint. Get them wrong and nothing will work.

• All responses follow JSON:API v1.1 — Content-Type: application/vnd.api+json
• Auth: Authorization: Bearer — HS256, validated server-side. Get the token from POST /sessions with type: "email".
• External apps send their API key raw in Authorization (no Bearer/ApiKey prefix). They link users with POST /accounts/external (existing accounts only when phone AND email both match, with contacts_verified: true), check a manager's business with POST /sessions/api/business-access (same CNPJ, nothing created) and log them in with POST /sessions/api (session) or POST /sessions/api/handoff (one-time token JWT, 30 s, single use, exchanged via POST /sessions loginType: "token"). ilove.me uses this to open Contabeleza: POST /sessions/external with handoff: true returns a mei.contabeleza.com.br/session/login-by-token/ URL; users without management.accounting end up on meipro.
• Business context: ilm-business: — required header on most endpoints. Get the business id from the login response under data.businesses[].id.
• Attribute names are kebab-case — created-at, tax-number, not created_at or taxNumber.
• id is always a string — even when numeric.
• Type/status enums use snake_case — new_contract, profesional_invoice_emission, not_applicable, pass_only, etc. See the general guides for Portuguese translations.
• Tag conventions — operations are tagged with domain groups (businesses, professionals, professional-contracts, etc.) plus marking tags: Privado (internal-use, not for general public), Obsoleto (deprecated — will be removed), Admin (restricted to admin roles). Deprecated operations also have deprecated: true in the spec.
• fiscal-entities exposes computed status strings for each credential: status_pass_govs, status_pass_invoices, and status_certificate — each can be valid, invalid, none, not-validated, or processing-validation. status_certificate additionally can be expired when the active cert is past its expiration-date. The emission_status field is one of missing_setup, missing_validation, active, inactive (note: missing_auth is no longer a value — it is now an error code returned by operations that require auth). The last_emission_validation field on the seller carries the latest EmissionValidation record, whose statuses array (audit trail per attempt) defines the canonical emission validation state: none → validating → succeeded/failed. Dedicated emission-validations endpoints (POST/GET on /invoices-emission/validate, /validate-emission, /validation-status) return the full EmissionValidation JSON:API resource with invoice HasOne relationship and attributes: status, author, author_type, authentication_type, canceled_at, is_valid. Derived boolean fields has_pass_gov, has_pass_invoices, and has_certificate are also returned: each is false when the corresponding status is none or inactive, true otherwise.
• Query parameters for sideloading, filtering, sorting, pagination:
• ?include=businesses — sideload related resources
• ?fields[professionals]=name,email — sparse fieldsets
• ?filter[status]=active — server-defined filtering
• ?sort=-created-at — prefix with - for descending
• ?page[number]=2&page[size]=25 — pagination

3. If you need to test the API

The docs site has mock endpoints mounted at every documented path. They return the inferred example from the OpenAPI spec. Use them to:

• Validate your request shapes
• See what a response looks like
• Iterate quickly without hitting staging

You can hit the mocks locally with npm start (Express, port 4321) or against the deployed site directly via the Cloudflare Pages Function.

4. Quick reference

• OpenAPI spec: public/openapi.json (or https://${API_CONTABELEZA_URL:-api-docs.contabeleza.com.br}/openapi.json)
• Swagger UI: /docs
• Models reference: /models
• Endpoint browser: / (collapsible groups, search, tag filters)
• Tech guides: /guides/tech — 23 guides: architecture-components, architecture-flows, authentication, ilm-business, jsonapi, environments, invoice-emission-setup, invoice-emission, credential-setup, mei-diagnosis, mei-revenue, das-emission, business-requests, test-fixtures, test-fixtures-cpf, test-fixtures-cnpj-mei, test-fixtures-cnpj-non-mei, test-credentials, contracts-lifecycle, business-resources, professionals, revenue, internal-endpoints
• General guides: /guides/geral — 12 Portuguese guides: autenticacao, emissao-notas, conceitos-da-plataforma, ambientes, configurando-emissao, configuracao-de-credenciais, emitindo-notas-fiscais, emissao-de-das, diagnostico-mei, faturamento-mei, business-requests, gestao-contratos
• Account-level professional endpoints: GET /accounts/{id}/professional-invoices and GET /accounts/{id}/professional-contracts — list all invoices/contracts for all professionals associated with the account via the fiscal entity owner relationship. Each item includes professional-id and tenant-id fields.
• Changelog: /changelog
• This document: /ai (rendered) and /ai.md (raw)

For an existing professional contract that now has its signed document, use PUT /professional-contracts/{id}/pdf with a PDF multipart file (maximum 10 MB) or an existing pdf_url. The endpoint approves contracts in filling or in_approval and closes the linked BusinessRequest.

5. Troubleshooting

Common Errors

Verify Your Setup

# Test authentication
curl -s -o /dev/null -w "%{http_code}" \
  -H "CF-Access-Client-Id: $API_CONTABELEZA_CLIENT_ID" \
  -H "CF-Access-Client-Secret: $API_CONTABELEZA_CLIENT_SECRET" \
  https://${API_CONTABELEZA_URL:-api-docs.contabeleza.com.br}/ai.md

# Expected output: 200

You have everything you need. Read carefully, test against the mocks, and ship.