Documentación API Veredata

Empecemos

Para realizar solicitudes, tienes que autenticar con las credenciales de tu usuario de sistema. Si aún no tienes una, consulta los pasos básicos para comenzar a implementar nuestra solución.

Autenticación

Para conectar la integración y tu cuenta de una manera segura, tienes que realizar todas las solicitudes a nuestra API utilizando HTTPS e incluir las credenciales de tu aplicación para autenticar cada interacción.

cURL ejemplo


curl -X POST \
  'https://apivd.veredata.co/v1' \
  -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Crear usuario

Para el uso del API se debe contar con un usuario de sistema dentro de la aplicación de VereData.

Pasos para la creación de un usuario de sistema:

Iniciar sesión en la aplicación.
En el menú de la aplicación, en la parte izquierda, ir a seguiridad -> Usuarios y dar clic en el botón Crear Usuario.
Ingresar la información del formulario y activar la opción ¿Usuario de sistema?
Importante: Un usuario de sistema no se puede conectar a la aplicación.
Al activar la opción ¿Usuario de sistema?, se habilitan dos campos adicionales. Contraseña y Repetir Contraseña.
Importante: Ambas contraseñas deben coincidir.
Cuando se termine de ingresar la información, dar clic en el botón Guardar. Si toda la información es correcta, se descargará un archivo CSV con información sensible del usuario como Api key y refresh token.

¡Importante!

Este archivo solo se genera una vez. No se padrá descargar desde la aplicación. ¡Guardarlo en un lugar seguro!

Nunca expongas tu clave privada en un repositorio público, ni la utilices en tu código. Siempre hazlo de manera segura desde tu servidor.

Refrescar token y crear un nuevo refresh token

Actualizar el token y crear un nuevo refresh token necesario para consumir el API.

Refrescar token

POST


curl -X POST \
  'https://apivd.veredata.co/v1' \
  -H 'x-api-key: $API_KEY' \
  -H 'Content-Type: application/json'
  -d '{
    "refresh_token": "$REFRESH_TOKEN"
  }'

$API_KEY: Información disponible en el archivo descargado al crear el usuario de sistema.
$REFRESH_TOKEN: Información disponible en el archivo descargado al crear el usuario de sistema.

Respuesta


{
  "uid": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "token": "XXXXXXXXXX.XXXXXXXXXX.XXXXXXXXXX",
  "refresh_token": "XXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXX_XXXXXXXXXX",
  "expires_in": "3600"
}

uid: Número de identificación generado automáticamente al crear un usuario de sistema.
token: Código de seguridad que identifica al usuario y acceder a los recursos protegidos. Su validez está determinada por el parámetro expires_in.
refresh_token: Código de seguridad utilizado para obtener tokens y el acceso a los recursos y sigan siendo válidos antes del final del período de validez del token.
expires_in: Tiempo de caducidad del token expresado en segundos. De forma predeterminada, el tiempo de caducidad es de 1 hora (3600 segundos).

Errores

400 (bad_request): No se puede o no se procesará la solicitud debido a un error del cliente.
- API key invalido o no enviado en el header de la petición.
- refresh_token invalido o no enviado en el body de la petición.

Crear un nuevo refresh token

POST

VereData API permite crear un nuevo refresh_token en caso de perdida. Esta petición se realiza enviando en el body el correo electrónico y contraseña.


curl -X POST \
  'https://apivd.veredata.co/v1' \
  -H 'x-api-key: $API_KEY' \
  -H 'Content-Type: application/json'
  -d '{
    "username": "$USERNAME",
    "password": "$PASSWORD"
  }'

$API_KEY: Información disponible en el archivo descargado al crear el usuario de sistema.
$USERNAME: Corre electrónico del usuario de sistema.
$PASSWORD: Contraseña del usuario de sistema.

Respuesta


{
  "uid": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "token": "XXXXXXXXXX.XXXXXXXXXX.XXXXXXXXXX",
  "refresh_token": "XXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXX_XXXXXXXXXX",
  "expires_in": "3600"
}

uid: Número de identificación generado automáticamente al crear un usuario de sistema.
token: Código de seguridad que identifica al usuario y acceder a los recursos protegidos. Su validez está determinada por el parámetro expires_in.
refresh_token: Código de seguridad utilizado para obtener tokens y el acceso a los recursos y sigan siendo válidos antes del final del período de validez del token.
expires_in: Tiempo de caducidad del token expresado en segundos. De forma predeterminada, el tiempo de caducidad es de 1 hora (3600 segundos).

Errores

400 (bad_request): No se puede o no se procesará la solicitud debido a un error del cliente.
- API key invalido o no enviado en el header de la petición.
- username o password invalidos o no enviados en el body de la petición.

