Clientes

A API de clientes permite listar, consultar, cadastrar e atualizar clientes do produtor autenticado.

Importante

Todas as rotas exigem Authorization: Bearer {token}. Os resultados são sempre limitados ao produtor dono do token; um cliente de outra conta não pode ser consultado ou alterado.

Observação

Escopo por produtor. As quatro rotas de clientes usam o produtor pai do token: quando o token pertence a uma subconta (funcionário vinculado a um produtor), a API opera sobre a base de clientes do produtor pai, não sobre a subconta. Pacotes, Produtos e Pedidos seguem o mesmo comportamento.

Endpoints disponíveis

Método	Endpoint	Permissão do token	Resultado
`GET`	`/api/v1/clientes`	`listar_cliente_api`	Lista paginada, até 500 clientes por página
`GET`	`/api/v1/clientes/{id}`	`editar_cliente_api`	Um cliente
`POST`	`/api/v1/clientes`	`criar_cliente_api`	Cadastra um cliente
`PUT`	`/api/v1/clientes/{id}`	`editar_cliente_api`	Atualiza somente os campos enviados

Observação

Na implementação atual, a consulta individual (GET /clientes/{id}) exige a permissão editar_cliente_api, embora seja uma operação de leitura.

Listar clientes

GET

bash

curl --request GET \
  --url 'https://ev.paylog.cash/api/v1/clientes?page=1' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN'

http

GET /api/v1/clientes?page=1 HTTP/1.1
Host: ev.paylog.cash
Accept: application/json
Authorization: Bearer SEU_TOKEN

Parâmetros de consulta

Campo	Tipo	Obrigatório	Comportamento atual
`page`	inteiro	Não	Página solicitada. Quando omitido, usa `1`.

Resposta `200`

json

{
  "current_page": 1,
  "data": [
    {
      "id": 2048,
      "sexo": "F",
      "cpf": "52998224725",
      "nome": "Cliente Exemplo API",
      "data_nascimento": "1990-05-12",
      "inscricao_estadual": null,
      "email": "[email protected]",
      "endereco": "Avenida Paulista",
      "numero": "1000",
      "complemento": "Conjunto 101",
      "bairro": "Bela Vista",
      "cidade": "Sao Paulo",
      "estado": "SP",
      "pais": "Brasil",
      "cep": "01310100",
      "telefone": "1133334444",
      "celular": "11987654321",
      "referencia_externa": "CRM-2048",
      "created_at": "2026-07-22 09:30:00",
      "updated_at": "2026-07-22 09:30:00"
    }
  ],
  "first_page_url": "https://ev.paylog.cash/api/v1/clientes?page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "https://ev.paylog.cash/api/v1/clientes?page=1",
  "links": [
    {
      "url": null,
      "label": "&laquo; Anterior",
      "page": null,
      "active": false
    },
    {
      "url": "https://ev.paylog.cash/api/v1/clientes?page=1",
      "label": "1",
      "page": 1,
      "active": true
    },
    {
      "url": null,
      "label": "Próxima &raquo;",
      "page": null,
      "active": false
    }
  ],
  "next_page_url": null,
  "path": "https://ev.paylog.cash/api/v1/clientes",
  "per_page": 500,
  "prev_page_url": null,
  "to": 1,
  "total": 1
}

Campos de `data[]`

Todos os campos abaixo são sempre incluídos em cada item. Os campos marcados como anuláveis podem conter null em cadastros históricos.

