Referência da API

Criar cliente

Cria um cliente vinculado à sua conta. Clientes são entidades persistentes usadas para associar assinaturas, payment links e invoices — útil para agrupar histórico de cobranças de um mesmo pagador. CPF/CNPJ é único por conta e imutável após a criação: se errou, delete e crie de novo. A chave de API precisa da permissão isInvoiceAvailable.

POST/v2/customers

Autenticação

HTTP Basic Auth. Envie sua secret key no header:

Authorization: Basic {base64(secret:SUA_SECRET_KEY)}

Parâmetros

namestringobrigatório

Nome completo do cliente. Mínimo 2, máximo 255 caracteres.

Exemplo: João Silva

emailstringobrigatório

E-mail válido. Normalizado pra lowercase no armazenamento.

Exemplo: joao.silva@exemplo.com

documentstringobrigatório

CPF (11 dígitos) ou CNPJ (14 dígitos). Aceita com ou sem máscara — máscara é removida antes de salvar. Único por conta. Imutável após criação.

Exemplo: 123.456.789-01

phonestringopcional

Telefone com ou sem máscara. Dígitos são normalizados antes de salvar. Máximo 20 dígitos.

Exemplo: 11987654321

birthDatestring (ISO 8601)opcional

Data de nascimento em formato ISO. Pode ser apenas a data (YYYY-MM-DD).

Exemplo: 1990-05-15

cepstringopcional

CEP, 8 dígitos. Aceita com ou sem hífen.

Exemplo: 01310100

addressstringopcional

Logradouro (rua, avenida, etc).

Exemplo: Avenida Paulista

addressNumberstringopcional

Número do endereço. String porque pode ser 'S/N' ou conter letras.

Exemplo: 1000

complementstringopcional

Complemento do endereço (apartamento, sala, etc).

Exemplo: Sala 501

neighborhoodstringopcional

Bairro.

Exemplo: Bela Vista

citystringopcional

Cidade.

Exemplo: São Paulo

statestringopcional

UF, 2 letras maiúsculas.

Exemplo: SP

notesstringopcional

Anotações livres sobre o cliente (uso interno seu).

Exemplo: Cliente recorrente do plano premium

successUrlstring (https)opcional

Pra onde o comprador é levado depois do pagamento ser confirmado. É a sua página de obrigado — e é onde o pixel de conversão registra a venda. Só aceita https. Vazio ou null = o comprador fica na própria página de pagamento.

Exemplo: https://sualoja.com/obrigado

failureUrlstring (https)opcional

Pra onde levar quando o pagamento é recusado. Só aceita https. Opcional — sem isso, quem não conseguir pagar continua na página, podendo tentar outro método.

Exemplo: https://sualoja.com/pagamento-recusado

checkoutLogoUrlstring (URL)opcional

Logo exibido no topo da página de pagamento, no lugar do nome. Sem logo, aparece um selo com as iniciais na cor da marca. Ver Personalizar o checkout.

Exemplo: https://sualoja.com/logo.png

