Technical guides
Reference docs for developers integrating with the Contabeleza API. From authentication to invoice emission — everything you need to wire the API into your app.
Getting started
The essentials — log in, pick a business, understand the protocol, and know which environment to hit.
Authentication & Tokens
Login flows, JWT claims, token refresh, password reset, API keys — everything about proving who you are.
ilm-business header
The required header that scopes every request to a business tenant. How to find your business id.
JSON:API conventions
Content type, resource documents, collections, errors, field naming, and query parameters.
Environments
Production, staging, QA, and local mock — base URLs, how to switch, and notes per environment.
Setup & configuration
Store credentials, configure providers, and run validations before you can emit invoices.
Invoice Emission — Setup
The setup phase: storing credentials (pass-gov, pass-invoices, certificate), the setup orchestrator, validation pipeline, and emission-status state machine.
Credential Setup
Three credential types to configure: pass-gov, pass-invoices, digital certificate. Create, update, clear, and validate each one.
Core workflows
The flows that matter most — emitting invoices, MEI diagnosis, DAS generation, and revenue tracking.
Invoice Emission
The actual NFS-e emission flow: invoice model, lifecycle, async emission pipeline, cancellation, sync worker, callbacks, JSON:API shapes.
MEI Diagnosis
The two-phase pipeline that evaluates a MEI fiscal entity across 6 dimensions — CNPJ, DAS, DASN, divida ativa, invoice emission, revenue.
Revenue
Revenue resumes per fiscal entity with per-FE status, forward projection (ok/warning/danger), errored/processing month lists, and aggregated totals. Per-CNPJ data, monthly-refreshed cache with premature-detection, two auth paths (pass-invoices vs digital certificate), trailing-12-month support for non-MEI entities.
DAS Emission
How the accounting service fetches, generates, and serves the monthly DAS boletos for MEI — Serpro vs InfoSimples, sync vs async strategies.
BusinessRequests
The async workflow engine: 4 request types (new_contract, new_contract_pdf, profesional_invoice_emission, terminate_contract), status workflow, JSON schemas, cascading webhooks.
Contract Lifecycle
ProfessionalContract status machine, status-update endpoints, termination PDF paths, deprecated endpoints.
Resource management
CRUD operations for businesses, professionals, categories, services, and schedules.
Business Resources
The core resource management endpoints: businesses, professionals, categories, services, and week schedules. All the CRUD operations.
Professionals
Professional model, ownership checks, fiscal entity linking, and relationship to the broader business domain.
Revenue
Revenue resumes per fiscal entity with per-FE status, forward projection, and aggregated totals. Monthly-refreshed cache with premature-detection.
Testing
Test fixtures, credential validation, and mock scenarios for integration testing.
Test Fixtures
Hub guide — CPF, CNPJ, and document numbers. Links to focused guides with fixtures and scenarios.
CPF Fixtures
Individual CPFs — standalone, linked to MEI/non-MEI CNPJs, and error scenarios (not found, invalid format, rate limit).
CNPJ MEI Fixtures
MEI companies — scenario-specific, sequential range, and complete test workflow.
CNPJ Non-MEI Fixtures
Regular companies — scenario-specific, sequential range, and complete test workflow.
Test Credentials
Password-based error scenarios for certificate, pass-invoices, and pass-govs validation. Curl examples for each error type.
Internal endpoints ★
Admin-only and external-app-token endpoints. Restricted to internal tooling — not for general API consumers.