Campo	Tipo	Sempre retornado	Descrição
`id`	inteiro	Sim	Identificador numérico do cliente.
`sexo`	string ou `null`	Sim	Sexo informado no cadastro; a API não restringe os valores.
`cpf`	string ou `null`	Sim	CPF ou CNPJ armazenado somente com dígitos.
`nome`	string ou `null`	Sim	Nome do cliente.
`data_nascimento`	`YYYY-MM-DD` ou `null`	Sim	Data de nascimento. Nesta listagem, a data usa o formato do banco.
`inscricao_estadual`	string ou `null`	Sim	Inscrição estadual, quando informada.
`email`	string ou `null`	Sim	E-mail do cliente.
`endereco`	string ou `null`	Sim	Logradouro.
`numero`	string ou `null`	Sim	Número do endereço.
`complemento`	string ou `null`	Sim	Complemento do endereço.
`bairro`	string ou `null`	Sim	Bairro.
`cidade`	string ou `null`	Sim	Cidade.
`estado`	string ou `null`	Sim	Estado/UF.
`pais`	string ou `null`	Sim	País.
`cep`	string ou `null`	Sim	CEP armazenado.
`telefone`	string ou `null`	Sim	Telefone principal.
`celular`	string ou `null`	Sim	Celular, quando informado.
`referencia_externa`	string ou `null`	Sim	Identificador do cliente no sistema integrador.
`created_at`	datetime ou `null`	Sim	Criação no formato `YYYY-MM-DD HH:mm:ss`.
`updated_at`	datetime ou `null`	Sim	Última atualização no formato `YYYY-MM-DD HH:mm:ss`.

Metadados da paginação

Campo	Tipo	Sempre retornado	Descrição
`current_page`	inteiro	Sim	Página atual.
`data`	array	Sim	Clientes da página; pode ser `[]`.
`first_page_url`	string	Sim	URL da primeira página.
`from`	inteiro ou `null`	Sim	Posição do primeiro item; `null` quando não há resultados.
`last_page`	inteiro	Sim	Última página disponível.
`last_page_url`	string	Sim	URL da última página.
`links`	array	Sim	Links navegáveis da paginação.
`links[].url`	string ou `null`	Sim	URL do link; `null` quando indisponível.
`links[].label`	string	Sim	Rótulo HTML do link.
`links[].page`	inteiro ou `null`	Sim	Página do link.
`links[].active`	booleano	Sim	Indica o link da página atual.
`next_page_url`	string ou `null`	Sim	Próxima página, quando existir.
`path`	string	Sim	URL base da coleção.
`per_page`	inteiro	Sim	Limite fixo de `500` itens por página.
`prev_page_url`	string ou `null`	Sim	Página anterior, quando existir.
`to`	inteiro ou `null`	Sim	Posição do último item; `null` quando vazio.
`total`	inteiro	Sim	Total de clientes encontrados.

Atenção

Clientes unificados aparecem na listagem, mas não na consulta individual. Quando dois cadastros duplicados são unificados no painel, o registro absorvido continua existindo na tabela e continua sendo devolvido por GET /api/v1/clientes. Já GET /api/v1/clientes/{id} e PUT /api/v1/clientes/{id} ignoram registros absorvidos e respondem 401 para eles. Se um ID retornado pela listagem responde 401 na consulta individual, o cadastro foi unificado — use o cliente que o absorveu.

Consultar um cliente

GET

bash

curl --request GET \
  --url 'https://ev.paylog.cash/api/v1/clientes/2048' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN'

http

GET /api/v1/clientes/2048 HTTP/1.1
Host: ev.paylog.cash
Accept: application/json
Authorization: Bearer SEU_TOKEN

Parâmetro de rota

Campo	Tipo	Obrigatório	Descrição
`id`	inteiro	Sim	ID de um cliente pertencente ao produtor autenticado.

Resposta `200`

json

{
  "code": 200,
  "cliente": {
    "id": 2048,
    "sexo": "F",
    "cpf": "52998224725",
    "nome": "Cliente Exemplo API",
    "data_nascimento": "1990-05-12T00:00:00.000000Z",
    "email": "[email protected]",
    "endereco": "Avenida Paulista",
    "numero": "1000",
    "complemento": "Conjunto 101",
    "bairro": "Bela Vista",
    "cidade": "Sao Paulo",
    "estado": "SP",
    "pais": "Brasil",
    "cep": "01310100",
    "telefone": "1133334444",
    "celular": "11987654321",
    "referencia_externa": "CRM-2048",
    "created_at": "2026-07-22T12:30:00.000000Z",
    "updated_at": "2026-07-22T12:30:00.000000Z",
    "inscricao_estadual": null
  }
}

