Saltar al contenido principal

API (OpenAPI)

Si tu sistema tiene una API REST, la conectas subiendo el archivo que la describe — el OpenAPI (antes Swagger). La plataforma lee el archivo, descubre los endpoints y sabe cómo llamar a cada uno: parámetros, paginación y dónde están los registros en la respuesta.

En el workspace Aurora Energia, el conector ERP Aurora Energia es una API así: de él vienen las facturas, las notas fiscales y las unidades consumidoras del portal.

Conectar una API​

  1. En Datos › Conectores, haz clic en Conectar fuente y abre la pestaña API.

  2. Completa los campos:

    CampoQué informar
    Nombre del conectorUn nombre para reconocer la fuente, como ERP Aurora Energia. Al subir la spec, el nombre del archivo ya viene como sugerencia
    OpenAPI specEl archivo openapi.json o .yaml — versiones 2.0 o 3.x, hasta 5 MB
    Base URLLa dirección de la API, como https://erp.auroraenergia.com.br/api/v2. Si la spec declara un servidor, ya viene completada
    Formato de la respuestaJSON o XML
    Tipo de autenticaciónCómo la API verifica quién está llamando (consulta abajo)

  3. Haz clic en Probar conexión para verificar.

  4. Haz clic en Conectar y sincronizar.

En cuanto eliges el archivo, la pantalla muestra lo que se encontró: el formato, la versión de OpenAPI y cuántas operaciones hay (y cuántas son de lectura). Los avisos sobre la spec aparecen justo debajo.

Autenticación​

La plataforma sugiere el tipo de autenticación a partir de la spec. Puedes cambiarlo:

TipoCómo funciona
Sin autenticaciónLa API es abierta
Header (API key)Uno o más headers con la clave, como X-Api-Key. Usa Agregar header para incluir otros
Query stringLa clave va como parámetro en la URL. Usa Agregar parámetro para incluir otros
Bearer tokenEl token va en el header Authorization: Bearer …
Basic authUsuario y contraseña
Certificado (mTLS)Un certificado del cliente (.pfx, .p12 o .pem) y su contraseña, cuando la haya

Las credenciales se cifran y nunca vuelven a la pantalla.

Probar la conexión​

La prueba llama a un endpoint de lectura que no necesita parámetros (pidiendo un solo registro, cuando pagina) y verifica que la API responda, acepte las credenciales y devuelva los registros donde la spec indica. Si la spec no tiene un endpoint así, la prueba solo verifica que la Base URL responda.

Endpoints​

En la página del conector, la pestaña Endpoints lista las operaciones de la API:

Conector de API (OpenAPI) activo, con operaciones y sincronizaciones

ColumnaQué muestra
NombreEl nombre de la operación, como Listar facturas. Las operaciones marcadas como desactivada u obsoleta no aparecen al crear entidades
OrigenEl método y la ruta, como GET /faturas
AccesoLectura o Escritura
IncrementalSi el endpoint acepta un filtro de "modificado desde" — así la sincronización lee solo lo que cambió

Los endpoints de lectura son los que se convierten en entidades: haz clic en Crear entidad junto a uno de ellos. En ERP Aurora Energia, Listar facturas (GET /faturas) se convirtió en la entidad Fatura; Solicitar reconexión (POST /unidades/{id}/religacao) es de escritura y no se convierte en entidad.

Cambiar la spec​

Cuando la API cambia, abre el conector, haz clic en Editar y sube el archivo nuevo en OpenAPI spec. Los endpoints se leen de nuevo, y los que tienen la misma clave mantienen sus configuraciones. En Editar también cambias la Base URL, el formato de la respuesta y la autenticación.

Productos del catálogo Kobana​

Para los productos Kobana, la spec ya viene lista. En la pestaña Catálogo de Conectar fuente:

  1. Haz clic en Conectar en el producto: Financeiro Inteligente, Faturamento Automático, Régua de Cobrança o Gateway Bancário.
  2. Elige el Entorno: Producción o Sandbox.
  3. Pega el Token de acceso (la pantalla indica dónde emitir el token de cada producto).
  4. En Financeiro Inteligente, informa el ID del workspace solo si la organización tiene más de uno.
  5. Haz clic en Conectar con el nombre del producto.

Las operaciones del producto se importan, y el conector aparece en la lista con el tipo Catálogo Kobana. Un producto ya conectado muestra el botón Otro entorno, para conectar también el sandbox (o la producción).

Próximos pasos​