Saltar al contenido principal

Spots

Ver en Git

Spots

Spots es la nueva versión de zonas de gestión.El mismo se basa en una modalidad API REST y para identificar cada recurso se utilizan uuids en vez de ids para poder crearlos desde la app en modo offline

UUID_PATTERN = ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[1][0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$

Descargar Collección de Postman V 1.1

Changelog​

15 de Enero de 2025:​

Se le agregó la posibilidad de generar tags y variables a nivel de espacio (antes era solo a nivel de usuario que es el default en esta nueva version).

Para generar un tag o una variable a nivel de espacio no hay más que hacer que pasarle el parámetro "scope" con el valor "user" o "workspace" en el JSON con el que se genera la variable, el tag o el spot.

La posibilidad de generar tanto variables como tags a nivel de espacio está controlada por una funcionalidad/permiso para cada caso, según corresponde:

Código de PermisoPermiso
1101Crear tag de marcador a nivel de espacio
1102Crear variable de marcador a nivel de espacio
1103Borrar tag de marcador a nivel de espacio
1104Borrar variable de marcador a nivel de espacio

También se modificó a la API getSpots (en particular con el método POST) que antiguamente permitía filtrar spots de a un tag (con el parámetro "tag_uuid". Ahora se le agregó un parámetro "tag_uuids" que recibe un arreglo de uuids de tags y devuelve los spots que contienen dichos tags.

Errores generales​

Además de los códigos de error comunes a todo aurapi (code < 0), todos los endpoints y métodos que se listan debajo utilizan ciertos códigos de error para indicar errores comunes.

- {'code': 1, 'info': 'Parameter missing'}
- {'code': 2, 'info': 'Parameter missmatch'}
- {'code': 3, 'info': 'No results'}

- {'code': 10, 'info': 'No tiene permisos para ver zonas de gestion'}
- {'code': 11, 'info': 'No tiene permisos para crear la zona de gestion'}
- {'code': 12, 'info': 'No tiene permisos para modificar la zona de gestion'}
- {'code': 13, 'info': 'No tiene permisos para eliminar la zona de gestion'}

- {'code': 10, 'info': 'No tiene permisos para ver comentarios de zonas de gestion'}
- {'code': 11, 'info': 'No tiene permisos para crear comentarios de zonas de gestion'}
- {'code': 12, 'info': 'No tiene permisos para modificar comentarios de zonas de gestion'}
- {'code': 13, 'info': 'No tiene permisos para eliminar comentarios de zonas de gestion'}

Además cada endpoint particular puede tener errores ad-hoc, cuyos códigos son > 50 y éstos se indican en su sección.

Spots​

/api/spots/spot

POST​

  • Si el uuid no se envía, se genera uno.
  • DEPRECATEDag_id corresponde a la vieja versión de este endpoint, por lo que se aconseja no utilizarlo más. Utilizar tags en cambio.
  • Para asociar tags al Spot por crear, los objetos enviados en tags pueden exixtir o no:
    • Si se envía solo el uuid, se busca un tag existente que no haya sido eliminado
    • Si se envía uuid y tag se creará, si es que no existe.
    • Si se envía sólo tag, se creará el tag, generarándose el uuid.
    • Se puede enviar la variable "scope" = "user" | "workspace" para generar el tag a nivel usuario o a nivel espacio
  • El objecto de data puede incluir las variables (###PATCH-2). Si alguna de las incluídas no tiene un unit_id válido, se saltea.
  • Las variables también aceptan un atributo scope para generar las variables a nivel de usuario o a nivel de workspace
{
    "type": "object",
    "properties": {
        "uuid": {"type": "string",
                 "pattern": UUID_PATTERN,
                 "description": "UUID v1 to set as map spot reference"},
        "field_id": {"type": "integer", "minimum": 0,
                     "description": "Id of the field where the map spot is being created (required)"},
        "name": {"type": "string", "description": "Name (title) of the map spot (required)"},
        "shape": {"type": "string",
                  "description": "WKT of POINT or POLYGON type that defines "
                                 "the shape of the map spot (required)"},
        "tag_id": {"type": "integer", "minimum": 0,
                   "description": "id of the tag to be associated with (required)"},
        "tags": {"type": "array",
                 "items": {"type": "object",
                        "properties": {'uuid': {"type": "string", "pattern": UUID_PATTERN},
                                        'tag': {"type": "string"}
                                        'scope': {"type": "string", "enum":["user","woskspace"]}
}},
                 "description": "array of objects with uuids/names of the tags to be associated with (required). if uuid is not sent, tag will be created"},

        "group_uuid": {"type": "string",
                       "pattern": UUID_PATTERN,
                       "description": "UUID v1 to set as group identifier of the map spot"},

        "texts": {
            "description": "array of objects that define texts in the chat-like area of map spots",
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "uuid": {"type": "string",
                             "pattern": UUID_PATTERN,
                             "description": "UUID v1 to set as msg identifier"},
                    "text": {"type": "string", "description": "text of the chat-like post"},
                    "timestamp_usr": {"type": "string", "format": "date-time",
                                      "description": "user defined timestamp of the chat-like post. Must be "
                                                     "in local time and format YYYY-MM-DDTHH:MM:SSZ"},
                    "imgs": {
                        "description": "array with image identifiers and coordinates. "
                                       "Images must be uploaded by means of the /spots/text put method",
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "coordinate": {"type": "string",
                                               "description": "POINT type WKT indicating the "
                                                              "GPS coordinate of the image"},
                                "uuid": {"type": "string",
                                         "description": "UUID v1 reference of the image to state in "
                                                        "the /spots/text put method when uploading"}
                            }
                        },
                        "required": ['coordinate', 'uuid']
                    }
                }
            }
        },

        "sample_set": {
            "type": "object",
            "properties": {
                "sample_set_type": {"type": "string",
                                    "description": "type of sample to be linked to the map spot"},
                "sample_set_uuid": {"type": "string",
                                    "pattern": UUID_PATTERN,
                                    "description": "UUID v1 of the sample to be linked to the map spot"}
            },
            "required": ["sample_set_type", "sample_set_uuid"]

        },

        "data": {
            "type": "object",
            "properties": {
                "variables": {"type": "array",
                              "items": {
                                    "type": "object",
                                    "properties": {"name": {"type": "string"},
                                                    "unit_id": {"type": "integer",
                                                                "minimum": 0},
                                                    "value": {"type": "number"},
                                                    "scope": {"type": "string", "enum":["user","woskspace"]}
}},
                                    "additionalProperties": False}
                            }
        }

    },
    "required": ["field_id", "shape"]
}