Campo	Tipo	Sempre retornado	Descrição
`code`	inteiro	Sim	Código de sucesso no corpo; atualmente `200`.
`cliente`	objeto	Sim	Cliente encontrado.
`cliente.id`	inteiro	Sim	Identificador numérico do cliente.
`cliente.sexo`	string ou `null`	Sim	Sexo informado no cadastro.
`cliente.cpf`	string ou `null`	Sim	CPF ou CNPJ armazenado.
`cliente.nome`	string ou `null`	Sim	Nome do cliente.
`cliente.data_nascimento`	ISO 8601 ou `null`	Sim	Data de nascimento serializada pelo modelo.
`cliente.email`	string ou `null`	Sim	E-mail do cliente.
`cliente.endereco`	string ou `null`	Sim	Logradouro.
`cliente.numero`	string ou `null`	Sim	Número do endereço.
`cliente.complemento`	string ou `null`	Sim	Complemento do endereço.
`cliente.bairro`	string ou `null`	Sim	Bairro.
`cliente.cidade`	string ou `null`	Sim	Cidade.
`cliente.estado`	string ou `null`	Sim	Estado/UF.
`cliente.pais`	string ou `null`	Sim	País.
`cliente.cep`	string ou `null`	Sim	CEP armazenado.
`cliente.telefone`	string ou `null`	Sim	Telefone principal.
`cliente.celular`	string ou `null`	Sim	Celular, quando informado.
`cliente.referencia_externa`	string ou `null`	Sim	Identificador no sistema integrador.
`cliente.created_at`	ISO 8601 ou `null`	Sim	Data de criação.
`cliente.updated_at`	ISO 8601 ou `null`	Sim	Data da última atualização.
`cliente.inscricao_estadual`	string ou `null`	Sim	Inscrição estadual, quando informada.

Atenção

Cliente inexistente, cliente pertencente a outro produtor e cliente unificado (absorvido por um duplicado) retornam a mesma resposta 401. Essa igualdade evita revelar a existência de dados de outra conta.

json

{
  "code": 401,
  "message": "Nao autorizado"
}

Cadastrar um cliente

POST

bash

curl --request POST \
  --url 'https://ev.paylog.cash/api/v1/clientes' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "cpf": "52998224725",
    "nome": "Cliente Exemplo API",
    "data_nascimento": "12/05/1990",
    "email": "[email protected]",
    "telefone": "1133334444",
    "celular": "11987654321",
    "sexo": "F",
    "cep": "01310100",
    "endereco": "Avenida Paulista",
    "numero": "1000",
    "complemento": "Conjunto 101",
    "bairro": "Bela Vista",
    "cidade": "Sao Paulo",
    "estado": "SP",
    "pais": "Brasil",
    "inscricao_estadual": null,
    "referencia_externa": "CRM-2048"
  }'

http

POST /api/v1/clientes HTTP/1.1
Host: ev.paylog.cash
Accept: application/json
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

Corpo da requisição

json

{
  "cpf": "52998224725",
  "nome": "Cliente Exemplo API",
  "data_nascimento": "12/05/1990",
  "email": "[email protected]",
  "telefone": "1133334444",
  "celular": "11987654321",
  "sexo": "F",
  "cep": "01310100",
  "endereco": "Avenida Paulista",
  "numero": "1000",
  "complemento": "Conjunto 101",
  "bairro": "Bela Vista",
  "cidade": "Sao Paulo",
  "estado": "SP",
  "pais": "Brasil",
  "inscricao_estadual": null,
  "referencia_externa": "CRM-2048"
}

jsonc

