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

> Documentación de la API pública para integraciones externas

# API Pública

## Introducción

Esta API permite a sistemas externos integrarse con Goil para:

* **Autenticación**: Obtener un token de acceso por negocio e identificador externo.
* **Cuentas**: Crear, consultar, listar, actualizar y eliminar cuentas (usuarios) del negocio.
* **Notificaciones**: Enviar notificaciones push y/o WhatsApp a teléfonos o cuentas.
* **Alertas**: Crear y actualizar alertas geolocalizadas (requiere token Bearer).

## Base URL

```
https://community.goil.app/api/v1/external
```

## Autenticación

### Header obligatorio en la mayoría de endpoints

Incluye el identificador del negocio en todas las peticiones:

```
x-client-id: <businessId>
```

### Login para obtener Bearer token

1. Llama a **POST** `/authentication/login` con:
   * Body: `{ "externalId": "...", "businessId": "..." }`
   * Opcional: header `x-client-id` con el mismo `businessId`
   * Opcional: header `x-client-platform` para indicar la plataforma
2. En la respuesta obtendrás `data.accessToken`.
3. Para endpoints de **Alertas** (`POST /alert`, `PUT /alert/:id`), envía:

   ```
   Authorization: Bearer <accessToken>
   x-client-id: <businessId>
   ```

## Primer paso recomendado

1. **Login**\
   `POST /authentication/login` con `externalId` y `businessId` (y opcionalmente `x-client-id` en header).
2. **Crear o comprobar cuenta**\
   `POST /account/create` para registrar un usuario, o `POST /account/check` para comprobar si existe por teléfono o tags.
3. **Enviar notificación**\
   `POST /notification/send` con `message` y uno de: `phones`, `accountIDs` o `accountTypeIDs`.

## Respuestas

* **Éxito**: El cuerpo suele ir en `data` (p. ej. `{ "data": { "account": { ... } } }`).
* **Error**: Códigos 4xx/5xx con cuerpo como `{ "timestamp": ..., "error": "mensaje", "data": {} }`.

## API Reference

En la pestaña **API Reference** encontrarás la especificación OpenAPI completa con todos los endpoints, esquemas de request/response y códigos de error.