> For the complete documentation index, see [llms.txt](https://bolten.gitbook.io/bolten-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bolten.gitbook.io/bolten-docs/configuracoes-avancadas/api.md).

# 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**.