# API

### Documentación de la API (Beta)

> ✨ **¡Bienvenido(a) a nuestra API Beta!**
>
> Esta funcionalidad está en desarrollo activo. Eso significa que podemos agregar nuevos endpoints y funcionalidades con el tiempo. Nos encantaría conocer tus comentarios, así que, si necesitas algo específico, ponte en contacto con nuestro equipo de soporte.

#### ¿Qué es la API de Bolten?

Nuestra API REST te permite interactuar programáticamente con los datos de tu proyecto en Bolten. Con ella, puedes leer, crear y actualizar información, abriendo un mundo de posibilidades para integraciones y automatizaciones.

**Casos de uso comunes**

* Crear oportunidades en Bolten a partir de un formulario en tu sitio web.
* Sincronizar datos de leads con una plataforma de Business Intelligence (BI).
* Integrar Bolten con otros sistemas internos de gestión (ERP).

***

#### Autenticación y autorización

La autenticación en nuestra API se realiza a través de una clave de API (API Key).

* **Clave por usuario:** Cada usuario en Bolten puede tener claves de API que estarán asociadas a su cuenta.
* **Acceso:** La clave de un proyecto concede acceso a los recursos disponibles según los permisos del usuario asociado. Por ejemplo, si el usuario es un socio y, dado que tiene permiso para acceder a algún componente de un proyecto de un cliente, si existe la ruta en la API, la acción en cuestión podrá ejecutarse.

#### **¿Cómo generar una clave de API para socios?**

En el área del socio, ve a la sección `API Keys` y haz clic en el botón en la esquina superior derecha (`+ API Key`). Hecho esto, aparecerá justo debajo un campo para que nombres tu clave. Recuerda usar un nombre que tenga sentido para el uso que le darás (por ejemplo, `clave n8n` en caso de que se utilice para integrar con n8n).

<figure><img src="https://1580422610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaHm1VFs056Yg2At7HGkE%2Fuploads%2FttXLC1UGYSNJBFEg1TbB%2Fimage.png?alt=media&#x26;token=0dbd0f0f-653f-4b5f-b9e3-5d0c9111ada5" alt=""><figcaption></figcaption></figure>

Después de eso, haz clic en el botón `Generar`. Con eso, la clave se creará y se mostrará en pantalla para que pueda copiarse.

{% hint style="warning" %}
Copia y guarda la clave en este momento. Después de eso ya no podrá recuperarse.
{% endhint %}

<figure><img src="https://1580422610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaHm1VFs056Yg2At7HGkE%2Fuploads%2FkWf12fVYlXi7Wr3JVhll%2Fimage.png?alt=media&#x26;token=c5cbba5e-9bde-4d1b-add8-6515ded23354" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Al hacer clic en el valor de la clave, se copiará automáticamente al portapapeles.
{% endhint %}

Si necesitas eliminar la clave, en el mismo panel haz clic en el icono de la papelera, en la misma línea donde aparece listada.

**¿Cómo autenticar solicitudes?**

Debes enviar tu clave de API en el encabezado `Authorization` de cada solicitud, utilizando el esquema `Bearer`.

`Authorization: Bearer TU_CLAVE_SECRETA_DEL_PROYECTO`

**Ejemplo con CURL:**

```bash
curl -X GET 'https://app.bolten.io/kanban/api/v1/4b646f9b-edc5-4314-9219-519f8c0838a8/opportunities' \
  -H 'Authorization: Bearer TU_CLAVE_SECRETA_DEL_PROYECTO'
```

***

#### Límite de tasa

Todos nuestros recursos están limitados a **1 solicitud por segundo** por clave de API. **Ese límite se verifica cada 10 segundos.**

**Los recursos diferentes se tratan dentro del mismo límite**. Un `GET /contact` y un `POST /opportunities` se tratan como 2 solicitudes, y podrías repetir ese flujo 5 veces en un intervalo de 10 s.

***

#### La estructura dinámica de las entidades

Uno de los recursos más potentes de Bolten es que la estructura de algunas entidades (sus campos) es totalmente personalizable por proyecto. Esto significa que, antes de crear o actualizar una oportunidad, contacto o negocio, es una buena práctica consultar qué campos están disponibles.

Para ello, utiliza el endpoint cuyo final termina en `/schema`. Este devolverá la estructura exacta de los campos configurados en tu proyecto.

Los componentes disponibles en la API que usan la estructura dinámica son:

* Opportunities (Gestión de oportunidades/Kanban)
* Contacts (Gestión de contactos)

#### **Regla de oro para creación y actualización**

Al enviar datos a los endpoints de creación (`POST`) y actualización (`PATCH`):

* Si el nombre de un campo en tu JSON **corresponde exactamente** al nombre de un campo configurado en el proyecto, su valor se guardará.
* Si un campo enviado **no existe** en el proyecto, será **ignorado silenciosamente**.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bolten.gitbook.io/bolten-docs/es/configuraciones-avanzadas/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.