Thiago Morangos API — Documentação

Base URL fixa: https://api.thiagomorangos.com.br/
Esta documentação descreve o contrato público da API (rotas, autenticação, headers e formatos de resposta).

1) Visão geral

1.1 Base URL e versionamento

A API é acessada sempre pela base URL fixa: https://api.thiagomorangos.com.br/
As rotas públicas seguem o prefixo: /api/v1/… (versionamento por caminho).

1.2 Convenções HTTP

• JSON por padrão: endpoints aceitam/retornam JSON (exceto preflight OPTIONS que responde sem body).
• Content-Type esperado em requests com body: application/json.
• Status codes: 200/201, 400, 401, 403, 404, 429, 500 e 502.
• Headers: CORS habilitado (ver seção CORS).

1.3 Padrão de resposta JSON e erros

{
  "ok": true,
  "message": "…",
  "data": {},
  "timestamp": "2026-01-25T00:00:00.000Z"
}

{
  "ok": false,
  "error": true,
  "message": "…",
  "timestamp": "2026-01-25T00:00:00.000Z"
}

Observação: alguns endpoints retornam campos adicionais específicos (por exemplo, dados de token, paginação, etc.). Sempre trate campos extras como extensões do contrato para manter compatibilidade futura.

1.4 Quickstart (60s)

1.5 Resumo de endpoints

2) Autenticação e autorização

A API usa:

