Criar cliente

Cadastra um cliente final na agenda do parceiro.

POST/v1/clientes

clientes:escrever Idempotency-Key aceita

Quando usar

Quando uma venda chega ao seu sistema com um destinatário novo e você quer guardá-lo na agenda do parceiro para os próximos pedidos.

Corpo

Parâmetro	Tipo	Padrão	Descrição
`nome` obrigatório	texto	—	Nome completo, de 3 a 120 caracteres.
`whatsapp`	texto	—	DDD + número, com ou sem o `55`. Aceita máscara: `(51) 99999-0000` vira `5551999990000`.
`endereco.cep` obrigatório	texto	—	Oito dígitos, com ou sem hífen.
`endereco.rua` obrigatório	texto	—	De 2 a 160 caracteres.
`endereco.numero` obrigatório	texto	—	Até 20 caracteres. Use `S/N` se não houver.
`endereco.complemento`	texto	—	Até 80 caracteres.
`endereco.bairro` obrigatório	texto	—	De 2 a 80 caracteres.
`endereco.cidade` obrigatório	texto	—	De 2 a 80 caracteres.
`endereco.uf` obrigatório	texto	—	Sigla do estado, com duas letras.

Exemplo

curl -X POST "https://api.otlshoes.com.br/v1/clientes" \
  -H "Authorization: Bearer otl_prod_SEU_TOKEN" \
  -H "Idempotency-Key: 7f3c1b9e-pedido-ml-123" \
  -H "Content-Type: application/json" \
  -d '{
  "nome": "Maria da Silva",
  "whatsapp": "5551999990000",
  "endereco": {
    "cep": "90000-000",
    "rua": "Rua das Flores",
    "numero": "10",
    "complemento": "ap 2",
    "bairro": "Centro",
    "cidade": "Porto Alegre",
    "uf": "RS"
  }
}'

curl -X POST "https://api-sandbox.otlshoes.com.br/v1/clientes" \
  -H "Authorization: Bearer otl_sbx_SEU_TOKEN" \
  -H "Idempotency-Key: 7f3c1b9e-pedido-ml-123" \
  -H "Content-Type: application/json" \
  -d '{
  "nome": "Maria da Silva",
  "whatsapp": "5551999990000",
  "endereco": {
    "cep": "90000-000",
    "rua": "Rua das Flores",
    "numero": "10",
    "complemento": "ap 2",
    "bairro": "Centro",
    "cidade": "Porto Alegre",
    "uf": "RS"
  }
}'

const resposta = await fetch('https://api.otlshoes.com.br/v1/clientes', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer otl_prod_SEU_TOKEN',
    'Idempotency-Key': '7f3c1b9e-pedido-ml-123',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "nome": "Maria da Silva",
    "whatsapp": "5551999990000",
    "endereco": {
      "cep": "90000-000",
      "rua": "Rua das Flores",
      "numero": "10",
      "complemento": "ap 2",
      "bairro": "Centro",
      "cidade": "Porto Alegre",
      "uf": "RS"
    }
  }),
});

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', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer otl_sbx_SEU_TOKEN',
    'Idempotency-Key': '7f3c1b9e-pedido-ml-123',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "nome": "Maria da Silva",
    "whatsapp": "5551999990000",
    "endereco": {
      "cep": "90000-000",
      "rua": "Rua das Flores",
      "numero": "10",
      "complemento": "ap 2",
      "bairro": "Centro",
      "cidade": "Porto Alegre",
      "uf": "RS"
    }
  }),
});

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');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer otl_prod_SEU_TOKEN',
    'Idempotency-Key: 7f3c1b9e-pedido-ml-123',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'nome' => 'Maria da Silva',
    'whatsapp' => '5551999990000',
    'endereco' => [
        'cep' => '90000-000',
        'rua' => 'Rua das Flores',
        'numero' => '10',
        'complemento' => 'ap 2',
        'bairro' => 'Centro',
        'cidade' => 'Porto Alegre',
        'uf' => 'RS',
    ],
]));

$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');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer otl_sbx_SEU_TOKEN',
    'Idempotency-Key: 7f3c1b9e-pedido-ml-123',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'nome' => 'Maria da Silva',
    'whatsapp' => '5551999990000',
    'endereco' => [
        'cep' => '90000-000',
        'rua' => 'Rua das Flores',
        'numero' => '10',
        'complemento' => 'ap 2',
        'bairro' => 'Centro',
        'cidade' => 'Porto Alegre',
        'uf' => 'RS',
    ],
]));

$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.post(
    "https://api.otlshoes.com.br/v1/clientes",
    headers={
        "Authorization": "Bearer otl_prod_SEU_TOKEN",
        "Idempotency-Key": "7f3c1b9e-pedido-ml-123",
    },
    json={
        "nome": "Maria da Silva",
        "whatsapp": "5551999990000",
        "endereco": {
            "cep": "90000-000",
            "rua": "Rua das Flores",
            "numero": "10",
            "complemento": "ap 2",
            "bairro": "Centro",
            "cidade": "Porto Alegre",
            "uf": "RS"
        }
    },
    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.post(
    "https://api-sandbox.otlshoes.com.br/v1/clientes",
    headers={
        "Authorization": "Bearer otl_sbx_SEU_TOKEN",
        "Idempotency-Key": "7f3c1b9e-pedido-ml-123",
    },
    json={
        "nome": "Maria da Silva",
        "whatsapp": "5551999990000",
        "endereco": {
            "cep": "90000-000",
            "rua": "Rua das Flores",
            "numero": "10",
            "complemento": "ap 2",
            "bairro": "Centro",
            "cidade": "Porto Alegre",
            "uf": "RS"
        }
    },
    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 testePOSTIdempotency-KeyCorpo (JSON)

Resposta

201 Created, com o cliente como ficou gravado:

{
  "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"
}

Regras que não se leem no JSON

A saída vem normalizada: CEP sem hífen, WhatsApp só com dígitos e o 55, UF em maiúsculas.
A API não impede clientes repetidos. Duas pessoas podem ter o mesmo nome e o mesmo endereço. Para não duplicar por nova tentativa, mande Idempotency-Key; para não duplicar por regra de negócio, procure antes com Listar clientes.
Campos que a API não conhece são ignorados.

Sem CPF

O cadastro não tem documento do cliente. A OTL guarda o mínimo necessário para entregar o pedido.

Erros possíveis

HTTP	`codigo`	Quando
400	`VALIDACAO`	Campo obrigatório ausente ou inválido. `detalhes` traz todos os problemas de uma vez, cada um com o `campo` (ex.: `endereco.cep`)
400	`REQUISICAO_INVALIDA`	O corpo não é um objeto JSON
403	`ESCOPO_INSUFICIENTE`	A integração não tem `clientes:escrever`
422	`IDEMPOTENCY_KEY_REUTILIZADA`	A mesma chave já foi usada com outro corpo