# API

### Documentação da API (Beta)

> ✨ **Bem-vindo(a) à nossa API Beta!**
>
> Esta funcionalidade está em desenvolvimento ativo. Isso significa que podemos adicionar novos endpoints e funcionalidades com o tempo. Adoraríamos ouvir seu feedback, então, se precisar de algo específico, entre em contato com nossa equipe de suporte.

#### O que é a API da Bolten?

Nossa API REST permite que você interaja programaticamente com os dados do seu projeto na Bolten. Com ela, você pode ler, criar e atualizar informações, abrindo um mundo de possibilidades para integrações e automações.

**Casos de Uso Comuns**

* Criar oportunidades na Bolten a partir de um formulário no seu site.
* Sincronizar dados de leads com uma plataforma de Business Intelligence (BI).
* Integrar a Bolten com outros sistemas internos de gestão (ERP).

***

#### Autenticação e Autorização

A autenticação na nossa API é feita através de uma Chave de API (API Key).

* **Chave por Usuário:** Cada usuário na Bolten pode ter chaves de API que estarão associadas à sua conta.
* **Acesso:** A chave de um projeto concede acesso aos recursos disponíveis conforme as permissões do usuário associado. Por exemplo, caso o usuário seja um parceiro e, dado que o mesmo tem a permissão de acessar algum componente de um projeto de um cliente, se existir a rota na API, a ação em questão poderá ser executada.

#### **Como gerar uma chave de API para parceiros?**

Na área do parceiro, vá até a seção `API Keys` e clique no botão no canto superior direito (`+ API Key`). Feito isso, logo abaixo aparecerá um campo para você nomear a sua chave. Lembre-se de utilizar um nome que faça sentido para o uso que você dará para a mesma (por exemplo, `chave n8n` caso seja utilizada para integrar com o 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>

Após isso, clique no botão `Gerar`. Com isso, a chave será criada e exibida na tela para ser copiada.

{% hint style="warning" %}
Copie e guarde a chave neste momento. Após isso ela não poderá mais ser recuperada.
{% 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" %}
Clicando no valor da chave, ela será automaticamente copiada para a área de transferência.
{% endhint %}

Caso necessite apagar a chave, no mesmo painel, clique no ícone do lixo, na mesma linha que a mesma se encontra listada.

**Como Autenticar Requisições?**

Você deve enviar sua Chave de API no cabeçalho `Authorization` de cada requisição, utilizando o esquema `Bearer`.

`Authorization: Bearer SUA_CHAVE_SECRETA_DO_PROJETO`

**Exemplo com CURL:**

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

***

#### Rate limit

Todos os nossos recursos são limitados a **1 requisição por segundo** por chave de API. **Esse limite é checado a cada 10 segundos.**

**Recursos diferentes são tratados dentro do mesmo limite**. Um `GET /contact` e um `POST /opportunities` são tratados como 2 requisições, e você poderia repetir esse fluxo 5 vezes num intervalo de 10s.

***

#### A Estrutura Dinâmica das entidades

Um dos recursos mais poderosos da Bolten é que a estrutura de algumas entidades (seus campos) é totalmente customizável por projeto. Isso significa que, antes de criar ou atualizar uma oportunidade, contato ou negócio, é uma boa prática consultar quais campos estão disponíveis.

Para isso, utilize o endpoint cujo final termina em `/schema`. Ele retornará a estrutura exata dos campos configurados no seu projeto.

Os componentes disponibilizados na API que usam a estrutura dinâmica são:

* Opportunities (Gestão de oportunidades/Kanban)
* Contacts (Gestão de contatos)

#### **Regra de Ouro para Criação e Atualização**

Ao enviar dados para os endpoints de criação (`POST`) e atualização (`PATCH`):

* Se o nome de um campo no seu JSON **corresponder exatamente** ao nome de um campo configurado no projeto, seu valor será salvo.
* Se um campo enviado **não existir** no projeto, ele será **silenciosamente ignorado**.


---

# Agent Instructions: 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/configuracoes-avancadas/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.