AI Guide

A guide for AI code CLIs to autonomously acquire all information needed to build functionalities on the Contabeleza API. Also available as raw markdown at /ai.md.

AI.md — Guide for AI Code CLIs

You are an AI code CLI tasked with building a new functionality that integrates with the Contabeleza API.

This document is your single source of truth for understanding the platform. It tells you exactly where to look, what to read, and in what order. Follow it step by step and you will have everything you need to write correct, working code.

Important: This document is served at /ai on the deployed docs site and at /ai (or /ai.md) on the local dev server. Read it first, then follow the links below.

0.1 Environment Variables

Before fetching the docs site, set these environment variables:

Variable	Required	Default	Description
`API_CONTABELEZA_CLIENT_ID`	Yes	—	Cloudflare Access Client ID
`API_CONTABELEZA_CLIENT_SECRET`	Yes	—	Cloudflare Access Client Secret
`API_CONTABELEZA_URL`	No	`api-docs.contabeleza.com.br`	Base URL for the API docs site

These are Cloudflare Access Service Tokens used to bypass ZeroTrust authentication. All curl examples below include the required headers.

---

0. The docs site is your primary source of truth

This repository (api-docs-contabeleza) is a static documentation site for the Contabeleza API. It contains:

An OpenAPI 3.0 spec with every documented endpoint, request/response shape, and example payload
A Models reference explaining every JSON:API type, its attributes, and its relationships
A Tech Guides section with deep technical docs for developers
A General Guides section (in Portuguese) for non-technical users
A Swagger UI at /docs for interactive exploration
An Endpoint browser at / with filter/search and collapsible groups

Before you touch any code outside this repo, fully read the docs site. Specifically:

Section	URL	What it tells you
Endpoints browser	`/`	Every operation, grouped by tag, with descriptions and use-cases. Collapsible groups, search, tag filters.
Swagger UI	`/docs`	Interactive reference — try requests, see schemas
Models	`/models`	Every JSON:API type — attributes, types, examples, relationships
Tech guides catalog	`/guides/tech`	All developer guides (auth, JSON:API, environments, invoice emission, etc.)
General guides catalog	`/guides/geral`	Portuguese guides for non-technical context (with type/status translations)
OpenAPI spec (raw)	`/openapi.json` or `/openapi.yaml`	The full spec as a single document — for programmatic access
Changelog	`/changelog`	Recent changes to the API
This document	`/ai` (rendered) and `/ai.md` (raw)	The bootstrap doc you are reading

1. Read the docs in this order

Do these in order. Don't skip steps.

Step 1.0 — Read `/AI_INDEX.md` (compact reference, ~270 lines)

This is a machine-generated index of every endpoint, model, and error code. It is designed specifically for AI agents — compact, scannable, and directly renderable.

Fetch it first to understand the full surface area of the API:

curl -s \
  -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_INDEX.md

It contains:

Tag tree — all endpoint groups with counts
Endpoint table — method, path, tag, response model, request model, error statuses
Model table — every JSON:API type with attribute and relationship counts
Error code index — unique error codes grouped by HTTP status

Start here. If the index covers your use case, you will know exactly which endpoints to fetch from the full spec.

Step 1.1 — Read `/openapi.json` (or fetch the raw spec)

This is the machine-readable source of truth. Fetch it:

curl -s \
  -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}/openapi.json | jq '.paths, .components.schemas'

For each path you'll see:

summary and description — what the endpoint does
tags — which resource it belongs to
parameters — what you send (path, query, header)
requestBody — the request schema
responses[200] — the success response with an example payload

For each schema in components.schemas you'll see the type, attributes, and relationships.

Start here. If the spec covers your use case, you have everything you need.

Step 1.2 — Read the Models reference at `/models`

The Models page renders the OpenAPI schemas with descriptions, types, and observed examples from captured traffic. It's the human-friendly version of components.schemas.

Use it to understand:

What attributes a resource has
What types they are (string, integer, etc.)
What relationships exist between resources
What real-world example values look like

Step 1.3 — Read the tech guide that matches your task