• Authorization: Bearer <token> para sessões (cliente e admin)
• X-Setup-Token para rotas administrativas sensíveis de setup/manutenção em /__admin/*

2.1 Fluxo de login do cliente

1. login-start: informe o telefone do cliente para iniciar o desafio de login (código). Em ambiente de desenvolvimento, a resposta pode incluir o codigo para facilitar testes.
2. login-confirm: informe telefone + codigo para confirmar o desafio e receber o session_token (use-o como Bearer nas rotas autenticadas).

2.2 Fluxo de login do admin

Login via usuário/senha → emissão de token Bearer com validade (expires_at). Rotas admin exigem token e algumas exigem nível mínimo (controle legado).

2.3 Rotas de setup (X-Setup-Token)

Rotas /__admin/* exigem X-Setup-Token com o valor configurado em SETUP_TOKEN no ambiente do Worker.

3) CORS e preflight (OPTIONS)

Preflight global com:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,POST,PUT,PATCH,DELETE,OPTIONS
Access-Control-Allow-Headers: Content-Type,Authorization,X-Setup-Token
Access-Control-Max-Age: 86400

4) Endpoints

As rotas abaixo estão agrupadas por domínio funcional. Quando campos exatos dependerem do schema do banco, esta documentação descreve o mínimo garantido e boas práticas de consumo.

4.1 Health

4.2 Consulta de CEP (ViaCEP)

Parâmetro: cep (somente números, com ou sem máscara).

4.3 Busca de imagens (Unsplash)

Querystring: q/query (obrigatório), page, per_page.

4.4 Autenticação do cliente

Autenticação de cliente via desafio por código (2 etapas). Ao final, a API retorna um session_token que deve ser usado como Authorization: Bearer <token>.

4.4.1 POST /api/v1/auth/login-start

Inicia o login: o usuário informa seu telefone e o servidor inicia um desafio (código de 6 caracteres). O código expira; quando presente, use o campo expira_em retornado pela API para exibir o prazo.

Headers

• Content-Type: application/json

Body (JSON)

• telefone (string) — telefone do cliente. Pode ser enviado com máscara; o servidor pode normalizar (aceite recomendado: somente dígitos).

Resposta de sucesso (200)

{
  "ok": true,
  "data": {
    "cliente_id": 123,
    "telefone": "16999999999",
    "expira_em": "2026-01-26T12:34:56.000Z",
    "codigo": "ABC123" 
  }
}

Obs.: o campo codigo pode estar presente apenas em DEV (use-o como opcional).

Erros comuns

• 400: dados inválidos (ex.: telefone ausente/ inválido). Retorna { ok:false, message }.
• 429: rate limit. Pode retornar { ok:false, message, retry_after }.

Exemplo (cURL)

BASE="https://api.thiagomorangos.com.br"

curl -s "$BASE/api/v1/auth/login-start"   -H "Content-Type: application/json"   -d '{"telefone":"16999999999"}'

4.4.2 POST /api/v1/auth/login-confirm

Confirma o código e retorna o token de sessão. O cliente deve persistir o token e enviá-lo como Bearer.

Headers

• Content-Type: application/json

Body (JSON)

• telefone (string) — mesmo telefone usado no login-start.
• codigo (string) — código recebido (6 caracteres). Em DEV pode ser alfanumérico (ex.: ABC123).

Resposta de sucesso (200)

{
  "ok": true,
  "data": {
    "session_token": "eyJ...",
    "expires_at": "2026-01-26T22:34:56.000Z",
    "cliente": {
      "id": 123,
      "nome": "João Silva",
      "telefone": "16999999999",
      "email": "joao@email.com",
      "tipo_pessoa": "PF"
    }
  }
}

Erros comuns

• 400/401: código inválido, expirado, ou não correspondente ao telefone. Retorna { ok:false, message }.
• 429: rate limit. Pode retornar { ok:false, message, retry_after }.

Exemplo (cURL)

BASE="https://api.thiagomorangos.com.br"

curl -s "$BASE/api/v1/auth/login-confirm"   -H "Content-Type: application/json"   -d '{"telefone":"16999999999","codigo":"ABC123"}'

4.4.3 POST /api/v1/auth/logout

Invalida a sessão atual (quando aplicável). Mesmo que o servidor responda com erro, o cliente deve remover o token local.

Headers

• Authorization: Bearer <session_token>

Exemplo (cURL)

BASE="https://api.thiagomorangos.com.br"
TOKEN="SEU_TOKEN_AQUI"

curl -s -X POST "$BASE/api/v1/auth/logout"   -H "Authorization: Bearer $TOKEN"

4.5 Meu perfil (cliente)

4.6 Produtos

4.7 Clientes e endereços

Endpoints de cadastro e manutenção de clientes (PF/PJ) e seus endereços. No contrato atual, estas rotas são tratadas como legado e podem não exigir Bearer — mantenha a proteção por borda (WAF/rate limit) se publicar publicamente.

4.7.1 Modelos (Cliente/Endereço)

Cliente (campos comuns)

• id (number) — identificador.
• nome (string) — nome do cliente (PF) ou contato principal (PJ).
• telefone (string) — telefone (recomendado: dígitos).
• email (string | null) — opcional.
• tipo_pessoa ("PF" | "PJ")
• ativo (boolean)
• criado_em/atualizado_em (ISO datetime)

Cliente PJ (campos adicionais)

• razao_social (string)
• cnpj (string)
• ie (string | null)
• isento_ie (boolean)

Endereço

• id (number)
• cliente_id (number)
• apelido (string) — ex.: "Casa", "Trabalho".
• cep (string) — ex.: "14020-000".
• rua (string)
• numero (string)
• complemento (string | null)
• bairro (string)
• cidade (string)
• uf (string) — 2 letras (ex.: "SP").
• distancia_km (number) — usado para cálculo de frete.
• principal (boolean) — indica endereço principal do cliente.
• criado_em/atualizado_em (ISO datetime)

4.7.2 GET /api/v1/clientes

Query params

• incluirInativos (boolean, opcional, default: false) — inclui registros desativados.
• tipo ("PF" | "PJ", opcional) — filtra por tipo.

Resposta (200)

{
  "ok": true,
  "count": 2,
  "data": [
    {
      "id": 1,
      "nome": "João Silva",
      "telefone": "16999887766",
      "email": "joao@email.com",
      "tipo_pessoa": "PF",
      "ativo": true,
      "criado_em": "2026-01-26T10:30:00.000Z"
    }
  ]
}

Exemplo (cURL)

BASE="https://api.thiagomorangos.com.br"

curl -s "$BASE/api/v1/clientes?incluirInativos=false&tipo=PF"

4.7.3 GET /api/v1/clientes/:id

Retorna o cliente e uma lista enderecos associada.

Resposta (200)

{
  "ok": true,
  "data": {
    "id": 1,
    "nome": "João Silva",
    "telefone": "16999887766",
    "email": "joao@email.com",
    "tipo_pessoa": "PF",
    "ativo": true,
    "criado_em": "2026-01-26T10:30:00.000Z",
    "enderecos": [
      {
        "id": 1,
        "apelido": "Casa",
        "cep": "14020-000",
        "rua": "Rua das Flores",
        "numero": "123",
        "complemento": "Apto 45",
        "bairro": "Centro",
        "cidade": "Ribeirão Preto",
        "uf": "SP",
        "distancia_km": 3.5,
        "principal": true,
        "criado_em": "2026-01-26T10:30:00.000Z"
      }
    ]
  }
}

Erro (404)

{
  "ok": false,
  "message": "Cliente não encontrado"
}

Exemplo (cURL)

BASE="https://api.thiagomorangos.com.br"
ID=1

curl -s "$BASE/api/v1/clientes/$ID"

4.7.4 POST /api/v1/clientes

Cria um novo cliente. Use tipo_pessoa para indicar PF ou PJ.

Headers

• Content-Type: application/json

Body (PF) — exemplo completo

{
  "nome": "Maria Santos",
  "telefone": "16988776655",
  "email": "maria@email.com",
  "tipo_pessoa": "PF"
}

Body (PJ) — exemplo completo

{
  "nome": "Contato Principal",
  "telefone": "1633334444",
  "email": "contato@empresa.com",
  "tipo_pessoa": "PJ",
  "razao_social": "Empresa Exemplo LTDA",
  "cnpj": "12.345.678/0001-99",
  "ie": "123456789",
  "isento_ie": false
}

Resposta (201)

{
  "ok": true,
  "message": "Cliente criado com sucesso",
  "data": {
    "id": 3,
    "nome": "Maria Santos",
    "telefone": "16988776655",
    "email": "maria@email.com",
    "tipo_pessoa": "PF",
    "ativo": true,
    "criado_em": "2026-01-26T15:30:00.000Z"
  }
}

Erro (400) — exemplo

{
  "ok": false,
  "message": "Nome e telefone são obrigatórios"
}

Exemplo (cURL)

BASE="https://api.thiagomorangos.com.br"

curl -s -X POST "$BASE/api/v1/clientes"   -H "Content-Type: application/json"   -d '{"nome":"Maria Santos","telefone":"16988776655","email":"maria@email.com","tipo_pessoa":"PF"}'

4.7.5 PUT /api/v1/clientes/:id

Atualiza dados do cliente. O contrato permite atualização parcial; para evitar divergência, prefira enviar o conjunto completo de campos que você mantém no seu cadastro.

Headers

• Content-Type: application/json

Body — exemplo (PF) com campos comuns

{
  "nome": "João Silva Santos",
  "telefone": "16999887766",
  "email": "joao.novo@email.com",
  "tipo_pessoa": "PF"
}

Body — exemplo (PJ) com campos adicionais

{
  "nome": "Contato Principal",
  "telefone": "1633334444",
  "email": "contato@empresa.com",
  "tipo_pessoa": "PJ",
  "razao_social": "Empresa Exemplo LTDA",
  "cnpj": "12.345.678/0001-99",
  "ie": "123456789",
  "isento_ie": false
}

Resposta (200)

{
  "ok": true,
  "message": "Cliente atualizado com sucesso",
  "data": {
    "id": 1,
    "nome": "João Silva Santos",
    "telefone": "16999887766",
    "email": "joao.novo@email.com",
    "tipo_pessoa": "PF",
    "ativo": true,
    "atualizado_em": "2026-01-26T16:00:00.000Z"
  }
}

Exemplo (cURL)

BASE="https://api.thiagomorangos.com.br"
ID=1

curl -s -X PUT "$BASE/api/v1/clientes/$ID"   -H "Content-Type: application/json"   -d '{"nome":"João Silva Santos","telefone":"16999887766","email":"joao.novo@email.com"}'

4.7.6 POST /api/v1/clientes/:id/enderecos

Adiciona um endereço ao cliente. O campo distancia_km influencia o cálculo do frete.

Headers

• Content-Type: application/json

Body — exemplo completo

{
  "apelido": "Trabalho",
  "cep": "14021-000",
  "rua": "Av. Nove de Julho",
  "numero": "500",
  "complemento": "Sala 12",
  "bairro": "Jardim América",
  "cidade": "Ribeirão Preto",
  "uf": "SP",
  "distancia_km": 6.2,
  "principal": false
}

Resposta (201)

{
  "ok": true,
  "message": "Endereço adicionado com sucesso",
  "data": {
    "id": 2,
    "cliente_id": 1,
    "apelido": "Trabalho",
    "cep": "14021-000",
    "rua": "Av. Nove de Julho",
    "numero": "500",
    "complemento": "Sala 12",
    "bairro": "Jardim América",
    "cidade": "Ribeirão Preto",
    "uf": "SP",
    "distancia_km": 6.2,
    "principal": false,
    "criado_em": "2026-01-26T16:10:00.000Z"
  }
}

Exemplo (cURL)

BASE="https://api.thiagomorangos.com.br"
CLIENTE_ID=1

curl -s -X POST "$BASE/api/v1/clientes/$CLIENTE_ID/enderecos"   -H "Content-Type: application/json"   -d '{"apelido":"Trabalho","cep":"14021-000","rua":"Av. Nove de Julho","numero":"500","complemento":"Sala 12","bairro":"Jardim América","cidade":"Ribeirão Preto","uf":"SP","distancia_km":6.2,"principal":false}'

4.7.7 PUT /api/v1/enderecos/:id

Atualiza campos do endereço. O contrato permite atualização parcial.

Headers

• Content-Type: application/json

Body — exemplo

{
  "apelido": "Trabalho - Matriz",
  "distancia_km": 6.5,
  "principal": true
}

Resposta (200)

{
  "ok": true,
  "message": "Endereço atualizado com sucesso",
  "data": {
    "id": 2,
    "apelido": "Trabalho - Matriz",
    "distancia_km": 6.5,
    "principal": true
  }
}

Exemplo (cURL)

BASE="https://api.thiagomorangos.com.br"
ENDERECO_ID=2

curl -s -X PUT "$BASE/api/v1/enderecos/$ENDERECO_ID"   -H "Content-Type: application/json"   -d '{"apelido":"Trabalho - Matriz","distancia_km":6.5,"principal":true}'

4.7.8 DELETE /api/v1/enderecos/:id

Remove um endereço. Em alguns cenários o Worker pode negar a remoção por regra de negócio (ex.: endereço vinculado a pedidos), retornando 409.

Resposta (200)

{
  "ok": true,
  "message": "Endereço removido com sucesso"
}

Exemplo (cURL)

BASE="https://api.thiagomorangos.com.br"
ENDERECO_ID=2

curl -s -X DELETE "$BASE/api/v1/enderecos/$ENDERECO_ID"

4.8 Frete

4.9 Pedidos (cliente)

4.10 Admin auth

4.11 Admin pedidos

4.12 Admin setup e manutenção

5) Erros, rate limits e boas práticas

5.1 Estrutura de erro

Os endpoints retornam JSON com ok: false e uma mensagem. Tratamento recomendado:

• Exiba message ao usuário (quando apropriado).
• Logue o body completo em ambiente de desenvolvimento.
• Trate 401 como “sessão expirada” e refaça login.
• Trate 403 em /__admin/* como “setup token inválido”.

5.2 Rate limits e retries

A API pode retornar 429, especialmente em rotas de login. Cliente deve aplicar: backoff exponencial (ex.: 0.5s, 1s, 2s, 4s) e limitar concorrência.

5.3 Idempotência e segurança no cliente

• Em falhas de rede, evite reenvio “cego” de POST que cria recursos (pedidos). Prefira confirmar por GET quando possível.
• Não logue tokens em produção (Bearer/Setup Token).

6) Integrações externas

• Turso: persistência (SQLite remoto via HTTP/libSQL).
• ViaCEP: lookup de CEP em /api/v1/cep/<cep>.
• Unsplash: busca via /api/v1/unsplash/search.

7) Variáveis de ambiente (env/secrets)

8) Exemplos práticos (cURL)

Health

curl -s "https://api.thiagomorangos.com.br/api/v1/health"

Preflight (OPTIONS)

curl -i -X OPTIONS "https://api.thiagomorangos.com.br/api/v1/health" \
  -H "Origin: https://seusite.com" \
  -H "Access-Control-Request-Method: GET"

Login do cliente (start + confirm) — pronto para copiar

# start
curl -s "https://api.thiagomorangos.com.br/api/v1/auth/login-start" \
  -H "Content-Type: application/json" \
  -d '{"telefone":"16992360202"}'

# confirm (substitua o codigo)
curl -s "https://api.thiagomorangos.com.br/api/v1/auth/login-confirm" \
  -H "Content-Type: application/json" \
  -d '{"telefone":"16992360202","codigo":"ABC123"}'

/me

curl -s "https://api.thiagomorangos.com.br/api/v1/me" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI"

Admin init-db

curl -s -X POST "https://api.thiagomorangos.com.br/__admin/init-db" \
  -H "X-Setup-Token: SEU_SETUP_TOKEN"

9) Smoke-test (script pronto)

Este script é seguro para rodar em ambiente de teste. Ele valida conectividade, CORS e endpoints públicos. (Evita criar pedidos automaticamente.) Se você definir TM_TOKEN, ele também valida /api/v1/me (GET) de forma não destrutiva.

#!/usr/bin/env bash
set -euo pipefail

BASE="https://api.thiagomorangos.com.br/"

echo "1) Health"
curl -fsS "$BASE/api/v1/health" >/dev/null
echo "OK"

echo "2) CORS preflight"
curl -s -D - -o /dev/null -X OPTIONS "$BASE/api/v1/health" \
  -H "Origin: https://example.com" \
  -H "Access-Control-Request-Method: GET" | grep -i "access-control-allow-origin" >/dev/null
echo "OK"

echo "3) Produtos (GET)"
curl -fsS "$BASE/api/v1/produtos" >/dev/null
echo "OK"

echo "4) /me (opcional, autenticado)"
if [[ -n "${TM_TOKEN:-}" ]]; then
  curl -fsS "$BASE/api/v1/me" -H "Authorization: Bearer $TM_TOKEN" >/dev/null
  echo "OK"
else
  echo "SKIP (defina TM_TOKEN para testar /me)"
fi

echo "Smoke-test concluído."

10) Segurança e hardening recomendado Recomendação

• Proteção de rotas “legado sem auth”: se possível, aplique WAF/rate limit/allowlist na borda para POST/PUT/DELETE sem autenticação.
• Rotação de secrets: pratique rotação periódica de TURSO_AUTH_TOKEN, SETUP_TOKEN, UNSPLASH_ACCESS_KEY.
• Menor privilégio: mantenha o SETUP_TOKEN fora de clientes e UIs públicas; utilize somente em operação controlada.

11) Observabilidade (recomendado) Recomendação

Recomendação para evoluções futuras sem regressão: adicionar (i) request-id, (ii) logs estruturados, (iii) métricas básicas. Esta seção descreve o padrão recomendado — não implica que já esteja implementado.

• Request-ID: gerar ou propagar X-Request-Id e logar junto.
• Logs estruturados: JSON logs por rota, latência e status code.
• Métricas: contadores por rota e status (via dashboards/Logpush, se aplicável).

12) Artefatos recomendados (OpenAPI / Postman) Recomendação

Para elevar a reprodutibilidade e evitar divergência entre código e docs, recomenda-se manter:

• OpenAPI (Swagger) como “fonte única de verdade” das rotas.
• Postman/Insomnia collection com variáveis (baseUrl, tokens) e requests prontos.
• Catálogo de erros com códigos internos (sem mudar mensagens atuais; pode ser campo adicional opcional no futuro).

13) FAQ e troubleshooting

• 401: token Bearer ausente/ inválido / expirado.
• 403 em /__admin/*: X-Setup-Token inválido ou SETUP_TOKEN não configurado.
• 429: respeite backoff e reduza concorrência.
• 500/502: env var ausente ou falha upstream (Unsplash/ViaCEP/Turso).
• 404: confirme prefixo /api/v1 e path sem dupla barra.

14) Changelog desta documentação

• 2026-01-26: detalhamento aprofundado de 4.4 Autenticação do cliente (login-start/login-confirm/logout) e 4.7 Clientes e endereços (modelos, payloads completos, exemplos e respostas esperadas). Correção dos exemplos de login e smoke-test com TM_TOKEN opcional.
• 2026-01-25: refinamento visual para aproximar ainda mais do padrão Google Developers com uma única barra lateral (com filtro e opção de minimizar/maximizar), ícone de morango na marca, responsividade aprimorada e eRubric + auditoria revisados com evidências explícitas.

15) eRubric Valuation — Qualidade da documentação (revisada)

Auditoria do eRubric (meta-avaliação) — Confiabilidade: 92%