> ## 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. # Clientes e veículos > Sincronizar a base de clientes do seu ERP: criar cliente, criar veículo, vincular o plano, conferir elegibilidade e abrir atendimento. 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](https://docs-koolisys.eixoassistencia.com.br/primeiros-passos.md)) 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. ```bash cURL theme={null} curl --request POST https://api-koolisys.eixoassistencia.com.br/v1/customers \ --header "Authorization: Bearer " \ --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" }' ``` ```js Node (fetch nativo) theme={null} const response = await fetch("https://api-koolisys.eixoassistencia.com.br/v1/customers", { method: "POST", headers: { Authorization: "Bearer ", "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](https://docs-koolisys.eixoassistencia.com.br/idempotencia.md)). * **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. ```bash cURL theme={null} curl --request POST https://api-koolisys.eixoassistencia.com.br/v1/customers/501/vehicles \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --data '{ "plate": "ABC1D23", "brand": "Fiat", "model": "Argo", "manufactureYear": 2022, "modelYear": 2023, "color": "Prata", "externalCode": "ERP-V-000456" }' ``` ```js Node (fetch nativo) theme={null} const response = await fetch( "https://api-koolisys.eixoassistencia.com.br/v1/customers/501/vehicles", { method: "POST", headers: { Authorization: "Bearer ", "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`. ```bash cURL (plano de cliente) theme={null} curl --request POST https://api-koolisys.eixoassistencia.com.br/v1/customers/501/plans \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --data '{ "contractPlanId": 73 }' ``` ```bash cURL (plano de veículo) theme={null} curl --request POST https://api-koolisys.eixoassistencia.com.br/v1/vehicles/9001/plans \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --data '{ "contractPlanId": 74 }' ``` ```js Node (fetch nativo) theme={null} const response = await fetch("https://api-koolisys.eixoassistencia.com.br/v1/customers/501/plans", { method: "POST", headers: { Authorization: "Bearer ", "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`): ```bash theme={null} # 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 " # 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 " # 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 " # Veículos: por placa, por cliente ou por situação curl "https://api-koolisys.eixoassistencia.com.br/v1/vehicles?plate=ABC1D23" \ --header "Authorization: Bearer " # A própria contratante: contratos vigentes e planos disponíveis curl https://api-koolisys.eixoassistencia.com.br/v1/company \ --header "Authorization: Bearer " ``` 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: ```bash theme={null} curl "https://api-koolisys.eixoassistencia.com.br/v1/eligibility?document=12345678900&plate=ABC1D23" \ --header "Authorization: Bearer " ``` Se `covered` vier `true`, abra o atendimento com `POST /v1/attendances` — o passo a passo completo está em [Abrir um atendimento](https://docs-koolisys.eixoassistencia.com.br/abrir-atendimento.md). 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.