Usar a API REST da Reonic

A Reonic oferece uma API REST pública que cobre projetos residenciais, projetos comerciais, contactos, tarefas, equipas, ficheiros, compromissos, componentes, atividades, estado e pipeline, etiquetas, notas, pacotes de planeamento, modelos de planeamento, modelos de oferta, modelos de listas de verificação, fontes de leads, quadros e colunas Kanban, conteúdo wiki, fotogrametria e controlo do tempo.

Se um sistema que quer ligar já tiver uma integração com nome próprio (HubSpot, Pipedrive, Lexoffice, Bexio, Hero, K2, Microsoft, Google, AroundHome, DAA, Wattfox, Bees & Bears, EOS, Photovate e outras), use essa. Está pré-configurada e é suportada. A API é para tudo o resto: sistemas feitos em casa, ferramentas de BI, CRM de nicho, dashboards personalizados e pontes para ferramentas sem integração própria. Para automações sem código e envios de eventos para fora, consulte os guias do Zapier e dos Webhooks.

Para quem é este artigo

Admins do instalador e admins de Workspace que constroem integrações personalizadas ou exportam dados da Reonic. Os seus clientes finais (proprietários, compradores comerciais) nunca veem a superfície da API.

Antes de começar

• Precisa de direitos de admin no seu Workspace Reonic.
• A API está disponível em todos os Workspaces. Se o painel de chaves API não aparecer nas suas definições, contacte o suporte da Reonic.
• A Reonic mantém em paralelo uma versão atual e uma versão anterior da API durante um período de transição. Se o seu Workspace tiver chaves na versão mais antiga, a página Definições > API / Programadores > API mostra um separador para cada uma. Construa todas as integrações novas sobre a versão atual.
• Um host de scripts, uma ferramenta de BI ou qualquer sistema capaz de enviar pedidos HTTPS.

Encontrar a página de definições da API

A configuração da API e dos webhooks vive numa página de definições separada da lista de integrações com nome próprio.

1. Abra Definições > API / Programadores. É distinta de Definições > Definições da empresa > Integrações (a página das integrações com nome próprio).
2. A categoria API / Programadores tem duas páginas: API (criar e gerir chaves) e Webhooks (configurar webhooks de saída e os hooks do Zapier).
3. Se o seu Workspace tiver chaves na versão anterior da API, a página API mostra um separador para a versão atual (pré-selecionado) e outro para a versão anterior. Os Workspaces com chaves apenas na versão atual veem uma única página.
4. Se não vir de todo a secção de chaves API, contacte o suporte da Reonic.

Criar uma chave API

As chaves API permitem que os seus scripts e sistemas externos se autentiquem na Reonic.

1. Na página API, clique em Criar novo para adicionar uma chave API.
2. Dê à chave um nome descritivo que lhe diga para que serve, por exemplo uma chave de leitura para o armazém ou uma chave de produção do Zapier. O nome aparece no registo de atividade, para poder distinguir as chaves.
3. Escolha o âmbito. Há três: Apenas leitura (leitura em todos os recursos), Leitura e escrita (leitura e escrita completas em todos os recursos) e Apenas criação de leads (um âmbito restrito que pode criar leads, projetos residenciais, contactos e notas, e mais nada). Para uma integração normal, escolha Apenas leitura ou Leitura e escrita. Apenas criação de leads destina-se a chaves de intermediários de leads que só devem acrescentar leads.
4. A Reonic gera a chave e mostra-a no momento da criação.
5. Copie-a de imediato para o seu cofre de segredos e depois guarde. Se já não tiver a chave, crie uma nova e remova a antiga.

Onde encontrar o ID do cliente

O seu ID do cliente é o identificador do seu Workspace. Na maioria das integrações não precisa dele em separado. Um pequeno número de integrações de parceiros, como algumas configurações de intermediários de leads, pede o ID do cliente como campo autónomo. Peça ao suporte da Reonic para confirmar o seu.

Chave API versus ID do cliente

A chave API é o segredo, como uma palavra-passe. Autentica cada pedido. O ID do cliente é o identificador do seu Workspace, como um nome de utilizador. Mantenha a chave API privada; o ID do cliente é a sua referência de Workspace para sistemas de parceiros.

Autenticar chamadas à API

A Reonic usa um cabeçalho de autenticação próprio em vez do cabeçalho Authorization padrão. A referência de endpoints indica o cabeçalho exato e mostra como o definir.

1. No seu cliente HTTP, defina o cabeçalho de autenticação da Reonic com o valor da sua chave API.
2. Envie o pedido para o endpoint em causa.
3. Se o pedido for rejeitado como não autenticado, verifique que definiu o cabeçalho de autenticação da Reonic (e não o cabeçalho Authorization padrão) e que copiou a chave completa.

