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 |
Antes de escribir
Sección titulada «Antes de escribir»- 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 422validation_failed, y el mensaje nombra el campo. Un cuerpo de más de 865.536 bytes da 413validation_failed. PATCHsolo cambia lo que envías. Un campo que no envías queda como está. Donde la página lo indica,nullquita un valor.
Versiones: ETag e If-Match
Sección titulada «Versiones: ETag e If-Match»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.
- Lee el recurso:
GET /v1/<ámbito>/{id}, y guarda suETag. - Envíalo, tal como lo recibiste, en la cabecera
If-MatchdelPATCHo delDELETE. - Si nadie ha cambiado el recurso desde tu lectura, la escritura se aplica. Si alguien lo ha cambiado, la respuesta es 412
precondition_failedy no se escribe nada: vuelve a leerlo, decide de nuevo y reenvía con el nuevoETag.
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.
Reintentos: Idempotency-Key
Sección titulada «Reintentos: Idempotency-Key»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.
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á.
Límite de escritura
Sección titulada «Límite de escritura»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.
Leer después de escribir
Sección titulada «Leer después de escribir»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.
Por qué se puede rechazar una escritura
Sección titulada «Por qué se puede rechazar una escritura»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 |
Relacionado
Sección titulada «Relacionado»- Claves y permisos: los permisos de escritura y la regla de los 90 días.
- Errores y límites de uso: todos los códigos de error y cuándo reintentar.
