Listings APIListings API
Iniciar sesión

Inicio rápido

Conéctate a Listings API, enumera tus ubicaciones, crea una ubicación y responde a una reseña en TypeScript.

1. Configura tu clave de API

Obtén tu clave en Claves de API → Nueva clave en el panel de desarrolladores de Listings API.

bash
export LISTINGSAPI_KEY="your-api-key"

new ListingsAPI() lee LISTINGSAPI_KEY del entorno automáticamente, o puedes pasar apiKey de forma explícita.

2. Enumera tus ubicaciones

quickstart.ts
import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI(); const result = await client.fetchAllLocations({ first: 5 });if (!Array.isArray(result)) {for (const location of result.locations) {  console.log(location.name, '--', location.city, location.stateIso);}console.log('\nhasNextPage:', result.pageInfo.hasNextPage);}
bash
npx tsx quickstart.ts

Salida esperada:

bash
Acme Dental Midtown -- New York NYAcme Dental Brooklyn -- Brooklyn NYAcme Dental Jersey City -- Jersey City NJ hasNextPage: false

fetchAllLocations devuelve un objeto con locations y pageInfo de forma predeterminada. Pasa fetchAll: true y el SDK recorrerá automáticamente las páginas mediante cursores y devolverá un Location[] sin anidar.

TypeScript
const all = await client.fetchAllLocations({ fetchAll: true, pageSize: 100 });if (Array.isArray(all)) {console.log('Total: ' + all.length + ' locations');}

3. Crea una ubicación

La API requiere name, city, countryIso, subCategoryId y un description de al menos 200 caracteres. Obtén valores válidos de subCategoryId desde client.fetchSubcategories() y usa el databaseId de cada entrada.

TypeScript
const created = await client.createLocation({name: 'Acme Dental',storeId: 'ACME-NYC-001',street: '123 Jump Street',city: 'New York',stateIso: 'NY',postalCode: '10013',countryIso: 'US',phone: '6443859313',subCategoryId: 1432,description:  'Acme Dental is a family-owned dental practice serving downtown New York since 2009. ' +  'Our team provides preventive checkups, cosmetic dentistry, orthodontics, and emergency care, ' +  'with same-day appointments, transparent pricing, and a patient-first approach on every visit.',});console.log(created);

Si los datos enviados no son válidos, el SDK lanza un ValidationError que contiene las entradas de error de la plataforma, incluso cuando la API responde con HTTP 200. No hay ningún indicador success que comprobar.

4. Responde a una reseña

Obtén las reseñas de una ubicación y luego responde mediante el ID de interacción. Se aceptan ID numéricos de ubicación en todas partes: el SDK los codifica en base64 automáticamente.

TypeScript
const reviews = await client.fetchInteractions(16808, {startDate: '2026-01-01',endDate:   '2026-06-30',first: 10,}); if (!Array.isArray(reviews)) {const unanswered = reviews.interactions.find(  (review) => (review.responses ?? []).length === 0,);if (unanswered) {  console.log(unanswered.rating, unanswered.content?.slice(0, 80));  await client.respondToReview(    unanswered.id,    'Thank you for the kind words! We look forward to seeing you at your next visit.',  );}}

5. Gestiona los errores

TypeScript
import { ListingsAPI, APIError, AuthenticationError } from 'listingsapi-js'; const client = new ListingsAPI({ apiKey: 'bad-key' }); try {await client.fetchAllLocations();} catch (error) {if (error instanceof AuthenticationError) {  console.log('Invalid API key. Check LISTINGSAPI_KEY.');} else if (error instanceof APIError) {  console.log('Status:', error.statusCode);  // can be 200 for payload-level errors  console.log('Code:',   error.code);        // first platform code, e.g. 'SY10005'  console.log('Errors:', error.errors);      // [{ code, message, context }, ...]}}

El SDK lanza errores tipados para las respuestas con códigos distintos de 2xx, para los cuerpos de respuesta con errores que la plataforma devuelve con HTTP 200 y para las operaciones de escritura que notifican success: false. También reintenta automáticamente las solicitudes que reciben respuestas 429 y 5xx. Consulta Gestión de errores para ver patrones de reintento y orientación sobre los códigos de estado.

Siguientes pasos