Referencia del SDK de Servidor

Todos los SDK de servidor de OneSignal se generan a partir de la misma especificación OpenAPI, por lo que comparten una interfaz consistente independientemente del lenguaje. Cada SDK envuelve la OneSignal REST API y proporciona modelos tipados para solicitudes y respuestas.

SDKs disponibles

Lenguaje	Paquete	Repositorio
Node.js	@onesignal/node-onesignal	GitHub
Python	onesignal-python-api	GitHub
Java	onesignal-java-client	GitHub
Go	onesignal-go-api	GitHub
PHP	onesignal/onesignal-php-api	GitHub
Ruby	onesignal	GitHub
C# (.NET)	OneSignalApi	GitHub
Rust	onesignal-rust-api	GitHub

Instalación

Los números de versión a continuación son ejemplos. Consulta el registro de paquetes de cada SDK para instalar la versión más reciente.

npm install @onesignal/node-onesignal

pip install onesignal-python-api

Maven

<dependency>
  <groupId>com.onesignal</groupId>
  <artifactId>onesignal-java-client</artifactId>
  <version>5.3.0</version>
</dependency>

Gradle

implementation "com.onesignal:onesignal-java-client:5.3.0"

go get github.com/OneSignal/onesignal-go-api/v5

Añade a composer.json:

{
  "require": {
    "onesignal/onesignal-php-api": "^5.3"
  }
}

Luego ejecuta composer update.

Añade a tu Gemfile:

gem 'onesignal', '~> 5.3'

Luego ejecuta bundle install.

dotnet add package OneSignalApi

Añade a Cargo.toml bajo [dependencies]:

onesignal-rust-api = "5.3.0"

Configuración

Cada SDK requiere autenticación mediante claves API. Hay dos tipos de clave disponibles:

REST API Key — requerida para la mayoría de los endpoints (envío de notificaciones, gestión de usuarios, etc.). Se encuentra en Configuración > Claves e IDs de tu app.
Organization API Key — solo requerida para endpoints a nivel de organización como crear o listar apps. Se encuentra en Configuración de Organización.

const OneSignal = require('@onesignal/node-onesignal');

const configuration = OneSignal.createConfiguration({
  restApiKey: 'YOUR_REST_API_KEY',
  organizationApiKey: 'YOUR_ORGANIZATION_API_KEY',
});

const client = new OneSignal.DefaultApi(configuration);

import onesignal
from onesignal.api import default_api

configuration = onesignal.Configuration(
    rest_api_key='YOUR_REST_API_KEY',
    organization_api_key='YOUR_ORGANIZATION_API_KEY',
)

with onesignal.ApiClient(configuration) as api_client:
    client = default_api.DefaultApi(api_client)

import com.onesignal.client.ApiClient;
import com.onesignal.client.Configuration;
import com.onesignal.client.auth.HttpBearerAuth;
import com.onesignal.client.api.DefaultApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

HttpBearerAuth restApiAuth = (HttpBearerAuth) defaultClient
    .getAuthentication("rest_api_key");
restApiAuth.setBearerToken("YOUR_REST_API_KEY");

HttpBearerAuth orgApiAuth = (HttpBearerAuth) defaultClient
    .getAuthentication("organization_api_key");
orgApiAuth.setBearerToken("YOUR_ORGANIZATION_API_KEY");

DefaultApi client = new DefaultApi(defaultClient);

import onesignal "github.com/OneSignal/onesignal-go-api"

restAuth := context.WithValue(
    context.Background(),
    onesignal.RestApiKey,
    "YOUR_REST_API_KEY",
)

orgAuth := context.WithValue(
    restAuth,
    onesignal.OrganizationApiKey,
    "YOUR_ORGANIZATION_API_KEY",
)

apiClient := onesignal.NewAPIClient(onesignal.NewConfiguration())

use onesignal\client\api\DefaultApi;
use onesignal\client\Configuration;
use GuzzleHttp;

$config = Configuration::getDefaultConfiguration()
    ->setRestApiKeyToken('YOUR_REST_API_KEY')
    ->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');

$client = new DefaultApi(
    new GuzzleHttp\Client(),
    $config
);

require 'onesignal'

OneSignal.configure do |config|
  config.rest_api_key = 'YOUR_REST_API_KEY'
  config.organization_api_key = 'YOUR_ORGANIZATION_API_KEY'
end

client = OneSignal::DefaultApi.new

using OneSignalApi.Api;
using OneSignalApi.Client;

var config = new Configuration();
config.BasePath = "https://api.onesignal.com";
config.AccessToken = "YOUR_REST_API_KEY";

var client = new DefaultApi(config);

