Tutorial: Crear un Servicio

Este tutorial muestra cómo agregar un servicio nuevo desde cero. El ejemplo usa un servicio ficticio para obtener “Webinars”.

---

Flujo resumido

1. Crear función en services/
2. Registrar en la vertical (inspiria.ts)
3. Tipar en CommonServices o SpecificServices
4. Usar con useServices('nombre')

---

1. Crea la función del servicio

   Colócala en la carpeta que corresponda según su naturaleza:

   Carpeta	Cuándo usarla
   services/inspiria/	Servicio exclusivo de Inspiria
   services/shared/	Servicio compartido entre verticales
   services/strapi/	Autenticación y endpoints de usuario

   Ejemplo: app/services/inspiria/webinars.ts

   import { ERROR_MESSAGES } from '~/constants/errorConstants'
   import type { LanguageCode } from '~/types/common'
   import type { WebinarsResponse } from '~/interfaces/api/strapi/webinars'
   import { visibleVertical } from '~/core/config'
   import { isProduction } from '~/core/utils'
   
   export async function getWebinars(lang: LanguageCode): Promise<WebinarsResponse | null> {
     try {
       const client = useStrapiClient()
       const apiUrl = isProduction() ? visibleVertical?.productionApi : visibleVertical?.developmentApi
   
       if (!apiUrl) throw new Error('The vertical API URL is not defined')
   
       const response = await client<WebinarsResponse>(
         `/webinars-page/${visibleVertical?.strapiService}/${lang}`,
         { method: 'GET' },
       )
   
       return response?.data ?? null
     } catch {
       throw new Error(ERROR_MESSAGES.DEFAULT_SERVICE_UNAVAILABLE)
     }
   }

   Tip

   No todos los servicios necesitan api-structures ni qs.stringify. Muchos usan directamente useStrapiClient() con un endpoint personalizado del backend. Las api-structures son opcionales para cuando necesitas construir queries complejas de Strapi (populate, filters, etc.).

2. Registra el servicio en la vertical

   Abre app/constants/verticals/inspiria.ts e importa + registra la función:

   import { getWebinars } from '~/services/inspiria/webinars'
   
   export const INSPIRIA: InspiriaVertical = {
     // ... configuración existente
     services: {
       // ... servicios existentes
       getWebinars: async (lang) => await getWebinars(lang),
     },
   }

   El wrapper async (lang) => await fn(lang) normaliza la firma para que useServices pueda inyectar el idioma automáticamente.

   Caution

   Si el servicio recibe parámetros adicionales además de lang, el wrapper los pasa también:

   getWebinarBySlug: async (lang, params) => await getWebinarBySlug(lang, params),

3. Declara el tipo en la interfaz correcta

   Abre app/interfaces/verticals.d.ts y decide:

   • CommonServices → si TODAS las verticales deben implementar este servicio
   • SpecificServices → si es exclusivo de una vertical

   // Si es común a todas las verticales:
   interface CommonServices {
     // ... existentes
     getWebinars: FunctionService<WebinarsResponse | null>
   }
   
   // Si es exclusivo de Inspiria:
   interface SpecificServices {
     // ... existentes
     getWebinars: FunctionService<WebinarsResponse | null>
   }

   Note

   Tipos de servicio disponibles:

   • FunctionService<TReturn> — recibe solo lang
   • FunctionService<TReturn, TParams> — recibe lang + params
   • SimpleService<TReturn> — sin parámetros
   • ObjectService<TReturn, TBody> — para POST con body

4. Usa el servicio

   En cualquier layout o componente:

   const { data, isPending } = useServices('getWebinars')

   Con parámetros:

   const { data } = useServices('getWebinarBySlug', { slug: route.params.slug })

---

Opcional: Interfaz de respuesta

Si la respuesta es compleja, crea una interfaz en app/interfaces/api/strapi/:

app/interfaces/api/strapi/webinars.d.ts

export interface WebinarsResponse {
  webinars: WebinarItem[]
  seo: Seo
}

export interface WebinarItem {
  id: number
  title: string
  slug: string
  date: string
}

Para servicios simples (como un contador), puedes tipar inline directamente en el servicio: Promise<{ count: number }>.

---

Checklist

• Función creada en services/ (inspiria, shared, o strapi)
• Importada y registrada en constants/verticals/inspiria.ts
• Tipo declarado en CommonServices o SpecificServices
• Funciona via useServices('nombre') en layout/componente