Versionado
Cómo evoluciona /v1, qué cuenta como un breaking change, y cómo se retira un path.
Todo cuelga de /v1. Ese prefijo es el contrato: un cliente escrito contra los endpoints de hoy sigue funcionando sin reescribirse.
Qué puede cambiar en /v1
Los cambios aditivos entran acá. Un endpoint nuevo, un campo opcional nuevo, un code de error nuevo. Los campos que ya existen conservan su significado, los requeridos siguen requeridos, y un cliente que ignora lo que no conoce sigue funcionando.
Qué no pasa en /v1
Un breaking change se lleva un prefijo nuevo (/v2), no una reescritura silenciosa de /v1. Breaking es: sacar o renombrar un campo, cambiar un tipo, volver obligatorio un campo que era opcional, o cambiar el significado de un code.
Hoy no hay /v2. Cuando lo haya, /v1 se queda el tiempo suficiente para migrar, y los dos prefijos se documentan juntos.
Deprecación
Hoy no hay nada deprecado.
Cuando un path o un campo se vaya a ir:
- Queda marcado en el spec OpenAPI (
deprecated: true). - Se dice en esta página, con el reemplazo.
- Las respuestas que todavía sirven el path viejo mandan un header
Sunset(una fecha HTTP), para que un cliente vea el plazo sin leer la documentación.
Hasta que eso pase, no trates /v1 como inestable. Que crezca por adición es el punto del prefijo.
Las keys no se versionan
Una API key de organización funciona en el prefijo que esté vigente. No se emite una key nueva para seguir usando /v1, y una key no está atada a una versión.
Límites de volumen
Cuánto podés pedir, cómo se ve un 429 y cómo esperar.
Push a lead POST
Creates the person (or reuses them, matched by phone or email) and their enquiry, in one call. Idempotent per `externalId` within your organization. A lead with a phone number and no conversation yet is what the automatic first contact reacts to: if the organization has it enabled, the approved template goes out on its own.