Encontrar a referência de endpoints

A referência de endpoints é uma página de documentação. É a lista autoritativa de todos os endpoints, do seu caminho exato, dos campos de pedido e de resposta e do cabeçalho de autenticação. Os seus endpoints dividem-se em dez grandes áreas:

• Pessoas — utilizadores, equipas.
• Projetos — projetos residenciais (a superfície residencial de solar, bomba de calor e wallbox) e projetos comerciais (o pipeline comercial).
• Trabalhar num projeto — atividades, estado, etiquetas, notas, ficheiros, quadros e colunas Kanban.
• Calendário — compromissos, feeds de calendário.
• Catálogo — componentes, fabricantes, pacotes de planeamento, modelos de planeamento, modelos de oferta.
• Configuração do Workspace — fontes de leads, modelos de listas de verificação, integrações.
• Wiki — conteúdo wiki.
• Serviços — marcações de serviço.
• Auxiliares da API — endpoints utilitários.
• Guias — páginas de guia de migração incorporadas.

Fazer a sua primeira chamada à API

Teste a ligação antes de construir seja o que for sobre ela.

1. Escolha um endpoint de leitura de baixo risco. Uma lista de projetos residenciais ou de contactos é um começo seguro. A referência de endpoints dá-lhe o caminho exato.
2. Faça a chamada com a sua chave API no cabeçalho de autenticação da Reonic.
3. A Reonic responde com um payload JSON. Os endpoints de lista devolvem um array de dados mais um bloco de paginação.
4. Confirme que a chamada ficou registada em Definições > Definições da empresa > Integrações com estado de sucesso.

Migrar para a versão atual da API

As duas versões da API correm em paralelo durante a transição, e a versão anterior mantém-se estável. Planeie a sua migração com antecedência para que as suas integrações estejam na versão atual bem antes de a anterior ser desativada. Peça ao suporte da Reonic a data prevista de desativação para poder planear em conformidade.

O grupo migração na referência de endpoints percorre os passos. Em resumo:

1. Crie uma nova chave na versão atual. Os endpoints atuais esperam uma chave da versão atual.
2. Trate das listas paginadas. Todas as respostas de lista trazem um array de dados mais um bloco de paginação. Atualize qualquer parser que assumisse um array simples.
3. Use as superfícies de projetos residenciais e de projetos comerciais. Substituem a antiga superfície de pedidos e ofertas: projetos residenciais para a linha de solar, bomba de calor e wallbox, projetos comerciais para a linha comercial.
4. Ajuste-se aos nomes de campo atuais. Alguns nomes de campo diferem da versão anterior, incluindo os campos de e-mail, morada e variantes. A referência de endpoints lista os nomes atuais.
5. Adote os limites e o comportamento de cache atuais. A referência de endpoints descreve como pedir uma leitura fresca em cada chamada e como reagir quando lhe é pedido que abrande (ver Lidar com limites de débito e cache).

Para recriar objetos que antes construía com os antigos auxiliares de duplicação, use o endpoint de criação padrão. A versão atual trata da duplicação através do fluxo de criação normal.

Paginar, filtrar e obter deltas

Os endpoints de lista usam paginação por número de página.

• Passe um número de página e um tamanho de página para percorrer os resultados.
• A resposta inclui ligações para a página seguinte e a anterior. Siga-as para percorrer o conjunto completo.
• Alguns endpoints paginam de forma diferente. A referência de endpoints assinala esses casos, incluindo um tamanho de página fixo no controlo do tempo, endpoints de resposta única como equipas e etiquetas, e uma janela temporal deslizante nos eventos de calendário.

Para obter deltas (apenas os registos alterados desde a sua última execução), os projetos residenciais expõem uma marca temporal de última edição que pode usar como marca de água. Nos restantes endpoints, guarde a marca temporal de alteração mais alta da resposta anterior e volte a ler a partir daí. O suporte a filtros por data de alteração varia consoante o endpoint. Se o seu script precisar de deltas, pergunte ao suporte da Reonic que endpoints de lista expõem o filtro.

Lidar com limites de débito e cache

A API aplica um limite de débito por Workspace, para que nenhuma integração sozinha sobrecarregue os seus dados. Se enviar pedidos mais depressa do que o limite, a Reonic responde a pedir-lhe que abrande.

