Ir al contenido

Escribir datos

Cómo cambia datos la API de Bookline: versiones con ETag e If-Match, reintentos seguros con Idempotency-Key, el límite de escritura y por qué se puede rechazar una escritura.

Algunos ámbitos se pueden cambiar a través de la API: locales, agentes, bases de conocimiento, contactos, campañas y equipo. Todas las escrituras siguen las reglas de esta página; la página de cada ámbito dice qué campos admite.

Método Qué hace Respuesta
POST Crea un recurso. Necesita un Idempotency-Key 201 con el recurso nuevo y su ETag
PATCH Cambia los campos que envías. Necesita If-Match 200 con el recurso tal como queda guardado y su nuevo ETag
DELETE Elimina un recurso. Necesita If-Match 204, sin cuerpo
  • La clave necesita el permiso de escritura del ámbito (venues:write, contacts:write…), y el acceso de su propietario en el portal tiene que permitir el cambio. Consulta qué puede cambiar cada clave.
  • Una clave con permiso de escritura caduca en 90 días como máximo.
  • El cuerpo es JSON, enviado con Content-Type: application/json. Un campo que la ruta no admite, o un valor fuera de sus reglas, da 422 validation_failed, y el mensaje nombra el campo. Un cuerpo de más de 865.536 bytes da 413 validation_failed.
  • PATCH solo cambia lo que envías. Un campo que no envías queda como está. Donde la página lo indica, null quita un valor.

Cada recurso que puedes cambiar tiene una versión. La lectura del detalle (GET por id) la devuelve en la cabecera ETag, y también cada escritura.

  1. Lee el recurso: GET /v1/<ámbito>/{id}, y guarda su ETag.
  2. Envíalo, tal como lo recibiste, en la cabecera If-Match del PATCH o del DELETE.
  3. Si nadie ha cambiado el recurso desde tu lectura, la escritura se aplica. Si alguien lo ha cambiado, la respuesta es 412 precondition_failed y no se escribe nada: vuelve a leerlo, decide de nuevo y reenvía con el nuevo ETag.
Ventana de terminal
ETAG=$(curl -s -D - -o /dev/null -H "apikey: $BOOKLINE_API_KEY" "$BASE/agents/<agent_id>" | awk 'tolower($1)=="etag:" {print $2}' | tr -d '\r')
curl -s -X PATCH "$BASE/agents/<agent_id>" \
-H "apikey: $BOOKLINE_API_KEY" \
-H "Content-Type: application/json" \
-H "If-Match: $ETAG" \
-d '{"name": "Recepción"}'

Un PATCH o un DELETE sin If-Match da 428 precondition_required. La respuesta a un PATCH trae el nuevo ETag, así que puedes hacer un segundo cambio sin volver a leer.

Una escritura que no cambia nada (el mismo nombre, una campaña ya pausada) no escribe nada y devuelve el recurso con su ETag actual.

Un POST crea algo, así que reintentarlo tras un error de red podría crearlo dos veces. Para evitarlo, todo POST necesita una cabecera Idempotency-Key: un valor que eliges tú, distinto para cada creación, de 1 a 255 caracteres imprimibles sin espacios (un UUID va bien). Sin ella, la respuesta es 400 invalid_query.

Ventana de terminal
curl -s -X POST "$BASE/contacts" \
-H "apikey: $BOOKLINE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"phone": "+34600111222", "given_name": "Ana"}'

Bookline recuerda cada clave durante 24 horas:

Si reenvías la misma clave… Respuesta
Con la misma petición, después de aplicarse De nuevo la primera respuesta, con el recurso tal como está ahora y la cabecera Idempotent-Replayed: true. No se crea nada dos veces
Con la misma petición, después de un rechazo 4xx Se procesa de nuevo: corrige la petición y reenvíala con la misma clave
Con otro cuerpo, o para otro cliente 409 conflict: “this Idempotency-Key was used for a different request”
Mientras la primera petición sigue en curso, o si se cortó sin terminar 409 conflict: comprueba si se aplicó antes de usar una clave nueva
Después de una respuesta que no dice si se aplicó (un 502, un 504 o un 503 del servicio de detrás) 409 conflict: “the request with this Idempotency-Key may have been applied; check before sending it with a new key”
Después de eliminarse el recurso creado 409 conflict: la petición se aplicó, pero lo que creó ya no existe

Así que, cuando una creación tarda demasiado o falla con un 5xx: lista primero el recurso (la lista de bases de conocimiento y la de contactos nunca se guardan en caché) y vuelve a crearlo con una clave nueva solo si no está.

Las escrituras tienen su propio límite de 10 por minuto por clave, aparte de las 60 lecturas. Una escritura cuya respuesta son datos personales (crear o cambiar un contacto, cambiar el acceso de un miembro del equipo) cuenta también en el límite de datos personales, de 30 por minuto, y queda registrada como una lectura de datos personales. Si superas el límite, la respuesta es 429 rate_limited con Retry-After. Consulta Errores y límites de uso.

Las escrituras nunca se guardan en caché, y tampoco la lectura del detalle de nada que puedas cambiar: un GET por id justo después de una escritura devuelve los datos nuevos. Otras listas pueden tardar hasta un minuto en reflejarlo.

Bookline registra cada escritura con la clave que la hizo.

Además de los códigos de error generales, una escritura se puede rechazar por una regla del ámbito. El message explica entonces el motivo (en inglés):

Estado Mensaje Dónde
403 This needs a key with access to the whole customer, not only to some venues. Escrituras de contactos, campañas y equipo; crear una base de conocimiento
403 A key cannot change its own owner’s access. Equipo
403 Only a customer key, or the key of one of the customer’s own users holding ADMIN access to ALL of it, can change team access. Equipo
403 This member is a partner of the customer: their access is set by Bookline. Equipo
409 The customer must keep at least one of its own users (not a partner) with ADMIN access to ALL. Equipo
422 access: every venue_ids entry must be a live venue of the customer. Equipo
409 Only a TEXT knowledge base can be changed or deleted through the API: change this one in the portal. Bases de conocimiento
409 A venue still uses this knowledge base: unlink it from its venues first. Bases de conocimiento
409 Another contact of the customer already has this phone or email. Contactos
422 A contact needs a valid phone number or an email. Contactos
409 The venue’s references do not allow this change: a booking integration it uses was deleted, or one of its agents needs a phone or an email in its contact details. Locales