> ## 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. # Cadastra um cliente > 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 devolve o cliente já criado (200), nunca um segundo cadastro. O vínculo de plano é um passo separado — `POST /v1/customers/{id}/plans`. ## OpenAPI ````yaml /referencia/openapi.json post /v1/customers openapi: 3.0.0 info: title: Koolisys — API Pública description: >- Contrato da API pública de integração da Koolisys: atendimentos, catálogo de serviços, elegibilidade, cadastro e consulta de clientes e veículos e a própria contratante. Gerada a partir do código — rotas, DTOs de entrada, projeções de resposta e escopos declarados —, nunca mantida à mão. version: 1.0.0 contact: {} servers: - url: https://api-koolisys.eixoassistencia.com.br description: API pública da Koolisys security: [] tags: - name: auth description: Emissão do token de curta duração a partir da chave de API - name: attendances description: Abertura, consulta e listagem de atendimentos - name: services description: Catálogo de serviços disponíveis - name: eligibility description: Consulta de elegibilidade de cliente e veículo - name: customers description: Cadastro, consulta, busca e listagem de clientes da contratante - name: vehicles description: Consulta e listagem de veículos da contratante - name: company description: 'A própria contratante: contratos vigentes e planos disponíveis' - name: meta description: A própria especificação paths: /v1/customers: post: tags: - customers summary: Cadastra um cliente description: >- 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 devolve o cliente já criado (200), nunca um segundo cadastro. O vínculo de plano é um passo separado — `POST /v1/customers/{id}/plans`. operationId: PublicCustomersController_create parameters: - name: Idempotency-Key in: header description: >- Identificador único da tentativa de cadastro, gerado pelo integrador (opcional) required: false schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePublicCustomerRequestDto' examples: default: value: document: '12345678900' type: PF name: Maria da Silva phone: '11999998888' email: maria@exemplo.com.br birthDate: '1990-05-10' contractDate: '2026-08-01' zipCode: 01310-100 addressLine: Av. Paulista number: '1000' complement: Sala 12 district: Bela Vista city: São Paulo state: SP externalCode: ERP-000123 responses: '200': description: Repetição idempotente — devolve o mesmo cliente já cadastrado content: application/json: schema: type: object required: - data - meta - errors properties: data: $ref: '#/components/schemas/PublicCustomer' meta: type: object description: Metadados da resposta — vazio nesta operação. properties: {} errors: type: array description: Sempre vazio numa resposta de sucesso. items: type: object maxItems: 0 example: data: id: 501 type: PF name: Maria da Silva socialName: null document: '12345678900' phone: '11999998888' email: maria@exemplo.com.br birthDate: '1990-05-10' contractDate: '2026-08-01' externalCode: ERP-000123 zipCode: 01310-100 addressLine: Av. Paulista number: '1000' complement: Sala 12 district: Bela Vista city: São Paulo state: SP status: ACTIVE createdAt: '2026-08-20T13:00:00.000Z' updatedAt: '2026-08-20T13:00:00.000Z' vehicles: - id: 9001 customerId: 501 plate: ABC1D23 chassis: 9BWZZZ377VT004251 renavam: '12345678901' brand: Fiat model: Argo manufactureYear: 2022 modelYear: 2023 color: Prata externalCode: ERP-V-000456 status: ACTIVE createdAt: '2026-08-20T13:02:00.000Z' updatedAt: '2026-08-20T13:02:00.000Z' plans: - contractPlanId: 73 contractCode: CT-2026-0001 planName: Plano Proteção Total appliesTo: CUSTOMER linkedTo: CUSTOMER vehicleId: null startedAt: '2026-08-20T13:05:00.000Z' meta: {} errors: [] '201': description: Cliente cadastrado content: application/json: schema: type: object required: - data - meta - errors properties: data: $ref: '#/components/schemas/PublicCustomer' meta: type: object description: Metadados da resposta — vazio nesta operação. properties: {} errors: type: array description: Sempre vazio numa resposta de sucesso. items: type: object maxItems: 0 example: data: id: 501 type: PF name: Maria da Silva socialName: null document: '12345678900' phone: '11999998888' email: maria@exemplo.com.br birthDate: '1990-05-10' contractDate: '2026-08-01' externalCode: ERP-000123 zipCode: 01310-100 addressLine: Av. Paulista number: '1000' complement: Sala 12 district: Bela Vista city: São Paulo state: SP status: ACTIVE createdAt: '2026-08-20T13:00:00.000Z' updatedAt: '2026-08-20T13:00:00.000Z' vehicles: - id: 9001 customerId: 501 plate: ABC1D23 chassis: 9BWZZZ377VT004251 renavam: '12345678901' brand: Fiat model: Argo manufactureYear: 2022 modelYear: 2023 color: Prata externalCode: ERP-V-000456 status: ACTIVE createdAt: '2026-08-20T13:02:00.000Z' updatedAt: '2026-08-20T13:02:00.000Z' plans: - contractPlanId: 73 contractCode: CT-2026-0001 planName: Plano Proteção Total appliesTo: CUSTOMER linkedTo: CUSTOMER vehicleId: null startedAt: '2026-08-20T13:05:00.000Z' meta: {} errors: [] '400': description: VALIDATION_ERROR content: application/json: example: data: null errors: - code: VALIDATION_ERROR message: 'customerDocument: Documento do cliente é obrigatório' field: customerDocument '401': description: INVALID_TOKEN content: application/json: example: data: null errors: - code: INVALID_TOKEN message: Token inválido. '403': description: INSUFFICIENT_SCOPE content: application/json: example: data: null errors: - code: INSUFFICIENT_SCOPE message: Escopo insuficiente para este endpoint. details: requiredScope: attendances.read '409': description: IDEMPOTENCY_CONFLICT content: application/json: example: data: null errors: - code: IDEMPOTENCY_CONFLICT message: >- Chave de idempotência já usada com um corpo de requisição diferente. '429': description: RATE_LIMITED content: application/json: example: data: null errors: - code: RATE_LIMITED message: Limite de requisições excedido. details: retryAfterSeconds: 42 '503': description: FEATURE_DISABLED content: application/json: example: data: null errors: - code: FEATURE_DISABLED message: 'Feature is disabled: public_api.enabled' security: - apiToken: [] components: schemas: CreatePublicCustomerRequestDto: type: object properties: document: type: string example: '12345678900' description: >- CPF ou CNPJ. Pontuação é ignorada; o documento é validado pelo `type`. type: type: string enum: - PF - PJ example: PF description: >- PF ou PJ. Quando ausente, é inferido do documento: 11 dígitos → PF, 14 dígitos → PJ. name: type: string example: Maria da Silva description: Nome ou razão social phone: type: string example: '11999998888' email: type: string example: maria@exemplo.com.br birthDate: type: string format: date example: '1990-05-10' description: Data de nascimento (`YYYY-MM-DD`) contractDate: type: string format: date example: '2026-08-01' description: Data de contratação junto ao parceiro (`YYYY-MM-DD`) zipCode: type: string example: 01310-100 addressLine: type: string example: Av. Paulista number: type: string example: '1000' complement: type: string example: Sala 12 district: type: string example: Bela Vista city: type: string example: São Paulo state: type: string example: SP description: UF, duas letras maiúsculas externalCode: type: string example: ERP-000123 description: >- Código do cliente no sistema do parceiro — único dentro da contratante required: - document - name PublicCustomer: type: object properties: id: type: integer format: int32 description: Identificador do cliente. type: type: string enum: - PF - PJ description: PF (pessoa física, CPF) ou PJ (pessoa jurídica, CNPJ). name: type: string description: Nome completo ou razão social. socialName: type: string nullable: true description: Nome social ou nome fantasia, quando informado. document: type: string description: CPF ou CNPJ, só dígitos. phone: type: string nullable: true description: Telefone de contato. email: type: string nullable: true description: E-mail de contato. birthDate: type: string format: date nullable: true description: Data de nascimento (`YYYY-MM-DD`). contractDate: type: string format: date nullable: true description: Data de contratação junto ao parceiro (`YYYY-MM-DD`). externalCode: type: string nullable: true description: Código do cliente no sistema do parceiro, informado no cadastro. zipCode: type: string nullable: true description: CEP. addressLine: type: string nullable: true description: Logradouro. number: type: string nullable: true description: Número. complement: type: string nullable: true description: Complemento. district: type: string nullable: true description: Bairro. city: type: string nullable: true description: Cidade. state: type: string nullable: true description: UF, duas letras maiúsculas. status: type: string enum: - ACTIVE - SUSPENDED - INACTIVE description: 'Situação do cliente: ACTIVE, SUSPENDED ou INACTIVE.' createdAt: type: string format: date-time description: Quando o cliente foi cadastrado (ISO 8601, UTC). updatedAt: type: string format: date-time description: >- Última alteração do cadastro (ISO 8601, UTC) — use em `updatedSince`. vehicles: description: Veículos do cliente, ativos e inativos (veja `status` de cada um). type: array items: $ref: '#/components/schemas/PublicVehicleSummary' plans: description: >- Vínculos de plano vigentes — feitos no cliente ou em veículos dele. Vazio quando nenhum plano cobre o cliente. type: array items: $ref: '#/components/schemas/PublicPlanLink' required: - id - type - name - socialName - document - phone - email - birthDate - contractDate - externalCode - zipCode - addressLine - number - complement - district - city - state - status - createdAt - updatedAt - vehicles - plans PublicVehicleSummary: type: object properties: id: type: integer format: int32 description: Identificador do veículo. customerId: type: integer format: int32 description: Identificador do cliente dono do veículo. plate: type: string description: >- Placa normalizada: maiúsculas, sem hífen (padrão antigo ou Mercosul). chassis: type: string nullable: true description: Chassi (VIN, 17 caracteres). renavam: type: string nullable: true description: RENAVAM (11 dígitos). brand: type: string nullable: true description: Marca. model: type: string nullable: true description: Modelo. manufactureYear: type: integer format: int32 nullable: true description: Ano de fabricação. modelYear: type: integer format: int32 nullable: true description: Ano do modelo. color: type: string nullable: true description: Cor. externalCode: type: string nullable: true description: Código do veículo no sistema do parceiro, informado no cadastro. status: type: string enum: - ACTIVE - INACTIVE description: 'Situação do veículo: ACTIVE ou INACTIVE.' createdAt: type: string format: date-time description: Quando o veículo foi cadastrado (ISO 8601, UTC). updatedAt: type: string format: date-time description: >- Última alteração do cadastro (ISO 8601, UTC) — use em `updatedSince`. required: - id - customerId - plate - chassis - renavam - brand - model - manufactureYear - modelYear - color - externalCode - status - createdAt - updatedAt PublicPlanLink: type: object properties: contractPlanId: type: integer format: int32 description: >- Identificador do plano dentro do contrato (o mesmo de `GET /v1/company`). contractCode: type: string description: Código do contrato ao qual o plano pertence. planName: type: string description: Nome comercial do plano. appliesTo: type: string enum: - CUSTOMER - VEHICLE description: >- A que o plano se aplica: CUSTOMER (cobre todos os veículos do cliente) ou VEHICLE (cobre um veículo por vínculo). linkedTo: type: string enum: - CUSTOMER - VEHICLE description: >- Onde o vínculo foi feito: no cliente (CUSTOMER) ou num veículo dele (VEHICLE). vehicleId: type: integer format: int32 nullable: true description: >- Veículo do vínculo quando `linkedTo` é VEHICLE. Nulo quando é no cliente. startedAt: type: string format: date-time description: Início da vigência do vínculo (ISO 8601, UTC). required: - contractPlanId - contractCode - planName - appliesTo - linkedTo - vehicleId - startedAt securitySchemes: apiToken: scheme: bearer bearerFormat: JWT type: http description: >- Token de curta duração devolvido por POST /v1/auth/token, carregando os escopos concedidos à chave — exigido por todo endpoint de dados. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.