Listar clientes

A agenda de clientes finais do parceiro — os destinatários dos pedidos dele.

GET/v1/clientes

Quando usar

Para espelhar a agenda no seu sistema, ou para achar um cliente já cadastrado antes de criar outro. A agenda é do parceiro: cada parceiro só enxerga a própria.

Dado pessoal de terceiros

A agenda guarda dados dos clientes finais do parceiro. O parceiro é o responsável por eles; quem integra trata esses dados só para a finalidade da integração. A OTL não usa a agenda para contato — só lê o endereço quando ele é usado em um pedido.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`limite`	número	50	Itens por página, de 1 a 100.
`cursor`	texto	—	O `proximoCursor` da resposta anterior.
`busca`	texto	—	Procura no nome, na cidade ou no WhatsApp.
`atualizadoDesde`	data	—	Só clientes criados ou alterados a partir desta data (com fuso).

Exemplo

curl "https://api.otlshoes.com.br/v1/clientes?busca=maria" \
  -H "Authorization: Bearer otl_prod_SEU_TOKEN"

curl "https://api-sandbox.otlshoes.com.br/v1/clientes?busca=maria" \
  -H "Authorization: Bearer otl_sbx_SEU_TOKEN"

const resposta = await fetch('https://api.otlshoes.com.br/v1/clientes?busca=maria', {
  headers: {
    Authorization: 'Bearer otl_prod_SEU_TOKEN',
  },
});

if (!resposta.ok) {
  const { erro } = await resposta.json();
  throw new Error(`${erro.codigo}: ${erro.mensagem} (${erro.requestId})`);
}
const dados = await resposta.json();

const resposta = await fetch('https://api-sandbox.otlshoes.com.br/v1/clientes?busca=maria', {
  headers: {
    Authorization: 'Bearer otl_sbx_SEU_TOKEN',
  },
});

if (!resposta.ok) {
  const { erro } = await resposta.json();
  throw new Error(`${erro.codigo}: ${erro.mensagem} (${erro.requestId})`);
}
const dados = await resposta.json();

<?php
$ch = curl_init('https://api.otlshoes.com.br/v1/clientes?busca=maria');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer otl_prod_SEU_TOKEN',
]);

$corpo = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status >= 400) {
    throw new Exception($corpo['erro']['codigo'] . ': ' . $corpo['erro']['mensagem']);
}

<?php
$ch = curl_init('https://api-sandbox.otlshoes.com.br/v1/clientes?busca=maria');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer otl_sbx_SEU_TOKEN',
]);

$corpo = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status >= 400) {
    throw new Exception($corpo['erro']['codigo'] . ': ' . $corpo['erro']['mensagem']);
}

import requests

resposta = requests.get(
    "https://api.otlshoes.com.br/v1/clientes",
    headers={
        "Authorization": "Bearer otl_prod_SEU_TOKEN",
    },
    params={
        "busca": "maria"
    },
    timeout=30,
)

if not resposta.ok:
    erro = resposta.json()["erro"]
    raise RuntimeError(f'{erro["codigo"]}: {erro["mensagem"]} ({erro["requestId"]})')
dados = resposta.json()

import requests

resposta = requests.get(
    "https://api-sandbox.otlshoes.com.br/v1/clientes",
    headers={
        "Authorization": "Bearer otl_sbx_SEU_TOKEN",
    },
    params={
        "busca": "maria"
    },
    timeout=30,
)

if not resposta.ok:
    erro = resposta.json()["erro"]
    raise RuntimeError(f'{erro["codigo"]}: {erro["mensagem"]} ({erro["requestId"]})')
dados = resposta.json()

Testar agora no ambiente de testes

A chamada é feita de verdade, do seu navegador para a API de testes (https://api-sandbox.otlshoes.com.br/v1). Use um token otl_sbx_…: ele fica só nesta aba, e some ao fechá-la. Token de produção não é aceito aqui.

Token de testeGET

Resposta

{
  "dados": [
    {
      "id": "cmg7h2k9x0003",
      "nome": "Maria da Silva",
      "whatsapp": "5551999990000",
      "endereco": {
        "cep": "90000000",
        "rua": "Rua das Flores",
        "numero": "10",
        "complemento": "ap 2",
        "bairro": "Centro",
        "cidade": "Porto Alegre",
        "uf": "RS"
      },
      "criadoEm": "2026-09-20T09:15:00-03:00",
      "atualizadoEm": "2026-09-29T14:03:00-03:00"
    },
    {
      "id": "cmg7h2k9x0007",
      "nome": "Pedro Alves",
      "whatsapp": null,
      "endereco": {
        "cep": "90000000",
        "rua": "Av. Brasil",
        "numero": "500",
        "complemento": null,
        "bairro": "Centro",
        "cidade": "Canoas",
        "uf": "RS"
      },
      "criadoEm": "2026-09-20T09:15:00-03:00",
      "atualizadoEm": "2026-09-29T14:03:00-03:00"
    }
  ],
  "paginacao": {
    "proximoCursor": null,
    "temMais": false
  }
}

Campo	Tipo	Descrição
`dados[].id`	texto	Identificador do cliente. Use nas outras rotas.
`dados[].nome`	texto	Nome completo do destinatário.
`dados[].whatsapp`	texto ou null	Só dígitos, com DDI: `55` + DDD + número. `null` = sem contato.
`dados[].endereco.cep`	texto	Oito dígitos, sem hífen.
`dados[].endereco.complemento`	texto ou null	Apartamento, bloco, referência.
`dados[].endereco.uf`	texto	Sigla do estado, em maiúsculas.
`dados[].criadoEm`	data	Quando entrou na agenda.
`dados[].atualizadoEm`	data	Última alteração.
`paginacao`	objeto	Veja Paginação.

Regras que não se leem no JSON

A ordem é por nome. Com atualizadoDesde, passa a ser da alteração mais antiga para a mais nova — a ordem certa para sincronizar.
Não há CPF do cliente. A OTL guarda o mínimo para entregar um pedido.
Cliente removido não aparece em atualizadoDesde: a remoção não deixa rastro na agenda.

Erros possíveis

HTTP	`codigo`	Quando
400	`PARAMETRO_INVALIDO`	`limite` fora de 1–100 ou data sem fuso
400	`CURSOR_INVALIDO`	Cursor alterado, ou de outra consulta
403	`ESCOPO_INSUFICIENTE`	A integração não tem `clientes:ler`

Ver também

Criar cliente