API de registro de dispositivos

La API de registro de dispositivos proporciona interfaces de servidor para registrar tokens de dispositivos y obtener registration_id en AppPush.

Obtener registration_id mediante un Token

Esta API permite que un servidor registre usuarios de AppPush mediante FCM Tokens o APNs Device Tokens y obtenga el registration_id generado por EngageLab. Después de obtenerlo, puede utilizar el registration_id para enviar notificaciones a usuarios específicos y para APIs relacionadas con dispositivos, como etiquetas y alias.

Límites de uso

• Cada solicitud permite registrar entre 1 y 500 Tokens.
• Una solicitud solo puede contener Tokens de una plataforma: un lote de FCM Tokens o un lote de APNs Device Tokens. No se pueden mezclar Tokens de FCM y APNs en la misma solicitud.
• Las solicitudes repetidas con la misma aplicación, plataforma y Token son idempotentes. No se crea un usuario duplicado y se devuelve el registration_id existente.
• Los resultados se devuelven en el mismo orden que los Tokens de la solicitud.

Endpoint

              
              POST /v4/devices/token/registration_id

            

La URL completa se compone de la Base URL del centro de datos de la aplicación y de la ruta anterior. Consulte Descripción general de REST API para conocer las direcciones de los centros de datos y el método de autenticación.

Encabezados de la solicitud

              
              Content-Type: application/json
Accept: application/json
Authorization: Basic base64_auth_string

            

Parámetros de la solicitud

Reglas de formato de los Tokens

• FCM Token: Debe ser una cadena no vacía de 400 caracteres como máximo. Solo se permiten caracteres ASCII imprimibles (0x21–0x7E). No se permiten espacios, saltos de línea ni espacios en blanco iniciales o finales.
• APNs Device Token: Debe ser una cadena hexadecimal no vacía, con un número par de caracteres y una longitud máxima de 400 caracteres. Solo se permiten 0-9, a-f y A-F. No se permiten espacios, corchetes angulares ni otros separadores.

Esta API solo valida el formato del Token y no puede confirmar si el Token es válido actualmente. La validez se determina mediante el resultado real del envío de FCM o APNs.

Ejemplo de solicitud Android (FCM)

              
              curl -X POST 'https://pushapi-sgp.engagelab.com/v4/devices/token/registration_id' \
  -u 'appKey:masterSecret' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "platform": "android",
    "tokens": [
      "fcm_token_1",
      "fcm_token_2"
    ]
  }'

            

Ejemplo de solicitud iOS (APNs)

              
              curl -X POST 'https://pushapi-sgp.engagelab.com/v4/devices/token/registration_id' \
  -u 'appKey:masterSecret' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "platform": "ios",
    "tokens": [
      "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    ],
    "apns_production": true
  }'

            

Parámetros de respuesta

Códigos de resultado individuales:

Ejemplo de respuesta correcta

En el primer registro, is_new es true:

              
              {
  "results": [
    {
      "token": "fcm_token_1",
      "registration_id": "13065ffa4e1a6cc91c3",
      "is_new": true,
      "code": 0
    },
    {
      "token": "fcm_token_2",
      "registration_id": "13065ffa4e1a6cc91c4",
      "is_new": true,
      "code": 0
    }
  ]
}

            

Si se vuelve a enviar un Token ya registrado, se devuelve el mismo registration_id y is_new es false:

              
              {
  "results": [
    {
      "token": "fcm_token_1",
      "registration_id": "13065ffa4e1a6cc91c3",
      "is_new": false,
      "code": 0
    }
  ]
}

            

Ejemplo de error de un Token individual

Si un Token de un lote tiene un formato no válido o no se puede registrar, ese elemento devuelve un error mediante code y message, mientras que los demás Tokens pueden procesarse normalmente. En el siguiente ejemplo, el Token vacío no supera la validación de formato:

              
              {
  "results": [
    {
      "token": "fcm_token_1",
      "registration_id": "13065ffa4e1a6cc91c3",
      "is_new": false,
      "code": 0
    },
    {
      "token": "",
      "is_new": false,
      "code": 21003,
      "message": "invalid fcm token format"
    }
  ]
}

            

Ejemplo de solicitud fallida

Si los parámetros generales de la solicitud no son válidos, la API devuelve HTTP 400. Por ejemplo, una solicitud de iOS sin apns_production devuelve:

              
              {
  "error": {
    "code": 21003,
    "message": "apns_production is required for ios"
  }
}

            

Errores frecuentes de solicitud:

• platform no es android ni ios;
• tokens está vacío o contiene más de 500 elementos;
• una solicitud de Android incluye apns_production;
• una solicitud de iOS no incluye apns_production.

Respuestas de la API

Códigos de estado HTTP

Consulte Código de estado HTTP.

Códigos de error

La siguiente tabla muestra los códigos de error a nivel de solicitud. En una solicitud por lotes, el error de un Token individual se devuelve mediante results[].code y results[].message y no afecta al procesamiento de los demás Tokens.