Notas

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

Use os endereços acima — são os que respondem hoje. A API está migrando para um endereço único ({BASE_URL}/api-v1/notes), que ainda não foi publicado: enquanto isso, qualquer chamada para ele devolve 404 not_found. Quando entrar no ar, esta página muda junto, e os endereços acima continuam valendo.

Escopos: notes:read para os GET; notes:write para a escrita.

Esta ficha não guarda o cliente na própria linha: o acesso é conferido pela ficha deals (campo deal_id). Por isso o parâmetro deal_id é obrigatório na listagem.

Nota registrada não é editada nem removida pela API — só listagem, consulta e criação.

Campos

Campo	Tipo	Escrita	Notas
`id`	uuid	somente leitura
`deal_id`	uuid	criar: obrigatório, editar: não	Formato uuid; deve existir na ficha `deals`.
`author_id`	uuid	somente leitura	Sempre quem criou a chave de API. Sem fallback: se não for mais membro ativo, a chamada falha.
`body`	string	criar: obrigatório, editar: não	De 1 a 10000 caracteres.
`kind`	string	criar: opcional, editar: não	Valores: `note`, `observation`.
`source`	string	somente leitura	Nota criada pela API pública nasce sempre 'integration'.
`agent_action_id`	uuid	somente leitura
`created_at`	datetime	somente leitura
`updated_at`	datetime	somente leitura

Listar notas

GET {BASE_URL}/api-v1-notes

Parâmetro (query)	Tipo	Notas
`deal_id`	uuid	Obrigatório: a nota é sempre lida e criada dentro de um negócio. Obrigatório.
`kind`	string	Valores: `note`, `observation`.
`since`	datetime	Só registros criados a partir desta data (ISO 8601). Compara: maior ou igual a.
`limit`	number	Tamanho da página. Padrão 50, máximo 200.
`cursor`	uuid	Próxima página — use o `meta.next_cursor` da resposta anterior.

Ordenação: id crescente. Paginação por cursor.

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

{
  "data": [ /* registros */ ],
  "meta": { "next_cursor": "8f3c...", "has_more": true }
}

Consultar um registro

GET {BASE_URL}/api-v1-notes/:id → o recurso completo, ou 404 not_found.

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

Criar

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

Campo	Tipo	Obrigatório	Notas
`deal_id`	uuid	Sim	Formato uuid; deve existir na ficha `deals`.
`body`	string	Sim	De 1 a 10000 caracteres.
`kind`	string	Não	Valores: `note`, `observation`.

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": "..." }'

Erros

HTTP	`code`	Quando
`401`	`missing_api_key` / `invalid_api_key` / `revoked_api_key`	Autenticação.
`403`	`insufficient_scope`	A chave não tem `notes:read` / `notes:write`.
`404`	`not_found`	O registro não existe neste cliente.
`422`	`validation_error`	Campo fora das regras da tabela acima.
`422`	`invalid_reference`	`deal_id` aponta para fora deste cliente.
`422`	`invalid_cursor`	O `cursor` enviado não é válido.
`405`	`method_not_allowed`	Método não suportado neste endereço.
`500`	`internal_error`	Falha interna.

Catálogo completo em Erros.

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 específicos desta ficha

HTTP	`code`	Quando
`400`	`bad_request`	Corpo ausente/JSON inválido.
`422`	`no_author_available`	Quem criou a API Key não é (mais) membro ativo do workspace.
`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).