{
  "cpf": "52998224725",                  // obrigatório: CPF ou CNPJ válido, diferente do documento do produtor
  "nome": "Cliente Exemplo API",         // obrigatório: string não vazia
  "data_nascimento": "12/05/1990",       // opcional: quando enviado, use DD/MM/AAAA
  "email": "[email protected]",    // obrigatório: e-mail válido
  "telefone": "1133334444",              // obrigatório: string não vazia
  "celular": "11987654321",              // opcional
  "sexo": "F",                           // opcional: a API aceita qualquer string não vazia
  "cep": "01310100",                     // obrigatório: string não vazia
  "endereco": "Avenida Paulista",        // obrigatório: string não vazia
  "numero": "1000",                      // obrigatório: string não vazia
  "complemento": "Conjunto 101",         // opcional
  "bairro": "Bela Vista",                // obrigatório: string não vazia
  "cidade": "Sao Paulo",                 // obrigatório: string não vazia
  "estado": "SP",                        // obrigatório: string não vazia
  "pais": "Brasil",                      // obrigatório: string não vazia
  "inscricao_estadual": null,             // opcional
  "referencia_externa": "CRM-2048"       // opcional: ID no seu sistema
}

Campos aceitos

Campo	Tipo	No `POST`	No `PUT`	Regras atuais
`cpf`	string	Obrigatório	Opcional	CPF ou CNPJ válido; não pode ser o documento do próprio produtor.
`nome`	string	Obrigatório	Opcional	Não vazio.
`data_nascimento`	string	Opcional	Opcional	Quando enviado, formato `DD/MM/AAAA`.
`email`	string	Obrigatório	Opcional	E-mail válido e não vazio.
`telefone`	string	Obrigatório	Opcional	Não vazio.
`celular`	string ou `null`	Opcional	Opcional	Sem validação de formato.
`sexo`	string	Opcional	Opcional	Quando enviado, não pode ser vazio; não há enumeração.
`cep`	string	Obrigatório	Opcional	Não vazio; a rota não valida quantidade de dígitos.
`endereco`	string	Obrigatório	Opcional	Não vazio.
`numero`	string	Obrigatório	Opcional	Não vazio.
`complemento`	string ou `null`	Opcional	Opcional	Pode ser vazio.
`bairro`	string	Obrigatório	Opcional	Não vazio.
`cidade`	string	Obrigatório	Opcional	Não vazio.
`estado`	string	Obrigatório	Opcional	Não vazio; a rota não limita a duas letras.
`pais`	string	Obrigatório	Opcional	Não vazio.
`inscricao_estadual`	string ou `null`	Opcional	Opcional	Sem validação de formato.
`referencia_externa`	string ou `null`	Opcional	Opcional	Referência do cliente no sistema integrador.

Importante

Campos internos não listados nesta tabela não fazem parte do contrato público e não devem ser enviados, mesmo que sejam ignorados ou aceitos pela camada de persistência atual.

Atenção

Não há verificação de duplicidade. A API não aplica regra de unicidade a cpf, email ou referencia_externa: enviar duas vezes o mesmo documento ou o mesmo e-mail cria dois cadastros distintos. Cabe ao integrador consultar antes de cadastrar (ou guardar o cliente retornado) para não duplicar a base.

As duas únicas validações aplicadas ao documento são: (1) cpf precisa ser um CPF ou CNPJ com dígitos verificadores válidos; (2) o documento não pode ser igual ao documento cadastrado do próprio produtor — nesse caso o erro é O cliente não pode ser cadastrado com o seu número de documento..

Observação

Corpo inválido devolve 400, não 422. As rotas de clientes não usam o envelope padrão de validação do Laravel; a resposta é 400 com as chaves code, message e erros. Veja Erros.

Resposta `200`

O cadastro retorna o ID numérico, e não o objeto completo. O status atual é 200.

json

{
  "code": 200,
  "message": "Cliente cadastrado com sucesso",
  "cliente": 2048
}

