Every deal is always linked to a real Lead. Contact data (name, company, email, phone)
is never duplicated on the deal — it is read from the Lead at read time.
Hierarchy
Resources
Pipelines and Groups
Create, configure, reorder and delete pipelines and their groups
Stages
Kanban columns, including the Won and Lost stages
Deals
Board, paginated listing, creation, editing and moving
Products
The account’s global product catalog
Activities, Files and History
Tasks, attachments and the event log of each deal
Special stages (kind)
A stage can have a kind that changes how a deal behaves when it enters that stage:
Each pipeline has at most one
won stage and one lost stage. They cannot be
deleted, because there is no route that recreates them.
Every new pipeline is born with four default stages:
And with the default loss reasons: Sem orçamento (no budget), Sem resposta / sumiu
(no reply / went dark), Fechou com concorrente (closed with a competitor),
Sem fit com o produto (no product fit), Momento errado (wrong timing).
Default stage names and loss reasons are created by the API in Portuguese. They are stored
values, not labels translated at read time — you receive them exactly as shown above. Rename
them through Configure a pipeline
if you want English names.
Rules enforced by the API
These rules are validated on the server — they are not merely interface guards:Losing a deal always requires a reason
Losing a deal always requires a reason
Moving a deal to the
lost stage (or creating it there) without loss_reason returns
400. There is no path that loses a deal silently.Deleting a stage that has deals requires a destination
Deleting a stage that has deals requires a destination
Deleting a stage that still contains deals without providing
target_stage_id returns
409. Deals are never removed along with the stage.Deleting a group that has pipelines is blocked
Deleting a group that has pipelines is blocked
Returns 409 with the pipeline count. Move them to another group first.
Deleting a product from the catalog does not break deals
Deleting a product from the catalog does not break deals
Existing product lines become one-off lines (
custom: true), preserving name and price.
The deals remain editable.The stage must belong to the pipeline
The stage must belong to the pipeline
Creating or moving a deal into a stage of another pipeline returns 400.
Permissions
Every Pipeline route — including the read ones — is protected by a granular permission. A custom role withoutpipeline.view gets 403 from the API, not just a hidden menu.
The OPERATOR system role gets
pipeline.view, pipeline.deals.create and
pipeline.deals.edit.
To discover the effective permissions of the authenticated user:
GET
/backend/roles/my-permissionsDeal value
A deal’s total (total) is calculated like this:
- If the deal has products: the sum of
price × qtyfor each line. - If it has no products: the legacy
valuefield is used.
total field always comes calculated in the response — there is no need to sum on the client.