> ## Documentation Index > Fetch the complete documentation index at: https://docs-corp.usight.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Inserir Clientes > Cria um ou mais clientes. Aceita objeto único (retorna 201 com dados) ou array (retorna 200/207/422 com `{ success, errors }`). Documento+código duplicado é rejeitado com 409. Campos de endereço são preenchidos automaticamente via CEP (ViaCEP) quando omitidos. ## OpenAPI ````yaml POST /clients openapi: 3.0.0 info: title: API Corp ERP version: 1.1.0 description: >- API para gerenciamento de clientes e faturas no ERP Corp. **Autenticação:** envie a API key no header `x-api-key` (ou `Authorization: Bearer `). Cada chave possui escopos (`clients:read`, `clients:write`, `invoices:read`, `invoices:write`) e pode ter data de expiração. **Paginação:** os endpoints GET são paginados via `page` (1-based) e `limit` (default 50, máximo 100). A resposta traz `count`, `page`, `limit` e `total_pages`. **Limites:** até 1000 registros por requisição POST (em lote); corpo de até 8 MB; até 120 requisições por minuto por chave (resposta 429 com `Retry-After`). Uma importação em lote conta como 1 requisição. servers: - url: https://api-corp.usight.com.br description: Produção - url: https://api-corp-sandbox.usight.com.br description: Sandbox (homologação) security: - ApiKeyAuth: [] paths: /clients: post: tags: - Clientes summary: Inserir Clientes description: >- Cria um ou mais clientes. Aceita objeto único (retorna 201 com dados) ou array (retorna 200/207/422 com `{ success, errors }`). Documento+código duplicado é rejeitado com 409. Campos de endereço são preenchidos automaticamente via CEP (ViaCEP) quando omitidos. operationId: postClientes requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/ClienteInput' - type: array items: $ref: '#/components/schemas/ClienteInput' examples: objeto_unico: summary: Objeto único value: cpf_cnpj: '12345678000190' codigo: '001' razao_social: Empresa Exemplo LTDA cep: '01001000' logradouro: Praça da Sé numero: '100' complemento: Sala 5 bairro: Sé cidade: São Paulo uf: SP classificacao_fiscal: simples_nacional cep_automatico: summary: Com CEP automático (sem endereço) value: cpf_cnpj: '12345678000190' codigo: '001' razao_social: Empresa Exemplo LTDA cep: '01001000' numero: '100' classificacao_fiscal: simples_nacional responses: '200': description: Lote inteiramente bem-sucedido content: application/json: schema: $ref: '#/components/schemas/LoteSuccess' '201': description: Cliente criado com sucesso (objeto único) content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/ClienteOutput' '207': description: Lote parcial — alguns itens falharam content: application/json: schema: $ref: '#/components/schemas/LoteSuccess' '400': description: >- Requisição inválida — JSON malformado, erro de validação ou lote acima de 1000 registros content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Não autorizado — API key ausente, inválida, revogada ou expirada content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- Sem permissão — a API key não possui o escopo necessário para esta operação content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Conflito — documento+código já cadastrado content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '413': description: Payload muito grande — corpo da requisição excede 8 MB content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: >- Muitas requisições — limite por minuto excedido. Veja o header `Retry-After`. headers: Retry-After: description: Segundos a aguardar antes de repetir a requisição schema: type: integer example: 60 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: ClienteInput: type: object required: - cpf_cnpj - codigo - razao_social - cep - numero - classificacao_fiscal properties: cpf_cnpj: type: string description: CPF (11 dígitos) ou CNPJ (14 dígitos) — valida dígitos verificadores example: '12345678000190' codigo: type: string description: Código de acesso do cliente — chave junto com o documento example: K0001 razao_social: type: string description: Razão social / nome do cliente example: Empresa Exemplo LTDA cep: type: string description: >- 8 dígitos — usado para preencher endereço e código do município automaticamente example: '01001000' logradouro: type: string description: Preenchido automaticamente pelo CEP se omitido example: Praça da Sé numero: type: string description: Número do endereço example: '100' complemento: type: string description: Complemento do endereço (opcional) example: Sala 5 bairro: type: string description: Preenchido automaticamente pelo CEP se omitido example: Sé cidade: type: string description: Preenchido automaticamente pelo CEP se omitido example: São Paulo uf: type: string description: 2 letras — preenchido automaticamente pelo CEP se omitido example: SP classificacao_fiscal: type: string description: Classificação fiscal do cliente enum: - normal - simples_nacional - nao_retem - orgao_publico - orgao_publico_ir example: simples_nacional LoteSuccess: type: object properties: success: type: integer example: 2 errors: type: array items: type: object properties: titulo: type: string codigo: type: string error: type: string example: [] ClienteOutput: type: object properties: id: type: string format: uuid example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 codigo: type: string example: '001' doc_number: type: string example: '12345678000190' name: type: string example: Empresa Exemplo LTDA cidade: type: string example: São Paulo uf: type: string example: SP codigo_cidade: type: string example: '3550308' classificacao_fiscal: type: string example: simples_nacional ErrorResponse: type: object properties: error: type: string example: Cliente não cadastrado para o código '001'. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- `Apikey` fornecida pelo Corp ERP. Também aceita `Authorization: Bearer `. ````