# Koolisys — API - [Introdução](https://docs-koolisys.eixoassistencia.com.br/introducao.md): Duas camadas: referência gerada do código e guias escritos para quem está chegando. - [Primeiros passos](https://docs-koolisys.eixoassistencia.com.br/primeiros-passos.md): Da chave de API à primeira chamada — sem reunião. - [Autenticação](https://docs-koolisys.eixoassistencia.com.br/autenticacao.md): Chave de longa duração, token de curta duração, e como cada um se comporta. - [Idempotência](https://docs-koolisys.eixoassistencia.com.br/idempotencia.md): Por que toda criação exige uma chave, e o que acontece ao repetir a chamada. - [Erros e limites](https://docs-koolisys.eixoassistencia.com.br/erros-e-limites.md): Os códigos estáveis, o que fazer com cada um, e como respeitar o rate limit. - [Abrir um atendimento](https://docs-koolisys.eixoassistencia.com.br/abrir-atendimento.md): Da elegibilidade ao acompanhamento, sem consultar outra fonte. - [Clientes e veículos](https://docs-koolisys.eixoassistencia.com.br/clientes-e-veiculos.md): Sincronizar a base de clientes do seu ERP: criar cliente, criar veículo, vincular o plano, conferir elegibilidade e abrir atendimento. - [Troca a chave de API por um token de curta duração](https://docs-koolisys.eixoassistencia.com.br/api-reference/auth/troca-a-chave-de-api-por-um-token-de-curta-duração.md): Recebe a chave de API como Bearer token e devolve um token JWT de curta duração, carregando os escopos concedidos à chave — exigido por todo endpoint de dados. Sem corpo de requisição: a chave de API vai no cabeçalho `Authorization: Bearer `. - [Lista atendimentos](https://docs-koolisys.eixoassistencia.com.br/api-reference/attendances/lista-atendimentos.md): Lista os atendimentos da contratante dona da chave, paginados por cursor. Nunca inclui rascunhos. - [Abre um atendimento](https://docs-koolisys.eixoassistencia.com.br/api-reference/attendances/abre-um-atendimento.md): Abre um atendimento aguardando a central escolher o prestador — esta chamada nunca aciona um prestador. Exige o cabeçalho Idempotency-Key: repetir a mesma chave com o mesmo corpo devolve o atendimento já criado (200), nunca um segundo atendimento. - [Consulta um atendimento](https://docs-koolisys.eixoassistencia.com.br/api-reference/attendances/consulta-um-atendimento.md): Consulta um atendimento pelo id. Um atendimento de outra contratante devolve a mesma resposta de recurso inexistente (404), nunca 403. - [Lista o catálogo de serviços](https://docs-koolisys.eixoassistencia.com.br/api-reference/services/lista-o-catálogo-de-serviços.md): Lista os serviços ativos do catálogo interno, até 100 itens, sem paginação. - [Lista os tipos de atendimento](https://docs-koolisys.eixoassistencia.com.br/api-reference/services/lista-os-tipos-de-atendimento.md): Lista os tipos de atendimento ativos com a categoria e os serviços que cada um agrupa, sem paginação. O `serviceId` do `POST /v1/attendances` precisa pertencer ao tipo escolhido. - [Consulta elegibilidade de cliente e veículo](https://docs-koolisys.eixoassistencia.com.br/api-reference/eligibility/consulta-elegibilidade-de-cliente-e-veículo.md): Verifica se um cliente e veículo têm cobertura ativa para acionar um atendimento. Só leitura — nunca consome cota de uso. - [Lista clientes](https://docs-koolisys.eixoassistencia.com.br/api-reference/customers/lista-clientes.md): Lista os clientes da contratante dona da chave, paginados por cursor, do mais recente ao mais antigo. `search` aceita nome, documento ou placa — o formato do termo decide. - [Cadastra um cliente](https://docs-koolisys.eixoassistencia.com.br/api-reference/customers/cadastra-um-cliente.md): Cadastra um cliente na contratante dona da chave. O documento (CPF/CNPJ) é único por contratante: um documento já cadastrado devolve 409 CUSTOMER_ALREADY_EXISTS com `details.customerId` apontando o registro existente. O cabeçalho Idempotency-Key é opcional: repetir a mesma chave com o mesmo corpo de… - [Consulta um cliente](https://docs-koolisys.eixoassistencia.com.br/api-reference/customers/consulta-um-cliente.md): Ficha do cliente com todos os veículos (ativos e inativos) e os vínculos de plano vigentes. Um cliente de outra contratante devolve a mesma resposta de recurso inexistente (404), nunca 403. - [Cadastra um veículo do cliente](https://docs-koolisys.eixoassistencia.com.br/api-reference/customers/cadastra-um-veículo-do-cliente.md): Cadastra um veículo no cliente informado (da contratante dona da chave). A placa é normalizada (maiúsculas, sem hífen) e é única entre os veículos ativos: uma placa já ativa devolve 409 VEHICLE_ALREADY_EXISTS — com `details.vehicleId` quando o veículo existente é da própria contratante, sem detalhes… - [Vincula um plano ao cliente](https://docs-koolisys.eixoassistencia.com.br/api-reference/customers/vincula-um-plano-ao-cliente.md): Vincula um plano do contrato (o `contractPlanId` de `GET /v1/company`) ao cliente informado. Só planos com `appliesTo: CUSTOMER` — um plano de veículo devolve 422 PLAN_TARGET_MISMATCH (use `POST /v1/vehicles/{id}/plans`). Plano inativo ou contrato fora de vigência devolve 422 PLAN_NOT_AVAILABLE; o m… - [Lista veículos](https://docs-koolisys.eixoassistencia.com.br/api-reference/vehicles/lista-veículos.md): Lista os veículos dos clientes da contratante dona da chave, paginados por cursor, do mais recente ao mais antigo. - [Consulta um veículo](https://docs-koolisys.eixoassistencia.com.br/api-reference/vehicles/consulta-um-veículo.md): Ficha do veículo com o cliente dono e o plano vigente que o cobre. Um veículo de outra contratante devolve a mesma resposta de recurso inexistente (404), nunca 403. - [Vincula um plano ao veículo](https://docs-koolisys.eixoassistencia.com.br/api-reference/vehicles/vincula-um-plano-ao-veículo.md): Vincula um plano do contrato (o `contractPlanId` de `GET /v1/company`) ao veículo informado. Só planos com `appliesTo: VEHICLE` — um plano de cliente devolve 422 PLAN_TARGET_MISMATCH (use `POST /v1/customers/{id}/plans`). Plano inativo ou contrato fora de vigência devolve 422 PLAN_NOT_AVAILABLE; o m… - [Consulta a própria contratante](https://docs-koolisys.eixoassistencia.com.br/api-reference/company/consulta-a-própria-contratante.md): Ficha da contratante dona da chave: dados cadastrais, contratos vigentes e os planos disponíveis nesses contratos (os que podem aparecer em `plans[]` dos clientes). - [Especificação OpenAPI da API pública](https://docs-koolisys.eixoassistencia.com.br/api-reference/meta/especificação-openapi-da-api-pública.md): Devolve o documento OpenAPI 3 gerado a partir do código: rotas, schemas de entrada, projeções de resposta, escopos e catálogo de erros da API pública (/v1/...). Nunca um arquivo mantido em paralelo. ## OpenAPI Specs - [openapi](/referencia/openapi.json) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.