Clientes e Endereços API REST Yep — Customers, Addresses e atributos EAV

Visão geral

A rota /api2/customers é integracional/administrativa, voltada para sincronização de cadastro com ERPs, CRMs e back-offices. Já a rota /api2/address centraliza o ciclo de vida dos endereços do cliente — criação, atualização, listagem e exclusão — preservando a semântica da Yep para billing e shipping default.

200

Limit máximoPor página em GET /api2/customers via limit.

20

Limit padrãoAplicado quando limit é omitido.

EAV

Atributos dinâmicosBusca e atualização por qualquer atributo EAV de customer.

2x

Marcadores defaultis_default_billing e is_default_shipping por endereço.

Todos os endpoints exigem Authorization: Bearer {token}. Os parâmetros podem ser enviados via query string ou body JSON em GET, conforme a conveniência do integrador.

Customers

CRUD completo do cadastro de cliente com listagem paginada, busca individual por ID e busca por atributo (e-mail, taxvat, celular ou qualquer EAV).

GET/api2/customers

Lista clientes com paginação determinística.

JSONClientes

page Opcional

Inteiro. Página atual da listagem. Padrão: 1.

limit Opcional

Inteiro. Quantidade por página. Padrão: 20; máximo: 200. Valores inválidos são normalizados para o padrão.

include_pagination Opcional

Boolean. Quando verdadeiro, retorna total, last_page e has_next no corpo da resposta.

Requisição

{
  "page": 1,
  "limit": 20,
  "include_pagination": true
}

Resposta

{
  "success": true,
  "page": 1,
  "limit": 20,
  "total": 150,
  "last_page": 8,
  "has_next": true,
  "customers": [
    {
      "customer_id": 123,
      "email": "cliente@email.com",
      "firstname": "João",
      "lastname": "Silva",
      "taxvat": "123.456.789-00",
      "celular": "11999999999",
      "custom_attributes": {
        "celular": "11999999999"
      }
    }
  ]
}

GET/api2/customerspor ID

Busca um cliente específico pelo ID Yep.

{
  "id": 123
}

{
  "success": true,
  "customer": {
    "customer_id": 123,
    "email": "cliente@email.com",
    "firstname": "João",
    "lastname": "Silva",
    "taxvat": "123.456.789-00",
    "custom_attributes": {}
  }
}

GET/api2/customerspor atributo

Busca por email, taxvat, alias cpf ou qualquer atributo EAV existente em customer — incluindo atributos customizados como celular.

{
  "attribute": "email",
  "value": "cliente@email.com"
}

{
  "attribute": "celular",
  "value": "11999999999"
}

Também são aceitos atalhos sem o invólucro attribute/value:

{
  "email": "cliente@email.com"
}

{
  "taxvat": "12.345.678/0001-99"
}

PATCH/api2/customers

Atualiza dados do cliente. O campo id é obrigatório.

{
  "id": 123,
  "firstname": "João",
  "lastname": "Silva",
  "email": "joao@email.com",
  "taxvat": "12.345.678/0001-99",
  "celular": "11999999999"
}

Também aceita atributos customizados agrupados em custom_attributes.

{
  "id": 123,
  "custom_attributes": {
    "celular": "11999999999",
    "marketplace_comissao": "10"
  }
}

{
  "success": true,
  "customer": {
    "customer_id": 123,
    "email": "joao@email.com",
    "taxvat": "12.345.678/0001-99",
    "celular": "11999999999",
    "custom_attributes": {
      "celular": "11999999999"
    }
  }
}

O campo canônico de CPF/CNPJ é taxvat, seguindo o padrão Yep. O alias cpf pode ser usado como entrada, mas a resposta sempre prioriza taxvat.

DELETE/api2/customers

Remove a conta do cliente. O campo id é obrigatório.

{
  "id": 123
}

{
  "success": true,
  "message": "Cliente removido com sucesso.",
  "customer_id": 123
}

Atributos de cliente

Referência consolidada dos campos suportados na leitura e atualização do cadastro.

Campos padrão

email, firstname, middlename, lastname
taxvat, dob, gender
group_id, website_id, store_id

CPF/CNPJ

O campo canônico é taxvat, seguindo o padrão Yep. O alias cpf pode ser usado como entrada, mas a resposta prioriza taxvat.

Atributos customizáveis

Qualquer atributo EAV existente em customer, como celular ou marketplace_comissao, pode ser lido e atualizado. Eles são aceitos tanto na raiz do payload quanto agrupados em custom_attributes.

Recomendação

Sempre que possível, envie atributos customizados dentro de custom_attributes. Isso evita ambiguidade com campos padrão e mantém o contrato preparado para futuras evoluções do cadastro.

Addresses

Gestão completa dos endereços do cliente, com aceite de address_id ou alias id, suporte a marcadores default e compatibilidade com a rota legada /api2/customers/addresses/{customer_id}.

GET/api2/address?customer_id=123

Lista endereços de um cliente.

