Internal Endpoints ★
Admin-only and external-app-token endpoints. These routes hit the accounting service directly, without going through core-contabeleza. They are not part of the public API surface.
Overview
The internal ★ group contains endpoints that bypass the core-contabeleza service and talk directly to the accounting service (Go). These are restricted to callers with an external-app-token or admin session.
On the endpoints page, internal endpoints are marked with a red ★ badge. On the models page, internal models appear in a collapsed section at the bottom.
Authentication
Internal endpoints accept two authentication methods:
| Method | Header | Use case |
|---|---|---|
external-app-token | Authorization: Bearer <token> | Service-to-service calls (n8n, internal tools) |
admin session | Authorization: Bearer <jwt> | Admin user logged into the platform |
The ilm-business header is not required for most internal endpoints — the fiscal entity ID is embedded in the path.
Proxy vs direct routes
The Contabeleza platform has two types of routes that reach the accounting service:
| Type | Path pattern | How it works |
|---|---|---|
| Proxy (tenant wrapper) | /businesses/{id}/fiscal-entity/*, /professionals/{id}/fiscal-entity/*, /professional-fiscal-entities* | API gateway → core-contabeleza (checks that the business/professional belongs to the ilm-business tenant) → accounting service (RabbitMQ) |
| Direct | /fiscal-entities/*, /buyer-fiscal-entities/*, /accounting/search/*, /accounting/callbacks/*, /accounting/diagnosis/* | API gateway → accounting service directly (routes registered by accounting in its config/routes.yaml; no core-contabeleza) |
Tenant apps use the proxy routes, which are part of the public API. Every route in the internal ★ group is a direct route. See Architecture — components.
Path prefixes
Internal endpoints use these path prefixes:
| Prefix | Description | Example |
|---|---|---|
/fiscal-entities | Seller fiscal entities (CRUD, MEI, revenue, credentials) | GET /fiscal-entities/{id} |
/buyer-fiscal-entities | Buyer fiscal entities (CRUD) | GET /buyer-fiscal-entities/{id} |
/accounting/search | InfoSimples lookups (address, fiscal info, municipal details). GET /accounting/search/fiscal-info with tax-number-type=cpf requires the birth-date query param (YYYY-MM-DD); errors: 400 BirthDateRequired, 400 InvalidBirthDate, 422 BirthDateMismatch, 404 CPFNotFound | GET /accounting/search/address/{id} |
/accounting/callbacks | Webhook receivers (eNotas, Serpro, InfoSimples) | POST /accounting/callbacks/enotas |
/accounting/diagnosis | MEI diagnosis by CNPJ (for flows that don't have the fiscal entity id yet) | POST /accounting/diagnosis/{cnpj} |
JSON:API type conventions
Internal endpoints return JSON:API responses. The type names use dashes (not underscores):
| Model | JSON:API type |
|---|---|
SellerFiscalEntity | fiscal-entities |
BuyerFiscalEntity | buyer-fiscal-entities |
Invoice | invoices |
FiscalEntityMei | fiscal-entity-meis |
FiscalEntityMeiCnd | fiscal-entity-mei-cnds |
FiscalEntityMeiDasn | fiscal-entity-mei-dasns |
FiscalEntityMeiCcmei | fiscal-entity-mei-ccmeis |
FiscalEntityRevenue | fiscal-entity-revenues |
FiscalEntityRevenueResume | fiscal-entity-revenue-resumes |
PassGov | fiscal-entity-pass-govs |
PassInvoice | fiscal-entity-pass-invoices |
FiscalEntityCertificate | fiscal-entity-certificates |
FiscalEntityRequest | fiscal-entity-requests |
Das | fiscal-entity-mei-dases |
Diagnosis | fiscal-entity-mei-diagnosis |
Deprecated & broken routes
Two routes are marked deprecated: true in the spec:
| Method | Path | Reason |
|---|---|---|
POST | /fiscal-entities/{id}/validate-emission | Replaced by the credential validation flow |
GET | /fiscal-entities/{id}/validation-status | Replaced by emission-status on the model |
Two routes are excluded from the spec because they have no handler method in the accounting service:
| Method | Path | Handler |
|---|---|---|
PUT | /fiscal-entities/{id}/certificate | add_certificate — missing |
POST | /fiscal-entities/{id}/mei/cnpj | update_cnpj — missing |
Admin-only endpoint
One endpoint is restricted to admin callers only:
| Method | Path | Description |
|---|---|---|
GET | /fiscal-entities/{id}/revalidate | Force revalidation of a fiscal entity's credentials |
This endpoint is tagged Privado and requires an admin JWT or external-app-token with admin permissions.