Importar datos desde una API externa

Este artículo describe cómo utilizar la función de Importador para importar datos desde una Interfaz de Programación de Aplicaciones (API) externa, y especifica los requisitos de formato de la API.

Para seguir este proceso, necesita tener los siguientes roles y permisos:

• Permiso para añadir registros al Formulario de destino
• Permiso para Editar registros si está actualizando Registros existentes
• Permiso para añadir Formularios, carpetas e informes (para poder diseñar el Formulario, si necesita un Formulario nuevo)

Formato de datos de origen admitido

• La API debe proporcionar una respuesta en formato JSON
• La respuesta JSON debe contener una matriz de objetos JSON, por ejemplo:

[
  { "name": "North Kivu", "code": "RD001" },
  { "name": "South Kivu", "code": "RD002" },
  { "name": "Ituri", "code": "RD003" }
]

• Se admiten objetos anidados, por lo que el siguiente ejemplo sería correcto:

{ "status": "OK",
  "data": 
    [  
      { "name": "North Kivu", "code": "RD001" },
      { "name": "South Kivu", "code": "RD002" }, 
      { "name": "Ituri", "code": "RD003" }
    ]
}

• Los nombres de los Campos deben ser consistentes, por lo que el siguiente ejemplo no funcionaría:

[
  { "location": "North Kivu" },
  { "loc": "South Kivu" },
  { "Location": "Ituri" }
]

• El punto final de la API debe admitir solicitudes HTTP GET

• Si la API no es pública, se admiten dos tipos de encabezados de Authorization:

• Autenticación de acceso básica: un nombre de usuario y una contraseña en codificación Base64

• Token de portador (Bearer token): un único token secreto. ActivityInfo enviará el encabezado de Autorización en el formato “Bearer ” como parte de la solicitud

• Accesible a través de HTTPS

Importar datos desde una API

Para importar datos desde una API utilizando la función de Importador, siga estos pasos:

1. Compruebe si cumple los prerrequisitos:

• Tener una cuenta de ActivityInfo
• Acceso al Formulario
• Permisos apropiados

2. Cree un Formulario en el que vaya a importar los datos. Es importante definir la estructura del Formulario antes de importar los datos.
   Si ya tiene un Formulario, navegue a su vista de Tabla.
3. Seleccione la herramienta “Importar” en la Barra de herramientas.

4. Haga clic en “Desde API”.

5. Configure la importación de la API rellenando los siguientes campos:

• URL de la API: pegue el enlace aquí. Solo se admiten protocolos seguros (https).
• Seleccione el método de autenticación, dependiendo del servicio externo: “Ninguno” para una API pública, por ejemplo; “Token de portador” o “Autenticación básica”. Consulte la documentación de la API que está utilizando para determinar qué método de autenticación se admite.

6. Haga clic en “Continuar” y espere a que se carguen los datos.
7. Seleccione la ruta de datos en la ventana de Vista previa de datos. Si la API no proporciona una matriz de objetos directamente, entonces necesita elegir una ruta a la matriz para importar.
   En este ejemplo, seleccione “data” como la ruta de consulta de la API.

Si tiene varias rutas de datos disponibles en la lista desplegable, entonces necesita determinar qué parte de la respuesta quiere importar.
En este ejemplo, puede ver que hay dos matrices de objetos (“provinces” y “changes”) en la respuesta de la API:

{
  "status": "OK",
  "provinces": [
    {
      "name": "North Kivu",
      "code": "RD001"
    },
    {
      "name": "South Kivu",
      "code": "RD002"
    }
  ],
  "changes": [
    { 
      "date": "2025-01-01",
      "version": 1
    },
    {
      "date": "2025-03-02",
      "version": 2
    }
  ]
}

No puede importar ambas matrices al mismo tiempo, necesita elegir una ruta de datos de la lista desplegable.

7. Haga clic en “Continuar” y espere a que se carguen los Registros.

8. Es hora de hacer coincidir las columnas y validar los Campos, haciendo clic en cada columna resaltada para resolver los problemas. Para más información, consulte Solución de problemas relacionados con el importador.
   En este paso, puede usar filtros para limitar los datos que quiere importar.

El filtrado no está disponible en los valores de Campos de referencia múltiple ni en los Campos no asignados. No se admite la asignación de Campos de destino.

Consejo: Puede configurar un Campo oculto con un valor predeterminado en su Formulario para habilitar el filtrado en el Campo de origen no asignado. De esta manera, el Campo no asignado se convierte en un Campo asignado.

9. Después de resolver las inconsistencias, haga clic en “Continuar” en la esquina superior derecha.
10. Los usuarios con el permiso “Gestionar configuraciones de importación” pueden optar por guardar esta configuración de importación para importaciones de datos repetidas, y compartirla con otros usuarios de la Base de datos. Las configuraciones guardadas no se ejecutan automáticamente.

La opción de configuración guardada incluye los siguientes aspectos:

• Origen de la importación (“Desde API” en este caso)
• URL de la API, autorización, ruta de datos
• Coincidencia de Campos, incluyendo valores constantes
• Filtros, si se aplican
• Las credenciales se almacenan, si utiliza la autenticación en el paso. Aunque las credenciales no son visibles para otros usuarios, tenga en cuenta que cualquier persona con el permiso de gestionar configuraciones de importación podrá utilizar las credenciales almacenadas para volver a ejecutar la importación en el futuro.

11. Revise el resumen de la importación:

• Si todo es correcto, proceda al siguiente paso.
• Si necesita empezar de nuevo, haga clic en “Cancelar”.
• Para volver a la parte del proceso de coincidencia de columnas y validación de Campos, haga clic en “Atrás”.
• Active el interruptor “Guardar configuración” para guardar esta configuración de importación, y haga clic en “Continuar” en la ventana emergente.

12. En caso de que esté guardando la configuración, escriba una etiqueta para la configuración guardada, y luego haga clic en “Guardar e importar registros” en la esquina superior derecha.

13. Si no está guardando una configuración personalizada, haga clic en “Importar registros” en la esquina superior derecha y espere a que se carguen las actualizaciones.