Registrar nota interna
POST /notes — registra uma nota interna em um contato ou negócio, visível só para a equipe.
/notes
Escopo necessário: notes:write
Registra uma nota interna em um contato ou negócio da organização (resolvida pela API key), em nome de quem criou a chave. A nota é visível só para a equipe: nada é enviado ao contato e nenhuma automação é disparada. Não há rota para editar nem apagar uma nota.
Endpoint
POST https://crm.oficinamartech.com/api/v1/notesCabeçalhos
| Cabeçalho | Obrigatório | Descrição |
|---|---|---|
Authorization | Sim | Bearer + a API key. |
Content-Type | Sim | application/json. |
Idempotency-Key | Sim | De 1 a 128 letras, números, ponto, hífen, sublinhado ou dois-pontos. Veja Repetição. |
Corpo
O corpo tem no máximo 64 KiB. Um campo fora desta tabela é recusado com 400.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
entity_type | contact | deal | Sim | Onde a nota fica: contato ou negócio. |
entity_id | UUID | Sim | Contato (GET /contacts) ou negócio (GET /deals), conforme entity_type. |
content | string (1-4000) | Sim | Texto da nota. |
Exemplo
curl -s -X POST "https://crm.oficinamartech.com/api/v1/notes" \
-H "Authorization: Bearer crm_live_SEU_PREFIXO_SEU_SEGREDO" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: nota-d3a1c0de-ligacao-2026-11-13" \
-d '{
"entity_type": "deal",
"entity_id": "d3a1c0de-58cc-4372-a567-0e02b2c3d479",
"content": "Cliente pediu proposta com pagamento em 3 parcelas."
}'Resposta 201
{
"replayed": false,
"note": {
"id": "5e5e5e5e-58cc-4372-a567-0e02b2c3d479",
"entity_type": "deal",
"entity_id": "d3a1c0de-58cc-4372-a567-0e02b2c3d479",
"content": "Cliente pediu proposta com pagamento em 3 parcelas.",
"created_by": "22222222-58cc-4372-a567-0e02b2c3d479",
"created_at": "2026-11-13T14:10:02.000Z"
}
}created_by é o user_id de quem criou a chave (GET /members).
A nota não pode ser editada nem apagada pela API. Confira o conteúdo e o destino antes de enviar.
Repetição e idempotência
O Idempotency-Key vale por chave de API. Repetir o mesmo pedido com a mesma chave devolve a nota original com 200 e replayed: true, sem registrar outra. Use uma chave por nota lógica e, se o resultado ficou incerto, repita com a mesma chave. A mesma chave com um pedido diferente responde 409 idempotency_conflict.
Erros
| Status | Código | Quando |
|---|---|---|
400 | invalid_idempotency_key | Idempotency-Key ausente ou fora do formato. |
400 | invalid_json | Corpo que não é JSON. |
400 | invalid_payload | Campo desconhecido, ausente ou inválido. |
401 | missing_api_key / invalid_api_key | API key ausente, inválida, expirada ou revogada. |
403 | missing_scope | A chave não tem o escopo notes:write. |
404 | not_found | Contato ou negócio inexistente ou de outra organização. |
409 | idempotency_conflict | A chave de idempotência já foi usada com outro pedido. |
413 | payload_too_large | Corpo acima de 64 KiB. |
429 | rate_limited | Acima do limite de requisições por chave ou por organização. |
429 | daily_limit | Teto das conexões de agente atingido (abaixo). Nada foi gravado. |
500 | — | Erro interno. Repita com a mesma chave de idempotência. |
Teto das conexões de agente
As chaves criadas por conexões de agente (MCP) de uma mesma pessoa fazem, juntas, no máximo 200 escritas (tarefas e notas) a cada 24 horas por organização. Acima disso a resposta é 429 com code: "daily_limit" e nada é gravado; repetir não resolve. Chaves de integração criadas em Configurações → API não têm esse teto.