Clientes e veículos

Este guia cobre o fluxo de sincronizar a base de clientes da sua contratante pela API pública: cadastrar o cliente, cadastrar os veículos dele, vincular o plano, conferir a cobertura e — quando precisar — abrir o atendimento. Todos os exemplos assumem um token já obtido (veja Primeiros passos) com os escopos customers.write, vehicles.write, plans.write, eligibility.read e attendances.write. Duas regras valem para tudo nesta página:

Tudo é escopado pela sua contratante. Um id de cliente, veículo ou plano de outra contratante responde 404 NOT_FOUND, indistinguível de um id inexistente.
O plano dita o alvo do vínculo. Cada plano de GET /v1/company diz em appliesTo se cobre o cliente inteiro (CUSTOMER) ou veículo a veículo (VEHICLE) — e o vínculo só pode ser feito nesse alvo. Encerrar ou trocar um vínculo continua sendo feito pela Koolisys.

1. Cadastre o cliente

POST /v1/customers cadastra o cliente na sua contratante. Só o documento e o nome são obrigatórios; type (PF/PJ) é inferido do documento quando omitido. Use externalCode para guardar o código do cliente no seu ERP — ele é único dentro da contratante.

curl --request POST https://api-koolisys.eixoassistencia.com.br/v1/customers \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: 3a1f0e9b-7c2d-4e5f-9a8b-1c2d3e4f5a6b" \
  --data '{
    "document": "12345678900",
    "name": "Maria da Silva",
    "phone": "11999998888",
    "email": "maria@exemplo.com.br",
    "birthDate": "1990-05-10",
    "city": "São Paulo",
    "state": "SP",
    "externalCode": "ERP-000123"
  }'

const response = await fetch("https://api-koolisys.eixoassistencia.com.br/v1/customers", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    document: "12345678900",
    name: "Maria da Silva",
    phone: "11999998888",
    email: "maria@exemplo.com.br",
    birthDate: "1990-05-10",
    city: "São Paulo",
    state: "SP",
    externalCode: "ERP-000123",
  }),
});

const body = await response.json();
console.log(body.data.id); // ex.: 501

A resposta (201) devolve a ficha completa — incluindo vehicles: [] e plans: [], ainda vazios. Guarde data.id: é ele que você usa nas outras chamadas. Três detalhes que valem dinheiro numa carga em lote:

Idempotency-Key é opcional, mas use. Repetir a mesma chave com o mesmo corpo devolve o mesmo cliente com 200, nunca um segundo cadastro — o timeout de rede vai acontecer (veja Idempotência).
Documento duplicado não é erro fatal. Um documento já cadastrado na sua contratante devolve 409 CUSTOMER_ALREADY_EXISTS com errors[0].details.customerId apontando o registro existente — siga com esse id em vez de tentar de novo.
O documento é validado de verdade (dígito verificador de CPF/CNPJ) — pontuação é ignorada.

2. Cadastre os veículos do cliente

POST /v1/customers/{id}/vehicles cadastra um veículo no cliente. Só a placa é obrigatória — ela é normalizada (maiúsculas, sem hífen) e é única entre os veículos ativos de todo o sistema.

curl --request POST https://api-koolisys.eixoassistencia.com.br/v1/customers/501/vehicles \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "plate": "ABC1D23",
    "brand": "Fiat",
    "model": "Argo",
    "manufactureYear": 2022,
    "modelYear": 2023,
    "color": "Prata",
    "externalCode": "ERP-V-000456"
  }'

const response = await fetch(
  "https://api-koolisys.eixoassistencia.com.br/v1/customers/501/vehicles",
  {
    method: "POST",
    headers: { Authorization: "Bearer <token>", "Content-Type": "application/json" },
    body: JSON.stringify({
      plate: "ABC1D23",
      brand: "Fiat",
      model: "Argo",
      manufactureYear: 2022,
      modelYear: 2023,
      color: "Prata",
      externalCode: "ERP-V-000456",
    }),
  },
);

const body = await response.json();
console.log(body.data.id, body.data.plate); // ex.: 9001 "ABC1D23"

Uma placa já ativa devolve 409 VEHICLE_ALREADY_EXISTS. Quando o veículo existente é da sua própria contratante, errors[0].details.vehicleId aponta o registro — siga com ele. Quando a placa está ativa em outra contratante, o 409 vem sem detalhes: a API não revela nada sobre dados de terceiros. A placa de um veículo excluído fica livre e pode ser recadastrada.

3. Vincule o plano

Sem plano vigente não há cobertura. Descubra os planos disponíveis em GET /v1/company (escopo company.read) — cada item traz o contractPlanId, o nome e o appliesTo. Aí vincule (escopo plans.write): plano de cliente em POST /v1/customers/{id}/plans, plano de veículo em POST /v1/vehicles/{id}/plans.