Scoring

POST

Scoring permite consultar el puntaje de un municipio o vereda creado por veredata y el cliente. La búsqueda del puntaje se puede realizar por:

Latitud y Longitud.
Código de vereda.
Nombre de departamento y municipio.
Código dane del municipio.


curl -X POST \
  'https://apivd.veredata.co/v1/scoring' \
  -H 'Authorization: $ACCESS_TOKEN' \
  -H 'Content-Type: application/json'
  -d '{
    "municipio_codigo_dane": $MUNICIPIO_DANE,
    "score_version": $SCORE_VERSION
  }'

$MUNICIPIO_DANE: Código dane del municipio.
$SCORE_VERSION: Versión del score.

Respuesta


{
  "score": X.XXXX
}

score: Puntación del municipio consultado.

Errores

400 (bad_request): No se puede o no se procesará la solicitud debido a un error del cliente.
- municipio código dane invalidos o no enviados en el body de la petición.
- Versión invalido o no enviado en el body de la petición.
401 (Unauthorized): Error del lado del cliente. Indica que el servidor espera en el header el token.

Históricos

POST

Históricos permite consultar todo el historial de los datos (modelos) con los que cuenta VereData. La búsqueda del historial se puede realizar por:

Latitud y Longitud.
Código de vereda.
Nombre de departamento y municipio.
Código dane del municipio.


curl -X POST \
  'https://apivd.veredata.co/v1/historic' \
  -H 'Authorization: $ACCESS_TOKEN' \
  -H 'Content-Type: application/json'
  -d '{
    "municipio_codigo_dane": $MUNICIPIO_DANE,
    "numero_datos": $NUMERO_DATOS,
    "datos": [
      {
        "modelo": "$MODELO",
        "variable": "$VARIABLE"
      }
    ]
  }'

$MUNICIPIO_DANE: Código dane del municipio.
$NUMERO_DATOS (opcional): Cantidad de datos a recuperar. Por defecto se recuperán 10 datos.
$MODELO: Nombre del modelo.
$VARIABLE: Nombre de la variable.

Respuesta

La petición devuelve un arregelo por cada modelo/variable.


[
  {
      "modelo": "XXXXXXXXXX",
      "variable": "XXXXXXXXXX",
      "datos": [],
      "periodo": []
  }
]

modelo: Nombre del modelo.
variable: Nombre de la variable.
datos: Entrega la información en un arraglo.
periodo: La respuesta puede ser en estos tres (3) formatos: YYYY, YYYYMM, YYYYMMDD. También se entrega en un arregelo.

Errores

400 (bad_request): No se puede o no se procesará la solicitud debido a un error del cliente.
- municipio código dane invalidos o no enviados en el body de la petición.
- datos arraglo de modelo/variable invalido o no enviado en el body de la petición.
401 (Unauthorized): Error del lado del cliente. Indica que el servidor espera en el header el token.

Mapas

POST

Mapas permite consultar información geográfica de Colombia (Municipio/Vereda/Logintud y Latitud).

  
  curl -X POST \
    'https://apivd.veredata.co/v1/maps' \
    -H 'Authorization: $ACCESS_TOKEN' \
    -H 'Content-Type: application/json'
    -d '{
      "municipio_codigo_dane": $MUNICIPIO_DANE,
      "capas": [
        $CAPA
      ]
    }'

$MUNICIPIO_DANE: Código dane del municipio.
$CAPA:Nombre de las capas (modelos). Esta variable es tipo arreglo y se debe enviar separado por coma.

Respuesta

La petición devuelve un arregelo por cada capa.

  
  [
    {
        "capa": "XXXXXXXXXX",
        "nombre_capa": "XXXXXXXXXX XXXXXXXXXX",
        "color": "XXXXX",
        "geo_json": []
    }
  ]

capa: Nombre de la capa (modelo).
nombre_capa: Nombre legible de la capa.
color: Color en formator hexadecimal para pintar la capa.
geo_json: Arreglo con la información geográfica.

Errores

400 (bad_request): No se puede o no se procesará la solicitud debido a un error del cliente.
- municipio código dane invalidos o no enviados en el body de la petición.
- capa arraglo de capas invalido o no enviado en el body de la petición.
401 (Unauthorized): Error del lado del cliente. Indica que el servidor espera en el header el token.

Empecemos

Autenticación

cURL ejemplo

Crear usuario

Pasos para la creación de un usuario de sistema:

¡Importante!

Refrescar token y crear un nuevo refresh token

Refrescar token

Respuesta

Errores

Crear un nuevo refresh token

Respuesta

Errores

Scoring

Respuesta

Errores

Históricos

Respuesta

Errores

Mapas

Respuesta

Errores