If you need to...	Read this guide
Log in, get a token, refresh	`/guides/tech/authentication`
Send the `ilm-business` header	`/guides/tech/ilm-business`
Understand the JSON:API envelope	`/guides/tech/jsonapi`
Know which environment to hit	`/guides/tech/environments`
Set up a fiscal entity for emission	`/guides/tech/invoice-emission-setup` — three-step flow: company setup (`POST /invoices-emission`), credential storage via dedicated endpoints, and explicit emission validation (`POST /invoices-emission/validate`)
Configure and validate credentials (pass-gov, pass-invoices, certificate)	`/guides/tech/credential-setup` — how to store, validate, and clear each credential type. Overview of the async validation pattern and the structured error vocabulary from the portal.
Understand the `status_*` computed fields on a fiscal entity	`/guides/tech/invoice-emission-setup` § "emission-status state machine" — explains `status_pass_govs`, `status_pass_invoices`, `status_certificate` (incl. `expired`), `emission_status` (no longer `missing_auth`), and `emission_validation` (via `last_emission_validation` on the seller, with `statuses` audit trail)
Actually emit an invoice	`/guides/tech/invoice-emission`
Run the MEI diagnosis	`/guides/tech/mei-diagnosis`
Generate DAS boletos	`/guides/tech/das-emission`
Build an async workflow (contracts, invoice batches, terminations)	`/guides/tech/business-requests` — for contract termination, the distrato PDF can be attached either at create time (`data.pdf_url`) or at the status→closed transition (top-level `termination_pdf_url` field in the status-update payload); see the "Attaching a distrato on the closed transition" section
Understand contract lifecycle and statuses	`/guides/tech/contracts-lifecycle` — creation, approval, termination, and status machine
Manage businesses, professionals, categories	`/guides/tech/business-resources` — CRUD for businesses, professionals, week-schedules, business-categories, professional-categories, professional-services
List and manage professionals	`/guides/tech/professionals` — professional catalog, ownership checks, personal documents
Query revenue data	`/guides/tech/revenue` — revenue resumes, limits, batch list, per-entity queries
Understand test fixtures (CPF/CNPJ)	`/guides/tech/test-fixtures` — hub guide linking to focused CPF, CNPJ MEI, and CNPJ non-MEI fixture guides
CPF fixtures for individuals	`/guides/tech/test-fixtures-cpf` — standalone CPFs, CPFs linked to MEI/non-MEI CNPJs, error scenarios
MEI CNPJ fixtures	`/guides/tech/test-fixtures-cnpj-mei` — MEI companies with scenario-specific fixtures and test workflow
Non-MEI CNPJ fixtures	`/guides/tech/test-fixtures-cnpj-non-mei` — regular companies with scenario-specific fixtures and test workflow
Test credential error scenarios	`/guides/tech/test-credentials` — password-based error scenarios for certificate, pass-invoices, and pass-govs validation
Use internal accounting endpoints	`/guides/tech/internal-endpoints` — admin-only routes, direct accounting service, proxy vs direct, JSON:API types, deprecated/broken routes

Read the relevant guide fully before writing any code. The guides explain the data flow, gotchas, and edge cases that the OpenAPI spec alone doesn't capture.

Step 1.4 — Read the general guides for business context

The general guides (in Portuguese) explain the business context without code. Read them to understand *why* the API works the way it does:

/guides/geral/autenticacao — How login works
/guides/geral/conceitos-da-plataforma — Platform concepts (Professionals, Fiscal Entities, MEI, Invoices, Contracts)
/guides/geral/ambientes — Environments
/guides/geral/configurando-emissao — Configuring invoice emission
/guides/geral/configuracao-de-credenciais — Credential setup lifecycle (add, update, clear, validate)
/guides/geral/emitindo-notas-fiscais — Emitting invoices
/guides/geral/emissao-de-das — DAS-MEI emission
/guides/geral/diagnostico-mei — MEI diagnosis
/guides/geral/gestao-contratos — Gestão de contratos
/guides/geral/business-requests — The 4 async workflow types

The general guides use Portuguese labels with the original English enum values in tags (e.g. Novo Contrato new_contract). When you see a Portuguese label in a guide, the value in backticks is the actual enum string you send in API requests.


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".
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 — 20 guides: 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
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)
5. Troubleshooting
Common Errors

Error Cause Solution
403 Forbidden Missing or invalid Cloudflare Access headers Ensure CF-Access-Client-Id and CF-Access-Client-Secret are set correctly
401 Unauthorized Service token expired or revoked Generate a new Service Token in Cloudflare Zero Trust dashboard
Connection refused Wrong API_CONTABELEZA_URL Check the URL, default is api-docs.contabeleza.com.br
SSL certificate problem Network or proxy issue Verify network connectivity and SSL certificates

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.

Error	Cause	Solution
`403 Forbidden`	Missing or invalid Cloudflare Access headers	Ensure `CF-Access-Client-Id` and `CF-Access-Client-Secret` are set correctly
`401 Unauthorized`	Service token expired or revoked	Generate a new Service Token in Cloudflare Zero Trust dashboard
`Connection refused`	Wrong `API_CONTABELEZA_URL`	Check the URL, default is `api-docs.contabeleza.com.br`
`SSL certificate problem`	Network or proxy issue	Verify network connectivity and SSL certificates

AI Guide

AI.md — Guide for AI Code CLIs

0.1 Environment Variables

0. The docs site is your primary source of truth

1. Read the docs in this order

Step 1.0 — Read /AI_INDEX.md (compact reference, ~270 lines)

Step 1.1 — Read /openapi.json (or fetch the raw spec)

Step 1.2 — Read the Models reference at /models

Step 1.3 — Read the tech guide that matches your task

Step 1.4 — Read the general guides for business context

Step 1.5 — Check the Changelog at /changelog

2. Understand the API conventions

3. If you need to test the API

4. Quick reference

5. Troubleshooting

Common Errors

Verify Your Setup

Step 1.0 — Read `/AI_INDEX.md` (compact reference, ~270 lines)

Step 1.1 — Read `/openapi.json` (or fetch the raw spec)

Step 1.2 — Read the Models reference at `/models`

Step 1.5 — Check the Changelog at `/changelog`