Acorta una URL de destino en un enlace corto que después puede utilizar en el texto de un mensaje o en el portal de BulkGate.

## URL de la API

URL a la que se envían las solicitudes HTTP:

```url
https://portal.bulkgate.com/api/1.0/shortener/shorten
```

> [!NOTE]
> Si la solicitud no llega a su destino, repítala en el [servidor de respaldo](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/servidor-de-respaldo/) `backup1.bulkgate.com`.

## Métodos HTTP admitidos

- `POST` - `application/json`

```http
POST /api/1.0/shortener/shorten HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
```

> [!NOTE]
> La API tiene una cuota de `20` solicitudes por minuto.

## Tabla de parámetros

| NOMBRE DEL PARÁMETRO | VALOR | OBLIGATORIO | VALOR PREDETERMINADO |
|:------------------|:--------------------------------------------------------------------------------|:----------|:--------------|
| application_id    | [ID de aplicación](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/administracion-api/)                                   | **Sí**   | -             |
| application_token | [Token de autenticación de la aplicación](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/tokens-de-api/)                       | **Sí**   | -             |
| target_url        | URL que se va a acortar                                                            | **Sí**   | -             |
| url_type          | Dominio del enlace corto, consulte [Dominios admitidos](#dominios-admitidos)           | No        | `ur7.wf`      |

### Dominios admitidos

Los valores de `url_type` dependen de la configuración de la instancia y pueden cambiar: la lista actual para su cuenta la devuelve el [endpoint `domains`](https://www.bulkgate.com/es/documentacion/acortador-de-url/acortador-dominios-disponibles/). En el momento de redactar este texto:

| DOMINIO             | RESTRICCIÓN DE LA DIRECCIÓN DE DESTINO                    |
|:--------------------|:----------------------------------------------------------|
| `ur7.wf`            | Sin restricción. Valor predeterminado.                    |
| `ms6.fr`            | Sin restricción.                                          |
| `ur7.yt`            | Solo dominios de destino incluidos en la lista blanca.    |
| `ur7.tf`            | Solo dominios de destino incluidos en la lista blanca.    |
| `ms6.wf`            | Solo dominios de destino incluidos en la lista blanca.    |
| `ms6.tf`            | Solo dominios de destino incluidos en la lista blanca.    |
| `track-message.com` | Solo dominios de destino incluidos en la lista blanca.    |

En los dominios restringidos, la dirección de destino debe figurar en la lista blanca de su cuenta; de lo contrario, la solicitud falla con `domain_is_not_white_listed`. Algunos servicios públicos (Google, YouTube, Facebook, GitHub y otros) están siempre en la lista blanca.

## Ejemplo de solicitud

```http-json
POST /api/1.0/shortener/shorten HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
  "application_id": 451,
  "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
  "target_url": "www.bulkgate.com",
  "url_type": "ur7.wf"
}
```

## Respuesta

**En caso de éxito:**

```json
{
    "data": {
        "short_url": "http://ur7.wf/W",
        "target_url": "http://www.bulkgate.com/",
        "final_url": "http://www.bulkgate.com",
        "title": "SMS & other channels for business communication | BulkGate",
        "expiration": "2026-10-10T09:00:00+02:00"
    }
}
```

Los enlaces creados a través de la API son válidos durante **30 días**; `expiration` contiene la fecha de caducidad en formato ISO 8601.

Los tres campos de URL no son lo mismo:

| CAMPO        | VALOR                                                                                                    |
|:-------------|:---------------------------------------------------------------------------------------------------------|
| `short_url`  | El propio enlace acortado, formado a partir de `url_type` y la clave generada                            |
| `target_url` | La dirección tal como se ha guardado: se añade el esquema si falta y la URL se normaliza, de modo que `www.bulkgate.com` se convierte en `http://www.bulkgate.com/` |
| `final_url`  | La dirección que ha enviado, solo con el esquema añadido. **Las redirecciones no se siguen**, por lo que no es la página a la que llega finalmente el visitante |
| `title`      | Título leído de la página de destino                                                                     |


**En caso de error:**

```json
{
    "type": "url_is_not_valid",
    "code": 400,
    "error": "Url is not valid",
    "detail": null
}
```

```json
{
    "type": "the_per_minute_quota_has_been_exceeded",
    "code": 400,
    "error": "The per minute quota has been exceeded",
    "detail": null
}
```

Donde:

- **type** y **error** (descripción del error) se encuentran en la [tabla de tipos de error](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/tipos-de-error/)
- **code** es el código de error HTTP
- **detail** es información adicional sobre el error

### Tipos de error de la Shortener API

Además de los [tipos generales](https://www.bulkgate.com/es/documentacion/administracion-de-la-api/tipos-de-error/), la Shortener API devuelve sus propios tipos:

| TIPO                                    | CUÁNDO SE PRODUCE                                                      |
|:----------------------------------------|:-----------------------------------------------------------------------|
| `url_is_not_valid`                      | No se ha podido analizar `target_url`.                                 |
| `url_type_is_incorrect`                 | `url_type` no figura en la lista de dominios de la cuenta.             |
| `domain_is_not_white_listed`            | El dominio de destino no está en la lista blanca (en los dominios restringidos). |
| `url_is_not_allowed`                    | La dirección de destino apunta a una dirección local o interna.        |
| `url_can_not_be_redirected_out_of_target_domain` | La dirección de destino redirige fuera de su propio dominio.  |
| `url_can_not_be_created`                | No se ha podido crear el enlace.                                       |
| `the_per_minute_quota_has_been_exceeded`| Se ha agotado la cuota de 20 solicitudes por minuto.                   |