curl --request POST https://api-koolisys.eixoassistencia.com.br/v1/customers/501/plans \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{ "contractPlanId": 73 }'

curl --request POST https://api-koolisys.eixoassistencia.com.br/v1/vehicles/9001/plans \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{ "contractPlanId": 74 }'

const response = await fetch("https://api-koolisys.eixoassistencia.com.br/v1/customers/501/plans", {
  method: "POST",
  headers: { Authorization: "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({ contractPlanId: 73 }),
});

const body = await response.json();
console.log(body.data.planName, body.data.startedAt);

A resposta (201) é o vínculo criado — o mesmo objeto que aparece em plans[] na ficha do cliente. O que pode dar errado:

422 PLAN_TARGET_MISMATCH — o plano se aplica ao outro alvo: um plano VEHICLE não vincula pelo cliente, nem um plano CUSTOMER pelo veículo. Use a outra rota.
409 PLAN_ALREADY_LINKED — esse plano já está vigente nesse cliente/veículo; errors[0].details.beneficiaryPlanId aponta o vínculo existente — siga com ele.
422 PLAN_NOT_AVAILABLE — o plano está inativo no contrato, ou o contrato saiu de vigência.
404 NOT_FOUND — cliente, veículo ou contractPlanId inexistente ou de outra contratante.

O vínculo vale a partir do momento da criação. Um cliente/veículo pode ter mais de um plano vigente ao mesmo tempo (planos diferentes) — o que a API recusa é duplicar o mesmo plano.

4. Confira a base

Consultas para manter o seu ERP em dia (escopos customers.read / vehicles.read / company.read):

# Ficha do cliente, com veículos e vínculos de plano vigentes
curl https://api-koolisys.eixoassistencia.com.br/v1/customers/501 \
  --header "Authorization: Bearer <token>"

# Listagem paginada por cursor; `search` aceita nome, documento ou placa
curl "https://api-koolisys.eixoassistencia.com.br/v1/customers?limit=50&search=Maria" \
  --header "Authorization: Bearer <token>"

# Sincronização incremental: só o que mudou desde a última carga
curl "https://api-koolisys.eixoassistencia.com.br/v1/customers?updatedSince=2026-08-01T00:00:00.000Z" \
  --header "Authorization: Bearer <token>"

# Veículos: por placa, por cliente ou por situação
curl "https://api-koolisys.eixoassistencia.com.br/v1/vehicles?plate=ABC1D23" \
  --header "Authorization: Bearer <token>"

# A própria contratante: contratos vigentes e planos disponíveis
curl https://api-koolisys.eixoassistencia.com.br/v1/company \
  --header "Authorization: Bearer <token>"

As listagens paginam por cursor: repasse meta.nextCursor em ?cursor= até ele vir null (limit máximo de 100 por página). Na ficha do cliente, plans[] mostra os vínculos vigentes — appliesTo diz se o plano cobre o cliente inteiro (CUSTOMER) ou veículo a veículo (VEHICLE). GET /v1/company mostra de onde esses vínculos podem vir: os planos disponíveis nos contratos vigentes da sua contratante.

5. Elegibilidade e atendimento

Com o cliente e o veículo cadastrados e o plano vinculado, o resto é o fluxo que você já conhece:

curl "https://api-koolisys.eixoassistencia.com.br/v1/eligibility?document=12345678900&plate=ABC1D23" \
  --header "Authorization: Bearer <token>"

Se covered vier true, abra o atendimento com POST /v1/attendances — o passo a passo completo está em Abrir um atendimento. Se vier false, o cliente ainda não tem plano vigente para o serviço: confira o vínculo (passo 3) e o catálogo do plano antes de tentar criar (uma criação sem cobertura devolve 422 NOT_COVERED).

Fora do alcance da API

Nesta versão a API pública não altera nem exclui clientes e veículos (só cria e lê), não cria contratantes ou contratos, e não encerra nem troca vínculos de plano (só cria). Precisa corrigir um cadastro ou encerrar um vínculo? Fale com a central da Koolisys.

Comece aqui

Conceitos

Fluxos

1. Cadastre o cliente

2. Cadastre os veículos do cliente

3. Vincule o plano

4. Confira a base

5. Elegibilidade e atendimento

Fora do alcance da API

​1. Cadastre o cliente

​2. Cadastre os veículos do cliente

​3. Vincule o plano

​4. Confira a base

​5. Elegibilidade e atendimento

​Fora do alcance da API

1. Cadastre o cliente

2. Cadastre os veículos do cliente

3. Vincule o plano

4. Confira a base

5. Elegibilidade e atendimento

Fora do alcance da API