GET​

Parámetros en la query string. Los 10 parámetros son opcionales, aplicándose como condición AND a todas las zonas de gestión del usuario. Si no se envía ningún parámetro, se buscan todas.

Si no se incluye ninguna condición de "sample_set", sólo se buscan las zonas de gestión que no corresponden a muestras (Ej monitoreos,rinde)

Además, page_size y page permite aplicar un LIMIT page_size OFFSET page a todas las zonas de gestión. La respuesta incluye un parámetro bool continues que indica si hay más páginas para buscar.

Se ordenan por fecha de creación, listando primero las más recientes.

  • code: el código del spot. Puede ser incompleto, es decir, la primera parte, la última o algo del medio.
  • uuid: un uuid de spot, o varios separados por coma
  • group_uuid
  • farm_id
  • field_id
  • sample_set_type_id
  • sample_set_type
  • sample_set_uuid
  • date_from en formato YYYY-MM-DDTHH:MM:SSZ
  • date_to en formato YYYY-MM-DDTHH:MM:SSZ
  • tag_uuid: uuid de un tag. Se buscarán los Spots que tengan esta tag asociada.
  • page_size: default 50 - seteandolo en -1, se traen todas
  • page: default 0

PATCH​

Se actualizarán sólo los parámetros que se envíen, reemplazando los actuales.

  • tag_id corresponde a la vieja versión de este endpoint, por lo que se aconseja no utilizarlo más. Utilizar tags en cambio.
  • Para asociar tags al Spot, los objetos enviados en tags pueden exixtir o no:
    • Si se envía solo el uuid, se busca un tag existente que no haya sido eliminado.
    • Si se envía uuid y tag se creará, si es que no existe.
    • Si se envía sólo tag, se creará el tag, generarándose el uuid.
{
    "type": "object",
    "properties": {
        "uuid": {"type": "string",
                 "pattern": UUID_PATTERN,
                 "description": "UUID v4 to set as map spot reference"},
        "name": {"type": "string", "description": "Name (title) of the map spot (required)"},
        "shape": {"type": "string",
                  "description": "WKT of POINT or POLYGON type that defines the shape of the map spot ("
                                 "required)"},
        "tag_id": {"type": "integer", "minimum": 0,
                   "description": "id of the tag to be associated with (required)"},
        "tags": {"type": "array",
                 "items": {"type": "object",
                        "properties": {'uuid': {"type": "string", "pattern": UUID_PATTERN},
                                        'tag': {"type": "string"}}},
                 "description": "array of objects with uuids/names of the tags to be associated with (required). if uuid is not sent, tag will be created"},
                 
        "group_uuid": {"type": "string",
                       "pattern": UUID_PATTERN,
                       "description": "UUID v1 to set as group identifier of the map spot"},
        "sample_set": {
            "type": "object",
            "properties": {
                "sample_set_type": {"type": "string",
                                    "description": "type of sample to be linked to the map spot"},
                "sample_set_uuid": {"type": "string",
                                    "pattern": UUID_PATTERN,
                                    "description": "UUID v1 of the sample to be linked to the map spot"}
            },
            "required": ["sample_set_type", "sample_set_uuid"]
        },
        "data": {
            "type": "object"
        }
    }
}

