Geolocalizacion - CICO Emisores

GET/stores

Consultar el listado de tiendas disponibles dentro del ecosistema de tapi.

Objetivo

El servicio GET /stores permite al Emisor obtener el listado total de tiendas disponibles en la red, aplicando filtros de busqueda segun necesidad (actividad, cadena, montos, geolocalizacion, etc.) y permite ordenar los resultados. Ademas, opcionalmente puede devolver el historial mensual de cambios para cada tienda (direccion, estado, etc.), cuando se envia el parametro history=true.

Request

Headers

Campo	Tipo	Obligatorio	Descripción
x-authorization-token	String	Sí	Token de autorizacion del usuario/cliente.
x-api-key	String	Sí	API Key provista al cliente.

Query Parameters

Campo	Tipo	Obligatorio	Descripción
orderType	String	No	Orden de resultados. Valores permitidos: alphabetical (default), geo.
active	Boolean/String	No	Filtra tiendas activas o inactivas. Default: true.
latitude	Number	No	Coordenada para ordenamiento geografico (solo con orderType=geo).
longitude	Number	No	Coordenada para ordenamiento geografico (solo con orderType=geo).
radius	Number	No	Radio de busqueda en km (solo con orderType=geo). Ej: 5.
limit	Number	No	Cantidad maxima de resultados. Default: 500.
page	Number	No	Pagina a consultar. Default: 1.
networkId	Number	No	Filtra tiendas por cadena especifica.
networkName	String	No	Filtra por nombre del network (Farmacias del Ahorro, Walmart, etc).
amount	Number	No	Filtra tiendas que acepten un monto especifico dentro de su rango (minAmount/maxAmount).
updatedSince	String	No	Filtro para generar el reporte R26. Permite obtener todas las tiendas que hayan tenido modificaciones (alta, baja o actualizacion) a partir de una fecha determinada (YYYYMMDD).
history	Boolean	No	Si es true, incluye el historial de cambios de las tiendas.

Response

Response Body

Parámetro	Tipo	Descripción
stores	Array	Listado de tiendas. Cada elemento corresponde a una tienda.
links	Array	Enlaces de paginacion.

Ver la librería de errores de esta referencia

Lógica de ordenamiento por orderType

orderType = alphabetical (default)

Devuelve todas las tiendas en orden alfabético.
NO se deben enviar: latitude, longitude, radius.

orderType = geo

Requiere obligatoriamente:

latitude
longitude
radius

Ordena por cercanía dentro del radio permitido.

Definición de lastUpdateType y lastUpdateCode

lastUpdateType

Tipo de actualización reportada según regulaciones:

`lastUpdateType`	Descripción
Alta	Nueva tienda agregada a la red.
Baja	Tienda cerrada permanentemente.
Alta por Actualización	Cambio en atributos de dirección: Localidad, Municipio o Estado. Se reporta como ALTA del nuevo registro.
Baja por Actualización	Dirección anterior deja de ser válida por cambio operativo. Se reporta como BAJA del registro previo.
Reactivación	Una tienda que estaba dada de baja vuelve a estar operativa.

lastUpdateCode

Código CNBV (código de movimiento):

`lastUpdateCode`	Descripción
10	Alta
11	Baja
12	Alta por Actualización
13	Baja por Actualización
14	Reactivación

Generación del Reporte R26

Se agregaron nuevos filtros dentro de la API existente para automatizar el flujo mensual de envío de archivos de geolocalización desde el administrador de comisionistas hacia el emisor, utilizado para la confección del Reporte R26, exigido por la regulación mexicana. Estos filtros permiten obtener las modificaciones de las tiendas (alta, baja o actualización).

Obtener las tiendas que tuvieron cambios a partir de una fecha determinada (updatedSince): GET /stores?updatedSince={YYYYMMDD}
Traer todos los cambios históricos de una tienda (history): GET /stores?history=TRUE
Combinar ambos filtros: GET /stores?history=TRUE&updatedSince={YYYYMMDD}

Devuelve todos los cambios que se realizaron en las tiendas desde la fecha indicada.

Códigos de Localidades CNBV

Según dicta la CNBV para la generación de los reportes R26, se deben informar las localizaciones bajo la nomenclatura estipulada por ellos. Dentro de la API existen los siguientes campos, que se completan en función de dicha nomenclatura:

Campo	Definición
`countryCode`	Identificador numérico único asignado a cada país según el estándar del catálogo. Para registros correspondientes a la República Mexicana, el valor es constante.
`stateCode`	Clave numérica que identifica de manera única a cada una de las entidades federativas (estados) de un país. En México abarca un rango del 01 al 32 (por ejemplo, 30 para Veracruz).
`municipalityCode`	Clave numérica que identifica a la división político-administrativa secundaria (municipio o alcaldía) dentro de un estado en particular.
`localityCode`	Identificador numérico asignado a un asentamiento humano delimitado geográficamente (ciudad, pueblo, villa, ranchería o cabecera urbana) dentro de un municipio. Es secuencial y se repite en distintas regiones, por lo que requiere de sus campos superiores para tener un significado global. Comúnmente, el valor 1 o 0001 representa a la cabecera municipal o zona urbana principal.
`cnbvCode`	Clave maestra interbancaria e identificador único de doce (12) dígitos emitido por la CNBV. Es una llave compuesta concatenada que unifica la estructura geográfica jerárquica bajo el formato estricto: [countryCode (3 dígitos)] + [stateCode (2 dígitos)] + [municipalityCode (3 dígitos)] + [localityCode (4 dígitos)]. Es el campo principal utilizado para la validación regulatoria.

CLIENT LIBRARIES

REQUEST EXAMPLE

curl --request GET \
--url https://cash-in.homo.tapila.cloud/stores?orderType=geo&latitude=16.746033&longitude=-93.116759&radius=5 \
--header 'x-authorization-token: YOUR_TOKEN_HERE' \
--header 'x-api-key: YOUR_API_KEY_HERE'

Recomendamos ingresar en Desktop

Referencia API