# StudioW Public API

> API de leitura do StudioW Data Warehouse. Dados de transações, lançamentos, profissionais e relatórios da integração entre Trinx (gestão de salão) e Kamino (ERP financeiro).

## O que há de novo (20/07/2026)

- Novo endpoint GET /v1/pagamentos-kamino: todos os pagamentos do Kamino (pagos e pendentes, qualquer categoria/centro de custo — inclui despesas operacionais como aluguel, água, luz, condomínio), independente da integração Trinx↔Kamino. Cada item traz "situacao" (1=pendente, 2=pago) e um campo "pago" (boolean) já calculado.
- GET /v1/lancamentos agora retorna raw_data completo na listagem (antes só vinha em GET /v1/lancamentos/:id)
- Nova paginação por cursor em GET /v1/lancamentos e GET /v1/pagamentos-kamino: use after_id (em vez de page) para sincronizar/importar a tabela inteira sem o custo de COUNT(*)/OFFSET — ver seção Paginação abaixo. Histórico completo: https://github.com/Academia-Code/api-dwStw/blob/main/CHANGELOG.md

## Como autenticar

Esta API usa JWT. Você precisa de um access_token para todas as requisições (exceto /health e /llms.txt).

### Passo 1 — Obter tokens
POST https://api.studiow.com.br/auth/login
Content-Type: application/json

{ "email": "<email>", "password": "<senha>" }

Resposta: { "access_token": "eyJ...", "refresh_token": "abc...", "expires_in": 900 }

### Passo 2 — Usar o access_token
Inclua em todas as requisições:
Authorization: Bearer <access_token>

O access_token expira em 15 minutos.

### Passo 3 — Renovar quando expirar (HTTP 401)
POST https://api.studiow.com.br/auth/refresh
Content-Type: application/json

{ "refresh_token": "<refresh_token>" }

Resposta: novo access_token + novo refresh_token (o anterior é revogado).

## Endpoints disponíveis (todos GET, todos requerem auth)

- GET https://api.studiow.com.br/v1/transacoes — transações do salão (filtros: data_inicio, data_fim, estabelecimento_id, sent_to_kamino, page, per_page)
- GET https://api.studiow.com.br/v1/transacoes/:trinx_id — transação individual com raw_data completo
- GET https://api.studiow.com.br/v1/lancamentos — lançamentos enviados ao Trinx via Kamino (filtros: data_inicio, data_fim, estabelecimento_id, sent_to_trinx, page, per_page)
- GET https://api.studiow.com.br/v1/lancamentos/:trinx_id — lançamento individual com raw_data completo
- GET https://api.studiow.com.br/v1/pagamentos-kamino — todos os pagamentos do Kamino, pagos+pendentes, qualquer categoria/centro de custo (filtros: situacao, id_centro_custo, nome_conta_classificacao, data_inicio, data_fim, page, per_page)
- GET https://api.studiow.com.br/v1/pagamentos-kamino/:kamino_id — pagamento individual com raw_data completo
- GET https://api.studiow.com.br/v1/profissionais — mapeamento profissionais Trinx↔Kamino (filtros: ativo, estabelecimento_id)
- GET https://api.studiow.com.br/v1/profissionais/:id — profissional por ID numérico
- GET https://api.studiow.com.br/v1/estabelecimentos — mapeamento estabelecimentos Trinx↔Kamino (filtro: ativo)
- GET https://api.studiow.com.br/v1/estabelecimentos/:id — estabelecimento por ID numérico
- GET https://api.studiow.com.br/v1/jobs-log — histórico de execução dos workers (filtros: job_name, status, data_inicio, data_fim)
- GET https://api.studiow.com.br/v1/relatorios/resumo — métricas consolidadas (total transações, valor, status envio, jobs 24h)
- GET https://api.studiow.com.br/v1/relatorios/transacoes-por-profissional — volume e valor agrupados por profissional
- GET https://api.studiow.com.br/v1/relatorios/transacoes-por-forma-pagamento — volume, valor, ticket médio e taxas por forma de pagamento

## Paginação

Todas as listagens aceitam: page (padrão 1) e per_page (padrão 50, máx 200).
Resposta inclui: { "data": [...], "pagination": { "page", "per_page", "total", "total_pages" } }

Em GET /v1/lancamentos e GET /v1/pagamentos-kamino há também paginação por cursor: use after_id (comece com
after_id=0) em vez de page. Sem COUNT(*)/OFFSET, ideal para sincronizar/importar
a tabela inteira. Resposta: { "data": [...], "pagination": { "per_page", "next_after_id", "has_more" } }.
Use o next_after_id retornado como after_id na próxima chamada; pare quando has_more for false.

## Erros comuns

- 401: token ausente ou expirado → renove com POST /auth/refresh
- 429: rate limit (500 req/15min global, 20 req/15min em /auth)
- 404: recurso não encontrado

## Especificação completa

OpenAPI 3.1: https://api.studiow.com.br/openapi.yaml
Documentação visual: https://api.studiow.com.br/docs