API v1 · OpenAPI 1.2
La superficie pública estable continúa bajo /api/v1 y el contrato descargable identifica la revisión documental vigente.
API v1
Cambios previsibles, sin romper integraciones en silencio.
Consultá novedades, reglas de compatibilidad y deprecaciones antes de actualizar un cliente o desplegar una integración.
Política de versiones
Qué puede cambiar dentro de API v1.
La versión de la ruta protege el contrato principal; el changelog explica cada ampliación y cualquier transición futura.
Aditivos dentro de v1
Pueden incorporarse endpoints, headers y campos opcionales. Los clientes deben ignorar campos desconocidos que no necesiten.
Nueva versión mayor
No se eliminan ni renombran silenciosamente contratos documentados dentro de v1. Un cambio incompatible exige una nueva versión y guía de migración.
Ninguna activa
Toda deprecación futura deberá publicar el reemplazo recomendado, la fecha del anuncio y la fecha prevista de retiro.
Webhooks tienen su propio contrato.
El campo schema_version permite validar el payload antes de procesarlo. Un consumidor debe rechazar versiones que no soporte y deduplicar por Delivery ID.
Historial público
Novedades que afectan a quienes construyen sobre PietroCal.
Se registran cambios de contrato, confiabilidad, SDKs, documentación y herramientas para desarrolladores.
Referencia central de errores y diagnóstico
Se unificaron códigos centrales, decisiones de reintento, reconciliación idempotente y el paquete mínimo de soporte basado en X-Request-Id.
Guías completas por caso de uso
Se publicaron recorridos para agenda, contactos, disponibilidad, OAuth y Webhooks con scopes, orden de llamadas, errores y checklist.
Nuevo portal público para desarrolladores
Inicio rápido, ejemplos en cuatro lenguajes, mapa de recursos y acceso unificado a Swagger, OpenAPI, SDKs y documentación.
Presupuestos y observabilidad por credencial
Cada PAT y access token OAuth puede usar límites más restrictivos, consumo mensual individual y métricas operativas sin ampliar el plan del titular.
Cuota mensual compartida y rate limit central
Las credenciales comparten la cuota mensual del titular y publican límites, remanentes, consumo y resets mediante headers estables.
Entrega durable y consistencia de snapshots
Cada suscriptor aceptado crea una entrega lógica persistida, con Delivery ID estable, retries controlados y snapshots derivados del estado realmente guardado.
Eventos semánticos para agenda y reservas
Se diferenciaron reprogramaciones, cancelaciones, cambios de asistentes, finalización de tareas y transiciones del ciclo de Reservas.
SDKs oficiales e idempotencia durable
Los clientes PHP, JavaScript y Python generan Idempotency-Key segura y sólo reintentan transporte ambiguo cuando la creación está protegida.
Antes de actualizar
Validá el contrato, no supongas el formato.
Usá OpenAPI como referencia técnica, las guías para el flujo completo y este historial para entender cambios entre despliegues.