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

# Primeiros passos

> Da chave de API à primeira chamada — sem reunião.

Este guia leva você da chave de API na mão até a primeira resposta da Koolisys. Três passos:
obter a chave, trocar por token, fazer a primeira chamada.

## 1. Obtenha a chave de API

A chave é criada pela equipe da Koolisys, nas telas internas de gestão de contratantes — não existe
autoatendimento para isso. Peça à Koolisys que gere uma chave para a sua empresa, informando os
escopos que a integração precisa (ver [Autenticação](https://docs-koolisys.eixoassistencia.com.br/autenticacao.md#escopos)).

O segredo completo (algo como `kls_ab12cd34...`) aparece **uma única vez**, no momento da criação.
Copie e guarde com segurança — a Koolisys nunca consegue mostrá-lo de novo, só revogar e emitir
outro.

A chave em si nunca autentica uma chamada de dados diretamente: ela só serve para o passo seguinte.

## 2. Troque a chave por um token

Toda chamada de dados usa um token de curta duração, obtido com `POST /v1/auth/token`. Envie a
chave como Bearer token — sem corpo de requisição:

```bash cURL theme={null}
curl --request POST https://api-koolisys.eixoassistencia.com.br/v1/auth/token \
  --header "Authorization: Bearer kls_EXEMPLO000000000000000000000000000000000000000000000000000000000"
```

```js Node (fetch nativo) theme={null}
const response = await fetch("https://api-koolisys.eixoassistencia.com.br/v1/auth/token", {
  method: "POST",
  headers: {
    Authorization: "Bearer kls_EXEMPLO000000000000000000000000000000000000000000000000000000000",
  },
});

const body = await response.json();
console.log(body.data.token);
```

Resposta (`200`):

```json theme={null}
{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb21wYW55SWQiOiJiNmYyYTZiMC02ZTBhLTRjMWEtOWMzYS0yZTZhMmI2YjZhMTAifQ.assinatura-fictícia",
    "tokenType": "Bearer",
    "expiresAt": "2026-08-20T13:15:00.000Z"
  },
  "meta": {},
  "errors": []
}
```

O token vale por 15 minutos (900 segundos) e carrega os escopos concedidos à chave. Guarde-o em
memória, não em disco — ele expira sozinho e um novo se pede com a mesma chamada acima. Mais
detalhes em [Autenticação](https://docs-koolisys.eixoassistencia.com.br/autenticacao.md).

## 3. Faça a primeira chamada

Com o token em mãos, use-o como Bearer token em qualquer endpoint de dados. O mais simples para
validar que tudo está funcionando é listar o catálogo de serviços, que não exige nenhum parâmetro:

```bash cURL theme={null}
curl https://api-koolisys.eixoassistencia.com.br/v1/services \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb21wYW55SWQiOiJiNmYyYTZiMC02ZTBhLTRjMWEtOWMzYS0yZTZhMmI2YjZhMTAifQ.assinatura-fictícia"
```

```js Node (fetch nativo) theme={null}
const response = await fetch("https://api-koolisys.eixoassistencia.com.br/v1/services", {
  headers: {
    Authorization:
      "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb21wYW55SWQiOiJiNmYyYTZiMC02ZTBhLTRjMWEtOWMzYS0yZTZhMmI2YjZhMTAifQ.assinatura-fictícia",
  },
});

const body = await response.json();
console.log(body.data);
```

Resposta (`200`):

```json theme={null}
{
  "data": [
    { "id": 1, "name": "Guincho", "category": null },
    { "id": 2, "name": "Chaveiro", "category": null }
  ],
  "meta": {},
  "errors": []
}
```

Se a resposta vier com `401` e `code: "INVALID_TOKEN"`, o token expirou ou está mal formado — peça
um novo repetindo o passo 2. Se vier `503` e `code: "FEATURE_DISABLED"`, a API pública ainda não foi
habilitada para a sua contratante — fale com a Koolisys.

## Próximos passos

* Para abrir um atendimento de verdade, comece por [Abrir um atendimento](https://docs-koolisys.eixoassistencia.com.br/abrir-atendimento.md) —
  consultar elegibilidade antes evita metade dos erros de criação.
* Toda criação exige uma chave de idempotência: leia [Idempotência](https://docs-koolisys.eixoassistencia.com.br/idempotencia.md) antes de
  integrar `POST /v1/attendances`.
* A referência completa de cada rota, campo e erro está em [Referência](https://docs-koolisys.eixoassistencia.com.br/referencia/openapi).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.