Ir al contenido

Endpoints de objetos de datos

Usa estos endpoints para listar tipos de objetos de datos, gestionar registros de objetos de datos y gestionar relaciones entre objetos y usuarios.

Endpoints de objetos

Endpoints de relaciones entre objetos

Endpoints de relaciones de usuarios

URL base y autenticación

Utiliza el endpoint REST de tu espacio de trabajo y envía Authorization: Bearer YOUR_REST_API_KEY. En esta sección se explica dónde se alojan los endpoints de objetos de datos y cómo se autentican las solicitudes.

  • Para conocer los hosts de los endpoints, consulta Resumen de la API de Braze.
  • Todas las cargas útiles de solicitud y respuesta están en formato JSON.
  • Las solicitudes se limitan al espacio de trabajo propietario de la clave de API.
  • Si la clave tiene una lista de IP permitidas, las direcciones IP que no estén en la lista devuelven 403.

Permisos de clave de API

Esta sección asigna a cada endpoint su permiso obligatorio para que puedas delimitar el alcance de las claves de API de forma segura.

Permiso Grupo de endpoints
data_objects.read Lecturas de tipos y objetos, y lecturas de relaciones entre objetos
data_objects.create Creación de objetos
data_objects.update Reemplazo y actualización de objetos
data_objects.delete Eliminación de objetos
data_objects.user_relationships.read Lecturas de relaciones con usuarios
data_objects.user_relationships.create Creación de relaciones con usuarios
data_objects.user_relationships.update Reemplazo y actualización de relaciones con usuarios
data_objects.user_relationships.delete Eliminación de relaciones con usuarios
data_objects.object_relationships.create Creación de relaciones entre objetos
data_objects.object_relationships.update Reemplazo y actualización de relaciones entre objetos
data_objects.object_relationships.delete Eliminación de relaciones entre objetos
data_objects.bulk_upsert Creación o reemplazo masivo de objetos
data_objects.bulk_delete Eliminación masiva de objetos
data_objects.object_relationships.bulk_upsert Creación o reemplazo masivo de relaciones entre objetos
data_objects.object_relationships.bulk_delete Eliminación masiva de relaciones entre objetos
data_objects.user_relationships.bulk_upsert Creación o reemplazo masivo de relaciones con usuarios
data_objects.user_relationships.bulk_delete Eliminación masiva de relaciones con usuarios

Límites de velocidad

Esta sección explica las cuotas de solicitudes predeterminadas y los encabezados de respuesta para el tráfico de lectura y de escritura.

Contenedor Límite predeterminado
Lecturas de objetos de datos 1000 solicitudes por minuto
Escrituras de objetos de datos 1000 solicitudes por minuto
Escrituras masivas de objetos de datos 1000 solicitudes por minuto, compartidas entre los seis endpoints masivos y con las sincronizaciones de objetos de datos de la ingesta de datos en la nube

El límite de escritura masiva se aplica por espacio de trabajo y es independiente del límite de escritura de registro único.

Cada respuesta incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset.

Para las solicitudes limitadas, Braze devuelve 429 y una carga útil de error con id y message.

{
  "errors": [
    {
      "id": "rate-limit-exceeded",
      "message": "You have exceeded your limit of 1000 requests per minute."
    }
  ]
}

Límites del producto

Esta sección enumera los límites que Braze aplica a los objetos de datos y qué esperar cuando alcanzas uno. Para saber cómo se aplican estos límites a los registros de cuentas, consulta Límites de los objetos de cuenta.

Límites de cantidad

Estos límites se aplican a tu empresa en su conjunto, salvo que se indique lo contrario. Son capacidades iniciales. Si necesitas más registros o un límite más alto, ponte en contacto con el equipo de tu cuenta de Braze para solicitar un aumento.

Límite Valor predeterminado
Registros de objetos de datos por empresa (en todos los espacios de trabajo) 50 000
Campos por tipo de objeto de datos 500
Objetos de datos vinculados a un usuario 1000
Usuarios vinculados a un objeto de datos 10 000
Relaciones entre objetos para un objeto de datos 1000

Límites de campos y valores

Estos límites son fijos para todas las empresas.

