> ## Documentation Index > Fetch the complete documentation index at: https://developers.uvvipay.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Criar cliente > Cria um cliente ou reaproveita o cadastro existente. Cria o cadastro de um cliente. Guarde o `id` da resposta. Na hora de assinar, envie esse `id` em `customer_id`. Veja [`POST /v1/subscriptions`](/api-reference/recurrency/subscriptions/create). ## Fluxo 1. Envie `external_customer_id`, `name`, `email`, `phone` e `document`. 2. Guarde o `id` da resposta. 3. Crie a assinatura com `customer_id` igual a esse `id`. ## Cliente já cadastrado Se o `external_customer_id` e os dados (nome, e-mail, telefone e documento) forem iguais, a API responde `200` e devolve o mesmo `id`. Se os dados forem diferentes, a API responde `422` / `UVV154640`. O cadastro não muda. Se o documento (número e tipo) já estiver em outro `external_customer_id`, a API responde `422` / `UVV154718`. ## Endereço O endereço é opcional. Você pode cadastrar o cliente sem o bloco `address`. Se enviar `address`, preencha todos os campos: `zip_code`, `street`, `street_number`, `neighborhood`, `city`, `state` e `country`. Se faltar algum, a API responde `400`. **NOTA:** Pix Automático precisa de endereço completo. Sem ele, a criação da assinatura responde `422` / `UVV154361`. A resposta não inclui documento, telefone nem endereço. Erros comuns: `400` (body inválido), `401`/`403` (credenciais ou produto Recorrência), `422` (`UVV154640`, `UVV154718`), `429` (20 req/min). ## OpenAPI ````yaml POST /v1/customers openapi: 3.0.0 info: title: UvviPay Public API description: >- Endpoints públicos da plataforma UvviPay para integração de subcontas (submerchants). version: 1.0.0 contact: {} servers: - url: https://api.uvvipay.com.br description: Produção - url: https://api-staging.uvvipay.com.br description: Staging security: - client-id: [] client-secret: [] tags: [] paths: /v1/customers: post: tags: - Clientes summary: Criar cliente description: >- Cria um cliente na organização da credencial, ou reaproveita o registro se `external_customer_id` e os dados (nome, email, telefone, documento) forem iguais. Não atualiza cliente existente. Não aceita `organization_id` no body. O `id` retornado é o `customer_id` do create de assinatura. operationId: createRecurrencyCustomer parameters: - name: client-id in: header description: ID público da credencial do merchant required: true schema: type: string - name: client-secret in: header description: Secret da credencial do merchant required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRecurrencyCustomerRequestDto' responses: '200': description: Cliente reaproveitado. Mesmo `id`. Nenhuma linha nova. content: application/json: schema: $ref: '#/components/schemas/RecurrencyCustomerDto' example: id: 550e8400-e29b-41d4-a716-446655440001 external_customer_id: customer-ext-0001 name: John Doe email: john@example.com '201': description: Cliente criado. content: application/json: schema: $ref: '#/components/schemas/RecurrencyCustomerDto' example: id: 550e8400-e29b-41d4-a716-446655440001 external_customer_id: customer-ext-0001 name: John Doe email: john@example.com '400': description: >- Body inválido (`address` parcial, campo extra como `organization_id`, documento ausente) '401': description: Credenciais inválidas ou ausentes '403': description: Produto `recurrency` não habilitado para o merchant '422': description: >- Não processável (`UVV154640` dados divergentes no mesmo `external_customer_id`; `UVV154718` documento já vinculado a outro `external_customer_id`) content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionErrorDto' examples: data_mismatch: summary: Dados divergentes value: code: UVV154640 message: >- Nao foi possivel processar pagamento. Verifique os dados e tente novamente. external_id_mismatch: summary: Documento já vinculado value: code: UVV154718 message: >- Nao foi possivel processar pagamento. Verifique os dados e tente novamente. '429': description: Limite de requisições excedido (20 requests per 60 seconds) components: schemas: CreateRecurrencyCustomerRequestDto: type: object required: - external_customer_id - name - email - phone - document properties: external_customer_id: type: string description: Identificador do cliente no seu sistema. name: type: string description: Nome do cliente. email: type: string format: email description: Email do cliente. phone: type: string description: Telefone do cliente (somente dígitos). address: allOf: - $ref: '#/components/schemas/RecurrencyCustomerAddressDto' description: >- Endereço do cliente. Opcional. Quando enviado, todos os campos são obrigatórios. Se o cliente for usado com pix_type: automatic no create de assinatura, envie o endereço completo aqui. Este endpoint não valida Pix Automático. document: allOf: - $ref: '#/components/schemas/RecurrencyCustomerDocumentDto' description: Documento do cliente. additionalProperties: false description: >- Cadastro de cliente da recorrência. Não envie `organization_id`. Este endpoint não atualiza um cliente existente. RecurrencyCustomerDto: type: object properties: id: type: string format: uuid external_customer_id: type: string nullable: true name: type: string email: type: string format: email CreateSubscriptionErrorDto: type: object required: - code - message properties: code: type: string enum: - UVV154817 - UVV154293 - UVV154640 - UVV154158 - UVV154972 - UVV154431 - UVV154785 - UVV154069 - UVV154524 - UVV154306 - UVV154718 - UVV154862 - UVV154147 - UVV154225 - UVV154591 description: >- Código opaco estável no formato UVV154 + 3 dígitos para tratamento programático. message: type: string description: Mensagem de erro subscription_id: type: string description: >- Identificador da assinatura quando a falha ocorre apos a persistencia (ex.: cobranca sync). customer_id: type: string format: uuid description: >- Identificador do cliente quando a falha ocorre apos a persistencia. Reaproveitavel como customer_id em uma nova tentativa. invoice_id: type: string description: >- Identificador da invoice quando a falha ocorre apos a persistencia (ex.: cobranca sync). transaction_id: type: string nullable: true description: >- Identificador publico da transacao na adquirente, quando disponivel na tentativa recusada. failure_code: type: string nullable: true description: 'Categoria publica da falha de cobranca (ex.: issuer_declined).' failure_message: type: string nullable: true description: Mensagem publica associada a falha de cobranca. RecurrencyCustomerAddressDto: type: object required: - street - street_number - zip_code - city - state - country - neighborhood properties: street: type: string description: Logradouro do endereço do cliente. street_number: type: string description: Número do endereço. zip_code: type: string description: CEP (somente dígitos). city: type: string description: Cidade. state: type: string description: UF (sigla de 2 letras). country: type: string example: BR description: 'País ISO 3166-1 alpha-2 (ex.: BR).' neighborhood: type: string description: Bairro. RecurrencyCustomerDocumentDto: type: object required: - number - type properties: number: type: string example: '12345678901' description: Número do documento (somente dígitos). type: type: string enum: - cpf - cnpj description: 'Tipo do documento: cpf ou cnpj.' securitySchemes: client-id: type: apiKey in: header name: client-id client-secret: type: apiKey in: header name: client-secret ````