API pública e tokens de acesso

Como outro sistema consulta as vistorias do seu negócio por uma interface autenticada por token.

A API pública existe para que um sistema do seu negócio, um ERP ou um portal do cliente consulte as vistorias sem que alguém precise copiar dados na mão.

Onde emitir um token

No painel, em Negócio, Integrações, Tokens de API. Você precisa da permissão de ver as configurações do negócio para abrir a tela, e da permissão de alterá-las para emitir ou revogar um token.

Ao criar um token você informa:

Um nome, que diz onde ele é usado. É por ele que você vai saber qual sistema revogar depois.
Os escopos, que limitam o que aquele token alcança.
A validade, que pode ser de 30 dias, 90 dias, um ano ou nenhuma.

Autenticação por token

O acesso é feito com um token do próprio negócio, enviado como credencial na requisição. O contexto da empresa vem do token, e não de um cabeçalho que o chamador escolhe: por construção, um token não alcança dados de outro negócio.

O token tem escopo. Um token de leitura de vistorias lê vistorias e nada além disso.

O que a API cobre

Vistorias: listar, ler uma vistoria, ver o quadro de seções e itens, listar as fotos, abrir, atualizar, cancelar e baixar o laudo em PDF. Ao abrir ou atualizar, a integração também pode espelhar uma vistoria anterior do mesmo objeto, como no painel, e acompanhar a cópia das fotos pela própria vistoria.
Cadastros: imóveis, veículos, áreas, itens de vestuário e proprietários, além das listas de referência de segmentos, tipos de vistoria e das categorias e tipos de imóvel que o seu negócio pode escolher.
Negócio: o cadastro da empresa, os membros, os cargos e a trilha de auditoria.

Cada escopo corresponde a rotas que existem de verdade. Um escopo de escrita já concede a leitura correspondente: quem cria uma vistoria pela API consegue lê-la de volta sem marcar duas caixas.

Onde está a documentação técnica

Em documentacao.nottun.com. A página é montada a partir do contrato que a própria plataforma publica, então ela nunca fica diferente da versão no ar, e traz:

a referência de cada rota, com os campos que entram e os que voltam;
o link da foto de uma vistoria, que só existe depois que o laudo foi gerado - antes disso a foto aparece na listagem sem endereço público;
exemplos prontos em curl, JavaScript e PHP;
um console que executa a chamada de verdade: você cola o token, preenche os filtros e vê a resposta na própria página, sem escrever uma linha de código.

O que a listagem mostra

Cada token aparece com o nome, os escopos, a situação, o último uso, a validade e quem o emitiu. Do valor, só o começo é exibido: o suficiente para identificar a linha, nunca para usar o token.

A situação responde por que um token parou de funcionar:

Ativo: em uso normal.
Expirado: passou da validade escolhida.
Revogado: alguém o desativou no painel.

Revogar

Revogar é imediato e não tem volta. O sistema que estiver usando aquele token passa a receber erro de autenticação na chamada seguinte, então revogue quando desligar uma integração ou quando suspeitar de vazamento.

Limite de requisições

As chamadas são limitadas a 120 por minuto. Uma integração que consulta em laço apertado é barrada com o código 429; consulte com intervalo e trate essa resposta.

O que cada código de erro quer dizer

401: o token está ausente, inválido, expirado ou revogado.
402: o recurso de API não está no plano do negócio, ou a escrita é num segmento sem plano: a API num plano abre a integração, mas cadastrar ou alterar um imóvel, veículo, proprietário ou vistoria precisa do plano daquele segmento.
403: o token não tem o escopo que aquela rota exige, ou o segmento está desativado no negócio (details.reason SEGMENTINACTIVE, que vem antes de qualquer conferência de plano).
404: o registro não existe neste negócio.
409: outra alteração aconteceu ao mesmo tempo que o cadastro ou a atualização de um imóvel, de um veículo ou de uma vistoria. Nada foi gravado; envie a mesma requisição de novo.
422: o conteúdo enviado foi recusado pela validação ou por uma regra de negócio.
429: passou do limite de requisições por minuto.
500: falha do nosso lado. A mensagem é fixa e não traz detalhe interno; tente de novo em instantes.

Para manter uma base espelhada

Em vez de reler tudo de tempos em tempos, use o filtro updatedsince nas listagens: ele devolve só o que mudou desde a data informada. Toda listagem responde no mesmo formato, com a página atual, o tamanho da página e o total, então o laço de paginação é escrito uma vez e serve para qualquer recurso.

Guarde o token como senha

Requisito de plano

A API é um recurso de plano. Sem ele a tela continua abrindo e você continua vendo os tokens já emitidos, mas emitir um novo é recusado, e a própria tela avisa isso antes de você tentar.