API (OpenAPI)

Se o seu sistema tem uma API REST, você conecta ela enviando o arquivo que a descreve — o OpenAPI (antigo Swagger). A plataforma lê o arquivo, descobre os endpoints e sabe como chamar cada um: parâmetros, paginação e onde ficam os registros na resposta.

No workspace Aurora Energia, o conector ERP Aurora Energia é uma API assim: dele vêm as faturas, as notas fiscais e as unidades consumidoras do portal.

Conectar uma API

1. Em Dados › Conectores, clique em Conectar fonte e abra a aba API.

2. Preencha os campos:

   Campo	O que informar
   Nome do conector	Um nome para reconhecer a fonte, como ERP Aurora Energia. Ao enviar a spec, o nome do arquivo já vem como sugestão
   OpenAPI spec	O arquivo openapi.json ou .yaml — versões 2.0 ou 3.x, até 5 MB
   Base URL	O endereço da API, como https://erp.auroraenergia.com.br/api/v2. Se a spec declara um servidor, ele já vem preenchido
   Formato da resposta	JSON ou XML
   Tipo de autenticação	Como a API confere quem está chamando (veja abaixo)

3. Clique em Testar conexão para conferir.

4. Clique em Conectar e sincronizar.

Assim que você escolhe o arquivo, a tela mostra o que foi encontrado: o formato, a versão do OpenAPI e quantas operações há (e quantas são de leitura). Avisos sobre a spec aparecem logo abaixo.

Autenticação

A plataforma sugere o tipo de autenticação a partir da spec. Você pode trocar:

Tipo	Como funciona
Sem autenticação	A API é aberta
Header (API key)	Um ou mais headers com a chave, como X-Api-Key. Use Adicionar header para incluir outros
Query string	A chave vai como parâmetro na URL. Use Adicionar parâmetro para incluir outros
Bearer token	O token vai no header Authorization: Bearer …
Basic auth	Usuário e senha
Certificado (mTLS)	Um certificado do cliente (.pfx, .p12 ou .pem) e a senha dele, quando houver

As credenciais são cifradas e nunca voltam para a tela.

Testar a conexão

O teste chama um endpoint de leitura que não precisa de parâmetros (pedindo um só registro, quando ele pagina) e confere se a API responde, aceita as credenciais e devolve os registros onde a spec diz. Se a spec não tem um endpoint assim, o teste só confere se a Base URL responde.

Endpoints

Na página do conector, a aba Endpoints lista as operações da API:

Coluna	O que mostra
Nome	O nome da operação, como Listar faturas. Operações marcadas como desativada ou obsoleta não aparecem na hora de criar entidades
Origem	O método e o caminho, como GET /faturas
Acesso	Leitura ou Escrita
Incremental	Se o endpoint aceita um filtro de "alterado desde" — assim a sincronização lê só o que mudou

Os endpoints de leitura são os que viram entidades: clique em Criar entidade ao lado de um deles. No ERP Aurora Energia, Listar faturas (GET /faturas) virou a entidade Fatura; Solicitar religação (POST /unidades/{id}/religacao) é de escrita e não vira entidade.

Trocar a spec

Quando a API muda, abra o conector, clique em Editar e envie o arquivo novo em OpenAPI spec. Os endpoints são lidos de novo, e os que têm a mesma chave mantêm as configurações. Em Editar você também troca a Base URL, o formato da resposta e a autenticação.

Produtos do catálogo Kobana

Para os produtos Kobana, a spec já vem pronta. Na aba Catálogo de Conectar fonte:

1. Clique em Conectar no produto: Financeiro Inteligente, Faturamento Automático, Régua de Cobrança ou Gateway Bancário.
2. Escolha o Ambiente: Produção ou Sandbox.
3. Cole o Token de acesso (a tela diz onde emitir o token de cada produto).
4. No Financeiro Inteligente, informe o ID do workspace só se a organização tiver mais de um.
5. Clique em Conectar com o nome do produto.

As operações do produto são importadas, e o conector aparece na lista com o tipo Catálogo Kobana. Um produto já conectado mostra o botão Outro ambiente, para conectar também o sandbox (ou a produção).

Próximos passos

• Crie as entidades a partir dos endpoints de leitura.
• Defina de quanto em quanto tempo o conector sincroniza.