1. Quando lhe pedirem que abrande, recue antes de tentar de novo. Um recuo exponencial (2, 4, 8, 16 segundos) é um padrão seguro.
2. Se o serviço comunicar que está temporariamente indisponível, recue e tente de novo.
3. Em leituras grandes, espace as suas chamadas e acrescente uma pequena pausa entre páginas para se manter abaixo do limite.
4. As leituras repetidas são servidas a partir de uma cache de curta duração. Quando precisar dos dados mais recentes numa chamada específica, a referência de endpoints mostra como pedir uma leitura fresca.

Lidar com erros

A Reonic devolve erros HTTP estruturados que correspondem à semântica padrão 4xx e 5xx.

• Não autenticado — chave em falta ou inválida. Verifique que definiu o cabeçalho de autenticação da Reonic (e não o cabeçalho Authorization padrão) e que copiou a chave completa.
• Permissão negada — o âmbito da chave não inclui a operação, ou o recurso está fora do que a chave permite. Trate as respostas 4xx como terminais; não repita o pedido.
• Não encontrado — verifique o ID.
• Pedido para abrandar — está a enviar pedidos demasiado depressa. Recue e tente de novo.
• Erro de servidor (5xx) — comunique-o ao suporte com a marca temporal. Trate 5xx como transitório e repita com recuo.
• Temporariamente indisponível — recue e tente de novo.

Tarefas comuns na API

Estes são os padrões mais pedidos. Trate-os como pontos de partida. A referência de endpoints em direto lista todos os endpoints e a forma exata dos seus campos; o seu gestor de contas pode ajudar se ficar preso.

Criar um pedido

Use o endpoint de criação de projetos residenciais para leads de solar, bomba de calor e wallbox, e o endpoint de criação de projetos comerciais para o pipeline comercial. O endpoint devolve o ID do novo projeto.

Para o lead aparecer no mapa, a Reonic precisa de uma localização. Forneça uma morada para a Reonic procurar, ou um conjunto de coordenadas que já tenha resolvido. Inclua sempre um código postal e verifique as coordenadas devolvidas se a precisão exata for importante.

Defina o estado do projeto no momento da criação se quiser um estado inicial específico. Caso contrário, o pedido entra no estado inicial do Workspace.

Este é também o endpoint para importar leads de um sistema sem integração própria, por exemplo um formulário de contacto WordPress a publicar no seu endpoint de projetos residenciais ou de contactos. O caminho com menos código é uma ponte Zapier a partir do formulário WordPress.

Editar um pedido depois de criado

Atualize a maioria dos campos depois da criação, incluindo a morada, com o endpoint de atualização de projeto residencial ou comercial e o ID do projeto.

Criar uma oferta a partir de um projeto

Uma oferta (Angebot) na API é o orçamento com preço, em forma de variantes, que pende de um projeto. Junta uma ou mais variantes (cada uma com a sua lista de componentes, seleção de pacote, preços e eventual desconto ou financiamento) e os metadados ao nível da oferta (estado, estado de assinatura, notas e ficheiros anexados). É a mesma construção que vê no Portal, no separador Ofertas de um projeto.

O fluxo recomendado:

1. Crie o projeto através da API.
2. Retire o ID do projeto da resposta.
3. Chame o endpoint de criação de oferta com esse ID de projeto e a sua definição de variante.
4. A resposta contém o ID da nova oferta, que usa nas atualizações posteriores.

Deixe o estado da oferta por definir na criação se quiser que ela entre como rascunho. Para converter um pedido em oferta, chame o endpoint de criação de oferta com o ID do projeto, e a Reonic associa a nova oferta ao projeto de origem.

Definir ou atualizar o preço de uma oferta através da API

O endpoint de atualização de oferta aceita um preço ao nível da variante, o que é útil quando o seu sistema externo de preços precisa de enviar um preço final para a Reonic. A forma exata do campo depende da variante. Consulte a referência de endpoints ou pergunte ao suporte da Reonic.

Acrescentar notas ou ficheiros a uma oferta

Há endpoints dedicados para acrescentar uma nota e para carregar um ficheiro. Os ficheiros carregados (PDF, imagens) ficam anexados à oferta, ao projeto ou ao contacto que indicar.

Criar um contacto

Use o endpoint de criação de contactos. Não são precisas coordenadas ao criar contactos; só os projetos que aparecem no mapa precisam de localização.

Para importações em massa (migrar uma lista de contactos existente para a Reonic a partir de um CSV, de um CRM antigo ou de uma folha de cálculo), percorra os seus registos e crie um contacto por chamada, espaçando as chamadas para se manter abaixo do limite de débito. Para migrações pontuais maiores, corra o ciclo a partir da sua própria infraestrutura contra o mesmo endpoint. Todos os endpoints de criação devolvem o ID do novo recurso, por isso capte-o no momento da criação.

