> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Criar cliente
> Cria um cliente reutilizável na sua conta, com documento e e-mail únicos.
`POST /customers`
Faz parte do recurso [Clientes](/pt-BR/customers) — o cadastro, o que o torna único e a diferença
para o comprador da transação estão lá.
São obrigatórios **nome**, **e-mail**, **tipo**, **documento** e **telefone**. O endereço é opcional
e pode ser completado depois.
**Pessoa jurídica precisa informar o `documentType`.** Com `type: "company"`, omitir o campo
responde `400` — a API não deduz o tipo pelo tamanho do documento. Enviar
`documentType: "cpf"` junto de `type: "company"` também é recusado, assim como `cnpj` com
`individual`: são combinações incoerentes.
Em `type: "individual"`, omitir assume `cpf`. Quem usa passaporte informa
`documentType: "passport"`.
**Documento e e-mail não podem se repetir na sua conta**, e a violação responde `409` com
`error.code` — não `400`. É conflito com um cadastro existente, não campo malformado. Antes de
criar, procure por [`?document=`](/pt-BR/customers/list) para reaproveitar quem já existe.
O mesmo `409` também responde quando há uma requisição concorrente com a mesma
`Idempotency-Key` — nesse caso o corpo é `{ "error": "texto" }`, sem `code`. Ramifique pelo
formato, não só pelo status.
**O telefone segue E.164** — `+5511987654321`, com código do país. Na
[listagem](/pt-BR/customers/list) a busca por telefone ignora pontuação dos dois lados, então o
formato aqui não impede reencontrá-lo depois.
Endpoint idempotente. Envie o header `Idempotency-Key` para que um retry por timeout não crie o
mesmo cliente duas vezes. Veja [Convenções](/pt-BR/convencoes).
## OpenAPI
````yaml openapi/psp.json POST /customers
openapi: 3.0.3
info:
title: Z2Pay PSP API
version: 1.0.0
description: API pública do PSP — autenticação via API Key (Credential)
servers:
- url: https://api.sandbox.z2pay.com/v1
description: Sandbox
- url: https://api.z2pay.com/v1
description: Produção
security: []
tags:
- name: Cards
description: Cartões salvos de um cliente
- name: Chargebacks
description: Gerenciamento de chargebacks
- name: Customers
description: Gerenciamento de clientes (compradores)
- name: Fees
description: Tabela de taxas da conta (pix, boleto, cartão, saque, refund, chargeback)
- name: Recipients
description: Gerenciamento de recebedores (sellers/merchants que recebem repasses)
- name: Refunds
description: Gerenciamento de reembolsos e estornos
- name: Splits
description: Regras de divisão do valor de uma venda entre recebedores
- name: Transactions
description: Gerenciamento de transações e payments
- name: Wallets
description: Saldo, extrato e resumo da carteira de um recebedor, agrupados por moeda
- name: Webhooks
description: Configuração, gerenciamento e histórico de entregas de webhooks
- name: Withdrawals
description: Solicitação e acompanhamento de saques (payouts) por recipient
paths:
/customers:
post:
tags:
- Customers
summary: Criar cliente
description: >-
Cria um cliente na sua conta. Suporta idempotência via header
Idempotency-Key
operationId: CustomerController_create
parameters:
- name: Idempotency-Key
in: header
required: false
description: Chave única para garantir idempotência da requisição
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
minLength: 2
description: Nome completo do cliente.
email:
type: string
format: email
description: E-mail do cliente.
type:
type: string
enum:
- individual
- company
description: >-
Tipo de cliente: individual (pessoa física) ou company
(pessoa jurídica).
document:
type: string
minLength: 6
description: Documento do cliente (CPF ou CNPJ, somente dígitos).
documentType:
type: string
enum:
- cpf
- cnpj
- passport
description: >-
Tipo do documento: `cpf`, `cnpj` ou `passport`. Obrigatório
quando `type` é `company`; em `individual`, omitir assume
`cpf`.
phone:
type: string
minLength: 1
description: 'Telefone do cliente (formato E.164, ex.: +5511987654321).'
address:
type: object
properties:
street:
type: string
nullable: true
description: Logradouro (rua, avenida).
number:
type: string
nullable: true
description: Número do endereço.
complement:
type: string
nullable: true
description: Complemento do endereço (apartamento, bloco, sala).
neighborhood:
type: string
nullable: true
description: Bairro.
city:
type: string
nullable: true
description: Cidade.
state:
type: string
nullable: true
description: 'Estado ou UF (ex.: SP).'
postalCode:
type: string
nullable: true
description: CEP / código postal (somente dígitos).
country:
type: string
nullable: true
description: 'País (código ISO 3166-1 alfa-2, ex.: BR).'
required:
- street
- number
- complement
- neighborhood
- city
- state
- postalCode
- country
description: Endereço do cliente.
required:
- name
- email
- type
- document
- phone
responses:
'201':
description: Cliente criado
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Identificador único do registro.
name:
type: string
description: Nome do registro.
email:
type: string
description: E-mail de contato.
type:
type: string
description: >-
Tipo de lançamento (sale, refund, chargeback, withdrawal,
fee, etc)
document:
type: string
description: Documento (CPF ou CNPJ) do titular.
documentType:
type: string
description: 'Tipo de documento: cpf ou cnpj.'
phone:
type: string
description: Telefone de contato.
address:
type: object
nullable: true
properties:
street:
type: string
nullable: true
description: Logradouro (rua, avenida).
number:
type: string
nullable: true
description: Número do endereço.
complement:
type: string
nullable: true
description: Complemento do endereço (apartamento, bloco, sala).
neighborhood:
type: string
nullable: true
description: Bairro.
city:
type: string
nullable: true
description: Cidade.
state:
type: string
nullable: true
description: 'Estado ou UF (ex.: SP).'
postalCode:
type: string
nullable: true
description: CEP / código postal (somente dígitos).
country:
type: string
nullable: true
description: 'País (código ISO 3166-1 alfa-2, ex.: BR).'
description: Endereço do cliente.
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
updatedAt:
type: string
format: date-time
description: Data e hora da última atualização do registro (ISO 8601).
example:
id: cust_kyz6cwnbm55aax1lhxewn01o4
name: Maria Oliveira
email: maria.oliveira@example.com
type: individual
document: '12345678909'
documentType: cpf
phone: '+5511987654321'
address:
street: Av. Paulista
number: '1578'
complement: Apto 142
neighborhood: Bela Vista
city: São Paulo
state: SP
postalCode: 01310-200
country: BR
createdAt: '2025-06-29T13:45:30.000Z'
updatedAt: '2025-06-29T13:45:30.000Z'
'400':
description: >-
Requisição inválida — algum parâmetro ou campo do corpo não passou
na validação
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
issues:
type: array
description: >-
Um item por campo rejeitado. Nunca vem vazio: se há
400 de validação, há pelo menos um.
items:
type: object
properties:
path:
type: string
description: >-
Campo que falhou. Vem vazio quando o erro é do
corpo como um todo.
message:
type: string
description: O que há de errado com esse campo.
example:
error:
code: VALIDATION_ERROR
message: Validation failed
issues:
- path: status
message: >-
Status inválido. Valores aceitos: pending,
waiting_payment, paid, refused, canceled, refunded
- path: startDate
message: >-
Data deve ser ISO 8601 com timezone (ex.:
2026-06-24T00:00:00Z)
'401':
description: Chave de API ausente, malformada ou inválida
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: UNAUTHORIZED
message: Invalid API key
'409':
description: >-
Documento ou e-mail já cadastrado nesta conta (`error.code`), ou
requisição concorrente com a mesma Idempotency-Key (`error` como
texto)
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: A request with this idempotency key is already being processed
'422':
description: >-
Idempotency-Key já usada com um corpo diferente. Use uma chave nova
para uma operação diferente
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: Idempotency key already used with a different request body
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````