> ## Documentation Index > Fetch the complete documentation index at: https://docs.korbit.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Criar cliente > Cadastra um cliente na sua base Korbit. O e-mail é o identificador natural: duplicado retorna `409 CUSTOMER_EMAIL_TAKEN`. Compradores que já pagaram por link também aparecem aqui automaticamente. ## OpenAPI ````yaml /openapi/korbit-public-v1.json post /v1/customers openapi: 3.1.0 info: title: Korbit API version: 1.0.0 description: >- API de pagamentos da Korbit para merchants: PIX, cartão (com 3DS), assinaturas, checkout por link, payouts, antecipações e refunds — com idempotência, webhooks assinados e ambiente sandbox. contact: name: Suporte Korbit email: suporte@korbit.com.br servers: - url: https://api.korbit.com.br description: Produção (chaves kbt_live_) - url: https://api-test.korbit.com.br description: Sandbox (chaves kbt_test_) security: - bearerAuth: [] tags: - name: Antecipações - name: Assinaturas - name: Atividade - name: Catálogo - name: Chaves de API - name: Checkout - name: Clientes e Pedidos - name: Pagamentos - name: Refunds e Disputas - name: Saldo e Saques - name: Sandbox - name: Webhooks paths: /v1/customers: post: tags: - Clientes e Pedidos summary: Criar cliente description: >- Cadastra um cliente na sua base Korbit. O e-mail é o identificador natural: duplicado retorna `409 CUSTOMER_EMAIL_TAKEN`. Compradores que já pagaram por link também aparecem aqui automaticamente. operationId: createCommerceCustomer parameters: - schema: type: string minLength: 1 maxLength: 255 in: header name: idempotency-key required: true requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - email properties: email: type: string format: email minLength: 3 maxLength: 320 description: >- E-mail único na sua base — usado no portal do cliente e nas cobranças recorrentes. externalId: type: string minLength: 1 maxLength: 128 description: >- Seu identificador interno do cliente para sincronização com sua base. name: type: string minLength: 1 maxLength: 200 description: Nome completo do cliente. phone: type: string minLength: 5 maxLength: 32 description: Telefone do cliente (formato E.164 recomendado). responses: '200': description: Default Response content: application/json: schema: type: object additionalProperties: false required: - address - archivedAt - createdAt - email - environment - externalId - id - name - phone - taxId - updatedAt properties: address: anyOf: - type: object additionalProperties: false required: - city - complement - neighborhood - number - state - street - zipcode properties: city: type: string minLength: 1 maxLength: 120 complement: anyOf: - type: string maxLength: 120 - type: 'null' neighborhood: type: string minLength: 1 maxLength: 120 number: type: string minLength: 1 maxLength: 32 state: type: string minLength: 2 maxLength: 2 street: type: string minLength: 1 maxLength: 160 zipcode: type: string minLength: 8 maxLength: 8 - type: 'null' archivedAt: anyOf: - type: string format: date-time - type: 'null' createdAt: type: string format: date-time email: type: string format: email maxLength: 320 environment: type: string enum: - live - test externalId: anyOf: - type: string maxLength: 128 - type: 'null' id: type: string format: uuid name: anyOf: - type: string maxLength: 200 - type: 'null' phone: anyOf: - type: string maxLength: 32 - type: 'null' taxId: anyOf: - type: object additionalProperties: false required: - number - type properties: number: type: string minLength: 11 maxLength: 14 pattern: ^[0-9]+$ type: type: string enum: - CPF - CNPJ - type: 'null' stats: type: object additionalProperties: false required: - activePlan - activeSubscriptions - hasHadSubscription - lastPaidAt - paidAmountMinor - paymentsCount properties: activePlan: anyOf: - type: object additionalProperties: false required: - billingInterval - intervalCount - productName properties: billingInterval: type: string enum: - MONTH - YEAR intervalCount: type: integer minimum: 1 maximum: 12 productName: type: string minLength: 1 maxLength: 200 - type: 'null' activeSubscriptions: type: integer minimum: 0 hasHadSubscription: type: boolean lastPaidAt: anyOf: - type: string format: date-time - type: 'null' paidAmountMinor: type: integer minimum: 0 maximum: 9007199254740991 paymentsCount: type: integer minimum: 0 updatedAt: type: string format: date-time '201': description: Default Response content: application/json: schema: type: object additionalProperties: false required: - address - archivedAt - createdAt - email - environment - externalId - id - name - phone - taxId - updatedAt properties: address: anyOf: - type: object additionalProperties: false required: - city - complement - neighborhood - number - state - street - zipcode properties: city: type: string minLength: 1 maxLength: 120 complement: anyOf: - type: string maxLength: 120 - type: 'null' neighborhood: type: string minLength: 1 maxLength: 120 number: type: string minLength: 1 maxLength: 32 state: type: string minLength: 2 maxLength: 2 street: type: string minLength: 1 maxLength: 160 zipcode: type: string minLength: 8 maxLength: 8 - type: 'null' archivedAt: anyOf: - type: string format: date-time - type: 'null' createdAt: type: string format: date-time email: type: string format: email maxLength: 320 environment: type: string enum: - live - test externalId: anyOf: - type: string maxLength: 128 - type: 'null' id: type: string format: uuid name: anyOf: - type: string maxLength: 200 - type: 'null' phone: anyOf: - type: string maxLength: 32 - type: 'null' taxId: anyOf: - type: object additionalProperties: false required: - number - type properties: number: type: string minLength: 11 maxLength: 14 pattern: ^[0-9]+$ type: type: string enum: - CPF - CNPJ - type: 'null' stats: type: object additionalProperties: false required: - activePlan - activeSubscriptions - hasHadSubscription - lastPaidAt - paidAmountMinor - paymentsCount properties: activePlan: anyOf: - type: object additionalProperties: false required: - billingInterval - intervalCount - productName properties: billingInterval: type: string enum: - MONTH - YEAR intervalCount: type: integer minimum: 1 maximum: 12 productName: type: string minLength: 1 maxLength: 200 - type: 'null' activeSubscriptions: type: integer minimum: 0 hasHadSubscription: type: boolean lastPaidAt: anyOf: - type: string format: date-time - type: 'null' paidAmountMinor: type: integer minimum: 0 maximum: 9007199254740991 paymentsCount: type: integer minimum: 0 updatedAt: type: string format: date-time '400': description: Default Response content: application/json: schema: type: object additionalProperties: false required: - detail - instance - requestId - status - title - type properties: code: type: string detail: type: string instance: type: string requestId: type: string status: type: integer minimum: 400 maximum: 599 title: type: string type: type: string '401': description: Default Response content: application/json: schema: type: object additionalProperties: false required: - detail - instance - requestId - status - title - type properties: code: type: string detail: type: string instance: type: string requestId: type: string status: type: integer minimum: 400 maximum: 599 title: type: string type: type: string '403': description: Default Response content: application/json: schema: type: object additionalProperties: false required: - detail - instance - requestId - status - title - type properties: code: type: string detail: type: string instance: type: string requestId: type: string status: type: integer minimum: 400 maximum: 599 title: type: string type: type: string '409': description: Default Response content: application/json: schema: type: object additionalProperties: false required: - detail - instance - requestId - status - title - type properties: code: type: string detail: type: string instance: type: string requestId: type: string status: type: integer minimum: 400 maximum: 599 title: type: string type: type: string '429': description: Default Response content: application/json: schema: type: object additionalProperties: false required: - detail - instance - requestId - status - title - type properties: code: type: string detail: type: string instance: type: string requestId: type: string status: type: integer minimum: 400 maximum: 599 title: type: string type: type: string security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Korbit API key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.