Filtrar atividades por tipo de elemento pai

O endpoint de atividades suporta um filtro por tipo de elemento pai que limita as atividades a um determinado tipo de registo, por exemplo um projeto residencial, um projeto comercial, um pacote, um componente, um contacto, um job de fotogrametria ou um utilizador. Consulte a referência de endpoints para os valores exatos aceites.

Exportar dados

O caminho mais limpo para exportações em massa é listar o endpoint relevante com paginação e guardar a resposta. Alvos habituais:

• Ofertas ganhas — leia todas as ofertas e filtre por estado, ou leia a lista do estado ganho.
• Contactos — leia os contactos com paginação e guarde-os localmente.
• Projetos comerciais — leia os projetos comerciais.
• Compromissos — leia os compromissos da superfície de calendário da Reonic. Os calendários externos Microsoft ou Google leem-se diretamente nesses serviços.
• Versões de componentes — leia os componentes e agrupe por componente pai onde existirem versões.
• Estado dos quadros Kanban — leia os quadros e colunas Kanban para instantâneos dos quadros de projeto.
• Fontes de leads — leia as fontes de leads para conhecer a taxonomia de canais configurada no Workspace.

Para produzir um ficheiro Excel dos seus pedidos, ofertas, estatísticas ou dados em bruto, leia o endpoint de lista relevante e carregue a resposta JSON no Excel, no Google Sheets ou na sua ferramenta de BI.

Usar a versão atual da API nas integrações externas

Construa sempre as integrações externas sobre a versão pública atual da API, incluindo o carregamento de ficheiros. É o contrato estável e suportado para ler e escrever os seus dados a partir de fora do Portal.

Fazer a ponte para ferramentas sem integração própria

Para sistemas que não estão no catálogo de integrações com nome próprio (Datev, Monday.com, Craftnote, sincronização de contactos do Office 365, Zoho CRM, envio de e-mail em massa), construa sobre a API para enviar dados para fora de forma agendada, ou ligue-os através do Zapier.

• Datev — envie faturas para fora da Reonic através da API e importe-as no Datev do lado da contabilidade, ou use o Lexoffice ou o Sevdesk como ponte (ambos têm exportação nativa para Datev). O caminho Lexoffice ou Sevdesk é também a forma de envolver um consultor fiscal (Steuerbüro), que normalmente já tem acesso a uma dessas ferramentas.
• Sincronização de contactos do Office 365 — a integração Microsoft trata dos calendários; sincronize contactos com um Zap personalizado ou uma integração à medida contra o seu endpoint de contactos.
• E-mail em massa — a Reonic não é uma ferramenta de e-mail marketing. Exporte os seus contactos através da API e envie a campanha a partir de uma plataforma dedicada (Mailchimp, Brevo, HubSpot Marketing).
• Zoho CRM — faça a ponte com um fluxo Zapier (um gatilho novo lead no Zoho CRM a publicar no seu endpoint de projetos residenciais ou de contactos), ou programe uma sincronização periódica Zoho-Reonic na sua própria infraestrutura. Ambos os caminhos precisam dos campos de morada descritos em Criar um pedido.
• Calendário Microsoft 365 / Google Workspace — estes têm integrações dedicadas em Definições > Definições da empresa > Integrações, e não o caminho da API. Configure-os aí e depois leia os calendários externos do Outlook ou do Google diretamente nesses serviços. A API expõe os compromissos da Reonic.
• Intermediários de leads (AroundHome, DAA, Wattfox e outros) — estes têm integrações dedicadas em Definições > Definições da empresa > Integrações, por isso use-as em vez da API genérica. No AroundHome, o ID de cliente é o identificador específico da integração; consulte o painel de administração do AroundHome para saber o formato exato. Recorra à API ou ao Zapier apenas para fontes de leads fora do catálogo de integrações com nome próprio.

Se quiser uma integração própria para uma fonte de grande volume, diga-o ao seu gestor de contas.

Onde vivem as integrações com nome próprio

Todas as integrações com nome próprio vivem em Definições > Definições da empresa > Integrações (e não em API / Programadores), cada uma com a sua página de configuração e credenciais por Workspace. Para o financiamento Bees & Bears não precisa de chave API. Configure a integração diretamente em Definições > Definições da empresa > Integrações, e a Reonic trata das credenciais.