use onesignal::apis::configuration::Configuration;

fn create_configuration() -> Configuration {
    let mut config = Configuration::new();
    config.rest_api_key_token = Some("YOUR_REST_API_KEY".to_string());
    config.organization_api_key_token = Some("YOUR_ORGANIZATION_API_KEY".to_string());
    config
}

Almacena tus claves API en variables de entorno o en un gestor de secretos. Nunca las incluyas en el control de versiones.

Enviar una notificación push

Envía notificaciones push a Suscripciones web y móviles segmentando un segmento. Estos ejemplos muestran el camino feliz — agrega manejo de errores (try/catch, callbacks de error) para uso en producción.

const notification = new OneSignal.Notification();
notification.app_id = 'YOUR_APP_ID';
notification.contents = { en: 'Hello from OneSignal!' };
notification.headings = { en: 'Push Notification' };
notification.included_segments = ['Subscribed Users'];

const response = await client.createNotification(notification);
console.log('Notification ID:', response.id);

notification = onesignal.Notification(
    app_id='YOUR_APP_ID',
    contents=onesignal.StringMap(en='Hello from OneSignal!'),
    headings=onesignal.StringMap(en='Push Notification'),
    included_segments=['Subscribed Users'],
)

response = client.create_notification(notification)
print('Notification ID:', response.id)

import com.onesignal.client.model.Notification;
import com.onesignal.client.model.StringMap;

Notification notification = new Notification();
notification.setAppId("YOUR_APP_ID");

StringMap contents = new StringMap();
contents.en("Hello from OneSignal!");
notification.setContents(contents);

StringMap headings = new StringMap();
headings.en("Push Notification");
notification.setHeadings(headings);

notification.setIncludedSegments(Arrays.asList("Subscribed Users"));

var response = client.createNotification(notification);
System.out.println("Notification ID: " + response.getId());

notification := *onesignal.NewNotification("YOUR_APP_ID")
notification.SetContents(onesignal.StringMap{En: onesignal.PtrString("Hello from OneSignal!")})
notification.SetHeadings(onesignal.StringMap{En: onesignal.PtrString("Push Notification")})
notification.SetIncludedSegments([]string{"Subscribed Users"})

response, _, err := apiClient.DefaultApi
    .CreateNotification(orgAuth)
    .Notification(notification)
    .Execute()

if err != nil {
    log.Fatal(err)
}
fmt.Println("Notification ID:", response.GetId())

use onesignal\client\model\Notification;
use onesignal\client\model\StringMap;

$content = new StringMap();
$content->setEn('Hello from OneSignal!');

$headings = new StringMap();
$headings->setEn('Push Notification');

$notification = new Notification();
$notification->setAppId('YOUR_APP_ID');
$notification->setContents($content);
$notification->setHeadings($headings);
$notification->setIncludedSegments(['Subscribed Users']);

$response = $client->createNotification($notification);
echo 'Notification ID: ' . $response->getId();

notification = OneSignal::Notification.new({
  app_id: 'YOUR_APP_ID',
  contents: { en: 'Hello from OneSignal!' },
  headings: { en: 'Push Notification' },
  included_segments: ['Subscribed Users']
})

response = client.create_notification(notification)
puts "Notification ID: #{response.id}"

using OneSignalApi.Model;

var notification = new Notification(appId: "YOUR_APP_ID")
{
    Contents = new StringMap(en: "Hello from OneSignal!"),
    Headings = new StringMap(en: "Push Notification"),
    IncludedSegments = new List<string> { "Subscribed Users" }
};

var response = client.CreateNotification(notification);
Console.WriteLine("Notification ID: " + response.Id);

Nota: El SDK de .NET no normaliza automáticamente los caracteres de nueva línea. Si tu contenido contiene \r\n, normalízalo antes de pasarlo a Contents:

var normalizedContent = yourContent
   .Replace("\\r\\n", "\n")
   .Replace("\\n", "\n")
   .Replace("\r\n", "\n")
   .Replace("\r", "\n");

use onesignal::apis::default_api;
use onesignal::models::{Notification, StringMap};

let mut contents = StringMap::new();
contents.en = Some("Hello from OneSignal!".to_string());

let mut headings = StringMap::new();
headings.en = Some("Push Notification".to_string());

let mut notification = Notification::new("YOUR_APP_ID".to_string());
notification.contents = Some(Box::new(contents));
notification.headings = Some(Box::new(headings));
notification.included_segments = Some(vec!["Subscribed Users".to_string()]);

let config = create_configuration();
let response = default_api::create_notification(&config, notification).await;

Enviar un email

Envía emails a Suscripciones con el canal email.

