{ "openapi": "3.1.0", "info": { "title": "MAJOR Creators API", "version": "1.0.0", "description": "API do sistema interno de gestão de influenciadores/afiliados da MAJOR Cosméticos. Endpoints versionados em /v1/*. Auth via Supabase: cookie (web) ou Bearer JWT (mobile)." }, "servers": [ { "url": "https://api.creators.majorcare.com.br/api", "description": "Current host" }, { "url": "https://api.creators.majorcare.com.br/api", "description": "Production" } ], "paths": { "/v1/auth/session": { "get": { "tags": [ "auth" ], "summary": "Sessão atual do usuário", "description": "Retorna user_id, email, is_admin e creator_id (se vinculado).", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "is_admin": { "type": "boolean" }, "creator_id": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "user_id", "email", "is_admin", "creator_id" ] } } } }, "NaN": { "description": "Status NaN", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/auth/magic-link": { "post": { "tags": [ "auth" ], "summary": "Envia magic link de login", "description": "Dispara email com link de auth via Supabase. Rate limit free tier: 2 emails/h. Portal tem fallback de senha quando rate limit atingido.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "redirect_to": { "type": "string", "format": "uri" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent": { "type": "boolean" }, "email": { "type": "string", "format": "email" } }, "required": [ "sent", "email" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate Limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/admin/creators": { "get": { "tags": [ "admin" ], "summary": "Lista creators com filtros opcionais", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "paused", "archived" ] } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name_full": { "type": "string" }, "handle": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "nullable": true }, "instagram": { "type": "string", "nullable": true }, "tiktok": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "paused", "archived" ] }, "commission_pct": { "type": "number" }, "monthly_value": { "type": "number" }, "contract_signed_at": { "type": "string", "format": "date-time", "nullable": true }, "contract_pdf_url": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name_full", "handle", "email", "phone", "instagram", "tiktok", "status", "commission_pct", "monthly_value", "contract_signed_at", "contract_pdf_url", "created_at" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [ "admin" ] }, { "cookieAuth": [ "admin" ] } ] }, "post": { "tags": [ "admin" ], "summary": "Cria novo creator", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name_full": { "type": "string", "minLength": 2 }, "handle": { "type": "string", "minLength": 2, "maxLength": 60 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "nullable": true }, "doc_type": { "type": "string", "enum": [ "cpf", "cnpj" ] }, "doc_number": { "type": "string", "minLength": 11 }, "birth_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "nullable": true }, "address": { "type": "string", "nullable": true }, "instagram": { "type": "string", "nullable": true }, "tiktok": { "type": "string", "nullable": true }, "bank": { "type": "string", "nullable": true }, "pix_holder": { "type": "string", "nullable": true }, "pix_key": { "type": "string", "nullable": true }, "pix_key_type": { "type": "string", "enum": [ "cpf", "cnpj", "email", "phone", "random" ], "nullable": true }, "commission_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "monthly_value": { "type": "number", "minimum": 0 }, "notes": { "type": "string", "nullable": true } }, "required": [ "name_full", "handle", "email", "phone", "doc_type", "doc_number", "birth_date", "address", "instagram", "tiktok", "bank", "pix_holder", "pix_key", "pix_key_type", "notes" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name_full": { "type": "string" }, "handle": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "nullable": true }, "instagram": { "type": "string", "nullable": true }, "tiktok": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "paused", "archived" ] }, "commission_pct": { "type": "number" }, "monthly_value": { "type": "number" }, "contract_signed_at": { "type": "string", "format": "date-time", "nullable": true }, "contract_pdf_url": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name_full", "handle", "email", "phone", "instagram", "tiktok", "status", "commission_pct", "monthly_value", "contract_signed_at", "contract_pdf_url", "created_at" ] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [ "admin" ] }, { "cookieAuth": [ "admin" ] } ] } }, "/v1/admin/creators/{id}": { "get": { "tags": [ "admin" ], "summary": "Detalhe de um creator", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name_full": { "type": "string" }, "handle": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "nullable": true }, "instagram": { "type": "string", "nullable": true }, "tiktok": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "paused", "archived" ] }, "commission_pct": { "type": "number" }, "monthly_value": { "type": "number" }, "contract_signed_at": { "type": "string", "format": "date-time", "nullable": true }, "contract_pdf_url": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name_full", "handle", "email", "phone", "instagram", "tiktok", "status", "commission_pct", "monthly_value", "contract_signed_at", "contract_pdf_url", "created_at" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [ "admin" ] }, { "cookieAuth": [ "admin" ] } ] }, "patch": { "tags": [ "admin" ], "summary": "Atualiza creator (qualquer campo)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name_full": { "type": "string", "minLength": 2 }, "handle": { "type": "string", "minLength": 2, "maxLength": 60 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "nullable": true }, "doc_type": { "type": "string", "enum": [ "cpf", "cnpj" ] }, "doc_number": { "type": "string", "minLength": 11 }, "birth_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "nullable": true }, "address": { "type": "string", "nullable": true }, "instagram": { "type": "string", "nullable": true }, "tiktok": { "type": "string", "nullable": true }, "bank": { "type": "string", "nullable": true }, "pix_holder": { "type": "string", "nullable": true }, "pix_key": { "type": "string", "nullable": true }, "pix_key_type": { "type": "string", "enum": [ "cpf", "cnpj", "email", "phone", "random" ], "nullable": true }, "commission_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "monthly_value": { "type": "number", "minimum": 0 }, "notes": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "paused", "archived" ] }, "contract_signed_at": { "type": "string", "format": "date-time", "nullable": true }, "contract_docx_url": { "type": "string", "nullable": true }, "contract_pdf_url": { "type": "string", "nullable": true } }, "required": [ "contract_signed_at", "contract_docx_url", "contract_pdf_url" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name_full": { "type": "string" }, "handle": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "nullable": true }, "instagram": { "type": "string", "nullable": true }, "tiktok": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "paused", "archived" ] }, "commission_pct": { "type": "number" }, "monthly_value": { "type": "number" }, "contract_signed_at": { "type": "string", "format": "date-time", "nullable": true }, "contract_pdf_url": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name_full", "handle", "email", "phone", "instagram", "tiktok", "status", "commission_pct", "monthly_value", "contract_signed_at", "contract_pdf_url", "created_at" ] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [ "admin" ] }, { "cookieAuth": [ "admin" ] } ] }, "delete": { "tags": [ "admin" ], "summary": "Soft delete: arquiva o creator (status='archived')", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [ "admin" ] }, { "cookieAuth": [ "admin" ] } ] } }, "/v1/admin/coupons": { "post": { "tags": [ "admin" ], "summary": "Cria cupom Shopify + DB com rollback automático", "description": "1. Valida creator. 2. Chama Shopify Admin API (price_rule + discount_code). 3. INSERT no DB. 4. Se DB falhar, deleta cupom Shopify (best-effort).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "creator_id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "minLength": 3, "maxLength": 30, "pattern": "^[A-Z0-9_-]+$" }, "discount_type": { "type": "string", "enum": [ "percentage", "fixed" ], "default": "percentage" }, "discount_value": { "type": "number", "minimum": 0 }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time", "nullable": true }, "usage_limit": { "type": "integer", "minimum": 0, "nullable": true } }, "required": [ "creator_id", "code", "discount_value", "ends_at", "usage_limit" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "creator_id": { "type": "string", "format": "uuid", "nullable": true }, "code": { "type": "string" }, "discount_type": { "type": "string", "enum": [ "percentage", "fixed" ] }, "discount_value": { "type": "number" }, "status": { "type": "string", "enum": [ "active", "paused", "deleted" ] }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time", "nullable": true }, "usage_limit": { "type": "number", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "creator_id", "code", "discount_type", "discount_value", "status", "starts_at", "ends_at", "usage_limit", "created_at" ] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "502": { "description": "Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [ "admin" ] }, { "cookieAuth": [ "admin" ] } ] } }, "/v1/admin/contracts/generate": { "post": { "tags": [ "admin" ], "summary": "[STUB Fase 2] Gera contrato via skill influencer-contract", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "creator_id": { "type": "string", "format": "uuid" } }, "required": [ "creator_id" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "stub": { "type": "boolean" }, "message": { "type": "string" }, "skill_input": {} }, "required": [ "stub", "message", "skill_input" ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [ "admin" ] }, { "cookieAuth": [ "admin" ] } ] } }, "/v1/admin/payouts/close": { "post": { "tags": [ "admin" ], "summary": "Fecha mês: calcula payouts e UPSERT em payouts (idempotente)", "description": "Body: { month: 'YYYY-MM' }. UNIQUE(creator_id, period_start, period_end) garante idempotência.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "month": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" } }, "required": [ "month" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "number" }, "period_start": { "type": "string" }, "period_end": { "type": "string" }, "payouts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "creator_id": { "type": "string", "format": "uuid" }, "period_start": { "type": "string" }, "period_end": { "type": "string" }, "attributions_count": { "type": "number" }, "gross_revenue": { "type": "number" }, "total_commission": { "type": "number" }, "fixed_seeding": { "type": "number" }, "total_payout": { "type": "number" }, "status": { "type": "string", "enum": [ "draft", "approved", "paid", "cancelled" ] }, "paid_at": { "type": "string", "format": "date-time", "nullable": true }, "pix_receipt_url": { "type": "string", "nullable": true } }, "required": [ "id", "creator_id", "period_start", "period_end", "attributions_count", "gross_revenue", "total_commission", "fixed_seeding", "total_payout", "status", "paid_at", "pix_receipt_url" ] }, "nullable": true }, "message": { "type": "string" } }, "required": [ "created", "period_start", "period_end", "payouts" ] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [ "admin" ] }, { "cookieAuth": [ "admin" ] } ] } }, "/v1/admin/payouts/{id}/approve": { "post": { "tags": [ "admin" ], "summary": "Aprovar payout (draft → approved)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "creator_id": { "type": "string", "format": "uuid" }, "period_start": { "type": "string" }, "period_end": { "type": "string" }, "attributions_count": { "type": "number" }, "gross_revenue": { "type": "number" }, "total_commission": { "type": "number" }, "fixed_seeding": { "type": "number" }, "total_payout": { "type": "number" }, "status": { "type": "string", "enum": [ "draft", "approved", "paid", "cancelled" ] }, "paid_at": { "type": "string", "format": "date-time", "nullable": true }, "pix_receipt_url": { "type": "string", "nullable": true } }, "required": [ "id", "creator_id", "period_start", "period_end", "attributions_count", "gross_revenue", "total_commission", "fixed_seeding", "total_payout", "status", "paid_at", "pix_receipt_url" ] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [ "admin" ] }, { "cookieAuth": [ "admin" ] } ] } }, "/v1/admin/payouts/export-conta-simples": { "get": { "tags": [ "admin" ], "summary": "Exporta CSV de payouts para import manual no Conta Simples", "description": "Retorna text/csv com colunas: chave_pix, tipo_chave, nome_beneficiario, cpf_cnpj, valor, descricao", "parameters": [ { "name": "month", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "approved", "paid" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [ "admin" ] }, { "cookieAuth": [ "admin" ] } ] } }, "/v1/portal/me": { "get": { "tags": [ "portal" ], "summary": "Creator do usuário logado", "description": "Auto-link: se não houver user_id vinculado mas email bater, atualiza.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name_full": { "type": "string" }, "handle": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "nullable": true }, "instagram": { "type": "string", "nullable": true }, "tiktok": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "paused", "archived" ] }, "commission_pct": { "type": "number" }, "monthly_value": { "type": "number" }, "bank": { "type": "string", "nullable": true }, "pix_holder": { "type": "string", "nullable": true }, "pix_key_type": { "type": "string", "enum": [ "cpf", "cnpj", "email", "phone", "random" ], "nullable": true }, "pix_key_masked": { "type": "string", "nullable": true }, "contract_signed_at": { "type": "string", "format": "date-time", "nullable": true }, "contract_pdf_url": { "type": "string", "nullable": true }, "notification_preferences": {}, "locale": { "type": "string" }, "timezone": { "type": "string" } }, "required": [ "id", "name_full", "handle", "email", "phone", "instagram", "tiktok", "status", "commission_pct", "monthly_value", "bank", "pix_holder", "pix_key_type", "pix_key_masked", "contract_signed_at", "contract_pdf_url", "notification_preferences", "locale", "timezone" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/portal/dashboard": { "get": { "tags": [ "portal" ], "summary": "Métricas do mês atual + recente", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_month": { "type": "object", "properties": { "period_start": { "type": "string" }, "period_end": { "type": "string" }, "attributions_count": { "type": "number" }, "gross_revenue": { "type": "number" }, "accrued_commission": { "type": "number" } }, "required": [ "period_start", "period_end", "attributions_count", "gross_revenue", "accrued_commission" ] }, "last_month": { "type": "object", "properties": { "attributions_count": { "type": "number" }, "gross_revenue": { "type": "number" }, "accrued_commission": { "type": "number" } }, "required": [ "attributions_count", "gross_revenue", "accrued_commission" ] }, "active_coupons": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "creator_id": { "type": "string", "format": "uuid", "nullable": true }, "code": { "type": "string" }, "discount_type": { "type": "string", "enum": [ "percentage", "fixed" ] }, "discount_value": { "type": "number" }, "status": { "type": "string", "enum": [ "active", "paused", "deleted" ] }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time", "nullable": true }, "usage_limit": { "type": "number", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "creator_id", "code", "discount_type", "discount_value", "status", "starts_at", "ends_at", "usage_limit", "created_at" ] } }, "recent_attributions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "yampi_order_id": { "type": "number" }, "yampi_order_number": { "type": "string", "nullable": true }, "coupon_code": { "type": "string" }, "coupon_id": { "type": "string", "format": "uuid", "nullable": true }, "creator_id": { "type": "string", "format": "uuid", "nullable": true }, "customer_email": { "type": "string", "nullable": true }, "order_value": { "type": "number", "nullable": true }, "product_value": { "type": "number", "nullable": true }, "discount_value": { "type": "number", "nullable": true }, "commission_pct": { "type": "number", "nullable": true }, "commission_value": { "type": "number", "nullable": true }, "order_status": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "webhook", "reconciliation_cron", "historical_import" ] }, "ordered_at": { "type": "string", "format": "date-time", "nullable": true }, "paid_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "yampi_order_id", "yampi_order_number", "coupon_code", "coupon_id", "creator_id", "customer_email", "order_value", "product_value", "discount_value", "commission_pct", "commission_value", "order_status", "source", "ordered_at", "paid_at" ] }, "maxItems": 10 } }, "required": [ "current_month", "last_month", "active_coupons", "recent_attributions" ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/portal/coupons": { "get": { "tags": [ "portal" ], "summary": "Cupons do creator com agregado de uso", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "discount_type": { "type": "string", "enum": [ "percentage", "fixed" ] }, "discount_value": { "type": "number" }, "status": { "type": "string", "enum": [ "active", "paused", "deleted" ] }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time", "nullable": true }, "usage_limit": { "type": "number", "nullable": true }, "stats": { "type": "object", "properties": { "uses": { "type": "number" }, "revenue": { "type": "number" }, "commission": { "type": "number" } }, "required": [ "uses", "revenue", "commission" ] } }, "required": [ "id", "code", "discount_type", "discount_value", "status", "starts_at", "ends_at", "usage_limit", "stats" ] } } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/portal/payouts": { "get": { "tags": [ "portal" ], "summary": "Histórico de payouts do creator", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "creator_id": { "type": "string", "format": "uuid" }, "period_start": { "type": "string" }, "period_end": { "type": "string" }, "attributions_count": { "type": "number" }, "gross_revenue": { "type": "number" }, "total_commission": { "type": "number" }, "fixed_seeding": { "type": "number" }, "total_payout": { "type": "number" }, "status": { "type": "string", "enum": [ "draft", "approved", "paid", "cancelled" ] }, "paid_at": { "type": "string", "format": "date-time", "nullable": true }, "pix_receipt_url": { "type": "string", "nullable": true } }, "required": [ "id", "creator_id", "period_start", "period_end", "attributions_count", "gross_revenue", "total_commission", "fixed_seeding", "total_payout", "status", "paid_at", "pix_receipt_url" ] } } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/portal/contract": { "get": { "tags": [ "portal" ], "summary": "URL do PDF do contrato (signed se for Supabase Storage)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "nullable": true }, "signed_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_in": { "type": "number" } }, "required": [ "url", "signed_at" ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/portal/profile": { "patch": { "tags": [ "portal" ], "summary": "Atualiza campos editáveis do próprio perfil", "description": "Apenas phone, address, redes sociais, PIX, prefs. Campos críticos: usar admin.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "instagram": { "type": "string", "nullable": true }, "tiktok": { "type": "string", "nullable": true }, "bank": { "type": "string", "nullable": true }, "pix_holder": { "type": "string", "nullable": true }, "pix_key": { "type": "string", "nullable": true }, "pix_key_type": { "type": "string", "enum": [ "cpf", "cnpj", "email", "phone", "random" ], "nullable": true }, "notification_preferences": {}, "locale": { "type": "string" }, "timezone": { "type": "string" } }, "required": [ "phone", "address", "instagram", "tiktok", "bank", "pix_holder", "pix_key", "pix_key_type" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "updated": { "type": "boolean" }, "fields": { "type": "array", "items": { "type": "string" } } }, "required": [ "updated", "fields" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/portal/devices/register": { "post": { "tags": [ "portal", "mobile" ], "summary": "Registra device token para push notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "platform": { "type": "string", "enum": [ "ios", "android", "web" ] }, "provider": { "type": "string", "enum": [ "expo", "fcm", "apns", "webpush" ], "default": "expo" }, "app_version": { "type": "string", "nullable": true }, "device_name": { "type": "string", "nullable": true } }, "required": [ "token", "platform", "app_version", "device_name" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "token": { "type": "string" }, "platform": { "type": "string" }, "provider": { "type": "string" } }, "required": [ "id", "token", "platform", "provider" ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/portal/devices/{id}": { "delete": { "tags": [ "portal", "mobile" ], "summary": "Remove device token (push)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } } }, "components": { "schemas": { "CreatorPublic": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name_full": { "type": "string" }, "handle": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "nullable": true }, "instagram": { "type": "string", "nullable": true }, "tiktok": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "paused", "archived" ] }, "commission_pct": { "type": "number" }, "monthly_value": { "type": "number" }, "contract_signed_at": { "type": "string", "format": "date-time", "nullable": true }, "contract_pdf_url": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name_full", "handle", "email", "phone", "instagram", "tiktok", "status", "commission_pct", "monthly_value", "contract_signed_at", "contract_pdf_url", "created_at" ] }, "CreatorCreate": { "type": "object", "properties": { "name_full": { "type": "string", "minLength": 2 }, "handle": { "type": "string", "minLength": 2, "maxLength": 60 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "nullable": true }, "doc_type": { "type": "string", "enum": [ "cpf", "cnpj" ] }, "doc_number": { "type": "string", "minLength": 11 }, "birth_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "nullable": true }, "address": { "type": "string", "nullable": true }, "instagram": { "type": "string", "nullable": true }, "tiktok": { "type": "string", "nullable": true }, "bank": { "type": "string", "nullable": true }, "pix_holder": { "type": "string", "nullable": true }, "pix_key": { "type": "string", "nullable": true }, "pix_key_type": { "type": "string", "enum": [ "cpf", "cnpj", "email", "phone", "random" ], "nullable": true }, "commission_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "monthly_value": { "type": "number", "minimum": 0 }, "notes": { "type": "string", "nullable": true } }, "required": [ "name_full", "handle", "email", "phone", "doc_type", "doc_number", "birth_date", "address", "instagram", "tiktok", "bank", "pix_holder", "pix_key", "pix_key_type", "notes" ] }, "CreatorUpdate": { "type": "object", "properties": { "name_full": { "type": "string", "minLength": 2 }, "handle": { "type": "string", "minLength": 2, "maxLength": 60 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "nullable": true }, "doc_type": { "type": "string", "enum": [ "cpf", "cnpj" ] }, "doc_number": { "type": "string", "minLength": 11 }, "birth_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "nullable": true }, "address": { "type": "string", "nullable": true }, "instagram": { "type": "string", "nullable": true }, "tiktok": { "type": "string", "nullable": true }, "bank": { "type": "string", "nullable": true }, "pix_holder": { "type": "string", "nullable": true }, "pix_key": { "type": "string", "nullable": true }, "pix_key_type": { "type": "string", "enum": [ "cpf", "cnpj", "email", "phone", "random" ], "nullable": true }, "commission_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "monthly_value": { "type": "number", "minimum": 0 }, "notes": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "paused", "archived" ] }, "contract_signed_at": { "type": "string", "format": "date-time", "nullable": true }, "contract_docx_url": { "type": "string", "nullable": true }, "contract_pdf_url": { "type": "string", "nullable": true } }, "required": [ "contract_signed_at", "contract_docx_url", "contract_pdf_url" ] }, "CouponPublic": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "creator_id": { "type": "string", "format": "uuid", "nullable": true }, "code": { "type": "string" }, "discount_type": { "type": "string", "enum": [ "percentage", "fixed" ] }, "discount_value": { "type": "number" }, "status": { "type": "string", "enum": [ "active", "paused", "deleted" ] }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time", "nullable": true }, "usage_limit": { "type": "number", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "creator_id", "code", "discount_type", "discount_value", "status", "starts_at", "ends_at", "usage_limit", "created_at" ] }, "CouponCreate": { "type": "object", "properties": { "creator_id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "minLength": 3, "maxLength": 30, "pattern": "^[A-Z0-9_-]+$" }, "discount_type": { "type": "string", "enum": [ "percentage", "fixed" ], "default": "percentage" }, "discount_value": { "type": "number", "minimum": 0 }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time", "nullable": true }, "usage_limit": { "type": "integer", "minimum": 0, "nullable": true } }, "required": [ "creator_id", "code", "discount_value", "ends_at", "usage_limit" ] }, "AttributionPublic": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "yampi_order_id": { "type": "number" }, "yampi_order_number": { "type": "string", "nullable": true }, "coupon_code": { "type": "string" }, "coupon_id": { "type": "string", "format": "uuid", "nullable": true }, "creator_id": { "type": "string", "format": "uuid", "nullable": true }, "customer_email": { "type": "string", "nullable": true }, "order_value": { "type": "number", "nullable": true }, "product_value": { "type": "number", "nullable": true }, "discount_value": { "type": "number", "nullable": true }, "commission_pct": { "type": "number", "nullable": true }, "commission_value": { "type": "number", "nullable": true }, "order_status": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "webhook", "reconciliation_cron", "historical_import" ] }, "ordered_at": { "type": "string", "format": "date-time", "nullable": true }, "paid_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "yampi_order_id", "yampi_order_number", "coupon_code", "coupon_id", "creator_id", "customer_email", "order_value", "product_value", "discount_value", "commission_pct", "commission_value", "order_status", "source", "ordered_at", "paid_at" ] }, "PayoutPublic": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "creator_id": { "type": "string", "format": "uuid" }, "period_start": { "type": "string" }, "period_end": { "type": "string" }, "attributions_count": { "type": "number" }, "gross_revenue": { "type": "number" }, "total_commission": { "type": "number" }, "fixed_seeding": { "type": "number" }, "total_payout": { "type": "number" }, "status": { "type": "string", "enum": [ "draft", "approved", "paid", "cancelled" ] }, "paid_at": { "type": "string", "format": "date-time", "nullable": true }, "pix_receipt_url": { "type": "string", "nullable": true } }, "required": [ "id", "creator_id", "period_start", "period_end", "attributions_count", "gross_revenue", "total_commission", "fixed_seeding", "total_payout", "status", "paid_at", "pix_receipt_url" ] }, "DashboardSummary": { "type": "object", "properties": { "current_month": { "type": "object", "properties": { "period_start": { "type": "string" }, "period_end": { "type": "string" }, "attributions_count": { "type": "number" }, "gross_revenue": { "type": "number" }, "accrued_commission": { "type": "number" } }, "required": [ "period_start", "period_end", "attributions_count", "gross_revenue", "accrued_commission" ] }, "last_month": { "type": "object", "properties": { "attributions_count": { "type": "number" }, "gross_revenue": { "type": "number" }, "accrued_commission": { "type": "number" } }, "required": [ "attributions_count", "gross_revenue", "accrued_commission" ] }, "active_coupons": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "creator_id": { "type": "string", "format": "uuid", "nullable": true }, "code": { "type": "string" }, "discount_type": { "type": "string", "enum": [ "percentage", "fixed" ] }, "discount_value": { "type": "number" }, "status": { "type": "string", "enum": [ "active", "paused", "deleted" ] }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time", "nullable": true }, "usage_limit": { "type": "number", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "creator_id", "code", "discount_type", "discount_value", "status", "starts_at", "ends_at", "usage_limit", "created_at" ] } }, "recent_attributions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "yampi_order_id": { "type": "number" }, "yampi_order_number": { "type": "string", "nullable": true }, "coupon_code": { "type": "string" }, "coupon_id": { "type": "string", "format": "uuid", "nullable": true }, "creator_id": { "type": "string", "format": "uuid", "nullable": true }, "customer_email": { "type": "string", "nullable": true }, "order_value": { "type": "number", "nullable": true }, "product_value": { "type": "number", "nullable": true }, "discount_value": { "type": "number", "nullable": true }, "commission_pct": { "type": "number", "nullable": true }, "commission_value": { "type": "number", "nullable": true }, "order_status": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "webhook", "reconciliation_cron", "historical_import" ] }, "ordered_at": { "type": "string", "format": "date-time", "nullable": true }, "paid_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "yampi_order_id", "yampi_order_number", "coupon_code", "coupon_id", "creator_id", "customer_email", "order_value", "product_value", "discount_value", "commission_pct", "commission_value", "order_status", "source", "ordered_at", "paid_at" ] }, "maxItems": 10 } }, "required": [ "current_month", "last_month", "active_coupons", "recent_attributions" ] }, "SessionInfo": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "is_admin": { "type": "boolean" }, "creator_id": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "user_id", "email", "is_admin", "creator_id" ] }, "ApiError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "sb-access-token" } } } }