checkoutBrandColorstring (#RRGGBB)opcional

Cor da marca, em hex. Pinta o botão de pagar e os destaques. O contraste do texto sobre ela é calculado automaticamente — cor clara recebe texto escuro.

Exemplo: #1E6F4C

checkoutLocaleenum | nullopcional

Idioma da página de pagamento: pt-BR, es ou en. null ou "auto" deriva da moeda da conta (BRL → português, MXN e ARS → espanhol). Só preencha quando você cobra numa moeda e vende para outro público.

Exemplo: es

metaPixelIdstringopcional

ID do pixel da Meta (Facebook/Instagram). Só o ID, sem o script. O evento de compra dispara quando o pagamento é confirmado — inclusive no Pix, que confirma depois. Sem ID, nenhum script de terceiro é carregado na página.

Exemplo: 1234567890123456

googleAdsIdstringopcional

ID de conversão do Google Ads (AW-...). Precisa do par com googleAdsLabel — sozinho não registra nada.

Exemplo: AW-123456789

googleAdsLabelstringopcional

Rótulo da ação de conversão do Google Ads. É por ação de conversão, e normalmente se cria uma por produto — por isso este campo é do checkout, não da conta.

Exemplo: AbC-D_efGh12345

tiktokPixelIdstringopcional

ID do pixel do TikTok. Só o ID, sem o script.

Exemplo: CXXXXXXXXXXXXXXXXXXX

successUrlstring (https)opcional

Exemplo: https://sualoja.com/obrigado

failureUrlstring (https)opcional

Pra onde levar quando o pagamento é recusado. Só aceita https. Opcional — sem isso, quem não conseguir pagar continua na página, podendo tentar outro método.

Exemplo: https://sualoja.com/pagamento-recusado

checkoutLogoUrlstring (URL)opcional

Logo exibido no topo da página de pagamento, no lugar do nome. Sem logo, aparece um selo com as iniciais na cor da marca. Ver Personalizar o checkout.

Exemplo: https://sualoja.com/logo.png

checkoutBrandColorstring (#RRGGBB)opcional

Cor da marca, em hex. Pinta o botão de pagar e os destaques. O contraste do texto sobre ela é calculado automaticamente — cor clara recebe texto escuro.

Exemplo: #1E6F4C

checkoutLocaleenum | nullopcional

Exemplo: es

metaPixelIdstringopcional

Exemplo: 1234567890123456

googleAdsIdstringopcional

ID de conversão do Google Ads (AW-...). Precisa do par com googleAdsLabel — sozinho não registra nada.

Exemplo: AW-123456789

googleAdsLabelstringopcional

Rótulo da ação de conversão do Google Ads. É por ação de conversão, e normalmente se cria uma por produto — por isso este campo é do checkout, não da conta.

Exemplo: AbC-D_efGh12345

tiktokPixelIdstringopcional

ID do pixel do TikTok. Só o ID, sem o script.

Exemplo: CXXXXXXXXXXXXXXXXXXX

metadataobjectopcional

Objeto JSON arbitrário. Use para anexar informação do seu sistema (source de tráfego, IDs externos, tags, etc).

Exemplo: { "source": "landing-page" }

Body da requisição

Content-Type: application/json

JSON

{
  "name": "João Silva",
  "email": "joao.silva@exemplo.com",
  "document": "12345678901",
  "phone": "11987654321",
  "birthDate": "1990-05-15",
  "cep": "01310100",
  "address": "Avenida Paulista",
  "addressNumber": "1000",
  "complement": "Sala 501",
  "neighborhood": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "notes": "Cliente recorrente do plano premium",
  "metadata": {
    "source": "landing-page",
    "campaign": "black-friday-2026"
  }
}

Respostas

201

Cliente criado. Retorna o objeto completo, incluindo todos os campos preenchidos e os normalizados.

JSON

{
  "id": "c8a5f4d2-1b3e-4c9f-8a7d-2e5f6c1d4b9a",
  "createdByUserId": "u-1234",
  "name": "João Silva",
  "email": "joao.silva@exemplo.com",
  "document": "12345678901",
  "phone": "11987654321",
  "birthDate": "1990-05-15T00:00:00.000Z",
  "cep": "01310100",
  "address": "Avenida Paulista",
  "addressNumber": "1000",
  "complement": "Sala 501",
  "neighborhood": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "notes": "Cliente recorrente do plano premium",
  "metadata": { "source": "landing-page", "campaign": "black-friday-2026" },
  "deletedAt": null,
  "createdAt": "2026-05-26T14:32:01.923Z",
  "updatedAt": "2026-05-26T14:32:01.923Z"
}

400

Erro de validação. Campos obrigatórios faltando, e-mail inválido, documento inválido ou nome fora dos limites.

JSON

{
  "status": 400,
  "error": "Email invalido"
}

409

Já existe um cliente com esse document na sua conta.

JSON

{
  "status": 409,
  "error": "Ja existe um cliente com esse documento. Edite o existente."
}

Exemplos

cURL

curl -X POST "https://api.ihubplay.com/v2/customers" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "email": "joao.silva@exemplo.com",
    "document": "12345678901",
    "phone": "11987654321"
  }'

JavaScript

const token = Buffer.from("secret:" + process.env.IHUBGAMES_SECRET_KEY).toString("base64");
 
const res = await fetch("https://api.ihubplay.com/v2/customers", {
  method: "POST",
  headers: {
    Authorization: `Basic ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "João Silva",
    email: "joao.silva@exemplo.com",
    document: "12345678901",
    phone: "11987654321",
  }),
});
 
if (res.status === 409) {
  // Cliente ja existe na sua conta — busca pelo document via list?search=
  console.log("ja cadastrado, edita o existente");
} else if (res.ok) {
  const customer = await res.json();
  console.log("criado:", customer.id);
}