const notification = new OneSignal.Notification();
notification.app_id = 'YOUR_APP_ID';
notification.email_subject = 'Important Update';
notification.email_body = '<h1>Hello!</h1><p>This is an HTML email.</p>';
notification.included_segments = ['Subscribed Users'];
notification.channel_for_external_user_ids = 'email';

const response = await client.createNotification(notification);

notification = onesignal.Notification(
    app_id='YOUR_APP_ID',
    email_subject='Important Update',
    email_body='<h1>Hello!</h1><p>This is an HTML email.</p>',
    included_segments=['Subscribed Users'],
    channel_for_external_user_ids='email',
)

response = client.create_notification(notification)

Notification notification = new Notification();
notification.setAppId("YOUR_APP_ID");
notification.setEmailSubject("Important Update");
notification.setEmailBody("<h1>Hello!</h1><p>This is an HTML email.</p>");
notification.setIncludedSegments(Arrays.asList("Subscribed Users"));
notification.setChannelForExternalUserIds("email");

var response = client.createNotification(notification);

notification := *onesignal.NewNotification("YOUR_APP_ID")
notification.SetEmailSubject("Important Update")
notification.SetEmailBody("<h1>Hello!</h1><p>This is an HTML email.</p>")
notification.SetIncludedSegments([]string{"Subscribed Users"})
notification.SetChannelForExternalUserIds("email")

response, _, err := apiClient.DefaultApi
    .CreateNotification(orgAuth)
    .Notification(notification)
    .Execute()

$notification = new Notification();
$notification->setAppId('YOUR_APP_ID');
$notification->setEmailSubject('Important Update');
$notification->setEmailBody('<h1>Hello!</h1><p>This is an HTML email.</p>');
$notification->setIncludedSegments(['Subscribed Users']);
$notification->setChannelForExternalUserIds('email');

$response = $client->createNotification($notification);

notification = OneSignal::Notification.new({
  app_id: 'YOUR_APP_ID',
  email_subject: 'Important Update',
  email_body: '<h1>Hello!</h1><p>This is an HTML email.</p>',
  included_segments: ['Subscribed Users'],
  channel_for_external_user_ids: 'email'
})

response = client.create_notification(notification)

var notification = new Notification(appId: "YOUR_APP_ID")
{
    EmailSubject = "Important Update",
    EmailBody = "<h1>Hello!</h1><p>This is an HTML email.</p>",
    IncludedSegments = new List<string> { "Subscribed Users" },
    ChannelForExternalUserIds = "email"
};

var response = client.CreateNotification(notification);

let mut notification = Notification::new("YOUR_APP_ID".to_string());
notification.email_subject = Some("Important Update".to_string());
notification.email_body = Some("<h1>Hello!</h1><p>This is an HTML email.</p>".to_string());
notification.included_segments = Some(vec!["Subscribed Users".to_string()]);
notification.channel_for_external_user_ids = Some("email".to_string());

let response = default_api::create_notification(&config, notification).await;

Enviar un SMS

Envía mensajes de texto SMS a Suscripciones con el canal sms.

const notification = new OneSignal.Notification();
notification.app_id = 'YOUR_APP_ID';
notification.contents = { en: 'Your SMS message content here' };
notification.included_segments = ['Subscribed Users'];
notification.channel_for_external_user_ids = 'sms';
notification.sms_from = '+15551234567';

const response = await client.createNotification(notification);

notification = onesignal.Notification(
    app_id='YOUR_APP_ID',
    contents=onesignal.StringMap(en='Your SMS message content here'),
    included_segments=['Subscribed Users'],
    channel_for_external_user_ids='sms',
    sms_from='+15551234567',
)

response = client.create_notification(notification)

StringMap contents = new StringMap();
contents.en("Your SMS message content here");

Notification notification = new Notification();
notification.setAppId("YOUR_APP_ID");
notification.setContents(contents);
notification.setIncludedSegments(Arrays.asList("Subscribed Users"));
notification.setChannelForExternalUserIds("sms");
notification.setSmsFrom("+15551234567");

var response = client.createNotification(notification);

notification := *onesignal.NewNotification("YOUR_APP_ID")
notification.SetContents(onesignal.StringMap{En: onesignal.PtrString("Your SMS message content here")})
notification.SetIncludedSegments([]string{"Subscribed Users"})
notification.SetChannelForExternalUserIds("sms")
notification.SetSmsFrom("+15551234567")

response, _, err := apiClient.DefaultApi
    .CreateNotification(orgAuth)
    .Notification(notification)
    .Execute()

$content = new StringMap();
$content->setEn('Your SMS message content here');

