API de Taply

Taply expone una API HTTP en https://api.gettaply.com, documentada con OpenAPI 3.1. Cubre hoy la parte de perfiles, enlaces, medios y tarjetas de Taply: crear un perfil, publicarlo, gestionar sus enlaces y resolver una tarjeta física. Las respuestas son JSON y la especificación se genera desde el mismo código que atiende las peticiones. La configuración de agentes, los canales y las conversaciones todavía no tienen superficie pública: se administran desde el panel. Cuando se publiquen, se anunciarán aquí.

Qué ofrece la API

Los recursos que la especificación publica hoy se agrupan así:

• Identidad y onboarding — sincronizar al llamante y leer su estado (GET /v1/me), y crear, leer, actualizar y completar sesiones de onboarding.
• Perfiles — crear, listar, leer y actualizar perfiles, comprobar y cambiar su slug, y publicarlos o despublicarlos.
• Enlaces — crear, listar, actualizar, borrar y reordenar los enlaces de un perfil propio.
• Media — subir bytes de imagen, listarlos, leerlos, borrarlos y asociarlos a un perfil, incluido el avatar.
• Destinos y tarjetas — gestionar destinos y las tarjetas físicas que apuntan a ellos, con reclamo por código de un solo uso.
• Analítica — leer agregados de clics de enlace y de entradas para un perfil o una tarjeta que el llamante posea.
• Endpoints públicos — lectura de un perfil publicado por slug, resolución del código público de una tarjeta, media transformada y un sitemap de perfiles publicados.

La lista autoritativa —con parámetros, esquemas de respuesta y códigos de error de cada operación— es siempre la especificación, no esta página. Si algo diverge, manda la especificación.

Especificación OpenAPI

El documento OpenAPI 3.1 se sirve en https://api.gettaply.com/openapi.json. Es público, no requiere autenticación y se genera desde el mismo código que atiende las peticiones, de modo que no puede quedar desactualizado respecto a la implementación desplegada. Puedes pasarlo directamente a un generador de clientes, a Postman o a un agente que necesite descubrir las operaciones disponibles.

Primera llamada (sin credenciales)

GET /health es público y no lleva autenticación. Es la forma más rápida de comprobar conectividad y el estado de los subsistemas de los que depende la API:

curl -s https://api.gettaply.com/health

Respuesta:

{
  "status": "ok",
  "checks": {
    "d1": "ok",
    "auth": "ok",
    "access": "ok",
    "kv": "ok",
    "r2": "ok",
    "mediaSourceSigning": "ok",
    "claimCodeHmac": "ok"
  }
}

Devuelve 200 cuando todos los subsistemas requeridos están listos y 503 con "status": "degraded" cuando alguno no lo está. Puedes probarlo en el navegador: https://api.gettaply.com/health.

Autenticación

Las rutas bajo /v1 que operan sobre datos de una cuenta exigen un token Bearer en la cabecera Authorization. El token es la sesión del titular de la cuenta, emitida como JWT por el proveedor de autenticación (Stytch), y se valida localmente en cada petición.

curl -s https://api.gettaply.com/v1/me \
  -H "Authorization: Bearer $TAPLY_TOKEN"

La API es multi-tenant: el token determina la cuenta, y toda operación se resuelve contra los recursos que esa cuenta posee. Pedir un recurso ajeno no devuelve datos de otro negocio. Los endpoints bajo /v1/public/ no llevan token porque sirven contenido ya publicado, y los que están bajo /v1/internal/ usan un principal de operador distinto del token del titular: no forman parte de la superficie pública.

Errores y trazabilidad

Todos los errores comparten una misma forma JSON, con un código estable pensado para ramificar en código y un mensaje pensado para leerse:

{
  "error": {
    "code": "authentication_required",
    "message": "Missing or malformed Authorization header",
    "requestId": "2ba3ea27-e342-4abc-92a2-41fa595fd57a"
  }
}

El campo requestId coincide con la cabecera de respuesta x-request-id, que va en todas las respuestas, incluidas las correctas. Guárdalo: es lo que permite localizar una petición concreta en los registros. Si reportas un fallo, inclúyelo. Algunos errores añaden un campo details con contexto específico de la operación.

Versioning & deprecation policy

El versionado es por URL. Todas las rutas de negocio viven bajo el prefijo /v1. Las rutas de servicio —/health y /openapi.json— son deliberadamente no versionadas: describen la API, no el dominio.

• Cambios compatibles dentro de /v1: campos opcionales nuevos en las respuestas, endpoints nuevos, valores nuevos en enumeraciones extensibles. Tu cliente debe ignorar los campos que no conozca; no los tratamos como cambio incompatible.
• Cambios incompatibles —quitar o renombrar un campo, cambiar su tipo, endurecer una validación, retirar un endpoint— no se hacen sobre /v1. Van a una versión nueva de la URL (/v2), y /v1 sigue sirviendo su contrato.
• Deprecaciones: cuando una operación quede obsoleta se anunciará en esta página y se marcará como deprecated en la especificación OpenAPI. Las respuestas de esa operación llevarán la cabecera Deprecation y, cuando haya fecha de retirada fijada, también Sunset con esa fecha (RFC 9745 y RFC 8594), además de un Link a la alternativa cuando exista.
• Ventana: una operación anunciada como obsoleta seguirá respondiendo al menos hasta la fecha publicada en su cabecera Sunset. Nunca se retira una operación sin haberla anunciado antes por esta vía.

A día de hoy no hay ninguna operación deprecada: todo lo que aparece en la especificación está vigente. Cuando eso cambie, este apartado listará qué queda obsoleto, desde cuándo, hasta cuándo responde y con qué se sustituye.

Rate limiting

La API está protegida contra abuso a nivel de plataforma. Los límites por cuenta aún no están documentados como contrato público y por eso no publicamos cifras aquí: prometer un número que luego no se sostiene es peor que no darlo.

El compromiso es el siguiente: cuando los límites se publiquen, se expondrán con las cabeceras estándar RateLimit y RateLimit-Policy (IETF RateLimit header fields for HTTP), de modo que un cliente pueda leer cuánta cuota le queda y cuándo se renueva sin adivinar. Una petición rechazada por exceso responderá 429 con el mismo formato de error de arriba y una cabecera Retry-After. Este apartado se actualizará con las cifras concretas y la fecha desde la que aplican.

Mientras tanto, la recomendación práctica: reintenta con retroceso exponencial ante 429 y 503, no hagas polling agresivo y reutiliza conexiones.

Soporte

Dudas sobre la API, integraciones o comportamientos que no cuadren con la especificación: contact@gettaply.com, indicando el endpoint, lo que esperabas y el x-request-id de la respuesta. Para contexto sobre el producto, acerca de Taply; para las condiciones de uso, los términos.