Campo	Tipo	Sempre retornado	Descrição
`code`	inteiro	Sim	Código de sucesso no corpo (`200`).
`message`	string	Sim	Mensagem de confirmação.
`cliente`	inteiro	Sim	ID do cliente criado.

Atualizar um cliente

Somente os campos presentes no corpo são alterados. Consulte a coluna No PUT da tabela anterior.

PUT

bash

curl --request PUT \
  --url 'https://ev.paylog.cash/api/v1/clientes/2048' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "nome": "Cliente Atualizado",
    "data_nascimento": "13/05/1990",
    "complemento": "Sala 12"
  }'

http

PUT /api/v1/clientes/2048 HTTP/1.1
Host: ev.paylog.cash
Accept: application/json
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

json

{
  "nome": "Cliente Atualizado",
  "data_nascimento": "13/05/1990",
  "complemento": "Sala 12"
}

jsonc

{
  "nome": "Cliente Atualizado",          // opcional: altera somente o nome
  "data_nascimento": "13/05/1990",      // opcional: quando enviado, use DD/MM/AAAA
  "complemento": "Sala 12"              // opcional: pode ser limpo com uma string vazia
}

Resposta `200`

json

{
  "code": 200,
  "cliente": {
    "id": 2048,
    "code": "CUST01KY56XRPDEG7K9KG7G8CDT7SN",
    "ml_buyer_id": null,
    "pais": "Brasil",
    "nome": "Cliente Atualizado",
    "sexo": "F",
    "cpf": "52998224725",
    "inscricao_estadual": null,
    "data_nascimento": "1990-05-13T12:30:00.000000Z",
    "email": "[email protected]",
    "endereco": "Avenida Paulista",
    "numero": "1000",
    "complemento": "Sala 12",
    "bairro": "Bela Vista",
    "cidade": "Sao Paulo",
    "estado": "SP",
    "cep": "01310100",
    "telefone": "1133334444",
    "celular": "11987654321",
    "referencia_externa": "CRM-2048",
    "platform_customer_id": null,
    "plataforma_origem": null,
    "created_at": "2026-07-22T12:30:00.000000Z",
    "updated_at": "2026-07-22T12:45:00.000000Z",
    "email_valido": 1,
    "cart_abandoned": false,
    "cart_abandoned_at": null,
    "merged_into_id": null,
    "merged_at": null
  }
}

O PUT serializa o modelo completo por compatibilidade. Além dos campos públicos já descritos, os campos abaixo são sempre incluídos nessa resposta atual:

Campo	Tipo	Sempre retornado	Descrição
`code`	inteiro	Sim	Código de sucesso no envelope.
`cliente.id`	inteiro	Sim	ID numérico.
`cliente.code`	string	Sim	Identificador público ULID do cliente, gerado pelo Paylog.
`cliente.ml_buyer_id`	string ou `null`	Sim	Identificador de comprador do Mercado Livre, quando aplicável. Somente leitura.
`cliente.pais`	string ou `null`	Sim	País.
`cliente.nome`	string ou `null`	Sim	Nome.
`cliente.sexo`	string ou `null`	Sim	Sexo informado.
`cliente.cpf`	string ou `null`	Sim	CPF/CNPJ normalizado.
`cliente.inscricao_estadual`	string ou `null`	Sim	Inscrição estadual.
`cliente.data_nascimento`	ISO 8601 ou `null`	Sim	Data serializada pelo modelo.
`cliente.email`	string ou `null`	Sim	E-mail.
`cliente.endereco`	string ou `null`	Sim	Logradouro.
`cliente.numero`	string ou `null`	Sim	Número.
`cliente.complemento`	string ou `null`	Sim	Complemento.
`cliente.bairro`	string ou `null`	Sim	Bairro.
`cliente.cidade`	string ou `null`	Sim	Cidade.
`cliente.estado`	string ou `null`	Sim	Estado/UF.
`cliente.cep`	string ou `null`	Sim	CEP.
`cliente.telefone`	string ou `null`	Sim	Telefone.
`cliente.celular`	string ou `null`	Sim	Celular.
`cliente.referencia_externa`	string ou `null`	Sim	Referência externa.
`cliente.platform_customer_id`	string ou `null`	Sim	Identificador recebido da plataforma de origem. Somente leitura.
`cliente.plataforma_origem`	inteiro ou `null`	Sim	Código interno da plataforma de origem. Somente leitura.
`cliente.created_at`	ISO 8601 ou `null`	Sim	Data de criação.
`cliente.updated_at`	ISO 8601 ou `null`	Sim	Data de atualização.
`cliente.email_valido`	inteiro	Sim	Indicador legado de validação do e-mail. Somente leitura.
`cliente.cart_abandoned`	booleano	Sim	Indica associação a carrinho abandonado. Somente leitura.
`cliente.cart_abandoned_at`	ISO 8601 ou `null`	Sim	Data do carrinho abandonado. Somente leitura.
`cliente.merged_into_id`	inteiro ou `null`	Sim	Cliente de destino quando houve unificação. Somente leitura.
`cliente.merged_at`	ISO 8601 ou `null`	Sim	Data da unificação. Somente leitura.