Límite Valor
Campos por tipo de relación (relaciones con usuarios y relaciones entre objetos) 25. Los campos de relación no cuentan para el límite de campos por tipo de objeto de datos.
Longitud del valor del atributo 255 caracteres
Campos de fecha Cadenas de fecha y hora RFC 3339 que incluyan una hora y una zona horaria, como 2026-11-03T00:00:00Z. Braze rechaza los valores que solo contienen la fecha, como 2026-11-03. Para más detalles, consulta Formato de los campos de fecha.
Longitud y formato de object_id 250 caracteres. Solo letras, números, guiones y guiones bajos.
Longitud y formato del nombre del campo 250 caracteres. Solo letras, números y guiones bajos, y no puede empezar por un guion bajo.
Nombres de campo reservados id, external_id, object_id y display_name no se pueden usar como nombres de campos personalizados.

Formato de los campos de fecha

Los campos de fecha solo aceptan cadenas de fecha y hora RFC 3339 que incluyan tanto una hora como una zona horaria. Braze requiere el valor completo para no tener que adivinar nunca una hora o una zona horaria. Si tu origen almacena valores que solo contienen la fecha, como fechas de renovación o de contrato en tu almacén de datos, conviértelos antes de enviarlos, por ejemplo, en la transformación de tu almacén.

Valor Resultado
2026-11-03T00:00:00Z Aceptado
2026-11-03T00:00:00-05:00 Aceptado
2026-11-03 Rechazado porque no tiene hora ni zona horaria
2026-11-03T00:00:00 Rechazado porque no tiene zona horaria

Este formato se aplica a los campos de fecha de los objetos de datos, las relaciones con usuarios y las relaciones entre objetos. La forma en que Braze informa de un valor rechazado depende de cómo lo envíes:

  • Los endpoints de creación, reemplazo y actualización de un solo registro devuelven 400. Si hay más de un atributo no válido, el error solo nombra el primero.
  • Los endpoints de inserción y actualización masiva aceptan la solicitud con 202 y luego registran un error de procesamiento data-object-schema-mismatch para el registro, como attributes: renewal_date is not valid for its field.
  • Las sincronizaciones de la ingesta de datos en la nube utilizan el mismo procesamiento que los endpoints masivos, por lo que Braze no aplica una fila con un valor que solo contiene la fecha, y el error aparece en los registros de sincronización.

Por ejemplo, una solicitud de un solo registro que envía 2026-11-03 para un campo de fecha renewal_date devuelve esta respuesta 400:

{
  "error": "Validation failed: Attrs do not conform to field definitions: The property '#/renewal_date' must be a valid RFC3339 date/time string"
}

Qué ocurre cuando alcanzas un límite

Una solicitud que superaría un límite de cantidad devuelve 422 con un id de error que identifica el límite:

{
  "errors": [
    {
      "id": "data-object-record-limit-exceeded",
      "message": "This company has reached its data object record limit"
    }
  ]
}
Límite id de error
Registros de objetos de datos por empresa data-object-record-limit-exceeded
Campos por tipo de objeto de datos data-object-field-limit-exceeded
Campos por tipo de relación data-object-field-limit-exceeded
Objetos de datos vinculados a un usuario data-objects-per-user-limit-exceeded
Usuarios vinculados a un objeto de datos users-per-data-object-limit-exceeded
Relaciones entre objetos para un objeto de datos data-object-relationship-limit-exceeded

Tus registros y relaciones existentes se mantienen: solo se rechaza la solicitud que superaría el límite. Para liberar espacio bajo un límite, elimina los registros que ya no necesites o quita las relaciones que ya no uses. Para aumentar un límite de cantidad, ponte en contacto con el equipo de tu cuenta de Braze.

Las solicitudes que no superan la validación, como un object_id o un valor de atributo demasiado largo, devuelven 400. Las solicitudes que superan el límite de velocidad devuelven 429.

Conceptos básicos

Esta sección define los identificadores clave que se utilizan en todos los endpoints de objetos de datos.

  • type_name: El nombre de máquina del tipo de objeto de datos, único dentro de un espacio de trabajo.
  • object_id: Tu identificador de objeto, único dentro de un tipo.
  • user: El usuario en una solicitud de escritura de relación de usuario, identificado exactamente por uno de los siguientes: external_id, braze_id, alias, email o phone.
  • attributes: Datos del objeto o de la relación, con claves por nombre de campo, validados con el esquema configurado.

