Recursos

Os dez recursos da API, suas rotas, escopos, operações e como eles se relacionam entre si.

Cada recurso desta seção segue a mesma anatomia: métodos e escopos, filtros e ordenação, exemplo de payload, tabela de campos de escrita e exemplos curl prontos para colar.

Mapa dos recursos

Recurso	Rota base	Escopo	Operações
Contatos	/v1/leads	leads	read, insert, update, delete
Empresas	/v1/companies	companies	read, insert, update
Negociações	/v1/deals	deals	read, insert, update
Produtos da negociação	/v1/deals/{id}/products	deal_products	read, insert, update, delete
Tarefas	/v1/tasks	tasks	read, insert, update
Produtos do catálogo	/v1/products	products	read, insert, update
Origens	/v1/sources	sources	read, insert, update
Anotações	/v1/deals/{id}/annotations	annotations	read, insert
Arquivos	/v1/deals/{id}/files	files	read, insert, delete
Propostas	/v1/deals/{id}/proposals	proposals	read, insert, update

Como os recursos se relacionam

A negociação é o centro do modelo. Ela exige pelo menos um contato e vive dentro de um funil; empresa, origem e responsável são opcionais. Produtos da negociação, tarefas, anotações, arquivos e propostas pendem dela.

Funil (kanban) ─── Estágio (kanban_status)
                        │
Contato ────────────► Negociação ◄──────── Empresa
                        │  ▲                  ▲
Origem ─────────────────┘  │                  │
                           │            Contato (company_id)
     ┌─────────────┬───────┴───────┬─────────────┬──────────────┐
Produtos da     Tarefas        Anotações      Arquivos      Propostas
negociação                  (linha do tempo)
     │
Produto do catálogo

Ordem de criação recomendada

Recursos independentes primeiro, para que os ids existam quando a negociação for criada:

1. Origem, empresa e produto do catálogo

2. Contato (com tags e campos personalizados)

3. Negociação, referenciando os ids acima

4. Linhas de produto, tarefas, arquivos, propostas e anotações

O passo a passo executável está no Guia rápido.

Convenções que se repetem

• Somente leitura: id, created_at, updated_at e campos calculados como total_amount, total_price, deal_count, lead_count e status.

• Imutáveis no PUT: cnpj da empresa, kanban_id da negociação, product_id da linha de produto e deal_id da tarefa.

• Criados por nome: tags do contato, category da tarefa e category do produto.

• Exclusão disponível: apenas contatos, produtos da negociação e arquivos.

Nesta seção