Autenticação

🔑
Como autenticar
Toda requisição exige uma chave de API no header Authorization, no formato Bearer.

Authorization: Bearer imn_seuconvenio_...

A chave é criada em Configurações > Chaves de API, dentro do próprio sistema.

🚧
O valor aparece uma única vez
Guarde a chave no momento da criação, antes de fechar a tela. Se perder, gire a chave (não crie outra), para manter o histórico de uso.

🔐 Comportamento de credencial

Situação	Resposta
Credencial inexistente, revogada ou expirada	`401` silencioso (sem `code`): essas podem ser sondadas por quem não tem chave nenhuma
Chave válida, mas sem o escopo da rota	`403` com `code: SCOPE_DENIED`, dizendo qual escopo falta

🎫 Escopos

Cada chave declara o que pode fazer. A chave nasce sem escopo e o convênio marca, um a um, o que aquela integração pode; não existe escopo "tudo".

Escopo	O que libera
`leads:write`	`POST /leads`
`imoveis:read`	`POST /properties/search`, `GET /properties/{id}` e `GET /properties/{id}/owners`
`imoveis:write`	`POST /properties`, `PUT /properties/{id}`, `PATCH /properties/{id}/status`, fotos por URL, proprietários e etiquetas do imóvel
`pessoas:read`	`POST /people/search` e `GET /people/{id}`
`pessoas:write`	`POST /people`, `PUT /people/{id}`, aplicar e tirar etiqueta da pessoa
`condominios:read`	`POST /condominios/search` e `GET /condominios/{id}`
`condominios:write`	`POST /condominios` e `PUT /condominios/{id}`
`atendimentos:read`	`POST /atendimentos/search` e `GET /atendimentos/{id}`
`captacoes:read`	`POST /captacoes/search` e `GET /captacoes/{id}`
`atividades:read`	`POST /atividades/search` e `GET /atividades/{id}`
`visitas:read`	`POST /visitas/search` e `GET /visitas/{id}`
`propostas:read`	`POST /propostas/search` e `GET /propostas/{id}`
`negocios:read`	`POST /negocios/search` e `GET /negocios/{id}`
`localizacao:write`	`POST /schema/cities` e `POST /schema/neighborhoods`
`midias:write`	`POST /schema/midias`
`usuarios:read`	`GET /users` e `GET /users/{id}`
`etiquetas:read`	`GET /tags` e `GET /tags/{id}`
`etiquetas:write`	`POST /tags` e `PUT /tags/{id}`
`lancamentos:read`	`POST /lancamentos/search`, `GET /lancamentos/{id}` e `GET /lancamentos/{id}/units`
`lancamentos:write`	`POST /lancamentos`, `PUT /lancamentos/{id}`, `PATCH /lancamentos/{id}/status` e os blocos
`contratos:read`	`POST /contratos/search`, `GET /contratos/{id}` e `GET /contratos/{id}/movements`. Só existe no convênio com o módulo Administrativo
`chaves:read`	`GET /properties/{id}/keys`, `GET /key-boards` e `GET /key-boards/{id}/panel`
`atendimentos:write`	Anotar (`POST /atendimentos/{id}/annotations`), descartar (`POST /atendimentos/{id}/discard`) e etiquetar o atendimento
`atividades:write`	`POST /atividades`, `PUT /atividades/{id}`, `POST /atividades/{id}/complete` e `/cancel`
`visitas:write`	Agendar (`POST /atendimentos/{id}/visitas`), reagendar (`PUT /visitas/{id}`), situação (`PATCH /visitas/{id}/status`) e parecer (`PUT /visitas/{id}/feedback`)
`propostas:write`	Incluir proposta (`POST /atendimentos/{id}/propostas`)

📘
Listas de apoio
As rotas de catálogo de imóvel (/schema/enums, /schema/lookups, /schema/neighborhoods, /schema/property-types, /schema/properties) aceitam qualquer um dos dois escopos de imóvel. As listas de apoio gerais (GET /schema/support e GET /schema/holidays) aceitam qualquer escopo, menos a chave que só manda lead.

📘
Etiqueta num registro é escrita no registro
Aplicar ou tirar etiqueta de um imóvel pede imoveis:write, e de uma pessoa pede pessoas:write. etiquetas:write cuida só do cadastro da etiqueta.

Quem pode conceder cada escopo

A chave só recebe os escopos que quem a cria pode conceder, conforme as permissões dessa pessoa no sistema. O escopo que ela não pode conceder aparece travado na criação da chave. Se a integração precisar de um escopo que não está disponível, peça a um administrador do convênio. contratos:read só existe no convênio com o módulo Administrativo.

Escopo não se altera depois de criada

Depois de criada, a chave não muda de escopo. Precisa de outro conjunto? Crie uma chave nova com os escopos certos, troque na integração e revogue a antiga. Girar a chave troca só o segredo e mantém os mesmos escopos.

🔄 Rotação de chave

Girar cria uma chave nova e mantém a antiga válida pelo prazo escolhido (imediato, 24 horas ou 7 dias). Troque a credencial na sua integração dentro desse prazo.

✅ Boas práticas da chave

❗️
Guarde no servidor, nunca no cliente
A chave dá acesso aos dados do convênio: mantenha-a no backend, em variável de ambiente ou cofre de segredos. Nunca em app mobile, front-end ou repositório. E nunca em URL: ela viaja no header Authorization; em query string ou caminho, vaza em logs e histórico.

Escopo mínimo. Crie a chave só com o escopo que a integração precisa. Um integrador que só envia leads usa leads:write, e nada além. Precisou de mais depois? Crie uma chave nova com o conjunto certo e revogue a antiga.
Uma chave por integração/origem. Além de organizar o histórico de uso, permite revogar uma sem afetar as outras, e a mídia do lead é derivada da chave.
Rotacione ao suspeitar de vazamento. Gire a chave (não crie outra à toa) e atualize a integração dentro do prazo de convivência.