DELETE​

En la query string se incluye el parámetro uuid con el uuid de la zona de gestión a eliminar.

GET SPOTS​

POST​

POST /api/spots/getspot

Este endpoint se utiliza para hacer el GET SPOTS desde la App.

Los 9 parámetros son opcionales, aplicándose como condición AND a todas las zonas de gestión del usuario. Si no se envía ningún parámetro, se buscan todas.

Si no se incluye ninguna condición de "sample_set", sólo se buscan las zonas de gestión que no corresponden a muestras (Ej monitoreos,rinde)

Además, page_size y page permiten paginar las zonas de gestión que cumplen los filtros indicados.

  • page_size: default 50 - seteandolo en -1, se traen todas
  • page: default 0

La respuesta incluye un parámetro bool continues que indica si hay más páginas para buscar.

Se ordenan por fecha de creación, listando primero las más recientes.

{
    "type": "object",
    "properties": {
        "uuid": {
            "type": "array",
            "items": {"type": "string",
                      "pattern": UUID_PATTERN,
                      "description": "..."}
        },
        "group_uuid": {
            "type": "array",
            "items": {"type": "string",
                      "pattern": UUID_PATTERN,
                      "description": "..."}
        },

        "sample_set_uuid": {
            "type": "array",
            "items": {"type": "string",
                      "pattern": UUID_PATTERN,
                      "description": "..."}
        },

        "field_id": {"type": "integer",
                     "minimum": 0,
                     "description": "..."},

        "farm_id": {"type": "integer",
                    "minimum": 0,
                    "description": "..."},

        "sample_set_type_id": {"type": "integer",
                               "minimum": 0,
                               "description": "..."},

        "sample_set_type": {"type": "string",
                            "description": "..."},

        "date_from": {"type": "string", "format": "date-time",
                      "description": "filter spots by creation date. format: YYYY-MM-DDTHH:MM:SSZ"},
        "date_to": {"type": "string", "format": "date-time",
                    "description": "filter spots by creation date. format: YYYY-MM-DDTHH:MM:SSZ"},

        "tag_uuid": {"type": "string",
                     "pattern": UUID_PATTERN,
                     "description": "get spots that have this tag"},
        "tag_uuids": {
                    "type": "array",
                    "items": {
                        "type": "string",
                        "pattern": UUID_PATTERN,
                    },
                    "description": "get spots that have these tags",
                },
        "page_size": {"type": "integer", "minimum": -1, "description": "..."},
        "page": {"type": "integer", "minimum": 0, "description": "..."}
    }
}

POST /api/spots/all

Este endpoint es exactamente igual al anterior, con la diferencia que en la respuesta, dentro de cada zona de gestión, se incluyen los mensajes y imágenes de cada una. La paginación aplica sólo a las zonas de gestión.

