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

# API de GoCliente

> Conectá otras herramientas con tokens de acceso y la API REST de GoCliente.

La API REST te deja leer y cargar información de tu estudio desde otras herramientas: planillas, sistemas propios o automatizaciones. Cada token pertenece a tu organización y solo accede a sus datos.

## Crear un token

<Steps>
  <Step title="Abrí los tokens">
    Entrá a **API Tokens** y tocá **Nuevo token**. Necesitás permiso de configuración.
  </Step>

  <Step title="Definí el acceso">
    Escribí un **Nombre del Token**, elegí la **Expiración** (**Sin expiración**, **30 días**, **90 días** o **1 año**) y marcá solo los **Permisos (scopes)** que necesita la integración.
  </Step>

  <Step title="Copiá el token">
    Tocá **Crear token** y copiá el valor. El token completo se muestra **una sola vez**: guardalo en un lugar seguro.
  </Step>
</Steps>

En la lista ves el estado, los alcances, el último uso y el vencimiento de cada token. **Revocar** lo desactiva en el momento.

<Warning>
  Un token da acceso a los datos de tu estudio. No lo compartas ni lo publiques; si se filtra, revocalo y creá otro.
</Warning>

## Autenticación

La URL base es `https://app.gocliente.com/api`. Mandá el token en el encabezado `Authorization` de cada pedido:

```bash theme={null}
curl "https://app.gocliente.com/api/clients" \
  -H "Authorization: Bearer gck_..."
```

| Respuesta          | Qué significa                                        |
| ------------------ | ---------------------------------------------------- |
| `401 Unauthorized` | Falta el token, es inválido, está revocado o venció. |
| `403 Forbidden`    | El token no tiene el alcance que pide ese endpoint.  |

## Alcances

| Alcance            | Qué permite                                    |
| ------------------ | ---------------------------------------------- |
| `clients:read`     | Leer el listado y la búsqueda de clientes.     |
| `clients:write`    | Crear clientes.                                |
| `obligations:read` | Leer obligaciones tributarias.                 |
| `billing:read`     | Leer la facturación mensual y sus indicadores. |
| `tasks:read`       | Leer tareas y el tablero Kanban.               |
| `org:read`         | Ver la organización y el equipo.               |

## Endpoints

### Listar clientes

`GET /api/clients` · alcance `clients:read`

Busca por nombre, nombre fantasía, RUT o email, con filtro por estado.

| Parámetro | Tipo                          | Descripción                                        |
| --------- | ----------------------------- | -------------------------------------------------- |
| `q`       | texto                         | Búsqueda por nombre, nombre fantasía, RUT o email. |
| `status`  | `activo` · `inactivo` · `all` | Estado del cliente. Por defecto, `activo`.         |
| `limit`   | número                        | Máximo de resultados. Por defecto 100, tope 500.   |

```bash theme={null}
curl "https://app.gocliente.com/api/clients?q=gonzalez&limit=20" \
  -H "Authorization: Bearer gck_..."
```

### Historial de un cliente

`GET /api/clients/:id/audit` · alcance `clients:read`

Devuelve la auditoría de las acciones hechas sobre un cliente.

```bash theme={null}
curl "https://app.gocliente.com/api/clients/clm_xxxxxx/audit" \
  -H "Authorization: Bearer gck_..."
```

### Crear un cliente

`POST /api/clients` · alcance `clients:write`

El único campo obligatorio es `name` (razón social). Si el RUT ya existe en el estudio, la respuesta es `409`.

| Campo          | Tipo   | Descripción                                               |
| -------------- | ------ | --------------------------------------------------------- |
| `name`         | texto  | Razón social. **Obligatorio.**                            |
| `fantasyName`  | texto  | Nombre fantasía.                                          |
| `taxId`        | texto  | RUT o CI.                                                 |
| `monthlyFee`   | número | Honorario mensual.                                        |
| `taxGroup`     | texto  | Grupo DGI, por ejemplo `CEDE`, `NO_CEDE` o `LITERAL_E`.   |
| `taxPayerType` | texto  | Tipo de contribuyente, por ejemplo Monotributo, SAS o SA. |

```bash theme={null}
curl -X POST "https://app.gocliente.com/api/clients" \
  -H "Authorization: Bearer gck_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Nueva Empresa SRL", "monthlyFee": 5000, "taxGroup": "CEDE"}'
```

### Obligaciones tributarias

`GET /api/obligations` · alcance `obligations:read`

| Parámetro     | Tipo                            | Descripción                            |
| ------------- | ------------------------------- | -------------------------------------- |
| `clientId`    | texto                           | Solo las de un cliente.                |
| `status`      | `PENDING` · `COMPLETED` · `all` | Estado. Por defecto, `all`.            |
| `from` / `to` | fecha `aaaa-mm-dd`              | Rango de vencimiento.                  |
| `limit`       | número                          | Máximo de resultados. Por defecto 100. |

```bash theme={null}
curl "https://app.gocliente.com/api/obligations?status=PENDING&from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer gck_..."
```

### Facturación mensual

`GET /api/billing` · alcance `billing:read`

Requiere `month` y `year`. Con `summary=true` suma los indicadores del mes: total facturado, cobrado, pendiente y tasa de cobranza.

| Parámetro  | Tipo             | Descripción                            |
| ---------- | ---------------- | -------------------------------------- |
| `month`    | 1 a 12           | Mes. **Obligatorio.**                  |
| `year`     | número           | Año. **Obligatorio.**                  |
| `clientId` | texto            | Solo un cliente.                       |
| `isPaid`   | `true` · `false` | Filtra por estado de pago.             |
| `summary`  | `true`           | Incluye los indicadores del mes.       |
| `limit`    | número           | Máximo de resultados. Por defecto 200. |

```bash theme={null}
curl "https://app.gocliente.com/api/billing?month=10&year=2026&summary=true" \
  -H "Authorization: Bearer gck_..."
```

### Tareas

`GET /api/tasks` · alcance `tasks:read`

Lista las tareas que no son privadas. Con `withColumns=true` devuelve el tablero Kanban ordenado por columnas.

| Parámetro     | Tipo                              | Descripción                            |
| ------------- | --------------------------------- | -------------------------------------- |
| `withColumns` | `true`                            | Devuelve la estructura del tablero.    |
| `clientId`    | texto                             | Solo las de un cliente.                |
| `priority`    | `LOW` · `MEDIUM` · `HIGH` · `all` | Prioridad.                             |
| `assigneeId`  | texto                             | Solo las de un integrante.             |
| `limit`       | número                            | Máximo de resultados. Por defecto 100. |

```bash theme={null}
curl "https://app.gocliente.com/api/tasks?withColumns=true" \
  -H "Authorization: Bearer gck_..."
```

### Equipo

`GET /api/team/members` · alcance `org:read`

Lista los integrantes de la organización.

```bash theme={null}
curl "https://app.gocliente.com/api/team/members" \
  -H "Authorization: Bearer gck_..."
```

<Note>
  ¿Necesitás un endpoint que no está en esta lista? Escribinos a [hola@gocliente.com](mailto:hola@gocliente.com).
</Note>