Criar cliente

Este endpoint é utilizado para cadastrar um cliente (pagador) no ecossistema da Celcoin para utilização do link de pagamento. O registro do cliente é o primeiro passo obrigatório para a operação, já que nenhuma cobrança ou Link de Pagamento pode ser gerado sem estar associado a um perfil de pagador existente na base.

Para criar um cliente, tendo um token válido, utilize o endpoint Criar Cliente.

Modelo de Requisição:

Request

curl --location --request PATCH ' https://sandbox.openfinance.celcoin.dev//baas/v1/payment-links/customers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ****' \
--data-raw '{
    "name": "João",
    "surname": "apelido 1",
    "document": "15663289003",
    "emails": [
      "[email protected]"
    ],
    "phones": [
      "11999999999"
    ],
    "address": {
      "cep": "01310100",
      "street": "Avenida Paulista",
      "number": "1000",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "Bela Vista"
    },
    "externalCustomerId": "customer-4975801-006"
  }'

Campos da requisição

Objeto	Campo	Descrição	tipo	limitação de caracteres	Obrigatório
	name	Nome completo do cliente.	string	255	Sim
	surname	Apelido do cliente, deve ser único no sistema. Ex.: 'joao.silva' Não é permitido usar o mesmo apelido para outro cliente.	string	255	Sim
	document	Número do documento (CPF ou CNPJ). Somente número.	string	11 ou 14 caracteres sem máscara	Sim
	emails	Lista de e-mails do cliente.	array	array de strings com 255 caracteres cada	Sim
	phones	Lista de telefones do cliente.	array	array de strings com 255 caracteres cada	Sim
address		Endereço do cliente (veja campos abaixo).	array		Sim
address.	cep	CEP (apenas números)	string	8 caracteres sem máscara	Sim
address.	street	Nome da rua/avenida	string	255	Sim
address.	number	Número do endereço	string	15, apenas dígitos ou “S/N”	Sim
address.	state	UF (ex: "SP").	string	2 caracteres	Sim
address.	city	Nome da cidade	string	255	Sim
externalCustomerId		Identificador de controle interno do tenant.	string	255	Sim

🚧
Atenção

Deve-se utilizar um identificador externo, denominado externalCustomerId na criação do cliente. Esse identificador pode também ser utilizado nas cobranças futuras que serão criadas para esse cliente.

Um mesmo cliente pode ser cadastrado mais de uma vez com o mesmo documento. Seu cadastro não é sobrescrito. A cada requisição é criado um novo ID para o cliente.

Response

{
    "version": "1.0.0",
    "body": {
        "id": "6a1734548a806146a4e79d08",
        "name": "João",
        "surname": "apelido 1",
        "document": "15663289003",
        "documentType": "CPF",
        "emails": [
            "[email protected]"
        ],
        "phones": [
            "11999999999"
        ],
        "address": {
            "cep": "01310100",
            "street": "Avenida Paulista",
            "number": "1000",
            "state": "SP",
            "city": "São Paulo",
            "neighborhood": "Bela Vista"
        },
        "externalCustomerId": "customer-4975801-006",
        "createdAt": "2026-05-27T18:13:40.507Z",
        "updatedAt": "2026-05-27T18:13:40.507Z"
    },
    "status": 201
}

Campos da resposta:

Objeto	Campo	Descrição	tipo
	name	Nome completo do cliente.	string
	surname	Apelido do cliente, deve ser único no sistema. Ex.: 'joao.silva' Não é permitido usar o mesmo apelido para outro cliente.	string
	document	Número do documento (CPF ou CNPJ). Somente número.	string
	emails	Lista de e-mails do cliente.	array
	phones	Lista de telefones do cliente.	array
address		Endereço do cliente (veja campos abaixo).	array
address.	cep	CEP (apenas números)	string
address.	street	Nome da rua/avenida	string
address.	number	Número do endereço	string
address.	state	UF (ex: "SP").	string
address.	city	Nome da cidade	string
externalCustomerId		Identificador de controle interno do tenant.	string