Registros e ids

Los identificadores son cadenas opacas. No supongas nunca su formato, su longitud ni su orden, y no construyas ninguno. Los cursores de paginación son opacos de la misma manera. Los números legibles, como orderNumber o contactNumber, son para las personas: usa id para direccionar un registro.

Solo algunos recursos tienen un campo escribible para una referencia de tu sistema. La tabla se genera a partir de la especificación.

POST /api/v1/contacts/lookup acepta hasta 200 referencias y compara cada una, de forma exacta y sin ninguna normalización, con el contactNumber de los contactos, y con nada más. Devuelve dos listas: notFound, las referencias que no coinciden con ningún contacto, y contacts, los contactos que coincidieron, cada uno con id, name y contactNumber. No escribe nada, aunque sea un POST.

La respuesta no empareja una referencia con un contacto, y el orden de contacts no está garantizado. Empárejalos tú mismo comparando el contactNumber de cada contacto con tu referencia. Como contactNumber no es único, pueden devolverse varios contactos para una referencia: decide qué hacer en ese caso en lugar de tomar el primero. Usa notFound para saber qué crear, y guarda el id de Filmo en tu propia tabla cuando lo tengas.

Guarda tu id externo y el id de Filmo juntos en tu propia base de datos. Una Idempotency-Key solo deduplica reintentos durante 24 horas; no sustituye esa tabla (Idempotencia). Con la tabla puedes actualizar el registro correcto, detectar duplicados y decidir qué eliminar. Para el patrón en un CRM, consulta el tutorial de sincronización de contactos.

Los valores de los campos personalizados se leen en el mapa customFields de un registro, indexados por el identificador de la definición del campo. Las definiciones vienen de GET /api/v1/custom-fields, con la entidad a la que se aplica cada una (applyAt), el tipo y los valores que acepta un desplegable. Los valores viajan dentro de cada recurso; el endpoint de definiciones no los devuelve. v1 no tiene ninguna operación que escriba un campo personalizado: los cuerpos de creación y actualización no tienen la propiedad customFields, así que establécelos en la app.

• Etiquetas: GET /api/v1/tags devuelve el vocabulario con cuántas entidades usan cada una. POST /api/v1/tags/{tagId}/assignments asocia una etiqueta existente a una entidad. DELETE /api/v1/tags/{tagId}/assignments quita el vínculo y no borra la etiqueta.
• Notas: POST /api/v1/notes escribe una nota en una entidad y GET /api/v1/notes lee las notas de una entidad, nunca las de todas. No se devuelve quién escribió una nota. Mencionar a usuarios les envía una notificación en Filmo.