Comece pelo fluxo de informação

Uma integração útil parte de uma necessidade específica. Atualizar a última imagem em um portal, recuperar registros de um período ou apresentar timelapses publicados são objetivos diferentes. Cada um exige frequência, volume e controles próprios. Descrever primeiro o fluxo evita criar uma chave ampla apenas porque a tecnologia permite. A equipe deve saber qual sistema consulta, qual conteúdo recebe e qual público vê o resultado.

Também é importante distinguir disponibilidade de API de integração pronta. Uma API oferece um contrato para aplicações se comunicarem; o conector para um ERP, um CRM ou um painel específico pode exigir desenvolvimento, configuração e homologação. A decisão deve considerar quem mantém esse código, como as falhas serão identificadas e quem responde quando uma alteração no sistema de destino afetar o fluxo.

Mapeie a necessidade aos recursos disponíveis

A API pública do Timelapse de Obras, no contrato /v1, permite consultar câmeras, a imagem mais recente, imagens por período e timelapses publicados disponíveis à integração. Há ainda consultas de transmissão ao vivo e clima quando esses recursos estão habilitados no ambiente. Essas rotas são de leitura. Elas não devem ser interpretadas como uma autorização para executar toda ação administrativa ou solicitar qualquer processamento que existe na interface do produto.

Uma integração deve tratar cada resposta conforme o contrato documentado. Consultas por período usam paginação por cursor, e as datas precisam respeitar o formato e o fuso definidos. O cliente deve seguir o cursor de continuidade até completar o conjunto desejado, sem presumir que a primeira resposta contém todo o acervo. A rota pública de timelapses não oferece a versão UHD, uma diferença relevante quando o destino exige uma resolução específica.

Dê a cada chave uma finalidade delimitada

A autenticação aceita uma chave autorizada, enviada no cabeçalho da requisição. O desenho recomendado para integrações de servidor mantém o segredo no ambiente que executa as consultas, fora do repositório público e da página entregue ao navegador. Uma chave não deve ser reutilizada indiscriminadamente entre aplicações com finalidades diferentes. Separar integrações ajuda a revisar acesso, consumo e revogação sem interromper todos os fluxos ao mesmo tempo.

No Timelapse de Obras, a chave pode ser limitada por escopo, obra, validade e restrições de origem ou IP. O acesso também acompanha as permissões atuais de quem a criou. Isso significa que a operação precisa prever mudanças de equipe: uma saída ou alteração de responsabilidade pode afetar uma integração. O processo de administração deve identificar o responsável técnico e revisar periodicamente os vínculos e as chaves em uso.

Planeje consumo e recuperação de falhas

A frequência de consulta deve acompanhar a necessidade do negócio e a disponibilidade de registros, não apenas a capacidade de executar chamadas. Consultar continuamente uma imagem que muda em intervalos maiores pode consumir cota sem acrescentar informação. Defina uma política de atualização, considere armazenar temporariamente o resultado quando apropriado e documente por quanto tempo esse conteúdo pode permanecer no sistema de destino.

A API aplica limites por minuto e cotas mensais para a empresa e para a chave. Quando houver resposta 429, a aplicação deve respeitar a indicação de nova tentativa, em vez de repetir chamadas em sequência. Erros de autenticação, falta de permissão e indisponibilidade precisam de tratamentos diferentes. O identificador da requisição ajuda a relacionar o problema observado pela aplicação ao atendimento técnico, sem expor o segredo da chave em logs.

Homologue o comportamento, não apenas a primeira resposta

Receber uma resposta com sucesso é o começo da validação. Teste também a consulta a uma obra fora do escopo, a paginação, o intervalo sem registros, a chave expirada e a chave revogada. Confira o que a aplicação mostra ao usuário quando o conteúdo não está disponível. Uma mensagem clara sobre a última atualização é melhor do que manter uma imagem antiga sem contexto, fazendo parecer que ela representa o momento atual.

A homologação deve incluir o destino dos arquivos. Se a integração copia uma imagem para outro serviço, a política de retenção e as permissões desse serviço passam a fazer parte do fluxo. Revogar uma chave impede novas consultas autorizadas por ela, mas não apaga automaticamente cópias já distribuídas. Esse comportamento precisa estar claro para tecnologia, operação e responsáveis pela governança de dados.

Mantenha o contrato visível entre as equipes

Documente a finalidade, os recursos usados, os escopos, a frequência, o responsável e o procedimento de substituição da chave. Registre também os critérios de sucesso: que informação deve chegar, com qual atualização e qual comportamento em caso de falha. Esses detalhes tornam a manutenção menos dependente de uma pessoa e ajudam a avaliar mudanças de escopo sem perder o controle do que já está operando.

No ambiente do Timelapse de Obras, a documentação interativa é disponibilizada em /v1/docs e a especificação em /v1/openapi.json. A avaliação técnica deve confirmar URL, habilitação, limites e recursos contratados antes da implementação. Com esse contrato definido, a integração deixa de ser apenas uma conexão entre sistemas e passa a ser um fluxo de informação que a empresa consegue administrar.

Fontes e contexto

Conteúdo baseado no contrato público /v1 do produto. Documentação e especificação completas ficam no ambiente da implantação. Recursos, limites e condições devem ser confirmados no projeto técnico.