$notification = new Notification();
$notification->setAppId('YOUR_APP_ID');
$notification->setContents($content);
$notification->setIncludedSegments(['Subscribed Users']);
$notification->setChannelForExternalUserIds('sms');
$notification->setSmsFrom('+15551234567');

$response = $client->createNotification($notification);

notification = OneSignal::Notification.new({
  app_id: 'YOUR_APP_ID',
  contents: { en: 'Your SMS message content here' },
  included_segments: ['Subscribed Users'],
  channel_for_external_user_ids: 'sms',
  sms_from: '+15551234567'
})

response = client.create_notification(notification)

var notification = new Notification(appId: "YOUR_APP_ID")
{
    Contents = new StringMap(en: "Your SMS message content here"),
    IncludedSegments = new List<string> { "Subscribed Users" },
    ChannelForExternalUserIds = "sms",
    SmsFrom = "+15551234567"
};

var response = client.CreateNotification(notification);

let mut contents = StringMap::new();
contents.en = Some("Your SMS message content here".to_string());

let mut notification = Notification::new("YOUR_APP_ID".to_string());
notification.contents = Some(Box::new(contents));
notification.included_segments = Some(vec!["Subscribed Users".to_string()]);
notification.channel_for_external_user_ids = Some("sms".to_string());
notification.sms_from = Some("+15551234567".to_string());

let response = default_api::create_notification(&config, notification).await;

Referencia completa de la API

Cada SDK de servidor admite el mismo conjunto de endpoints de la API. Consulta la documentación de la API de tu SDK para la lista completa de métodos, incluyendo usuarios, suscripciones, segmentos, plantillas y más.

SDK	Referencia de la API
Node.js	DefaultApi.md
Python	DefaultApi.md
Java	DefaultApi.md
Go	DefaultApi.md
PHP	DefaultApi.md
Ruby	DefaultApi.md
C# (.NET)	DefaultApi.md
Rust	default_api docs

Para la REST API subyacente, consulta la referencia completa de la API.

Preguntas frecuentes

¿Qué SDK de servidor debería elegir?

Usa el SDK que coincida con el lenguaje de tu backend. Todos los SDK de servidor se generan a partir de la misma especificación OpenAPI y soportan los mismos endpoints, por lo que la funcionalidad es idéntica entre lenguajes.

¿Cuál es la diferencia entre la REST API Key y la Organization API Key?

La REST API Key tiene alcance para una sola app y es necesaria para la mayoría de las operaciones como enviar notificaciones y gestionar usuarios. La Organization API Key tiene alcance para tu organización y solo se necesita para crear o listar apps. La mayoría de las integraciones solo necesitan la REST API Key.

¿Puedo usar la REST API directamente en lugar de un SDK?

Sí. Los SDK de servidor son envoltorios de conveniencia alrededor de la OneSignal REST API. Puedes llamar a la API directamente usando cualquier cliente HTTP con el esquema de autenticación key (Authorization: key YOUR_REST_API_KEY).

¿Estos SDK son generados automáticamente?

Sí. Todos los SDK de servidor son generados a partir de la especificación OpenAPI de OneSignal usando OpenAPI Generator. Esto asegura cobertura de API consistente en todos los lenguajes.

Páginas relacionadas

Descripción general de la API REST

Endpoints, autenticación, límites de velocidad y formatos de solicitud/respuesta.

Claves e IDs

Encuentra tu App ID, clave de API REST y clave de API de Organización.

Mensajes transaccionales

Envía OTPs, recibos y alertas urgentes mediante API con datos personalizados.

Verificación de identidad

Protege tu integración con JWTs generados por el servidor para prevenir la suplantación de Usuarios.

​SDKs disponibles

​Instalación

​Configuración

​Enviar una notificación push

​Enviar un email

​Enviar un SMS

​Referencia completa de la API

​Preguntas frecuentes

​¿Qué SDK de servidor debería elegir?

​¿Cuál es la diferencia entre la REST API Key y la Organization API Key?

​¿Puedo usar la REST API directamente en lugar de un SDK?

​¿Estos SDK son generados automáticamente?

​Páginas relacionadas

Descripción general de la API REST

Claves e IDs

Mensajes transaccionales

Verificación de identidad

SDKs disponibles

Instalación

Configuración

Enviar una notificación push

Enviar un email

Enviar un SMS

Referencia completa de la API

Preguntas frecuentes

¿Qué SDK de servidor debería elegir?

¿Cuál es la diferencia entre la REST API Key y la Organization API Key?

¿Puedo usar la REST API directamente en lugar de un SDK?

¿Estos SDK son generados automáticamente?

Páginas relacionadas