MESSAGES​

/api/spots/msgs

POST​

{
    'type': 'object',
    'properties': {
        'uuid': {'type': 'string',
                 'pattern': UUID_PATTERN,
                 'description': 'UUID v1 of the spot to which msg belongs'},
        'texts': {
            'description': 'array of objects that define texts in the chat-like area of map spots',
            'type': 'array',
            'items': {
                'type': 'object',
                'properties': {
                    'uuid': {'type': 'string',
                             'pattern': UUID_PATTERN,
                             'description': 'UUID v1 of the msg'},
                    'text': {'type': 'string', 'description': 'text of the chat-like post'},
                    'timestamp_usr': {'type': 'string', 'format': 'date-time',
                                      'description': 'user defined timestamp of the chat-like post. Must be '
                                                     'in local time and format YYYY-MM-DDTHH:MM:SS'},
                    'imgs': {
                        'description': 'array with image identifiers and coordinates. '
                                       'Images must be uploaded by means of the /spots/text put method',
                        'type': 'array',
                        'items': {
                            'type': 'object',
                            'properties': {
                                'coordinate': {'type': 'string',
                                               'description': 'POINT type WKT indicating the '
                                                              'GPS coordinate of the image'},
                                'uuid': {'type': 'string',
                                         'pattern': UUID_PATTERN,
                                         'description': 'UUID v1 reference of the image to state in '
                                                        'the /spots/imgs put method when uploading'}
                            },
                            'required': ['uuid', 'coordinate']
                        }
                    }
                }
            }
        },
    },
    'required': ['uuid', 'texts']
}

GET​

Parámetros en la query string. Se envía el uuid de la zona de gestión de la cual se quieren obtener los mensajes.

page_size y page permiten paginar los mensajes. La respuesta incluye un parámetro bool continues que indica si hay más páginas para buscar.

Se ordenan por fecha de creación, listando primero las más recientes.

  • uuid: uuid de la zona de gestión de la cual se quieren obtener los mensajes
  • page_size: default 20 - seteandolo en -1, se traen todas
  • page: default 0

DELETE​

En la query string se incluye el parámetro uuid con el uuid del comentario a eliminar.

También se eliminan las imagenes asociadas, en caso de haberlas.

IMAGES​

/api/spots/msgs/imgs

PUT​

Subida de una imagen que haya sido previamente declarada.

Se debe incluir uuid en la query string con el uuid de la imagen a subir.

NOTA: El archivo debe ir adjunto en la request bajo el nombre img.

Errores​

  • Si hubo un error al guardar la imagen. {'code': 51, 'info': 'image could not be stored'}

GET​

Descargar una imagen que haya sido previamente subida.

Se debe incluir uuid en la query string con el uuid de la imagen a descargar. Alternativamente, se puede incluir el uuid en el path. Ej: /api/spots/msgs/imgs/<uuid>

Errores​

  • Si la imagen no se encuentra. {'code': 404, 'info': 'File not found'}

Tags​

/api/spots/tags

POST​

Cada tag se representa con un objeto que puede tener 2 keys: 'tag' y 'uuid'. Se pueden crear Tags de 2 maneras:

  • Enviando objetos con sólo la key tag: Se creará la tag, generando su correspondiente uuid
  • Enviando objetos con la key tag y uuid: Se creará la tag utilizando tag como nombre y el uuid enviado
  • Se puede setear el parametro "scope" = "user" | "workspace" para que el tag se genere a nivel de usuario o a nivel de espacio

Si el uuid ya existe, se ignora la tag enviada, independientemente si la tag fue previamente borrada o no.

{
    'type': 'object',
    'properties': {
        'uuid': {'oneOf': [{'type': 'string', 'pattern': UUID_PATTERN,
                            'description': 'UUID v1 of the spot to which msg belongs'},
                           {'type': 'null'}]},
        'tag': {'type': 'string',
                'description': 'the name of the tag'},
        'scope': {"type": "string", "enum":["user","woskspace"]}
    },
    'required': ['tag'],
    'additionalProperties': False
}

GET​

Por default, se buscan tanto las tags generales como las creadas por el usuario que hace la request.

