Referencia de la API HTTP de Bicheros, la plataforma argentina de cuidado de mascotas.
La especificación completa, en formato
OpenAPI 3.0
, está publicada en
/openapi.json
Incluye cada operación con un
operationId
único, descripción, parámetros tipados y esquemas de respuesta — compatible con
herramientas de function calling de LLMs.
Bicheros es una plataforma de cuidado de mascotas en Argentina: alojamiento canino, paseadores, veterinarias y peluquería, y una red de mascotas perdidas y encontradas ("Perdidogs"). La API HTTP documentada acá cubre dos casos de uso:
/api/campaigns/*
): consultar una campaña y generar/compartir el link de referido de un
usuario ya autenticado en bicheros.com. Pensado para el propio front-end
de la app, no para integraciones externas.
/api/v1/whatsapp/*
): usada por el workflow interno que orquesta la conversación de WhatsApp
de Bicheros. Requiere un token compartido que no se emite a terceros.
Para leer contenido público (perfiles de cuidadores, servicios, publicaciones de mascotas perdidas), Bicheros no expone una API JSON separada: esas páginas ya son HTML renderizado en el servidor, sin JavaScript requerido, listadas en /sitemap.xml.
Un agente que necesite leer ese contenido debería crawlear esas URLs directamente en vez de buscar un endpoint de API.
/api/campaigns/*
usa la sesión de Devise del usuario logueado (cookie de sesión del navegador).
/api/v1/whatsapp/*
usa un token Bearer compartido, enviado como
Authorization: Bearer <token>.
Una request sin credenciales válidas recibe
401
con un cuerpo JSON
{ "error": "unauthorized" }.
curl "https://bicheros.com/api/v1/whatsapp/conversations/current?phone=5491122334455" \ -H "Authorization: Bearer $WHATSAPP_BOT_INTERNAL_TOKEN"
Todos los endpoints bajo
/api/*
devuelven errores como JSON, nunca como página HTML, con al menos un código de
error estable (
error
) y, cuando aplica, un
message
y un
hint
para resolverlo. El detalle de cada código de error por endpoint está en la
especificación OpenAPI.
Los endpoints bajo
/api/v1/whatsapp/*
están limitados a 120 requests por minuto por IP y 20 por minuto por teléfono.
Cada respuesta incluye los encabezados estándar
RateLimit-Limit
,
RateLimit-Remaining
y
RateLimit-Reset
, y una respuesta
429
incluye además
Retry-After
en segundos.