{
  "success": true,
  "customer_id": 123,
  "default_billing_id": 10,
  "default_shipping_id": 11,
  "addresses": [
    {
      "address_id": 10,
      "customer_id": 123,
      "is_default_billing": true,
      "is_default_shipping": false,
      "firstname": "João",
      "lastname": "Silva",
      "street": ["Rua X", "123"],
      "city": "São Paulo",
      "region": "SP",
      "postcode": "01000-000",
      "country_id": "BR",
      "telephone": "11999999999",
      "custom_attributes": {}
    }
  ]
}

Compatibilidade mantida com a rota legada:

GET /api2/customers/addresses/123

GET/api2/address?address_id=456

Busca um endereço específico. Também aceita id no lugar de address_id.

{
  "success": true,
  "address": {
    "address_id": 456,
    "customer_id": 123,
    "is_default_billing": true,
    "is_default_shipping": false,
    "firstname": "João",
    "lastname": "Silva"
  }
}

POST/api2/address

Cria um novo endereço para o cliente. O campo customer_id é obrigatório.

{
  "customer_id": 123,
  "firstname": "João",
  "lastname": "Silva",
  "street": ["Rua X", "123", "Apto 2"],
  "city": "São Paulo",
  "region": "SP",
  "postcode": "01000-000",
  "country_id": "BR",
  "telephone": "11999999999",
  "is_default_billing": true,
  "is_default_shipping": true
}

{
  "success": true,
  "address": {
    "address_id": 456,
    "customer_id": 123,
    "is_default_billing": true,
    "is_default_shipping": true
  },
  "invalid_fields": []
}

PATCH/api2/address

Atualiza um endereço existente. Aceita address_id ou id.

{
  "address_id": 456,
  "telephone": "11888888888",
  "is_default_shipping": true
}

{
  "success": true,
  "address": {
    "address_id": 456,
    "customer_id": 123,
    "is_default_billing": false,
    "is_default_shipping": true,
    "telephone": "11888888888"
  }
}

DELETE/api2/address

Remove um endereço existente. Aceita address_id ou id.

{
  "address_id": 456
}

{
  "success": true,
  "message": "Endereço removido com sucesso.",
  "address_id": 456,
  "customer_id": 123
}

Marcadores default Novo

Cada endereço retorna os booleans is_default_billing e is_default_shipping, refletindo a relação com o cadastro do cliente. Ambos podem ser alterados em POST e PATCH.

is_default_billing Opcional

Boolean. Quando true, marca este endereço como padrão de cobrança no cadastro do cliente.

is_default_shipping Opcional

Boolean. Quando true, marca este endereço como padrão de entrega no cadastro do cliente.

Comportamento ao remover marcação

Enviar is_default_billing ou is_default_shipping como false remove o marcador do cadastro quando o endereço atual for o padrão correspondente. Para os demais casos, o campo é ignorado.

Formas de uso suportadas

Referência rápida das combinações testadas e homologadas para clientes e endereços.

Listagem padrão GET /api2/customers

Paginada com metadados GET /api2/customers?page=1&limit=100&include_pagination=1

Busca por ID GET /api2/customers + {"id":123}

Busca por e-mail GET /api2/customers + {"email":"cliente@email.com"}

Busca por taxvat (CPF/CNPJ) GET /api2/customers + {"taxvat":"12.345.678/0001-99"}

Busca por atributo EAV GET /api2/customers + {"attribute":"celular","value":"11999999999"}

Endereços do cliente GET /api2/address?customer_id=123

Endereço individual GET /api2/address?address_id=456

Compatibilidade legada GET /api2/customers/addresses/123

Recomendações para integração

Boas práticas consolidadas para sincronização de cadastro e endereços com ERPs e CRMs.

Evitar

Depender da rota legada /api2/customers/addresses/{id} em integrações novas — prefira /api2/address.
Atualizar marcadores default sem antes consultar default_billing_id e default_shipping_id do cliente.
Tratar cpf como campo canônico — a resposta sempre normaliza para taxvat.

Dica de sincronização

Em integrações de CRM, faça uma chamada inicial de GET /api2/customers com include_pagination=1 para descobrir o tamanho da base e, em seguida, paralelize GET /api2/address?customer_id={id} apenas para os clientes ativos do período — reduzindo carga e respeitando o limite de 200 por página.

Erros comuns

Status	Exemplo	Quando ocorre
`400`	`{"error":"JSON inválido."}`	Body JSON malformado ou parâmetro inválido.
`401`	`{"error":"Token ausente ou malformado."}`	Token ausente, expirado, inválido ou revogado.
`404`	`{"error":"Cliente não encontrado."}`	Cliente ou endereço inexistente.

Clientes e endereços

Visão geral

Customers

Requisição

Resposta

Atributos de cliente

Campos padrão

CPF/CNPJ

Atributos customizáveis

Recomendação

Addresses

Marcadores default Novo

Comportamento ao remover marcação

Formas de uso suportadas

Recomendações para integração

Recomendado

Evitar

Dica de sincronização

Erros comuns