Notas

GET   {BASE_URL}/api-v1-notes        # lista (exige deal_id)
GET   {BASE_URL}/api-v1-notes/:id     # detalhe
POST  {BASE_URL}/api-v1-notes        # cria

Escopos: notes:read para os GET; notes:write para POST.

Toda nota pertence a um negócio (deal_id obrigatório). Não há PATCH nem DELETE — uma nota criada pela API não é editável nem removível por este recurso.

☠️ A nota é o único caminho que o Otto lê de verdade (ele consulta comentários do negócio como contexto). Se você integra um sistema externo que produz informação relevante sobre um negócio (resumo de reunião, sinal de qualificação, etc.), é aqui que ela deve entrar.

O recurso Nota

Campo	Tipo	Notas
`id`	uuid
`deal_id`	uuid	Negócio ao qual a nota pertence.
`author_id`	uuid	Sempre o membro que criou a chave de API usada na chamada — ver "Autoria", abaixo.
`body`	string	Texto da nota. Até 10.000 caracteres.
`kind`	enum	`note` (registro de algo que aconteceu) ou `observation` (contexto livre do negócio). Padrão `note`.
`source`	enum	`user`, `automation`, `agent` ou `integration`. Toda nota criada por esta API nasce `integration`.
`created_at`	datetime
`updated_at`	datetime

Autoria

comments.author_id é obrigatório na tabela — uma chave de API não é uma pessoa, então a nota é assinada por quem criou a chave. Não existe um autor genérico "Integrações": se a pessoa que gerou a chave deixou de ser membro ativo do workspace, a chamada falha com 422 no_author_available em vez de atribuir a nota a outra pessoa em silêncio.

A origem (que a nota veio de fora) fica em source = "integration", não em author_id nem em kind — os dois continuam significando o que já significavam antes desta API existir.

Listar notas de um negócio

GET {BASE_URL}/api-v1-notes?deal_id=...

deal_id é obrigatório neste endpoint (a tabela de notas não tem workspace_id próprio — o isolamento por workspace passa por confirmar que o negócio pertence à sua conta).

Filtro (query)	Tipo	Notas
`deal_id`	uuid	Obrigatório.
`kind`	enum	`note` ou `observation`.
`since`	ISO 8601	`created_at >= since`.
`limit`	int	Padrão 50, máx 200.
`cursor`	uuid	Próxima página (veja paginação).

curl "{BASE_URL}/api-v1-notes?deal_id=8f3c..." \
  -H "X-API-Key: vnd_sua_chave_aqui"

{
  "data": [ { "id": "5e6f...", "deal_id": "8f3c...", "body": "Reunião concluída...", "kind": "note", "source": "integration", "...": "..." } ],
  "meta": { "next_cursor": null, "has_more": false }
}

Consultar uma nota

GET {BASE_URL}/api-v1-notes/:id → o recurso Nota, ou 404 not_found (inclusive quando a nota existe mas pertence a um negócio de outro workspace).

Criar uma nota

POST {BASE_URL}/api-v1-notes — escopo notes:write.

Campo	Tipo	Obrigatório	Notas
`deal_id`	uuid	Sim	Deve pertencer ao seu workspace.
`body`	string	Sim	1–10.000 caracteres.
`kind`	enum	Não	`note` ou `observation`. Padrão `note`.

curl -X POST "{BASE_URL}/api-v1-notes" \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "deal_id": "8f3c...", "body": "Reunião concluída: decisor presente, orçamento discutido." }'

Resposta 201 Created:

{
  "id": "5e6f...",
  "deal_id": "8f3c...",
  "author_id": "3c2d...",
  "body": "Reunião concluída: decisor presente, orçamento discutido.",
  "kind": "note",
  "source": "integration",
  "created_at": "2026-08-28T14:00:00.000Z",
  "updated_at": "2026-08-28T14:00:00.000Z"
}

Idempotência

Mesmo mecanismo dos demais POST da API — veja Atividades → Idempotência. Envie Idempotency-Key para reprocessar a mesma chamada sem duplicar a nota:

curl -X POST "{BASE_URL}/api-v1-notes" \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: call-9f21" \
  -d '{ "deal_id": "8f3c...", "body": "Reunião concluída: decisor presente." }'

Erros possíveis

HTTP	`code`	Quando
`401`	`missing_api_key` / `invalid_api_key` / `revoked_api_key`	Autenticação.
`403`	`insufficient_scope`	Falta `notes:read` ou `notes:write`.
`404`	`not_found`	Nota não existe, ou pertence a negócio de outro workspace.
`400`	`bad_request`	Corpo ausente/JSON inválido.
`422`	`validation_error`	Campo ou parâmetro inválido, incluindo `deal_id` ausente na listagem.
`422`	`invalid_reference`	`deal_id` fora do workspace.
`422`	`no_author_available`	Quem criou a API Key não é (mais) membro ativo do workspace.
`422`	`invalid_cursor`	`cursor` inválido.
`400`	`invalid_idempotency_key`	`Idempotency-Key` fora de 1–255 caracteres.
`422`	`idempotency_conflict`	Mesma `Idempotency-Key` com corpo ou recurso diferente.
`409`	`idempotency_in_progress`	Mesma `Idempotency-Key` já em processamento (corrida).
`405`	`method_not_allowed`	Método não suportado (inclui `PATCH`/`DELETE`, que este recurso não tem).
`500`	`internal_error`	Falha interna.