Primeiros passos

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). 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:

curl --request POST https://api-koolisys.eixoassistencia.com.br/v1/auth/token \
  --header "Authorization: Bearer kls_EXEMPLO000000000000000000000000000000000000000000000000000000000"

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):

{
  "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.

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:

curl https://api-koolisys.eixoassistencia.com.br/v1/services \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb21wYW55SWQiOiJiNmYyYTZiMC02ZTBhLTRjMWEtOWMzYS0yZTZhMmI2YjZhMTAifQ.assinatura-fictícia"

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):

{
  "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 — consultar elegibilidade antes evita metade dos erros de criação.
Toda criação exige uma chave de idempotência: leia Idempotência antes de integrar POST /v1/attendances.
A referência completa de cada rota, campo e erro está em Referência.

Comece aqui

Conceitos

Fluxos

1. Obtenha a chave de API

2. Troque a chave por um token

3. Faça a primeira chamada

Próximos passos

​1. Obtenha a chave de API

​2. Troque a chave por um token

​3. Faça a primeira chamada

​Próximos passos

1. Obtenha a chave de API

2. Troque a chave por um token

3. Faça a primeira chamada

Próximos passos