> For the complete documentation index, see [llms.txt](https://help.ticto.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.ticto.com.br/sou-produtor/conta-e-cadastro/credenciais-de-api-v2.md).

# Credenciais de API - V2

A API da Ticto permite integrar sua conta com ferramentas externas, automações e sistemas de gestão. Com as **credenciais de API v2**, você controla com precisão quais permissões cada integração terá, sem expor dados desnecessários.

***

## &#x20;Índice

* [Como acessar as Credenciais de API](#como-acessar-os-tokens-de-api)
* [Como gerar um Token](#como-gerar-um-token)
* [Escopos disponíveis](#escopos-disponiveis)
* [Copiar o token gerado](#copiar-o-token-gerado)
* [Gerenciar tokens ativos](#gerenciar-tokens-ativos)
* [Excluir um token](#excluir-um-token)
* [Testando a API](#testando-a-api)

***

## Como acessar os Tokens de API

{% stepper %}
{% step %}
Clique no seu **avatar** no canto superior direito da plataforma.

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2Frti2LIi3MBQ7LmF0YfaA%2Fimage.png?alt=media&amp;token=aa7e1326-8760-44e0-87b2-9b213a946b7b" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
No menu suspenso, selecione **Credencias de API**<br>

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FURpzUW4YLCEHiX18YWcB%2Fimage.png?alt=media&amp;token=637fed48-ed83-4267-ba6e-223fe0734cec" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
Você será direcionado para a tela de **Credenciais de API, na aba API v2.**\ <br>

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FIU1Kv5IuEHQeyBvdrC4a%2Fimage.png?alt=media&amp;token=2f14ac62-95b8-4c17-8ea6-3671db4d28eb" alt=""><figcaption></figcaption></figure></div>
{% endstep %}
{% endstepper %}

{% hint style="info" %}
💡 A tela exibe um resumo do fluxo de uso: **01** Nomeie e escolha os escopos → **02** Copie o token → **03** Use no header `Authorization: Bearer` → **04** Envie o `Idempotency-Key` em toda criação.
{% endhint %}

***

## Como gerar um Token

{% stepper %}
{% step %}
Clique no botão + Gerar token no canto superior direito.

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FP9QhkpaLZBl7mSei5gKz%2Fimage.png?alt=media&amp;token=2f136ced-478e-45a2-a9f2-59d50f9afd51" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
Preencha os campos do formulário e  defina os escopos de permissão que o token terá.

| Campo             | Descrição                                                              |
| ----------------- | ---------------------------------------------------------------------- |
| **Nome do token** | Identifique a integração. Ex.: `Integração central`                    |
| **Expira em**     | Data de expiração (opcional). Deixe em branco para token sem validade. |

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2Fak1ZgE5MObRTGzjE3FF2%2Fimage.png?alt=media&amp;token=4040c5ad-9ccf-4b49-9338-96662629aefc" alt=""><figcaption></figcaption></figure></div>

## Escopos disponíveis

Selecione apenas os escopos que a integração realmente precisa. Os escopos definem o que o token pode acessar ou executar.

### Acesso padrão

| Escopo              | Permissão                     | Código               |
| ------------------- | ----------------------------- | -------------------- |
| **Ler produtos**    | Consulta a lista de produtos  | `products:read`      |
| **Criar produtos**  | Cria e edita produtos         | `products:write`     |
| **Ler ofertas**     | Consulta ofertas cadastradas  | `offers:read`        |
| **Criar ofertas**   | Cria e edita ofertas          | `offers:write`       |
| **Ler pedidos**     | Consulta histórico de pedidos | `orders:read`        |
| **Ler assinaturas** | Consulta assinaturas ativas   | `subscriptions:read` |

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FhYwAgCDWOBHvUJcjRAkz%2Fimage.png?alt=media&amp;token=4f93158e-2e5f-42a1-a380-c2af518756e2" alt=""><figcaption></figcaption></figure></div>

### ⚠️ Dado financeiro

| Escopo         | Permissão                           | Código          |
| -------------- | ----------------------------------- | --------------- |
| **Ler saques** | Acesso a dados financeiros de saque | `cashouts:read` |

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FEzkh9vLao0bXfEsROahb%2Fimage.png?alt=media&amp;token=4116c178-ef55-4eb9-b3b3-b076e9b3d27b" alt=""><figcaption></figcaption></figure></div>

### 🚫 Ação destrutiva

{% hint style="warning" %}
⚠️ Conceda acesso a saques apenas se a integração realmente precisar. De preferência, use um **token separado** exclusivamente para isso.
{% endhint %}

| Escopo                   | Permissão                                         | Código                 |
| ------------------------ | ------------------------------------------------- | ---------------------- |
| **Cancelar assinaturas** | Cancela assinaturas de verdade, sem como desfazer | `subscriptions:cancel` |

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FDvs5qnCZ4O1auM2nFQQW%2Fimage.png?alt=media&amp;token=28d7231e-d412-4991-ba03-f73e23d40eac" alt=""><figcaption></figcaption></figure></div>

{% hint style="danger" %}
&#x20;O escopo **Cancelar assinaturas** executa uma ação irreversível. Nunca combine este escopo com outros. Use um token separado exclusivamente para essa finalidade.
{% endhint %}
{% endstep %}

{% step %}
Use os atalhos de seleção rápida para marcar grupos de escopos:

* **Somente leitura** — marca todos os escopos de leitura
* **Gerenciar catálogo** — marca produtos e ofertas (leitura e escrita)
* **Relatórios** — marca pedidos e assinaturas
  {% endstep %}

{% step %}
Após preencher os campos e definir as permissões. Clique em **Gerar token.**

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2Fa9BeI1egaI9C6NFhMYH5%2Fimage.png?alt=media&amp;token=e7c56b17-3a56-4c07-9f51-4169945a7bb3" alt=""><figcaption></figcaption></figure></div>
{% endstep %}
{% endstepper %}

***

## Copiar o token gerado

Após clicar em **Gerar token**, uma janela exibirá o token gerado.

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FARyZFTlJ2u33lgwiR4mt%2Fimage.png?alt=media&amp;token=637a1f49-fe98-4757-a7fa-0f769a0b2503" alt=""><figcaption></figcaption></figure></div>

{% hint style="danger" %}
🔐 **O token é exibido apenas uma vez.** Copie imediatamente e guarde em local seguro. Caso perca o token, será necessário excluí-lo e gerar um novo.
{% endhint %}

{% hint style="warning" %}
⚠️ **Não compartilhe seu token.** O uso indevido pode comprometer dados e integrações da sua conta.
{% endhint %}

***

## Gerenciar tokens ativos

Na tela de **Tokens da API v2**, todos os tokens criados são listados com as seguintes informações:

| Coluna         | Descrição                                         |
| -------------- | ------------------------------------------------- |
| **Nome**       | Identificação definida na criação                 |
| **Token**      | Valor parcial do token (formato `ticto_live_...`) |
| **Escopos**    | Permissões atribuídas ao token                    |
| **Último uso** | Data da última requisição autenticada             |
| **Ações**      | Opção para excluir o token                        |

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FcHE8uhfcpsdLlUTq6foz%2Fimage.png?alt=media&amp;token=14678557-3774-4ab0-99bf-4a96803f30bb" alt=""><figcaption></figcaption></figure></div>

***

## Excluir um token

Na lista de tokens, clique no **ícone de lixeira 🗑️** na coluna **Ações** ao lado do token que deseja remover.

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2F8JZap0jhdsGlhuW9Zfuq%2Fimage.png?alt=media&amp;token=f96f8089-5cfe-4e2a-a18b-23910a599699" alt=""><figcaption></figcaption></figure></div>

{% hint style="danger" %}
&#x20;Ao excluir um token, todas as integrações que o utilizam deixarão de funcionar imediatamente.
{% endhint %}

***

## Testando a API

A Ticto disponibiliza uma documentação interativa para testar os endpoints antes de integrar. <https://docs.ticto.com.br/introduction>

{% stepper %}
{% step %}
Na tela de tokens, clique em Documentação (canto superior direito).

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FShXvtd49noohQXvDgU1D%2Fimage.png?alt=media&amp;token=fc4b756d-de35-4a9b-a8fa-eef8a5571761" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
Na documentação, acesse a aba API Reference.

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FAkaBeytUe2kSQ79rp24o%2Fimage.png?alt=media&amp;token=c137a17f-ee34-47b6-9d09-986c97046c16" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
No menu lateral esquerdo, selecione o escopo e o endpoint que deseja testar. Ex.: Produtos → Listar produtos.

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2F3yqwAzLFJviGXbRGhXrD%2Fimage.png?alt=media&amp;token=d4a3ba94-75a6-4ace-a65c-119593eb7337" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
Clique em Try it ▶ para abrir o modo de teste interativo.

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FrkOLjxy5NP3H3Z31Oogm%2Fimage.png?alt=media&amp;token=c107bd6f-38a3-4d17-b779-db968452794a" alt=""><figcaption></figcaption></figure></div>

{% endstep %}

{% step %}
No campo Authorization, informe o token gerado no painel no formato:

```
Bearer ticto_live_seu_token_aqui
```

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2FLwwo8UibGXeCTiMtNBNx%2Fimage.png?alt=media&amp;token=5cb5f596-c05c-4765-8ac1-4ab5f8bea597" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
Clique em Send ▶ para enviar a requisição.

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2F3BIApSbawmf0u2L3yY24%2Fimage.png?alt=media&amp;token=66dff23a-ddd3-4372-a0f8-d92ab39b3b7c" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
O resultado da consulta ou ação será exibido na seção Response, com o código de status e os dados retornados.

<div data-with-frame="true"><figure><img src="https://3610983464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnWIfc9hpnMPQKmkeC8kA%2Fuploads%2Fbyc4EPsW8UkTmWAW7lQ4%2Fimage.png?alt=media&amp;token=bc1f545b-2c0d-4b4d-94b5-f9e5428d1fc7" alt=""><figcaption></figcaption></figure></div>

{% hint style="success" %}
✅ Um retorno **200 - OK** confirma que o token está funcionando corretamente e a integração está ativa.
{% endhint %}
{% endstep %}
{% endstepper %}