Cómo funcionan las relaciones

En esta sección se explican los tipos de relación, los vínculos de relación y el comportamiento de anchor antes de que uses las páginas de referencia de los endpoints.

Resumen del modelo de relaciones

Usa este diagrama para ver cómo encajan los tipos, los registros y las relaciones, y qué te permite hacer en Braze vincularlos. Defines los tipos en el panel y, después, escribes los registros y los vínculos entre ellos mediante estos endpoints.

%%{init: {"flowchart": {"wrappingWidth": 400}} }%%
flowchart LR
  subgraph define["Set up in the dashboard"]
    objtype["Data object types define<br/>the fields a record has"]
    reltype["Relationship types determine<br/>which links are allowed"]
  end

  subgraph write["Write with the API"]
    person["A person you<br/>send messages to"]
    record["A business record<br/>they belong to"]
    related["Another record<br/>connected to it"]
    person -- "A user relationship links<br/>a person to a record" --> record
    record -- "An object relationship links<br/>one record to another" --> related
  end

  subgraph unlock["What it unlocks"]
    segment["Segment people by the<br/>records they belong to"]
    liquid["Personalize messages with<br/>data from those records"]
  end

  define -- "decides what you<br/>are allowed to link" --> write
  write -- "makes these<br/>possible" --> unlock

Los tipos y los vínculos son independientes

  • Los tipos de relación definen qué vínculos son válidos y se administran en el panel.
  • Los vínculos de relación son los enlaces reales entre registros y se crean, actualizan y eliminan mediante estos endpoints de la API.
  • Antes de escribir relaciones, enumera los valores válidos de rel_kind con:
    • GET /data_objects/types/{type_name}/user_relationship_types
    • GET /data_objects/types/{type_name}/object_relationship_types
  • rel_kind no es único de forma global en todos los pares de tipos de objeto. Por ejemplo, rel_kind puede ser subaccount para un par de tipos de objeto y partner_account para otro.
  • Por eso, las escrituras de relaciones entre objetos requieren tanto rel_kind como related_type_name para identificar el tipo de relación previsto junto con el otro tipo de objeto de la asociación.
  • Si related_type_name no coincide con el tipo de relación de ese rel_kind, la solicitud devuelve 400.

anchor controla la dirección de la relación

Las relaciones entre objetos son direccionales. El objeto de la URL se interpreta según anchor.

anchor Rol del objeto de la URL Clave del objeto relacionado en las respuestas
source (predeterminado) Lado de origen (vínculo saliente) to_data_object
target Lado de destino (vínculo entrante) from_data_object

Crear el mismo vínculo desde la perspectiva del anchor opuesto sigue apuntando a una única relación subyacente. Una segunda llamada de creación para el mismo vínculo devuelve 409 (duplicate-object-relationship).

Asimetría de rutas en las relaciones con usuarios

Las lecturas y escrituras de relaciones con usuarios usan intencionadamente rutas de endpoint distintas:

  • Lectura: GET /data_objects/objects/{type_name}/{object_id}/user_relationships
  • Escritura: POST|PUT|PATCH|DELETE /data_objects/objects/{type_name}/{object_id}/users

Los atributos de relación son independientes de los atributos de objeto

  • Los endpoints de relaciones devuelven los atributos a nivel de vínculo en el campo attributes de nivel superior.
  • Los atributos de objeto permanecen anidados en to_data_object o from_data_object.
  • PUT reemplaza los attributes de la relación y PATCH fusiona los attributes de la relación.

Ejemplo práctico

Este ejemplo muestra un flujo de trabajo habitual con cuentas:

  1. Crea account/acct-123.
  2. Crea account/acct-456 como cuenta secundaria.
  3. Vincula un usuario a acct-123 con rel_kind: account_user.
  4. Vincula acct-123 a acct-456 con rel_kind: subaccount.

Para volver a leer los vínculos:

  • GET /data_objects/objects/account/acct-123/user_relationships para los usuarios vinculados
  • GET /data_objects/objects/account/acct-123/object_relationships para los vínculos salientes entre objetos
  • GET /data_objects/objects/account/acct-456/object_relationships?anchor=target para los vínculos entrantes entre objetos

