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

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.pagnovo.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.PAGNOVO_SECRET_KEY).toString("base64");
 
const res = await fetch("https://api.pagnovo.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);
}