> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Referencia del SDK de Servidor

> Instala, configura y usa los SDK de servidor de OneSignal para enviar notificaciones push, emails y SMS desde tu backend en Node.js, Python, Java, Go, PHP, Ruby, C# y Rust.

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](/reference/create-message) y proporciona modelos tipados para solicitudes y respuestas.

## SDKs disponibles

| Lenguaje  | Paquete                                                                                            | Repositorio                                                 |
| --------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| Node.js   | [@onesignal/node-onesignal](https://www.npmjs.com/package/@onesignal/node-onesignal)               | [GitHub](https://github.com/OneSignal/node-onesignal)       |
| Python    | [onesignal-python-api](https://pypi.org/project/onesignal-python-api/)                             | [GitHub](https://github.com/OneSignal/onesignal-python-api) |
| Java      | [onesignal-java-client](https://central.sonatype.com/artifact/com.onesignal/onesignal-java-client) | [GitHub](https://github.com/OneSignal/onesignal-java-api)   |
| Go        | [onesignal-go-api](https://pkg.go.dev/github.com/OneSignal/onesignal-go-api)                       | [GitHub](https://github.com/OneSignal/onesignal-go-api)     |
| PHP       | [onesignal/onesignal-php-api](https://packagist.org/packages/onesignal/onesignal-php-api)          | [GitHub](https://github.com/OneSignal/onesignal-php-api)    |
| Ruby      | [onesignal](https://rubygems.org/gems/onesignal)                                                   | [GitHub](https://github.com/OneSignal/onesignal-ruby-api)   |
| C# (.NET) | [OneSignalApi](https://www.nuget.org/packages/OneSignalApi)                                        | [GitHub](https://github.com/OneSignal/onesignal-dotnet-api) |
| Rust      | [onesignal-rust-api](https://crates.io/crates/onesignal-rust-api)                                  | [GitHub](https://github.com/OneSignal/onesignal-rust-api)   |

***

## Instalación

<Note>
  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.
</Note>

<Tabs>
  <Tab title="Node.js">
    ```bash theme={null}
    npm install @onesignal/node-onesignal
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install onesignal-python-api
    ```
  </Tab>

  <Tab title="Java">
    **Maven**

    ```xml theme={null}
    <dependency>
      <groupId>com.onesignal</groupId>
      <artifactId>onesignal-java-client</artifactId>
      <version>5.3.0</version>
    </dependency>
    ```

    **Gradle**

    ```groovy theme={null}
    implementation "com.onesignal:onesignal-java-client:5.3.0"
    ```
  </Tab>

  <Tab title="Go">
    ```bash theme={null}
    go get github.com/OneSignal/onesignal-go-api/v5
    ```
  </Tab>

  <Tab title="PHP">
    Añade a `composer.json`:

    ```json theme={null}
    {
      "require": {
        "onesignal/onesignal-php-api": "^5.3"
      }
    }
    ```

    Luego ejecuta `composer update`.
  </Tab>

  <Tab title="Ruby">
    Añade a tu `Gemfile`:

    ```ruby theme={null}
    gem 'onesignal', '~> 5.3'
    ```

    Luego ejecuta `bundle install`.
  </Tab>

  <Tab title="C# (.NET)">
    ```bash theme={null}
    dotnet add package OneSignalApi
    ```
  </Tab>

  <Tab title="Rust">
    Añade a `Cargo.toml` bajo `[dependencies]`:

    ```toml theme={null}
    onesignal-rust-api = "5.3.0"
    ```
  </Tab>
</Tabs>

***

## 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**.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    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);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    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);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    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())
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    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
    );
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    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
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    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);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    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
    }
    ```
  </Tab>
</Tabs>

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

***

## Enviar una notificación push

Envía notificaciones push a [Suscripciones](./subscriptions) 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.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    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);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    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());
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    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())
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    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();
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    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}"
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    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`:

    ```csharp theme={null}
    var normalizedContent = yourContent
       .Replace("\\r\\n", "\n")
       .Replace("\\n", "\n")
       .Replace("\r\n", "\n")
       .Replace("\r", "\n");
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    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;
    ```
  </Tab>
</Tabs>

***

## Enviar un email

Envía emails a [Suscripciones](./subscriptions) con el canal `email`.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    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);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    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);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    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()
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    $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);
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    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)
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    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);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    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;
    ```
  </Tab>
</Tabs>

***

## Enviar un SMS

Envía mensajes de texto SMS a [Suscripciones](./subscriptions) con el canal `sms`.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    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);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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)
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    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);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    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()
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    $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);
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    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)
    ```
  </Tab>

  <Tab title="C# (.NET)">
    ```csharp theme={null}
    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);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    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;
    ```
  </Tab>
</Tabs>

***

## 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](https://github.com/OneSignal/node-onesignal/blob/main/DefaultApi.md)              |
| Python    | [DefaultApi.md](https://github.com/OneSignal/onesignal-python-api/blob/main/docs/DefaultApi.md)   |
| Java      | [DefaultApi.md](https://github.com/OneSignal/onesignal-java-api/blob/main/docs/DefaultApi.md)     |
| Go        | [DefaultApi.md](https://github.com/OneSignal/onesignal-go-api/blob/main/docs/DefaultApi.md)       |
| PHP       | [DefaultApi.md](https://github.com/OneSignal/onesignal-php-api/blob/main/docs/Api/DefaultApi.md)  |
| Ruby      | [DefaultApi.md](https://github.com/OneSignal/onesignal-ruby-api/blob/main/docs/DefaultApi.md)     |
| C# (.NET) | [DefaultApi.md](https://github.com/OneSignal/onesignal-dotnet-api/blob/main/docs/DefaultApi.md)   |
| Rust      | [default\_api docs](https://github.com/OneSignal/onesignal-rust-api/blob/main/docs/DefaultApi.md) |

Para la REST API subyacente, consulta la [referencia completa de la API](/reference/create-message).

***

## 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](/reference/create-message). 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](https://openapi-generator.tech). Esto asegura cobertura de API consistente en todos los lenguajes.

***

## Páginas relacionadas

<Columns cols={2}>
  <Card title="Descripción general de la API REST" icon="code" href="/reference/rest-api-overview">
    Endpoints, autenticación, límites de velocidad y formatos de solicitud/respuesta.
  </Card>

  <Card title="Claves e IDs" icon="key" href="./keys-and-ids">
    Encuentra tu App ID, clave de API REST y clave de API de Organización.
  </Card>

  <Card title="Mensajes transaccionales" icon="paper-plane" href="./transactional-messages">
    Envía OTPs, recibos y alertas urgentes mediante API con datos personalizados.
  </Card>

  <Card title="Verificación de identidad" icon="shield-halved" href="./identity-verification">
    Protege tu integración con JWTs generados por el servidor para prevenir la suplantación de Usuarios.
  </Card>
</Columns>