Endpoints masivos

Utiliza los endpoints masivos para sincronizar objetos de datos, relaciones entre objetos y relaciones de usuarios desde tus propios sistemas en lotes. Cada solicitud crea, reemplaza o elimina hasta 50 registros, y Braze procesa el lote en segundo plano.

Método Endpoint Propósito
PUT /data_objects/objects Crear o reemplazar hasta 50 objetos de datos, de cualquier combinación de tipos
DELETE /data_objects/objects Eliminar hasta 50 objetos de datos, de cualquier combinación de tipos
PUT /data_objects/object_relationships Crear o reemplazar hasta 50 relaciones entre objetos
DELETE /data_objects/object_relationships Eliminar hasta 50 relaciones entre objetos
PUT /data_objects/user_relationships Crear o reemplazar hasta 50 relaciones entre usuarios y objetos
DELETE /data_objects/user_relationships Eliminar hasta 50 relaciones entre usuarios y objetos

Cuándo utilizar los endpoints masivos

Utiliza los endpoints masivos cuando sincronices muchos registros desde tus propios sistemas y no necesites que cada cambio se aplique antes de que llegue la respuesta. Utiliza los endpoints de registro único cuando necesites que el cambio sea visible de inmediato, cuando necesites leer registros o cuando quieras actualizar solo algunos de los atributos de un registro con PATCH.

Los endpoints masivos se diferencian de los endpoints de registro único en lo siguiente:

  • El procesamiento es asíncrono. Una respuesta 202 significa que Braze aceptó el lote y lo puso en cola, no que haya aplicado los registros. Braze comprueba si existen los tipos, los tipos de relación, los objetos y los usuarios, y si los atributos coinciden con los campos del tipo, cuando procesa el lote. Una solicitud que devuelve 202 aún puede producir fallos en registros individuales más adelante.
  • La validación es de todo o nada. Si algún registro de una solicitud no supera la validación, Braze rechaza toda la solicitud con 400, no almacena nada y enumera todos los errores.
  • Los registros se ordenan por la hora de recepción. Braze marca cada registro con la hora en que recibió la solicitud, así que no envíes updated_at. Cuando dos solicitudes cambian el mismo registro, prevalece la que Braze recibió más tarde.
  • Los registros pueden esperar a sus dependencias. La eliminación de un objeto o una relación que aún no existe, y una relación cuyo objeto o usuario aún no existe, quedan en espera en lugar de fallar de inmediato. Braze lo reintenta durante unas 40 horas (10 intentos). La creación o actualización de un objeto nunca queda en espera.
  • Los endpoints masivos utilizan sus propios permisos de clave de API y comparten un límite de velocidad de 1000 solicitudes por minuto por espacio de trabajo.
  • Los endpoints masivos nunca crean tipos de objetos de datos. Cada type_name debe existir previamente.

Los límites del producto se aplican a los endpoints masivos del mismo modo que a los endpoints de registro único.

Paginación y actualización de los datos

En esta sección se describe cómo funciona la paginación de las listas y cuánto tardan los datos en estar visibles después de las escrituras.

  • Los endpoints de listado admiten limit y offset.
  • limit tiene un valor predeterminado de 100 y se limita a un rango de 1 a 250.
  • offset tiene un valor predeterminado de 0, y los valores negativos se redondean a 0.
  • Las escrituras de un solo registro son visibles de inmediato para las lecturas y la personalización con Liquid. Las escrituras masivas se aplican cuando Braze procesa el lote en cola.
  • La pertenencia a un Segment basada en objetos de datos puede tener un retraso de hasta una hora, porque los filtros calculados se actualizan cada hora.

Comportamiento de errores

Esta sección resume los patrones de estado y de respuesta de error que utilizan los endpoints de objetos de datos.

  • 404, 409, 422 y 429 devuelven una matriz errors con id y message.
  • 400, 401 y 403 devuelven una única cadena error.
  • Los endpoints masivos devuelven los errores 400 y 500 como una matriz errors con id y message. Un error 400 también incluye el parameter que causa el fallo, cuando existe, y, para los errores a nivel de registro, el index del registro.
  • 422 significa que la solicitud superaría un límite del producto. Los valores de límite predeterminados varían según el contrato de cada empresa.

New Stuff!