• HubSpot, Photovate, Hero, Sevdesk — consulte as respetivas páginas de configuração em Definições > Definições da empresa > Integrações.
• Exportação de oferta para Photovate / K2 e associação de componentes ao Photovate — botões de exportação dedicados na oferta assinada. Para ofertas que precisem de dados K2 depois da assinatura, clique no botão de exportação na linha da assinatura.
• Financiamento (Bees & Bears, EOS) — o Bees & Bears cobre DE, AT, FR e BE; o EOS cobre o Brasil. Depois de um cliente assinar uma oferta com uma opção de financiamento, use o botão de exportação para o financiamento na oferta assinada. A Reonic envia os dados da oferta, os dados do cliente e o PDF assinado ao parceiro financeiro. Se a opção de exportação não aparecer, confirme com o seu gestor de contas que o seu Workspace tem a integração de financiamento ativa e que o utilizador tem o direito Financing Provider.
• Sevdesk depois de uma ligação expirada — para transferir uma oferta assinada para o Sevdesk quando a ligação de assinatura original expirou, emita um novo pedido de assinatura sobre a mesma variante, carregue o PDF assinado na nova linha de assinatura e clique no botão de exportação para o Sevdesk nessa linha.
• SMTP — a Reonic envia e-mails dirigidos ao cliente, como ligações de assinatura e avisos de fatura. Para enviar a partir do seu próprio domínio, configure um servidor SMTP de saída personalizado em Definições > Definições da empresa > Integrações > Servidor de email SMTP.
• Campos do formulário de contacto e UTM — o formulário de contacto suporta um conjunto limitado de campos adicionais e etiquetas de fonte de lead. A passagem de UTM em formulários incorporados é tratada pelo código de incorporação; fale com o seu gestor de contas sobre o seguimento de UTM no formulário de contacto.

Transferir ofertas entre Workspaces Reonic

Para mover uma oferta entre Workspaces Reonic:

1. Exporte o PDF da oferta a partir do Workspace de origem.
2. Volte a criar o projeto e a oferta no Workspace de destino, através da API ou manualmente no Portal.
3. Anexe o PDF exportado como ficheiro na oferta de destino.

Se isto se tornar uma necessidade recorrente, por exemplo num grupo de franquias que move ofertas entre Workspaces, fale com o seu gestor de contas sobre um padrão melhor.

Vale a pena saber

• A API está disponível em todos os Workspaces. As chaves aparecem na página Definições > API / Programadores > API.
• As duas versões da API correm em paralelo durante a transição. Construa as integrações novas sobre a versão atual e migre antes de a anterior ser desativada; peça ao suporte da Reonic a data prevista.
• A Reonic usa um cabeçalho de autenticação próprio, e não o cabeçalho Authorization padrão. Muitos clientes HTTP usam Authorization por predefinição; acrescente antes o cabeçalho de autenticação da Reonic como cabeçalho personalizado. A referência de endpoints indica-o.
• A referência de endpoints é o contrato autoritativo. Lista todos os endpoints, o seu caminho exato, os campos de pedido e de resposta e o cabeçalho de autenticação. Quando um campo ou caminho difere da versão anterior, a referência mostra o nome atual.
• Os erros de permissão surgem como erros HTTP estruturados. Trate 4xx como terminal (não repita) e 5xx como transitório (repita com recuo).
• Copie cada chave para o seu cofre de segredos no momento da criação. Se já não tiver uma chave, crie uma nova e remova a antiga.
• O âmbito das chaves API tem três níveis — Apenas leitura, Leitura e escrita e Apenas criação de leads (um âmbito restrito que só pode criar projetos residenciais, contactos e notas, para chaves de intermediários de leads). Crie chaves separadas com nomes descritivos para clareza de auditoria.
• Os limites de débito aplicam-se por Workspace. Se enviar pedidos demasiado depressa, a Reonic pede-lhe que abrande; recue e tente de novo. Todas as chaves de um Workspace partilham um único orçamento.
• As leituras repetidas são servidas a partir de uma cache de curta duração. Quando precisar dos dados mais recentes numa chamada específica, a referência de endpoints mostra como pedir uma leitura fresca.
• Remover uma chave deixa-a de funcionar. Desativar, rodar ou eliminar uma chave tira essa chave de serviço.
• Todas as chamadas à API ficam no registo de atividade da integração com o seu ID do cliente, o método, o estado e uma marca temporal, visível em Definições > Definições da empresa > Integrações.
• As atividades filtram-se por tipo de elemento pai. Limite as atividades a um projeto residencial, projeto comercial, pacote, componente, contacto, job de fotogrametria ou utilizador; consulte a referência de endpoints para os valores exatos.
• Os calendários externos não passam pela API. A API expõe os compromissos da Reonic; leia o Outlook ou o Google diretamente nesses serviços.
• Teste no seu Workspace com um pedido de teste claramente identificado, e limpe-o depois.

Última atualização a 12 de outubro de 2026