Observação

A listagem usa datas do banco (YYYY-MM-DD e YYYY-MM-DD HH:mm:ss), enquanto as respostas baseadas no modelo (GET individual e PUT) usam ISO 8601. Integrações devem aceitar ambos os formatos nos respectivos endpoints.

Erros

Status	Corpo atual	Quando ocorre
`400`	`{ "code": 400, "message": "Requisicao invalida", "erros": { … } }`	Corpo inválido no `POST` ou `PUT`.
`401`	`{ "message": "Unauthenticated." }`	Token ausente ou inválido.
`401`	`{ "code": 401, "message": "Nao autorizado" }`	Cliente inexistente, de outro produtor ou unificado.
`403`	`{ "errors": "User does not have the right permissions.", "code": 403 }`	Token sem a permissão exigida pela rota.
`405`	`{ "errors": "The DELETE method is not supported for route api/v1/clientes/1. Supported methods: GET, HEAD, PUT.", "code": 405 }`	Verbo não suportado (`DELETE`, `PATCH`, `POST` em `/clientes/{id}`). Ocorre antes da autenticação.
`500`	`{ "code": 500, "message": "Um erro interno ocorreu ao registrar cliente, tente novamente, se persistir contate o suporte" }`	Falha interna ao cadastrar ou atualizar.

Corpo de validação (400):

json

{
  "code": 400,
  "message": "Requisicao invalida",
  "erros": {
    "email": [
      "O campo email deve ser um endereço de e-mail válido."
    ]
  }
}

Observação

erros é um objeto no qual cada chave é o nome do campo rejeitado e o valor é um array de mensagens. Um POST com corpo vazio devolve, no mínimo, as chaves cpf, nome, email, telefone, cep, endereco, numero, bairro, cidade, estado e pais.

Importante

Os envelopes 403 e 405 usam a chave errors (plural, string), enquanto os erros gerados pelo próprio controlador usam message e erros. As duas formas convivem no contrato atual — trate ambas no seu cliente HTTP.

#Endpoints disponíveis

#Listar clientes

#Parâmetros de consulta

#Resposta 200

#Campos de data[]

#Metadados da paginação

#Consultar um cliente

#Parâmetro de rota

#Resposta 200

#Cadastrar um cliente

#Corpo da requisição

#Campos aceitos

#Resposta 200

#Atualizar um cliente

#Resposta 200

#Erros

Endpoints disponíveis

Listar clientes

Parâmetros de consulta

Resposta `200`

Campos de `data[]`

Metadados da paginação

Consultar um cliente

Parâmetro de rota

Resposta `200`

Cadastrar um cliente

Corpo da requisição

Campos aceitos

Resposta `200`

Atualizar um cliente

Resposta `200`

Erros