Versiones y changelog

El v1 de la ruta

https://api.fatureihoje.com/public/v1/me

El v1 es la versión del contrato, no la versión del programa. El programa detrás de ella cambia; lo que la v1 promete, no.

Mientras la ruta diga v1, lo que ya existe sigue existiendo, con el mismo nombre, el mismo tipo y el mismo significado.

Qué es aditivo

Estos cambios entran en la v1 en cualquier momento, sin aviso:

• Un campo nuevo en una respuesta. La respuesta puede ganar campos que usted nunca vio.
• Una ruta nueva. Un área que todavía no respondía pasa a responder.
• Un evento nuevo.
• Un filtro nuevo o un parámetro de consulta nuevo, siempre opcional.
• Un valor nuevo de enum. Un campo de estado puede pasar a devolver un valor que no existía.

Ninguno de ellos rompe a quien ya integra, siempre que su cliente siga tres reglas.

Las tres reglas del cliente que no se rompe

1. Ignore el campo que no conoce. Lea los campos que usa y deje pasar el resto. Una validación que rechaza toda la respuesta por un campo desconocido se rompe en el primer campo nuevo.
2. Tolere un valor de enum desconocido. Trate el valor que no reconoce como “otro” en vez de lanzar un error. Un switch sin caso por defecto es la falla más común aquí.
3. No dependa del texto. El orden de los campos del JSON y el texto de message no son contrato. Lo que sí es contrato está descrito en Errores.

Qué rompe

Estos cambios no ocurren en la v1. Solo existirían en una /public/v2:

• quitar o renombrar un campo de una respuesta;
• cambiar el tipo de un campo;
• volver obligatorio un campo que era opcional en la solicitud;
• dejar de aceptar un valor que era aceptado;
• cambiar el significado de un campo, aun manteniendo nombre y tipo;
• quitar una ruta.

La traba automática

Esto no es solo una promesa escrita. El contrato publicado de la v1 queda guardado en nuestro repositorio, y una verificación automática compara el contrato del código con ese archivo. Ella lista, campo por campo, qué desapareció, qué cambió de tipo, qué se volvió obligatorio y qué dejó de ser aceptado, y frena el cambio antes de que llegue a producción. Corre en el gancho de commit de quien toca el contrato y, sobre todo, dentro del proceso que genera la versión publicada de la API: ninguna versión llega a producción sin pasar por ella.

Una segunda verificación garantiza el otro lado: los esquemas de respuesta de la v1 no son cerrados. Es lo que hace que “un campo nuevo no rompe” sea verdad y no un estilo de redacción, porque un esquema cerrado rechazaría su propia respuesta apenas ganara un campo.

Cuando exista una /public/v2

Todavía no existe, y ninguna ruta está en desactivación.

Cuando eso cambie, la v1 no sale del aire junto con la llegada de la v2. El plan es avisar por dos caminos:

• los encabezados Deprecation y Sunset en las respuestas de la ruta que esté saliendo, con la fecha;
• un aviso por correo a los dueños de las claves de API activas.

Ninguno de los dos encabezados aparece hoy en ninguna respuesta, justamente porque no hay nada en desactivación. El plazo de convivencia entre v1 y v2 se va a anunciar junto con la v2, aquí en esta página.

Cómo se entera de lo que cambia

• Esta página. El changelog está aquí, en la sección de abajo.
• La Referencia. Se genera del código de la API, así que nunca lista una ruta que no existe ni esconde una que sí existe. Es la fuente más actual de lo que responde hoy.
• Correo, en los casos que exigen acción suya, como una desactivación.

Si su integración es importante para su negocio, vale la pena revisar la Referencia de tanto en tanto. Un campo nuevo no rompe nada, pero suele ser exactamente lo que usted estaba esperando.

Changelog

Cada entrada trae la fecha, qué cambió y si exige acción de quien ya integra. La lista campo por campo de lo que la API responde es siempre la Referencia.

v1 | por publicar

La primera versión pública del contrato. La fecha se agrega aquí el día en que se publique la v1. No exige acción: no hay versión anterior.

Qué trae la v1:

• Cuenta: GET /public/v1/me, con la empresa, los permisos de la clave, el miembro representado y el límite de llamadas.
• Clientes, con sus direcciones, y leads, con la tarea de contacto.
• Equipo, tareas y agenda.
• Órdenes de servicio, con los tipos de OS y las acciones de estado, inicio, conclusión y cancelación, y presupuestos, con envío, aprobación, rechazo, cancelación y conversión en venta o en OS.
• Ventas, con versiones, cobros, anulación de cobros, reprogramación de cuotas y cancelación.
• Finanzas: movimientos (incluidas transferencias, recurrencias y cuotas), cuentas y categorías.
• Productos, con variaciones y categorías, stock de solo lectura (saldo y extracto) y servicios, con categorías.
• Webhooks: registro de endpoints, secreto y rotación, ping, registro de entregas, reenvío y la lista de los eventos de los últimos 30 días, con el Catálogo de eventos.
• Lo que vale para todas las áreas: paginación por cursor, errores con código estable, idempotencia en todo POST y límites de uso por plan.

Próximo paso

• Errores: por qué code es estable y message no.
• Visión general: qué está disponible hoy y qué llega en las próximas fases.