Se pueden incluir parámetros en la query string para evitar algún tipo. Cualquier valor distinto de false, se defaultea a true

  • general=false: no se buscan las generales
  • user=false: no se buscan las creadas por el usuario

PATCH​

Solo se pueden editar las creadas por el usuario que hace el request.

{
    'type': 'object',
    'properties': {
        'uuid': {'type': 'string', 'pattern': UUID_PATTERN,
                 'description': 'UUID v1 of the spot to which msg belongs'},
        'tag': {'type': 'string',
                'description': 'the name of the tag'},
    },
    'required': ['uuid', 'tag'],
    'additionalProperties': False
}

DELETE​

Se incluye el parámetro uuid en la query string con el uuid de la tag a eliminar.

Solo se puede eliminar una tag creada por el usuario que hace la request.

Errores​

  • Si la tag esta siendo utilizada por alguna zona de gestión, no podrá eliminarse. {'code': 51, 'info':'It is not possible to delete a Tag that is in use'}

Variables​

/api/spots/variables

PATCH​

Las unidades se definen por un objeto con las keys "name", "unit_id" y "value", donde unit_id es el id de la unidad, los cuales se pueden consultar en GET api/utils/units

NOTA: El array enviado reemplaza el que esté guardado.

{
    "type": "object",
    "properties": {
        "uuid": {"type": "string",
                    "pattern": UUID_PATTERN,
                    "description": "UUID v4 to set as map spot reference"},
        "variables": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {"name": {"type": "string"},
                                "unit_id": {"type": "integer",
                                            "minimum": 0},
                                "value": {"type": "number"}}},
                "additionalProperties": False
        }
    },
    "required": ["uuid", "variables"],
    "additionalProperties": False
}

Sheets​

/api/spots/sheet

GET​

Opcionalmente, se pueden incluir filtros para aplicar como AND sobre las zonas de gestión a incluir en el excel.

farm_id field_id date_from: fecha de creación del Spot. Formato: YYYY-MM-DDTHH:MM:SSZ date_to: fecha de creación del Spot. Formato: YYYY-MM-DDTHH:MM:SSZ tag_uuid: uuid de un tag. Por ahora, se puede incluir uno solo.

POST​

Se debe incluir el archivo en formato xls, xlsx o csv en el formulario bajo la key sheet.

Errores​

  • Si el tipo de archivo enviado no es de uno de los formatos indicados: {'code': 51, 'info': 'file format not supported. It must be one of .csv, .xls, .xlsx'}
  • Si no se puede abrir el archivo. Seguramente por algún problema de incompatibilidad o archivo corrupto: {'code': 52, 'info': 'error loading sheet'}
  • Si el archivo no tiene la columna "Auravant_Spot_ID". Esta columna tiene los uuids de los Spots, por lo que si no se encuetra dicha columna, no hay mucho para hacer. {'code': 53, 'info': 'missing column: Auravant_Spot_ID'}
  • Si ninguna de los uuids de la columna "Auravant_Spot_ID" es válido o si no se corresponden a Spots vigentes: {'code': 54, 'info': 'No valid record was found'}
  • Si no se encuentran variables válidas para cargar: {'code': 55, 'info': 'No valid variables were found'}
  • Si la API responde con el error code: 12, significa que el usuario no tiene permisos sobre al menos 1 de los spots del excel

Respuesta​

El json de una respuesta exitosa tiene los siguientes campos:

  • variables : un objecto con las variables que se encontraron en el excel. Cada key de ese objeto es la variable, tal como figura en el excel, y su valor es null si no se pudo cargar (es decir que por algún motivo es inválida) o un objeto si es una variable válida. Ese objeto tiene las keys "name" con el nombre de la variable y "unit_id" con el id de la unidad que se identificó
  • loaded_spots: cantidad de spots (filas del excel) que se encontraron
  • ignored_spots: cantidad de spots (filas del excel) que se ignoraron

EJEMPLO:

rta = {
    'loaded_spots': 5,
    'ignored_spots': 0,
    'variables': {
        'K (Kg/tornillos)': null,
        'K (Kg/ha)': {
            'name': 'K',
            'unit_id': 49}}
}