API — Notas do contato

Nota é um texto livre preso à ficha do contato. Vale para o que a equipe precisa saber sempre que falar com aquela pessoa.

Três coisas diferentes com o mesmo nome

O que	Onde fica	Como se cria
Nota do contato	Na ficha, para sempre	Esta página
Nota interna da conversa	Dentro de um atendimento	POST /conversations/{id}/messages com private: true — veja mensagens
Nota do negócio	Dentro de uma oportunidade	POST /pipelines/{id}/deals/{id}/create_note — veja negócios

A escolha é de escopo: o que vale para a pessoa inteira vai na ficha; o que vale só para aquele atendimento vai na conversa.

Endpoints

Método	Endpoint	Ação
GET	/contacts/{contact_id}/notes	Lista, da mais recente para a mais antiga
GET	/contacts/{contact_id}/notes/{id}	Uma nota
POST	/contacts/{contact_id}/notes	Cria
PATCH	/contacts/{contact_id}/notes/{id}	Edita o texto
DELETE	/contacts/{contact_id}/notes/{id}	Apaga de vez

Todos sob /api/v1/accounts/{account_id}.

Criar

O texto vai dentro de um objeto note:

curl -X POST "https://app.smart2.com.br/api/v1/accounts/1/contacts/4521/notes" \
  -H "api_access_token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "note": { "content": "Prefere contato pela manhã. Não ligar depois das 18h." } }'

Sem o embrulho, a chamada volta 422 com param is missing or the value is empty: note.

O autor é o usuário dono do token — é o nome dele que aparece na ficha. Mais um motivo para cada integração ter o seu usuário; veja autenticação.

Resposta

{
  "id": 87,
  "content": "Prefere contato pela manhã. Não ligar depois das 18h.",
  "account_id": null,
  "contact_id": null,
  "user": {
    "id": 7,
    "name": "Integração ERP",
    "email": "[email protected]"
  },
  "created_at": 1758542400,
  "updated_at": 1758542400
}

Cuidado

account_id e contact_id voltam sempre nulos — é um defeito conhecido nosso, não um comportamento. Use os valores que você já mandou na URL; estão corretos no banco, só não são devolvidos.

As datas vêm como número, em segundos desde 1970.

Listar

curl ".../contacts/4521/notes" -H "api_access_token: SEU_TOKEN"

Devolve uma lista crua, sem payload em volta — diferente da maioria dos endpoints. Vem em ordem inversa, da mais nova para a mais velha, e sem paginação: contato com muita nota devolve todas de uma vez.

Editar e apagar

curl -X PATCH ".../contacts/4521/notes/87" \
  -H "Content-Type: application/json" \
  -d '{ "note": { "content": "Mudou: aceita ligação à tarde." } }'

curl -X DELETE ".../contacts/4521/notes/87" -H "api_access_token: SEU_TOKEN"

DELETE apaga mesmo — não é como o de mensagem, que só esvazia o conteúdo. Não há desfazer.

Caso de uso

Trazer as anotações do sistema antigo

Nota não tem chave externa, então a API não reconhece repetição: rodar o script duas vezes cria tudo duas vezes. A proteção é sua.

ja_tem = {n["content"] for n in
          requests.get(f"{BASE}/contacts/{contato_id}/notes", headers=H).json()}

for texto in notas_do_sistema_antigo(contato_id):
    if texto in ja_tem:
        continue
    requests.post(f"{BASE}/contacts/{contato_id}/notes", headers=H,
                  json={"note": {"content": texto}})

Nota ou campo personalizado?

Se o dado vai ser filtrado, segmentado ou contado — plano, cidade, CNPJ, data de renovação —, ele é campo personalizado, não nota. Nota é texto corrido que gente lê; não entra em filtro, segmento nem relatório.

Próximos passos

• Contatos
• Campos personalizados
• Mensagens — a nota interna da conversa