{ "openapi": "3.1.0", "info": { "title": "LeztyPay API", "version": "0.0.0" }, "servers": [ { "url": "https://api.leztypay.com" } ], "components": { "schemas": { "WebhookInboxItem": { "type": "object", "properties": { "id": { "type": "string" }, "acquirer": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "slug" ] }, "provider_event_id": { "type": "string" }, "event_type": { "type": [ "string", "null" ] }, "signature_valid": { "type": "boolean" }, "received_at": { "type": "string" }, "processed_at": { "type": [ "string", "null" ] }, "attempts": { "type": "integer" }, "error": { "type": [ "string", "null" ] }, "transaction_id": { "type": [ "string", "null" ] }, "withdrawal_id": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "reprocessed_at": { "type": [ "string", "null" ] } }, "required": [ "id", "acquirer", "provider_event_id", "event_type", "signature_valid", "received_at", "processed_at", "attempts", "error", "transaction_id", "withdrawal_id", "end_to_end_id", "reprocessed_at" ] }, "WebhookInboxDetail": { "allOf": [ { "$ref": "#/components/schemas/WebhookInboxItem" }, { "type": "object", "properties": { "raw_body": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "raw_body", "headers" ] } ] }, "WebhookInboxReprocessAccepted": { "type": "object", "properties": {} }, "WebhookInboundReceipt": { "type": "object", "properties": { "received": { "type": "boolean" }, "duplicate": { "type": "boolean" } }, "required": [ "received" ] }, "WebhookInboundError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } }, "parameters": {} }, "paths": { "/health": { "get": { "tags": [ "system" ], "summary": "Liveness probe", "responses": { "200": { "description": "processo vivo", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "version": { "type": "string" }, "uptime_s": { "type": "integer" } }, "required": [ "status", "version", "uptime_s" ] } } } } } } }, "/ready": { "get": { "tags": [ "system" ], "summary": "Readiness probe", "responses": { "200": { "description": "dependências ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "checks": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "enum": [ "ok" ] }, { "type": "string", "enum": [ "skipped" ] }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } ] } } }, "required": [ "status", "checks" ] } } } }, "503": { "description": "degradado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "checks": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "enum": [ "ok" ] }, { "type": "string", "enum": [ "skipped" ] }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } ] } } }, "required": [ "status", "checks" ] } } } } } } }, "/v1/me/auth/sign-up/email": { "post": { "tags": [ "auth" ], "summary": "Cadastro de seller", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 12 }, "accept_terms": { "type": "boolean", "enum": [ true ] }, "invite_token": { "type": "string", "minLength": 1 } }, "required": [ "name", "email", "password", "accept_terms", "invite_token" ] } } } }, "responses": { "200": { "description": "cadastro criado; sessão em `Set-Cookie` (`lm.session`, `HttpOnly`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "emailVerified": { "type": "boolean" }, "role": { "type": "string" }, "seller_id": { "type": [ "string", "null" ] } }, "required": [ "id", "email", "name", "emailVerified", "role", "seller_id" ] } }, "required": [ "user" ] } } } } } } }, "/v1/me/auth/sign-in/email": { "post": { "tags": [ "auth" ], "summary": "Login (5/min por email e por IP)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" }, "rememberMe": { "type": "boolean" } }, "required": [ "email", "password" ] } } } }, "responses": { "200": { "description": "login aceito; sessão em `Set-Cookie` (`lm.session`, `HttpOnly`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "emailVerified": { "type": "boolean" }, "role": { "type": "string" }, "seller_id": { "type": [ "string", "null" ] } }, "required": [ "id", "email", "name", "emailVerified", "role", "seller_id" ] } }, "required": [ "user" ] } } } } } } }, "/v1/me/auth/sign-out": { "post": { "tags": [ "auth" ], "summary": "Logout", "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } }, "required": [ "status" ] } } } } } } }, "/v1/me/auth/verify-email": { "get": { "tags": [ "auth" ], "summary": "Confirma o email pelo token enviado no cadastro", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "token", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "callbackURL", "in": "query" } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } }, "required": [ "status" ] } } } } } } }, "/v1/me/auth/request-password-reset": { "post": { "tags": [ "auth" ], "summary": "Envia email de recuperação de senha", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "redirectTo": { "type": "string" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "sempre 200, mesmo quando o email não pôde ser enviado", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } }, "required": [ "status" ] } } } } } } }, "/v1/me/auth/reset-password": { "post": { "tags": [ "auth" ], "summary": "Troca a senha pelo token e revoga as sessões", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "newPassword": { "type": "string", "minLength": 12 } }, "required": [ "token", "newPassword" ] } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } }, "required": [ "status" ] } } } } } } }, "/v1/me/auth/two-factor/enable": { "post": { "tags": [ "auth" ], "summary": "Habilita TOTP e devolve o URI e os backup codes", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string" }, "method": { "type": "string", "enum": [ "totp", "otp" ] } }, "required": [ "password" ] } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "totp" ] }, "totpURI": { "type": "string" }, "backupCodes": { "type": "array", "items": { "type": "string" } } }, "required": [ "method", "totpURI", "backupCodes" ] } } } } } } }, "/v1/me/auth/two-factor/verify-totp": { "post": { "tags": [ "auth" ], "summary": "Conclui a habilitação da 2FA / segundo fator do login", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "trustDevice": { "type": "boolean" } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "emailVerified": { "type": "boolean" }, "role": { "type": "string" }, "seller_id": { "type": [ "string", "null" ] } }, "required": [ "id", "email", "name", "emailVerified", "role", "seller_id" ] } }, "required": [ "user" ] } } } } } } }, "/v1/me/auth/two-factor/disable": { "post": { "tags": [ "auth" ], "summary": "Desabilita a 2FA e revoga todas as sessões", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string" } }, "required": [ "password" ] } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } }, "required": [ "status" ] } } } } } } }, "/v1/me/auth/two-factor/generate-backup-codes": { "post": { "tags": [ "auth" ], "summary": "Gera novos backup codes", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string" } }, "required": [ "password" ] } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "backupCodes": { "type": "array", "items": { "type": "string" } } }, "required": [ "backupCodes" ] } } } } } } }, "/v1/me/auth/step-up": { "post": { "tags": [ "auth" ], "summary": "Step-up de MFA da sessão de seller", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "password": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "step-up válido; a sessão fica sensível até `mfa_verified_until`", "content": { "application/json": { "schema": { "type": "object", "properties": { "mfa_verified_until": { "type": "string", "format": "date-time" } }, "required": [ "mfa_verified_until" ] } } } }, "401": { "description": "`invalid_mfa_code`" }, "403": { "description": "`mfa_required`, 2FA não habilitada" }, "429": { "description": "`rate_limited`" } } } }, "/v1/me/auth/two-factor/recovery/request": { "post": { "tags": [ "auth" ], "summary": "Pede o link que desliga a 2FA perdida (só seller)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 1 }, "redirect_to": { "type": "string", "format": "uri" } }, "required": [ "email", "password" ] } } } }, "responses": { "200": { "description": "sempre 200: a resposta não diz se a conta existe", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } }, "required": [ "status" ] } } } }, "429": { "description": "`rate_limited`" } } } }, "/v1/me/auth/two-factor/recovery/confirm": { "post": { "tags": [ "auth" ], "summary": "Desliga a 2FA pelo token do email, revoga sessões e trava saque por 24 h", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1 } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "2FA desligada", "content": { "application/json": { "schema": { "type": "object", "properties": { "withdrawals_locked_until": { "type": "string", "format": "date-time" } }, "required": [ "withdrawals_locked_until" ] } } } }, "401": { "description": "`invalid_mfa_code`, token inválido, expirado ou já usado" } } } }, "/v1/me/security/step-up-prefs": { "get": { "tags": [ "auth" ], "summary": "Toggles de confirmação extra do seller", "responses": { "200": { "description": "toggles; saque e chave PIX não aparecem (sempre exigem confirmação)", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "type": "boolean" }, "account": { "type": "boolean" } }, "required": [ "webhook", "account" ] } } } } } }, "put": { "tags": [ "auth" ], "summary": "Liga ou desliga os toggles de confirmação extra", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "type": "boolean" }, "account": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "toggles depois da mudança", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "type": "boolean" }, "account": { "type": "boolean" } }, "required": [ "webhook", "account" ] } } } }, "403": { "description": "`mfa_required`, piso incondicional (FIX-SEC-02/MÉDIO-1)" } } } }, "/v1/me/auth/invites/{token}": { "get": { "tags": [ "auth" ], "summary": "Confere um convite de cadastro e devolve o email travado no formulário", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "token do link do email; nunca é logado" }, "required": true, "description": "token do link do email; nunca é logado", "name": "token", "in": "path" } ], "responses": { "200": { "description": "convite ativo", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "email", "expires_at" ] } } } }, "404": { "description": "`resource_not_found`: inexistente, expirado, usado ou revogado" }, "429": { "description": "`rate_limited`" } } } }, "/v1/me/terms/accept": { "post": { "tags": [ "auth" ], "summary": "Aceita a versão corrente dos termos", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string", "minLength": 1 } }, "required": [ "version" ] } } } }, "responses": { "204": { "description": "termos aceitos" }, "400": { "description": "`validation_failed`, versão diferente de `TERMS_VERSION`" } } } }, "/v1/me/sessions": { "get": { "tags": [ "auth" ], "summary": "Sessões ativas do usuário", "responses": { "200": { "description": "sessões ativas; o token da sessão nunca é exposto", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "ip_address": { "type": [ "string", "null" ] }, "user_agent": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" }, "current": { "type": "boolean" } }, "required": [ "id", "ip_address", "user_agent", "created_at", "expires_at", "last_seen_at", "current" ] } } }, "required": [ "data" ] } } } } } } }, "/v1/me/sessions/{id}": { "delete": { "tags": [ "auth" ], "summary": "Revoga uma sessão do próprio usuário", "parameters": [ { "schema": { "type": "string", "description": "id público `ses_…` ou o uuid da sessão (compat)" }, "required": true, "description": "id público `ses_…` ou o uuid da sessão (compat)", "name": "id", "in": "path" } ], "responses": { "204": { "description": "sessão revogada" }, "404": { "description": "`resource_not_found`, sessão inexistente ou de outro user" } } } }, "/v1/me/postback-secret": { "get": { "tags": [ "auth" ], "summary": "Prefixo do segredo de postback vigente (nunca o segredo)", "responses": { "200": { "description": "prefixo; `null` antes de a store ter um segredo gerado", "content": { "application/json": { "schema": { "type": "object", "properties": { "prefix": { "type": [ "string", "null" ] }, "rotated_at": { "type": [ "string", "null" ], "format": "date-time" }, "previous_valid_until": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "prefix", "rotated_at", "previous_valid_until" ] } } } } } } }, "/v1/me/api-keys": { "get": { "tags": [ "api-keys" ], "summary": "Lista as API keys ativas da store", "responses": { "200": { "description": "keys ativas", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "key_prefix": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoke_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "mode", "key_prefix", "last_used_at", "revoke_at", "created_at" ] } } }, "required": [ "data" ] } } } } } }, "post": { "tags": [ "api-keys" ], "summary": "Cria uma API key (secret devolvido uma única vez)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "mode": { "type": "string", "enum": [ "live", "test" ] } }, "required": [ "name", "mode" ] } } } }, "responses": { "201": { "description": "key criada", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "key_prefix": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoke_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "key": { "type": "string" } }, "required": [ "id", "name", "mode", "key_prefix", "last_used_at", "revoke_at", "created_at", "key" ] } } } }, "400": { "description": "validation_failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "kyc_required (live sem KYC) ou mfa_required (step-up ausente)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "409": { "description": "invalid_state: limite de keys ativas por mode", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/api-keys/{id}/rotate": { "post": { "tags": [ "api-keys" ], "summary": "Rotaciona uma API key e agenda a revogação da antiga em 24 h", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "201": { "description": "key nova", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "key_prefix": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoke_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "key": { "type": "string" }, "old_key_revoke_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "mode", "key_prefix", "last_used_at", "revoke_at", "created_at", "key", "old_key_revoke_at" ] } } } }, "400": { "description": "validation_failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "mfa_required: step-up ausente ou expirado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "409": { "description": "invalid_state: limite de keys ativas por mode", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/api-keys/{id}": { "delete": { "tags": [ "api-keys" ], "summary": "Revoga uma API key imediatamente", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "revogada" }, "400": { "description": "validation_failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "mfa_required: step-up ausente ou expirado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/counters": { "get": { "tags": [ "counters" ], "summary": "Contadores para badges da sidebar e tabs (`X-Mode`, cache de 10 s)", "responses": { "200": { "description": "contadores", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_deliveries": { "type": "object", "properties": { "failed_24h": { "type": "integer", "minimum": 0 }, "dead": { "type": "integer", "minimum": 0 } }, "required": [ "failed_24h", "dead" ] }, "pix_keys": { "type": "object", "properties": { "pending_approval": { "type": "integer", "minimum": 0 } }, "required": [ "pending_approval" ] }, "kyc_status": { "type": "string", "enum": [ "none", "pending", "approved", "rejected" ] }, "withdrawals": { "type": "object", "properties": { "awaiting": { "type": "integer", "minimum": 0 }, "approved": { "type": "integer", "minimum": 0 }, "rejected": { "type": "integer", "minimum": 0 }, "processing": { "type": "integer", "minimum": 0 }, "successful": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "cancelled": { "type": "integer", "minimum": 0 } } }, "transactions": { "type": "object", "properties": { "pending": { "type": "integer", "minimum": 0 }, "paid": { "type": "integer", "minimum": 0 }, "expired": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "refunded": { "type": "integer", "minimum": 0 }, "chargeback": { "type": "integer", "minimum": 0 } } }, "ledger": { "type": "object", "properties": { "entries": { "type": "integer", "minimum": 0 }, "credits": { "type": "integer", "minimum": 0 }, "debits": { "type": "integer", "minimum": 0 }, "reserve": { "type": "integer", "minimum": 0 }, "withdrawals": { "type": "integer", "minimum": 0 } }, "required": [ "entries", "credits", "debits", "reserve", "withdrawals" ] } }, "required": [ "webhook_deliveries", "pix_keys", "kyc_status", "withdrawals", "transactions", "ledger" ] } } } } } } }, "/events": { "get": { "tags": [ "events" ], "summary": "Stream SSE do feed de eventos do seller", "description": "Frames: `id: evt_…` + `event: ` + `data: `; `event: ready` ao abrir, `: ping` de heartbeat, `event: replay_gap` quando o `Last-Event-ID` saiu da retenção e `event: reconnect` aos 55 min, no deploy e quando a conexão LISTEN cai. A API key vai no header `Authorization`; `?token=` não é aceito.", "parameters": [ { "schema": { "type": "string", "enum": [ "live", "test" ] }, "required": false, "name": "mode", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "types", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "last_event_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "token", "in": "query" } ], "responses": { "200": { "description": "stream aberto", "content": { "text/event-stream": { "schema": { "type": "string", "description": "Frames SSE separados por linha em branco", "example": "id: evt_01j9x\nevent: transaction.paid\ndata: {\"id\":\"evt_01j9x\",\"object\":\"event\",\"type\":\"transaction.paid\",\"mode\":\"live\",\"created_at\":\"...\",\"data\":{\"object\":{}}}\n\n: ping\n\n" } } } }, "401": { "description": "invalid_api_key ou session_required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "rate_limited: mais de 10 conexões simultâneas do mesmo seller", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/events": { "get": { "tags": [ "events" ], "summary": "Lista o feed de eventos do seller", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "types", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "to", "in": "query" }, { "schema": { "type": "string", "enum": [ "transaction", "withdrawal" ] }, "required": false, "name": "resource_type", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "resource_id", "in": "query" } ], "responses": { "200": { "description": "página do feed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "event" ] }, "type": { "type": "string" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "object": { "type": "object", "additionalProperties": {} } }, "required": [ "object" ] }, "internal": { "type": "boolean" } }, "required": [ "id", "object", "type", "mode", "created_at", "data", "internal" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "validation_failed ou invalid_cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/events/{id}": { "get": { "tags": [ "events" ], "summary": "Busca um evento do feed", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "envelope", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "event" ] }, "type": { "type": "string" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "object": { "type": "object", "additionalProperties": {} } }, "required": [ "object" ] }, "internal": { "type": "boolean" } }, "required": [ "id", "object", "type", "mode", "created_at", "data", "internal" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/events": { "get": { "tags": [ "events" ], "summary": "Lista o feed de eventos do seller", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "types", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "to", "in": "query" }, { "schema": { "type": "string", "enum": [ "transaction", "withdrawal" ] }, "required": false, "name": "resource_type", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "resource_id", "in": "query" } ], "responses": { "200": { "description": "página do feed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "event" ] }, "type": { "type": "string" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "object": { "type": "object", "additionalProperties": {} } }, "required": [ "object" ] }, "internal": { "type": "boolean" } }, "required": [ "id", "object", "type", "mode", "created_at", "data", "internal" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "validation_failed ou invalid_cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/events/{id}": { "get": { "tags": [ "events" ], "summary": "Busca um evento do feed", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "envelope", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "event" ] }, "type": { "type": "string" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "object": { "type": "object", "additionalProperties": {} } }, "required": [ "object" ] }, "internal": { "type": "boolean" } }, "required": [ "id", "object", "type", "mode", "created_at", "data", "internal" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/webhook-endpoints": { "get": { "tags": [ "webhook-endpoints" ], "summary": "Lista os webhook endpoints ativos da store", "responses": { "200": { "description": "endpoints", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "enabled": { "type": "boolean" }, "secret_prefix": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "disabled_reason": { "type": [ "string", "null" ], "enum": [ "auto", "manual", null ] }, "auto_disabled_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "url", "events", "enabled", "secret_prefix", "description", "created_at", "disabled_reason", "auto_disabled_at" ] } } }, "required": [ "data" ] } } } } } }, "post": { "tags": [ "webhook-endpoints" ], "summary": "Cria um webhook endpoint (secret devolvido uma única vez)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1 }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "description": { "type": "string", "maxLength": 200 } }, "required": [ "url", "events" ] } } } }, "responses": { "201": { "description": "endpoint criado", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "enabled": { "type": "boolean" }, "secret_prefix": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "disabled_reason": { "type": [ "string", "null" ], "enum": [ "auto", "manual", null ] }, "auto_disabled_at": { "type": [ "string", "null" ], "format": "date-time" }, "secret": { "type": "string" } }, "required": [ "id", "url", "events", "enabled", "secret_prefix", "description", "created_at", "disabled_reason", "auto_disabled_at", "secret" ] } } } }, "400": { "description": "validation_failed | invalid_url | invalid_event_type", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "mfa_required: step-up ausente ou expirado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "409": { "description": "invalid_state: limite de endpoints ativos por mode", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "# Sessão do painel (cookie), não API key: exige step-up de MFA recente.\ncurl https://api.leztypay.com/v1/me/webhook-endpoints \\\n -H 'Cookie: ' \\\n -H 'X-Requested-With: lm' \\\n -H 'X-Mode: live' \\\n -H 'Content-Type: application/json' \\\n -d '{\"url\":\"https://loja.exemplo.com/webhooks/lm\",\"events\":[\"transaction.paid\",\"transaction.refunded\"],\"description\":\"Loja principal\"}'" }, { "lang": "javascript", "label": "Node (fetch)", "source": "const res = await fetch('https://api.leztypay.com/v1/me/webhook-endpoints', {\n method: 'POST',\n credentials: 'include',\n headers: { 'X-Requested-With': 'lm', 'X-Mode': 'live', 'Content-Type': 'application/json' },\n body: JSON.stringify({\n url: 'https://loja.exemplo.com/webhooks/lm',\n events: ['transaction.paid', 'transaction.refunded'],\n description: 'Loja principal',\n }),\n});\n// 403 com o header X-MFA-Step-Up: required = refazer o MFA e repetir.\nconst { secret } = await res.json(); // whsec_... aparece só nesta resposta" } ] } }, "/v1/me/webhook-endpoints/{id}": { "patch": { "tags": [ "webhook-endpoints" ], "summary": "Atualiza um webhook endpoint", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1 }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "enabled": { "type": "boolean" }, "description": { "type": [ "string", "null" ], "maxLength": 200 } } } } } }, "responses": { "200": { "description": "endpoint atualizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "enabled": { "type": "boolean" }, "secret_prefix": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "disabled_reason": { "type": [ "string", "null" ], "enum": [ "auto", "manual", null ] }, "auto_disabled_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "url", "events", "enabled", "secret_prefix", "description", "created_at", "disabled_reason", "auto_disabled_at" ] } } } }, "400": { "description": "validation_failed | invalid_url | invalid_event_type", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "mfa_required: step-up ausente ou expirado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "webhook-endpoints" ], "summary": "Remove (soft delete) um webhook endpoint", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "removido" }, "403": { "description": "mfa_required: step-up ausente ou expirado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/webhook-endpoints/{id}/rotate-secret": { "post": { "tags": [ "webhook-endpoints" ], "summary": "Rotaciona o secret do endpoint; o antigo continua válido por 24 h", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "secret rotacionado", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string" }, "previous_secret_expires_at": { "type": "string", "format": "date-time" } }, "required": [ "secret", "previous_secret_expires_at" ] } } } }, "403": { "description": "mfa_required: step-up ausente ou expirado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/webhook-endpoints/{id}/stats": { "get": { "tags": [ "webhook-endpoints" ], "summary": "Agregado de entregas dos últimos 7 dias e último ping do endpoint", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "success_rate_7d": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "deliveries_7d": { "type": "integer" }, "last_ping_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_ping_ok": { "type": [ "boolean", "null" ] } }, "required": [ "success_rate_7d", "deliveries_7d", "last_ping_at", "last_ping_ok" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/webhook-endpoints/{id}/ping": { "post": { "tags": [ "webhook-endpoints" ], "summary": "Dispara uma entrega de teste (`type: ping`) para o endpoint", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "202": { "description": "entrega enfileirada", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery_id": { "type": "string" } }, "required": [ "delivery_id" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/postback-secret/rotate": { "post": { "tags": [ "webhook-endpoints" ], "summary": "Rotaciona o secret do `postback_url` da store (devolvido uma única vez)", "responses": { "200": { "description": "secret rotacionado", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string" } }, "required": [ "secret" ] } } } }, "403": { "description": "mfa_required: step-up ausente ou expirado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/webhook-deliveries": { "get": { "tags": [ "webhook-deliveries" ], "summary": "Lista as entregas de webhook do seller", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "endpoint_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "event_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "event_type", "in": "query" }, { "schema": { "type": "string", "enum": [ "success", "failed", "dead" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "to", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "entregas", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "endpoint_id": { "type": [ "string", "null" ] }, "target": { "type": "string", "enum": [ "endpoint", "postback", "utmify" ] }, "attempt": { "type": "integer" }, "status": { "type": "string", "enum": [ "success", "failed", "dead" ] }, "status_code": { "type": [ "integer", "null" ] }, "response_ms": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "target_host": { "type": "string" } }, "required": [ "id", "event_id", "event_type", "endpoint_id", "target", "attempt", "status", "status_code", "response_ms", "error", "created_at", "target_host" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "invalid_cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/webhook-deliveries/{id}": { "get": { "tags": [ "webhook-deliveries" ], "summary": "Detalha uma entrega de webhook", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "entrega", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "endpoint_id": { "type": [ "string", "null" ] }, "target": { "type": "string", "enum": [ "endpoint", "postback", "utmify" ] }, "attempt": { "type": "integer" }, "status": { "type": "string", "enum": [ "success", "failed", "dead" ] }, "status_code": { "type": [ "integer", "null" ] }, "response_ms": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "target_host": { "type": "string" }, "request_headers": { "type": "object", "additionalProperties": { "type": "string" } }, "response_body_excerpt": { "type": [ "string", "null" ] }, "payload": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "event_id", "event_type", "endpoint_id", "target", "attempt", "status", "status_code", "response_ms", "error", "created_at", "target_host", "request_headers", "response_body_excerpt", "payload" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/webhook-deliveries/{id}/retry": { "post": { "tags": [ "webhook-deliveries" ], "summary": "Reenvia uma entrega manualmente (`attempt = last + 1`)", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "202": { "description": "reenvio enfileirado", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery_id": { "type": "string" } }, "required": [ "delivery_id" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "409": { "description": "invalid_state: entrega já teve sucesso ou já tem retry agendado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/webhook-deliveries": { "get": { "tags": [ "webhook-deliveries" ], "summary": "Lista as entregas de webhook do seller", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "endpoint_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "event_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "event_type", "in": "query" }, { "schema": { "type": "string", "enum": [ "success", "failed", "dead" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "to", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "entregas", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "endpoint_id": { "type": [ "string", "null" ] }, "target": { "type": "string", "enum": [ "endpoint", "postback", "utmify" ] }, "attempt": { "type": "integer" }, "status": { "type": "string", "enum": [ "success", "failed", "dead" ] }, "status_code": { "type": [ "integer", "null" ] }, "response_ms": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "target_host": { "type": "string" } }, "required": [ "id", "event_id", "event_type", "endpoint_id", "target", "attempt", "status", "status_code", "response_ms", "error", "created_at", "target_host" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "invalid_cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -G https://api.leztypay.com/v1/webhook-deliveries \\\n -H 'Authorization: Bearer sk_live_...' \\\n -d status=dead \\\n -d limit=50" }, { "lang": "javascript", "label": "Node (fetch)", "source": "const query = new URLSearchParams({ status: 'dead', limit: '50' });\nconst res = await fetch(\n `https://api.leztypay.com/v1/webhook-deliveries?${query}`,\n { headers: { Authorization: `Bearer ${process.env.LM_API_KEY}` } },\n);\nconst { data, next_cursor } = await res.json();" } ] } }, "/v1/webhook-deliveries/{id}": { "get": { "tags": [ "webhook-deliveries" ], "summary": "Detalha uma entrega de webhook", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "entrega", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "endpoint_id": { "type": [ "string", "null" ] }, "target": { "type": "string", "enum": [ "endpoint", "postback", "utmify" ] }, "attempt": { "type": "integer" }, "status": { "type": "string", "enum": [ "success", "failed", "dead" ] }, "status_code": { "type": [ "integer", "null" ] }, "response_ms": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "target_host": { "type": "string" }, "request_headers": { "type": "object", "additionalProperties": { "type": "string" } }, "response_body_excerpt": { "type": [ "string", "null" ] }, "payload": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "event_id", "event_type", "endpoint_id", "target", "attempt", "status", "status_code", "response_ms", "error", "created_at", "target_host", "request_headers", "response_body_excerpt", "payload" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/webhook-deliveries/{id}/retry": { "post": { "tags": [ "webhook-deliveries" ], "summary": "Reenvia uma entrega manualmente (`attempt = last + 1`)", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "202": { "description": "reenvio enfileirado", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery_id": { "type": "string" } }, "required": [ "delivery_id" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "409": { "description": "invalid_state: entrega já teve sucesso ou já tem retry agendado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://api.leztypay.com/v1/webhook-deliveries/whd_01j9x5k8p2q3r4s5t6u7v8w9xy/retry \\\n -H 'Authorization: Bearer sk_live_...'" }, { "lang": "javascript", "label": "Node (fetch)", "source": "const res = await fetch(\n `https://api.leztypay.com/v1/webhook-deliveries/${deliveryId}/retry`,\n { method: 'POST', headers: { Authorization: `Bearer ${process.env.LM_API_KEY}` } },\n);\n// 202 { delivery_id }; 409 invalid_state se a entrega já foi bem-sucedida.\nconst { delivery_id } = await res.json();" } ] } }, "/v1/transactions": { "post": { "tags": [ "transactions" ], "summary": "Cria uma cobrança PIX", "description": "Exige o header `Idempotency-Key` (`^[A-Za-z0-9_\\-:.]{1,255}$`). Repetir a mesma key com o mesmo corpo devolve a resposta salva com `Idempotent-Replayed: true`, inclusive quando a resposta salva foi um erro do parceiro; nesse caso use uma key nova para tentar de novo. Rows salvas antes de FIX-PIX-LOOKUP guardam `502` e continuam replayando `502`.", "requestBody": { "required": true, "content": { "application/json": { "example": { "amount": 10000, "payment_method": "pix", "customer": { "name": "Maria Silva", "email": "maria@exemplo.com", "document": "123.456.789-09" }, "items": [ { "name": "Curso X", "quantity": 1, "unit_amount": 10000 } ], "pix": { "expires_in_seconds": 1800 }, "postback_url": "https://loja.exemplo.com/webhooks/lm", "metadata": { "order_id": "A123" } }, "schema": { "type": "object", "properties": { "amount": { "type": "integer" }, "payment_method": { "type": "string" }, "customer": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "email": { "type": "string", "maxLength": 254, "format": "email" }, "document": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "name", "email", "document" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 }, "unit_amount": { "type": "integer", "minimum": 0 } }, "required": [ "name", "quantity", "unit_amount" ] }, "maxItems": 50 }, "pix": { "type": "object", "properties": { "expires_in_seconds": { "type": "integer" } } }, "postback_url": { "type": "string", "maxLength": 2048 }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 } }, "description": { "type": "string", "maxLength": 140 }, "tracking": { "type": "object", "properties": { "src": { "type": "string", "maxLength": 255 }, "sck": { "type": "string", "maxLength": 255 }, "utm_source": { "type": "string", "maxLength": 255 }, "utm_campaign": { "type": "string", "maxLength": 255 }, "utm_medium": { "type": "string", "maxLength": 255 }, "utm_content": { "type": "string", "maxLength": 255 }, "utm_term": { "type": "string", "maxLength": 255 } }, "additionalProperties": false } }, "required": [ "amount", "customer" ] } } } }, "responses": { "201": { "description": "cobrança criada", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "transaction" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string" }, "payment_method": { "type": "string" }, "amount": { "type": "integer" }, "fee": { "type": "integer" }, "net": { "type": "integer" }, "reserve": { "type": "integer" }, "reserve_released_at": { "type": [ "string", "null" ] }, "customer": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "document": { "type": "string" }, "phone": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "quantity": { "type": "number" }, "unit_amount": { "type": "number" } } } }, "pix": { "type": "object", "properties": { "payload": { "type": [ "string", "null" ] }, "qr_base64": { "type": [ "string", "null" ] }, "expires_at": { "type": "string" } }, "required": [ "payload", "qr_base64", "expires_at" ] }, "postback_url": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": {} }, "tracking": { "type": [ "object", "null" ], "properties": { "src": { "type": [ "string", "null" ] }, "sck": { "type": [ "string", "null" ] }, "utm_source": { "type": [ "string", "null" ] }, "utm_campaign": { "type": [ "string", "null" ] }, "utm_medium": { "type": [ "string", "null" ] }, "utm_content": { "type": [ "string", "null" ] }, "utm_term": { "type": [ "string", "null" ] } }, "required": [ "src", "sck", "utm_source", "utm_campaign", "utm_medium", "utm_content", "utm_term" ] }, "acquirer": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "slug" ] }, "paid_at": { "type": [ "string", "null" ] }, "expired_at": { "type": [ "string", "null" ] }, "refunded_at": { "type": [ "string", "null" ] }, "chargeback_at": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "mode", "status", "payment_method", "amount", "fee", "net", "reserve", "reserve_released_at", "customer", "items", "pix", "postback_url", "metadata", "acquirer", "paid_at", "expired_at", "refunded_at", "chargeback_at", "failure_reason", "end_to_end_id", "created_at", "updated_at" ] } } } }, "400": { "description": "validation_failed, amount_too_small, amount_too_large, invalid_document, invalid_expires_in, invalid_url, missing_idempotency_key, unsupported_payment_method", "content": { "application/json": { "example": { "error": { "type": "invalid_request_error", "code": "invalid_document", "message": "customer.document is not a valid CPF or CNPJ", "param": "customer.document", "request_id": "req_01j9x5k8p2q3r4s5t6u7v8w9xy" } }, "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "seller_not_allowed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "409": { "description": "idempotency_conflict, idempotency_in_progress", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "502": { "description": "replay de uma row de idempotência anterior a FIX-PIX-LOOKUP", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "503": { "description": "acquirer_timeout, acquirer_rejected, acquirer_unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl https://api.leztypay.com/v1/transactions \\\n -H 'Authorization: Bearer sk_live_...' \\\n -H 'Idempotency-Key: order-A123-attempt-1' \\\n -H 'Content-Type: application/json' \\\n -d '{\"amount\":10000,\"payment_method\":\"pix\",\"customer\":{\"name\":\"Maria Silva\",\"email\":\"maria@exemplo.com\",\"document\":\"123.456.789-09\"},\"pix\":{\"expires_in_seconds\":1800},\"postback_url\":\"https://loja.exemplo.com/webhooks/lm\",\"metadata\":{\"order_id\":\"A123\"}}'" }, { "lang": "javascript", "label": "Node (fetch)", "source": "const res = await fetch('https://api.leztypay.com/v1/transactions', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.LM_API_KEY}`,\n // Mesma chave = mesma resposta. Repetir com chave nova cria outra cobrança.\n 'Idempotency-Key': 'order-A123-attempt-1',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n amount: 10000,\n payment_method: 'pix',\n customer: { name: 'Maria Silva', email: 'maria@exemplo.com', document: '123.456.789-09' },\n items: [{ title: 'Curso X', unit_price: 10000, quantity: 1, tangible: false }],\n pix: { expires_in_seconds: 1800 },\n postback_url: 'https://loja.exemplo.com/webhooks/lm',\n metadata: { order_id: 'A123' },\n }),\n});\nconst transaction = await res.json();" }, { "lang": "php", "label": "PHP (curl)", "source": "$ch = curl_init('https://api.leztypay.com/v1/transactions');\ncurl_setopt_array($ch, [\n CURLOPT_POST => true,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('LM_API_KEY'),\n 'Idempotency-Key: order-A123-attempt-1',\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'amount' => 10000,\n 'payment_method' => 'pix',\n 'customer' => [\n 'name' => 'Maria Silva',\n 'email' => 'maria@exemplo.com',\n 'document' => '123.456.789-09',\n ],\n 'pix' => ['expires_in_seconds' => 1800],\n 'postback_url' => 'https://loja.exemplo.com/webhooks/lm',\n 'metadata' => ['order_id' => 'A123'],\n ]),\n]);\n$transaction = json_decode(curl_exec($ch), true);" }, { "lang": "python", "label": "Python (requests)", "source": "import os\n\nimport requests\n\nres = requests.post(\n 'https://api.leztypay.com/v1/transactions',\n headers={\n 'Authorization': f\"Bearer {os.environ['LM_API_KEY']}\",\n 'Idempotency-Key': 'order-A123-attempt-1',\n },\n json={\n 'amount': 10000,\n 'payment_method': 'pix',\n 'customer': {\n 'name': 'Maria Silva',\n 'email': 'maria@exemplo.com',\n 'document': '123.456.789-09',\n },\n 'pix': {'expires_in_seconds': 1800},\n 'postback_url': 'https://loja.exemplo.com/webhooks/lm',\n 'metadata': {'order_id': 'A123'},\n },\n timeout=30,\n)\ntransaction = res.json()" } ] }, "get": { "tags": [ "transactions" ], "summary": "Lista cobranças do seller", "description": "Ordenado por `(created_at DESC, id DESC)`. `next_cursor` é nulo quando a página não veio cheia. `q` aceita **um** critério: id público (`txn_…`), email exato ou documento só com dígitos, qualquer outro formato é `400 validation_failed` com `param: \"q\"`. `with_totals=1` acrescenta `totals`: `filtered` (contagem e somas em centavos do subconjunto filtrado, sem paginar) e `by_status` (contagem dos seis status no MESMO recorte, mas ignorando o filtro `status`, é o que alimenta as tabs). Cobrança `expired` nunca aparece: sem `status` na query ela é excluída por padrão, e `status=expired` explícito (sozinho ou em csv) devolve `400 validation_failed`.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "enum": [ "0", "1" ] }, "required": false, "name": "with_totals", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "created_from", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "created_to", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "paid_from", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "paid_to", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "q", "in": "query" } ], "responses": { "200": { "description": "página de cobranças", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "transaction" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string" }, "payment_method": { "type": "string" }, "amount": { "type": "integer" }, "fee": { "type": "integer" }, "net": { "type": "integer" }, "reserve": { "type": "integer" }, "reserve_released_at": { "type": [ "string", "null" ] }, "customer": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "document": { "type": "string" }, "phone": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "quantity": { "type": "number" }, "unit_amount": { "type": "number" } } } }, "pix": { "type": "object", "properties": { "payload": { "type": [ "string", "null" ] }, "qr_base64": { "type": [ "string", "null" ] }, "expires_at": { "type": "string" } }, "required": [ "payload", "qr_base64", "expires_at" ] }, "postback_url": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": {} }, "tracking": { "type": [ "object", "null" ], "properties": { "src": { "type": [ "string", "null" ] }, "sck": { "type": [ "string", "null" ] }, "utm_source": { "type": [ "string", "null" ] }, "utm_campaign": { "type": [ "string", "null" ] }, "utm_medium": { "type": [ "string", "null" ] }, "utm_content": { "type": [ "string", "null" ] }, "utm_term": { "type": [ "string", "null" ] } }, "required": [ "src", "sck", "utm_source", "utm_campaign", "utm_medium", "utm_content", "utm_term" ] }, "acquirer": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "slug" ] }, "paid_at": { "type": [ "string", "null" ] }, "expired_at": { "type": [ "string", "null" ] }, "refunded_at": { "type": [ "string", "null" ] }, "chargeback_at": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "mode", "status", "payment_method", "amount", "fee", "net", "reserve", "reserve_released_at", "customer", "items", "pix", "postback_url", "metadata", "acquirer", "paid_at", "expired_at", "refunded_at", "chargeback_at", "failure_reason", "end_to_end_id", "created_at", "updated_at" ] } }, "next_cursor": { "type": [ "string", "null" ] }, "totals": { "type": "object", "properties": { "by_status": { "type": "object", "properties": { "pending": { "type": "integer" }, "paid": { "type": "integer" }, "expired": { "type": "integer" }, "failed": { "type": "integer" }, "refunded": { "type": "integer" }, "chargeback": { "type": "integer" } }, "required": [ "pending", "paid", "expired", "failed", "refunded", "chargeback" ] }, "filtered": { "type": "object", "properties": { "count": { "type": "integer" }, "gross_cents": { "type": "integer" }, "fee_cents": { "type": "integer" }, "net_cents": { "type": "integer" } }, "required": [ "count", "gross_cents", "fee_cents", "net_cents" ] } }, "required": [ "by_status", "filtered" ] } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "validation_failed, invalid_cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/transactions/{id}": { "get": { "tags": [ "transactions" ], "summary": "Consulta uma cobrança", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "cobrança", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "transaction" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string" }, "payment_method": { "type": "string" }, "amount": { "type": "integer" }, "fee": { "type": "integer" }, "net": { "type": "integer" }, "reserve": { "type": "integer" }, "reserve_released_at": { "type": [ "string", "null" ] }, "customer": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "document": { "type": "string" }, "phone": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "quantity": { "type": "number" }, "unit_amount": { "type": "number" } } } }, "pix": { "type": "object", "properties": { "payload": { "type": [ "string", "null" ] }, "qr_base64": { "type": [ "string", "null" ] }, "expires_at": { "type": "string" } }, "required": [ "payload", "qr_base64", "expires_at" ] }, "postback_url": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": {} }, "tracking": { "type": [ "object", "null" ], "properties": { "src": { "type": [ "string", "null" ] }, "sck": { "type": [ "string", "null" ] }, "utm_source": { "type": [ "string", "null" ] }, "utm_campaign": { "type": [ "string", "null" ] }, "utm_medium": { "type": [ "string", "null" ] }, "utm_content": { "type": [ "string", "null" ] }, "utm_term": { "type": [ "string", "null" ] } }, "required": [ "src", "sck", "utm_source", "utm_campaign", "utm_medium", "utm_content", "utm_term" ] }, "acquirer": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "slug" ] }, "paid_at": { "type": [ "string", "null" ] }, "expired_at": { "type": [ "string", "null" ] }, "refunded_at": { "type": [ "string", "null" ] }, "chargeback_at": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "mode", "status", "payment_method", "amount", "fee", "net", "reserve", "reserve_released_at", "customer", "items", "pix", "postback_url", "metadata", "acquirer", "paid_at", "expired_at", "refunded_at", "chargeback_at", "failure_reason", "end_to_end_id", "created_at", "updated_at" ] } } } }, "400": { "description": "validation_failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl https://api.leztypay.com/v1/transactions/txn_01j9x5k8p2q3r4s5t6u7v8w9xy \\\n -H 'Authorization: Bearer sk_live_...'" }, { "lang": "javascript", "label": "Node (fetch)", "source": "const res = await fetch(\n `https://api.leztypay.com/v1/transactions/${id}`,\n { headers: { Authorization: `Bearer ${process.env.LM_API_KEY}` } },\n);\nconst transaction = await res.json();" } ] } }, "/webhooks/in/{slug}": { "post": { "tags": [ "webhooks-inbound" ], "summary": "Recebe um evento do parceiro", "description": "Corpo cru do parceiro, verificado pela assinatura do adapter. Persiste antes de responder e processa de forma assíncrona (job `process-inbox`). Repetição exata devolve `duplicate: true`.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,40}$", "example": "fake" }, "required": true, "name": "slug", "in": "path" } ], "responses": { "200": { "description": "evento aceito", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInboundReceipt" } } } }, "400": { "description": "corpo malformado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInboundError" } } } }, "401": { "description": "assinatura inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInboundError" } } } }, "404": { "description": "acquirer inexistente ou desabilitado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInboundError" } } } }, "429": { "description": "acima de 300 requisições por minuto para o slug", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInboundError" } } } } } } }, "/v1/me/pix-keys": { "get": { "tags": [ "pix-keys" ], "summary": "Lista as chaves PIX do seller (ativas e inativas)", "responses": { "200": { "description": "chaves", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "type": { "type": "string", "enum": [ "cpf", "cnpj", "email", "phone", "evp" ] }, "owner_name": { "type": [ "string", "null" ] }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "verification_error": { "type": [ "string", "null" ], "enum": [ "ownership_mismatch", "key_not_found", "lookup_timeout", null ] }, "active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "partner_status": { "type": [ "string", "null" ], "enum": [ "pending_approval", "approved", "rejected", null ] }, "partner_reviewed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "key", "type", "owner_name", "verified_at", "verification_error", "active", "created_at", "partner_status", "partner_reviewed_at" ] } } }, "required": [ "data" ] } } } } } }, "post": { "tags": [ "pix-keys" ], "summary": "Cadastra a chave PIX do seller (o documento aprovado no KYC)", "description": "O corpo só tem `type` (`cpf` ou `cnpj`), que precisa ser igual ao `document_type` do seller: a chave é sempre o documento aprovado no KYC, que o painel só conhece mascarado. Não existe campo `key` (mandar um é `400 validation_failed`), e a titularidade não passa mais pelo DICT.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "cpf", "cnpj" ] } }, "required": [ "type" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "chave criada", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "type": { "type": "string", "enum": [ "cpf", "cnpj", "email", "phone", "evp" ] }, "owner_name": { "type": [ "string", "null" ] }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "verification_error": { "type": [ "string", "null" ], "enum": [ "ownership_mismatch", "key_not_found", "lookup_timeout", null ] }, "active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "partner_status": { "type": [ "string", "null" ], "enum": [ "pending_approval", "approved", "rejected", null ] }, "partner_reviewed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "key", "type", "owner_name", "verified_at", "verification_error", "active", "created_at", "partner_status", "partner_reviewed_at" ] } } } }, "400": { "description": "invalid_pix_key: `type` diferente do documento aprovado no KYC; validation_failed: campo desconhecido no corpo", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "kyc_required (sem documento aprovado) ou mfa_required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "409": { "description": "invalid_state: limite de chaves ativas ou chave duplicada", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "503": { "description": "acquirer_*: parceiro indisponível", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/pix-keys": { "get": { "tags": [ "pix-keys" ], "summary": "Lista as chaves PIX verificadas e ativas do seller", "responses": { "200": { "description": "chaves", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "type": { "type": "string", "enum": [ "cpf", "cnpj", "email", "phone", "evp" ] }, "owner_name": { "type": [ "string", "null" ] }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "verification_error": { "type": [ "string", "null" ], "enum": [ "ownership_mismatch", "key_not_found", "lookup_timeout", null ] }, "active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "partner_status": { "type": [ "string", "null" ], "enum": [ "pending_approval", "approved", "rejected", null ] }, "partner_reviewed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "key", "type", "owner_name", "verified_at", "verification_error", "active", "created_at", "partner_status", "partner_reviewed_at" ] } } }, "required": [ "data" ] } } } } } } }, "/v1/me/pix-keys/{id}/verify": { "post": { "tags": [ "pix-keys" ], "summary": "Reconfirma a chave e reenvia o registro ao parceiro (3 por dia, fuso America/Sao_Paulo)", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "chave", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "type": { "type": "string", "enum": [ "cpf", "cnpj", "email", "phone", "evp" ] }, "owner_name": { "type": [ "string", "null" ] }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "verification_error": { "type": [ "string", "null" ], "enum": [ "ownership_mismatch", "key_not_found", "lookup_timeout", null ] }, "active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "partner_status": { "type": [ "string", "null" ], "enum": [ "pending_approval", "approved", "rejected", null ] }, "partner_reviewed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "key", "type", "owner_name", "verified_at", "verification_error", "active", "created_at", "partner_status", "partner_reviewed_at" ] } } } }, "400": { "description": "validation_failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "409": { "description": "invalid_state: chave inativa", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "rate_limited: 3 verificações por dia; ver Retry-After", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "503": { "description": "acquirer_*: parceiro indisponível", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/pix-keys/{id}": { "delete": { "tags": [ "pix-keys" ], "summary": "Desativa a chave PIX (nunca apaga: saques históricos referenciam)", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "desativada (idempotente)" }, "400": { "description": "validation_failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "mfa_required: step-up ausente ou expirado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/push/vapid-public-key": { "get": { "tags": [ "push" ], "summary": "Chave pública VAPID para `pushManager.subscribe`", "responses": { "200": { "description": "chave", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" } }, "required": [ "key" ] } } } } } } }, "/v1/me/push-subscriptions": { "get": { "tags": [ "push" ], "summary": "Lista as subscriptions de push do usuário", "responses": { "200": { "description": "subscriptions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "endpoint_host": { "type": "string" }, "muted": { "type": "boolean" }, "user_agent": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "endpoint_host", "muted", "user_agent", "label", "last_used_at", "created_at" ] } } }, "required": [ "data" ] } } } } } }, "post": { "tags": [ "push" ], "summary": "Cadastra (ou reaproveita, por `endpoint`) uma subscription de push", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "type": "string", "maxLength": 2000, "format": "uri" }, "keys": { "type": "object", "properties": { "p256dh": { "type": "string", "minLength": 1, "maxLength": 500 }, "auth": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "p256dh", "auth" ] }, "user_agent": { "type": "string", "maxLength": 300 }, "label": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "endpoint", "keys" ] } } } }, "responses": { "201": { "description": "subscription cadastrada", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "endpoint_host": { "type": "string" }, "muted": { "type": "boolean" }, "user_agent": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "endpoint_host", "muted", "user_agent", "label", "last_used_at", "created_at" ] } } } }, "400": { "description": "validation_failed | invalid_url", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "409": { "description": "invalid_state: limite de subscriptions por usuário", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/push-subscriptions/{id}": { "patch": { "tags": [ "push" ], "summary": "Silencia ou reativa uma subscription", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "muted": { "type": "boolean" } }, "required": [ "muted" ] } } } }, "responses": { "200": { "description": "subscription atualizada", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "endpoint_host": { "type": "string" }, "muted": { "type": "boolean" }, "user_agent": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "endpoint_host", "muted", "user_agent", "label", "last_used_at", "created_at" ] } } } }, "400": { "description": "validation_failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "push" ], "summary": "Remove uma subscription", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "removida" }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/rates": { "get": { "tags": [ "rates" ], "summary": "Taxas vigentes do seller e as futuras já agendadas", "responses": { "200": { "description": "taxas", "content": { "application/json": { "schema": { "type": "object", "properties": { "current": { "type": "object", "properties": { "pix_fixed_cents": { "type": "integer", "minimum": 0, "maximum": 100000 }, "pix_pct_bps": { "type": "integer", "minimum": 0, "maximum": 2000 }, "withdraw_fee_cents": { "type": "integer", "minimum": 0, "maximum": 100000 }, "reserve_pct_bps": { "type": "integer", "minimum": 0, "maximum": 5000 }, "reserve_days": { "type": "integer", "minimum": 0, "maximum": 180 }, "chargeback_fee_cents": { "type": "integer", "minimum": 0, "maximum": 100000 }, "daily_withdraw_limit_cents": { "type": [ "integer", "null" ], "minimum": 100 }, "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "inherits_default": { "type": "boolean" }, "effective_from": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "pix_fixed_cents", "pix_pct_bps", "withdraw_fee_cents", "reserve_pct_bps", "reserve_days", "chargeback_fee_cents", "daily_withdraw_limit_cents", "id", "version", "inherits_default", "effective_from", "created_at" ] }, "scheduled": { "type": "array", "items": { "type": "object", "properties": { "pix_fixed_cents": { "type": "integer", "minimum": 0, "maximum": 100000 }, "pix_pct_bps": { "type": "integer", "minimum": 0, "maximum": 2000 }, "withdraw_fee_cents": { "type": "integer", "minimum": 0, "maximum": 100000 }, "reserve_pct_bps": { "type": "integer", "minimum": 0, "maximum": 5000 }, "reserve_days": { "type": "integer", "minimum": 0, "maximum": 180 }, "chargeback_fee_cents": { "type": "integer", "minimum": 0, "maximum": 100000 }, "daily_withdraw_limit_cents": { "type": [ "integer", "null" ], "minimum": 100 }, "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "inherits_default": { "type": "boolean" }, "effective_from": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "pix_fixed_cents", "pix_pct_bps", "withdraw_fee_cents", "reserve_pct_bps", "reserve_days", "chargeback_fee_cents", "daily_withdraw_limit_cents", "id", "version", "inherits_default", "effective_from", "created_at" ] } } }, "required": [ "current", "scheduled" ] } } } } } } }, "/v1/me": { "get": { "tags": [ "sellers" ], "summary": "Perfil do seller da sessão (documento sempre mascarado)", "responses": { "200": { "description": "perfil", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "seller" ] }, "display_name": { "type": "string" }, "legal_name": { "type": [ "string", "null" ] }, "document": { "type": [ "string", "null" ] }, "document_type": { "type": [ "string", "null" ], "enum": [ "cpf", "cnpj", null ] }, "status": { "type": "string", "enum": [ "pending_kyc", "active", "suspended", "closed" ] }, "kyc_status": { "type": "string", "enum": [ "none", "pending", "approved", "rejected" ] }, "pix_enabled": { "type": "boolean" }, "withdraw_auto_approve": { "type": "boolean" }, "payout_locked": { "type": "boolean" }, "terms_version": { "type": [ "string", "null" ] }, "store": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "created_at": { "type": "string", "format": "date-time" }, "email": { "type": [ "string", "null" ], "format": "email" }, "two_factor_enabled": { "type": "boolean" }, "revenue_goal_cents": { "type": [ "integer", "null" ] }, "notification_prefs": { "type": "object", "properties": { "payment": { "type": "boolean" }, "withdrawal": { "type": "boolean" }, "chargeback": { "type": "boolean" }, "kyc": { "type": "boolean" } }, "required": [ "payment", "withdrawal", "chargeback", "kyc" ] } }, "required": [ "id", "object", "display_name", "legal_name", "document", "document_type", "status", "kyc_status", "pix_enabled", "withdraw_auto_approve", "payout_locked", "terms_version", "store", "created_at", "email", "two_factor_enabled", "revenue_goal_cents", "notification_prefs" ] } } } }, "403": { "description": "`insufficient_role` ou `terms_not_accepted`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } }, "patch": { "tags": [ "sellers" ], "summary": "Atualiza nome de exibição, nome da loja, meta de recebimento e notificações", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "display_name": { "type": "string", "minLength": 2, "maxLength": 80 }, "store": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 80 } }, "required": [ "name" ] }, "revenue_goal_cents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000000 }, "notification_prefs": { "type": "object", "properties": { "payment": { "type": "boolean" }, "withdrawal": { "type": "boolean" }, "chargeback": { "type": "boolean" }, "kyc": { "type": "boolean" } } } } } } } }, "responses": { "200": { "description": "perfil", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "seller" ] }, "display_name": { "type": "string" }, "legal_name": { "type": [ "string", "null" ] }, "document": { "type": [ "string", "null" ] }, "document_type": { "type": [ "string", "null" ], "enum": [ "cpf", "cnpj", null ] }, "status": { "type": "string", "enum": [ "pending_kyc", "active", "suspended", "closed" ] }, "kyc_status": { "type": "string", "enum": [ "none", "pending", "approved", "rejected" ] }, "pix_enabled": { "type": "boolean" }, "withdraw_auto_approve": { "type": "boolean" }, "payout_locked": { "type": "boolean" }, "terms_version": { "type": [ "string", "null" ] }, "store": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "created_at": { "type": "string", "format": "date-time" }, "email": { "type": [ "string", "null" ], "format": "email" }, "two_factor_enabled": { "type": "boolean" }, "revenue_goal_cents": { "type": [ "integer", "null" ] }, "notification_prefs": { "type": "object", "properties": { "payment": { "type": "boolean" }, "withdrawal": { "type": "boolean" }, "chargeback": { "type": "boolean" }, "kyc": { "type": "boolean" } }, "required": [ "payment", "withdrawal", "chargeback", "kyc" ] } }, "required": [ "id", "object", "display_name", "legal_name", "document", "document_type", "status", "kyc_status", "pix_enabled", "withdraw_auto_approve", "payout_locked", "terms_version", "store", "created_at", "email", "two_factor_enabled", "revenue_goal_cents", "notification_prefs" ] } } } }, "400": { "description": "`validation_failed`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/terms": { "get": { "tags": [ "sellers" ], "summary": "Versão vigente dos termos (sem janela de graça: fora de dia é `403` imediato)", "responses": { "200": { "description": "termos vigentes", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string" }, "effective_from": { "type": "string", "format": "date-time" }, "summary": { "type": "string" } }, "required": [ "version", "effective_from", "summary" ] } } } }, "403": { "description": "`insufficient_role`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/balance": { "get": { "tags": [ "sellers" ], "summary": "Saldo e agregados do seller no mode do header `X-Mode` (default `live`)", "responses": { "200": { "description": "saldo", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "integer" }, "reserve": { "type": "integer" }, "pending_withdraw": { "type": "integer" }, "withdrawn": { "type": "integer" }, "gross": { "type": "integer" }, "fees": { "type": "integer" }, "refunds": { "type": "integer" }, "chargebacks": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "withdrawals_locked_until": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "available", "reserve", "pending_withdraw", "withdrawn", "gross", "fees", "refunds", "chargebacks", "updated_at", "withdrawals_locked_until" ] } } } }, "400": { "description": "`validation_failed`, `X-Mode` fora de `live|test`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/balance": { "get": { "tags": [ "sellers" ], "summary": "Saldo e agregados do seller no mode da API key", "responses": { "200": { "description": "saldo", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "integer" }, "reserve": { "type": "integer" }, "pending_withdraw": { "type": "integer" }, "withdrawn": { "type": "integer" }, "gross": { "type": "integer" }, "fees": { "type": "integer" }, "refunds": { "type": "integer" }, "chargebacks": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "withdrawals_locked_until": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "available", "reserve", "pending_withdraw", "withdrawn", "gross", "fees", "refunds", "chargebacks", "updated_at", "withdrawals_locked_until" ] } } } }, "401": { "description": "`invalid_api_key` ou `revoked_api_key`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`seller_not_allowed`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/kyc": { "get": { "tags": [ "kyc" ], "summary": "Submissão de KYC mais recente do seller (cria uma `draft` se não houver)", "responses": { "200": { "description": "submissão de KYC (nunca inclui `s3_key`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ] }, "company": { "type": "object", "properties": { "legal_name": { "type": "string", "minLength": 2, "maxLength": 200 }, "document": { "type": "string", "minLength": 1, "maxLength": 200 }, "document_type": { "type": "string", "enum": [ "cpf", "cnpj" ] }, "average_ticket_cents": { "type": "integer", "minimum": 0 }, "website": { "type": "string", "format": "uri" }, "offers": { "type": "string", "minLength": 1, "maxLength": 1000 } } }, "representative": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 200 }, "document": { "type": "string", "minLength": 1, "maxLength": 200 }, "birth_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "phone": { "type": "string", "pattern": "^\\+[1-9]\\d{7,14}$" }, "mother_name": { "type": "string", "minLength": 2, "maxLength": 200 } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "file_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "id_front", "id_back", "selfie", "company_doc" ] }, "content_type": { "type": "string" }, "size": { "type": "integer" }, "confirmed": { "type": "boolean" }, "uploaded_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "file_id", "kind", "content_type", "size", "confirmed", "uploaded_at" ] } }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "rejection_reason": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "company", "representative", "files", "submitted_at", "rejection_reason", "reviewed_at", "created_at", "updated_at" ] } } } }, "403": { "description": "`insufficient_role` ou `terms_not_accepted`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } }, "put": { "tags": [ "kyc" ], "summary": "Salva empresa e representante; em `rejected` abre uma `draft` nova copiando tudo", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company": { "type": "object", "properties": { "legal_name": { "type": "string", "minLength": 2, "maxLength": 200 }, "document": { "type": "string", "minLength": 1, "maxLength": 200 }, "document_type": { "type": "string", "enum": [ "cpf", "cnpj" ] }, "average_ticket_cents": { "type": "integer", "minimum": 0 }, "website": { "type": "string", "format": "uri" }, "offers": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "legal_name", "document", "document_type", "average_ticket_cents", "offers" ] }, "representative": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 200 }, "document": { "type": "string", "minLength": 1, "maxLength": 200 }, "birth_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "phone": { "type": "string", "pattern": "^\\+[1-9]\\d{7,14}$" }, "mother_name": { "type": "string", "minLength": 2, "maxLength": 200 } }, "required": [ "name", "document", "birth_date", "phone", "mother_name" ] } }, "required": [ "company", "representative" ] } } } }, "responses": { "200": { "description": "submissão de KYC (nunca inclui `s3_key`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ] }, "company": { "type": "object", "properties": { "legal_name": { "type": "string", "minLength": 2, "maxLength": 200 }, "document": { "type": "string", "minLength": 1, "maxLength": 200 }, "document_type": { "type": "string", "enum": [ "cpf", "cnpj" ] }, "average_ticket_cents": { "type": "integer", "minimum": 0 }, "website": { "type": "string", "format": "uri" }, "offers": { "type": "string", "minLength": 1, "maxLength": 1000 } } }, "representative": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 200 }, "document": { "type": "string", "minLength": 1, "maxLength": 200 }, "birth_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "phone": { "type": "string", "pattern": "^\\+[1-9]\\d{7,14}$" }, "mother_name": { "type": "string", "minLength": 2, "maxLength": 200 } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "file_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "id_front", "id_back", "selfie", "company_doc" ] }, "content_type": { "type": "string" }, "size": { "type": "integer" }, "confirmed": { "type": "boolean" }, "uploaded_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "file_id", "kind", "content_type", "size", "confirmed", "uploaded_at" ] } }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "rejection_reason": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "company", "representative", "files", "submitted_at", "rejection_reason", "reviewed_at", "created_at", "updated_at" ] } } } }, "400": { "description": "`validation_failed` ou `invalid_document`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "409": { "description": "`invalid_state` (pending/approved) ou `document_in_use`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/kyc/files": { "post": { "tags": [ "kyc" ], "summary": "URL assinada de `PUT` (5 min, SSE-KMS) para subir um arquivo direto no S3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "id_front", "id_back", "selfie", "company_doc" ] }, "content_type": { "type": "string", "enum": [ "image/jpeg", "image/png", "application/pdf" ] }, "size": { "type": "integer", "minimum": 1, "maximum": 10485760 } }, "required": [ "kind", "content_type", "size" ] } } } }, "responses": { "200": { "description": "ticket de upload", "content": { "application/json": { "schema": { "type": "object", "properties": { "file_id": { "type": "string" }, "upload_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "file_id", "upload_url", "expires_at" ] } } } }, "400": { "description": "`validation_failed`, `kind`, `content_type` ou `size`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "409": { "description": "`invalid_state`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/kyc/files/{file_id}/confirm": { "post": { "tags": [ "kyc" ], "summary": "Confere o objeto no S3 (`HEAD`) e marca o arquivo como enviado", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "file_id", "in": "path" } ], "responses": { "200": { "description": "submissão de KYC (nunca inclui `s3_key`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ] }, "company": { "type": "object", "properties": { "legal_name": { "type": "string", "minLength": 2, "maxLength": 200 }, "document": { "type": "string", "minLength": 1, "maxLength": 200 }, "document_type": { "type": "string", "enum": [ "cpf", "cnpj" ] }, "average_ticket_cents": { "type": "integer", "minimum": 0 }, "website": { "type": "string", "format": "uri" }, "offers": { "type": "string", "minLength": 1, "maxLength": 1000 } } }, "representative": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 200 }, "document": { "type": "string", "minLength": 1, "maxLength": 200 }, "birth_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "phone": { "type": "string", "pattern": "^\\+[1-9]\\d{7,14}$" }, "mother_name": { "type": "string", "minLength": 2, "maxLength": 200 } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "file_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "id_front", "id_back", "selfie", "company_doc" ] }, "content_type": { "type": "string" }, "size": { "type": "integer" }, "confirmed": { "type": "boolean" }, "uploaded_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "file_id", "kind", "content_type", "size", "confirmed", "uploaded_at" ] } }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "rejection_reason": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "company", "representative", "files", "submitted_at", "rejection_reason", "reviewed_at", "created_at", "updated_at" ] } } } }, "400": { "description": "`upload_not_found`, ausente, tamanho ou tipo diferente", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`resource_not_found`, arquivo de outro seller ou inexistente", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "409": { "description": "`invalid_state`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/kyc/submit": { "post": { "tags": [ "kyc" ], "summary": "Envia a submissão para análise (exige step-up de MFA)", "responses": { "200": { "description": "submissão de KYC (nunca inclui `s3_key`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ] }, "company": { "type": "object", "properties": { "legal_name": { "type": "string", "minLength": 2, "maxLength": 200 }, "document": { "type": "string", "minLength": 1, "maxLength": 200 }, "document_type": { "type": "string", "enum": [ "cpf", "cnpj" ] }, "average_ticket_cents": { "type": "integer", "minimum": 0 }, "website": { "type": "string", "format": "uri" }, "offers": { "type": "string", "minLength": 1, "maxLength": 1000 } } }, "representative": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 200 }, "document": { "type": "string", "minLength": 1, "maxLength": 200 }, "birth_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "phone": { "type": "string", "pattern": "^\\+[1-9]\\d{7,14}$" }, "mother_name": { "type": "string", "minLength": 2, "maxLength": 200 } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "file_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "id_front", "id_back", "selfie", "company_doc" ] }, "content_type": { "type": "string" }, "size": { "type": "integer" }, "confirmed": { "type": "boolean" }, "uploaded_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "file_id", "kind", "content_type", "size", "confirmed", "uploaded_at" ] } }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "rejection_reason": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "company", "representative", "files", "submitted_at", "rejection_reason", "reviewed_at", "created_at", "updated_at" ] } } } }, "400": { "description": "`kyc_incomplete`, `param` é o primeiro campo/kind ausente", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`mfa_required`, step-up ausente ou expirado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "409": { "description": "`invalid_state`, a submissão não está em `draft`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/integrations/utmify": { "get": { "tags": [ "integrations" ], "summary": "Estado da integração UTMify do seller", "responses": { "200": { "description": "integração", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "utmify" ] }, "configured": { "type": "boolean" }, "enabled": { "type": "boolean" }, "token_last4": { "type": [ "string", "null" ] }, "last_ok_at": { "type": [ "string", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "provider", "configured", "enabled", "token_last4", "last_ok_at", "last_error", "updated_at" ] } } } }, "401": { "description": "session_required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } }, "put": { "tags": [ "integrations" ], "summary": "Salva (ou troca) o token da UTMify e liga a integração", "description": "O token é cifrado no banco e nunca mais é devolvido; o painel só relê `token_last4`. Salvar liga a integração (`enabled = true`) e limpa o último erro.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 20, "maxLength": 128, "pattern": "^\\S+$" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "integração", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "utmify" ] }, "configured": { "type": "boolean" }, "enabled": { "type": "boolean" }, "token_last4": { "type": [ "string", "null" ] }, "last_ok_at": { "type": [ "string", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "provider", "configured", "enabled", "token_last4", "last_ok_at", "last_error", "updated_at" ] } } } }, "400": { "description": "validation_failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "401": { "description": "session_required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } }, "patch": { "tags": [ "integrations" ], "summary": "Liga ou desliga a integração sem trocar o token", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] } } } }, "responses": { "200": { "description": "integração", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "utmify" ] }, "configured": { "type": "boolean" }, "enabled": { "type": "boolean" }, "token_last4": { "type": [ "string", "null" ] }, "last_ok_at": { "type": [ "string", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "provider", "configured", "enabled", "token_last4", "last_ok_at", "last_error", "updated_at" ] } } } }, "400": { "description": "validation_failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } }, "delete": { "tags": [ "integrations" ], "summary": "Remove a integração (o token some do banco)", "responses": { "204": { "description": "removida" }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/integrations/utmify/test": { "post": { "tags": [ "integrations" ], "summary": "Envia um pedido sintético (`isTest`) para a UTMify e devolve o resultado", "responses": { "200": { "description": "resultado do envio", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status_code": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] } }, "required": [ "ok", "status_code", "error" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/transactions/{id}/timeline": { "get": { "tags": [ "transactions" ], "summary": "Timeline de uma cobrança", "description": "Eventos da própria cobrança, lançamentos de ledger que a referenciam (com o valor no sinal de negócio da conta) e cada tentativa de entrega de webhook, em ordem cronológica. `detail.target_url` sai só com o hostname para o seller.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "timeline", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "type": { "type": "string" }, "detail": { "type": [ "object", "null" ], "additionalProperties": {} } }, "required": [ "at", "type", "detail" ] } } }, "required": [ "data" ] } } } }, "400": { "description": "validation_failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/transactions": { "get": { "tags": [ "transactions" ], "summary": "Lista cobranças do seller da sessão", "description": "Ordenado por `(created_at DESC, id DESC)`. `next_cursor` é nulo quando a página não veio cheia. `q` aceita **um** critério: id público (`txn_…`), email exato ou documento só com dígitos, qualquer outro formato é `400 validation_failed` com `param: \"q\"`. `with_totals=1` acrescenta `totals`: `filtered` (contagem e somas em centavos do subconjunto filtrado, sem paginar) e `by_status` (contagem dos seis status no MESMO recorte, mas ignorando o filtro `status`, é o que alimenta as tabs). Cobrança `expired` nunca aparece: sem `status` na query ela é excluída por padrão, e `status=expired` explícito (sozinho ou em csv) devolve `400 validation_failed`. O `mode` vem do header `X-Mode` (default `live`).", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "enum": [ "0", "1" ] }, "required": false, "name": "with_totals", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "created_from", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "created_to", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "paid_from", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "paid_to", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "q", "in": "query" } ], "responses": { "200": { "description": "página de cobranças", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "transaction" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string" }, "payment_method": { "type": "string" }, "amount": { "type": "integer" }, "fee": { "type": "integer" }, "net": { "type": "integer" }, "reserve": { "type": "integer" }, "reserve_released_at": { "type": [ "string", "null" ] }, "customer": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "document": { "type": "string" }, "phone": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "quantity": { "type": "number" }, "unit_amount": { "type": "number" } } } }, "pix": { "type": "object", "properties": { "payload": { "type": [ "string", "null" ] }, "qr_base64": { "type": [ "string", "null" ] }, "expires_at": { "type": "string" } }, "required": [ "payload", "qr_base64", "expires_at" ] }, "postback_url": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": {} }, "tracking": { "type": [ "object", "null" ], "properties": { "src": { "type": [ "string", "null" ] }, "sck": { "type": [ "string", "null" ] }, "utm_source": { "type": [ "string", "null" ] }, "utm_campaign": { "type": [ "string", "null" ] }, "utm_medium": { "type": [ "string", "null" ] }, "utm_content": { "type": [ "string", "null" ] }, "utm_term": { "type": [ "string", "null" ] } }, "required": [ "src", "sck", "utm_source", "utm_campaign", "utm_medium", "utm_content", "utm_term" ] }, "acquirer": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "slug" ] }, "paid_at": { "type": [ "string", "null" ] }, "expired_at": { "type": [ "string", "null" ] }, "refunded_at": { "type": [ "string", "null" ] }, "chargeback_at": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "mode", "status", "payment_method", "amount", "fee", "net", "reserve", "reserve_released_at", "customer", "items", "pix", "postback_url", "metadata", "acquirer", "paid_at", "expired_at", "refunded_at", "chargeback_at", "failure_reason", "end_to_end_id", "created_at", "updated_at" ] } }, "next_cursor": { "type": [ "string", "null" ] }, "totals": { "type": "object", "properties": { "by_status": { "type": "object", "properties": { "pending": { "type": "integer" }, "paid": { "type": "integer" }, "expired": { "type": "integer" }, "failed": { "type": "integer" }, "refunded": { "type": "integer" }, "chargeback": { "type": "integer" } }, "required": [ "pending", "paid", "expired", "failed", "refunded", "chargeback" ] }, "filtered": { "type": "object", "properties": { "count": { "type": "integer" }, "gross_cents": { "type": "integer" }, "fee_cents": { "type": "integer" }, "net_cents": { "type": "integer" } }, "required": [ "count", "gross_cents", "fee_cents", "net_cents" ] } }, "required": [ "by_status", "filtered" ] } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "validation_failed, invalid_cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "401": { "description": "session_required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } }, "post": { "tags": [ "transactions" ], "summary": "Cria uma cobrança PIX pelo painel (sessão)", "description": "Mesmo corpo e mesma resposta de `POST /v1/transactions`, autenticado por sessão do painel em vez de chave de API (`spec/05` §4.2). O `mode` vem do header `X-Mode` (default `live`) e a loja é a do seller da sessão. Exige `Idempotency-Key` (`^[A-Za-z0-9_\\-:.]{1,255}$`); repetir a mesma key com o mesmo corpo devolve a resposta salva com `Idempotent-Replayed: true`. Em `live` o seller precisa estar `active` com PIX habilitado; em `test` basta não estar `closed`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "integer" }, "payment_method": { "type": "string" }, "customer": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "email": { "type": "string", "maxLength": 254, "format": "email" }, "document": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "name", "email", "document" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 }, "unit_amount": { "type": "integer", "minimum": 0 } }, "required": [ "name", "quantity", "unit_amount" ] }, "maxItems": 50 }, "pix": { "type": "object", "properties": { "expires_in_seconds": { "type": "integer" } } }, "postback_url": { "type": "string", "maxLength": 2048 }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 } }, "description": { "type": "string", "maxLength": 140 }, "tracking": { "type": "object", "properties": { "src": { "type": "string", "maxLength": 255 }, "sck": { "type": "string", "maxLength": 255 }, "utm_source": { "type": "string", "maxLength": 255 }, "utm_campaign": { "type": "string", "maxLength": 255 }, "utm_medium": { "type": "string", "maxLength": 255 }, "utm_content": { "type": "string", "maxLength": 255 }, "utm_term": { "type": "string", "maxLength": 255 } }, "additionalProperties": false } }, "required": [ "amount", "customer" ] } } } }, "responses": { "201": { "description": "cobrança criada", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "transaction" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string" }, "payment_method": { "type": "string" }, "amount": { "type": "integer" }, "fee": { "type": "integer" }, "net": { "type": "integer" }, "reserve": { "type": "integer" }, "reserve_released_at": { "type": [ "string", "null" ] }, "customer": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "document": { "type": "string" }, "phone": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "quantity": { "type": "number" }, "unit_amount": { "type": "number" } } } }, "pix": { "type": "object", "properties": { "payload": { "type": [ "string", "null" ] }, "qr_base64": { "type": [ "string", "null" ] }, "expires_at": { "type": "string" } }, "required": [ "payload", "qr_base64", "expires_at" ] }, "postback_url": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": {} }, "tracking": { "type": [ "object", "null" ], "properties": { "src": { "type": [ "string", "null" ] }, "sck": { "type": [ "string", "null" ] }, "utm_source": { "type": [ "string", "null" ] }, "utm_campaign": { "type": [ "string", "null" ] }, "utm_medium": { "type": [ "string", "null" ] }, "utm_content": { "type": [ "string", "null" ] }, "utm_term": { "type": [ "string", "null" ] } }, "required": [ "src", "sck", "utm_source", "utm_campaign", "utm_medium", "utm_content", "utm_term" ] }, "acquirer": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "slug" ] }, "paid_at": { "type": [ "string", "null" ] }, "expired_at": { "type": [ "string", "null" ] }, "refunded_at": { "type": [ "string", "null" ] }, "chargeback_at": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "mode", "status", "payment_method", "amount", "fee", "net", "reserve", "reserve_released_at", "customer", "items", "pix", "postback_url", "metadata", "acquirer", "paid_at", "expired_at", "refunded_at", "chargeback_at", "failure_reason", "end_to_end_id", "created_at", "updated_at" ] } } } }, "400": { "description": "validation_failed, amount_too_small, amount_too_large, invalid_document, invalid_expires_in, invalid_url, missing_idempotency_key, unsupported_payment_method", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "401": { "description": "session_required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "seller_not_allowed, insufficient_role, terms_not_accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "409": { "description": "idempotency_conflict, idempotency_in_progress", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "502": { "description": "replay de uma row de idempotência anterior a FIX-PIX-LOOKUP", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "503": { "description": "acquirer_timeout, acquirer_rejected, acquirer_unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/transactions/{id}": { "get": { "tags": [ "transactions" ], "summary": "Consulta uma cobrança do seller da sessão", "description": "Além do objeto `transaction`, o detalhe traz `fee_snapshot` (`pix_pct_bps`, `pix_fixed_cents`, `reserve_pct_bps`, `reserve_days` congelados na venda) e `reserve_release_at` (`paid_at + reserve_days`; `null` antes de `paid` e quando não houve reserva).", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "cobrança", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "transaction" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string" }, "payment_method": { "type": "string" }, "amount": { "type": "integer" }, "fee": { "type": "integer" }, "net": { "type": "integer" }, "reserve": { "type": "integer" }, "reserve_released_at": { "type": [ "string", "null" ] }, "customer": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "document": { "type": "string" }, "phone": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "quantity": { "type": "number" }, "unit_amount": { "type": "number" } } } }, "pix": { "type": "object", "properties": { "payload": { "type": [ "string", "null" ] }, "qr_base64": { "type": [ "string", "null" ] }, "expires_at": { "type": "string" } }, "required": [ "payload", "qr_base64", "expires_at" ] }, "postback_url": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": {} }, "tracking": { "type": [ "object", "null" ], "properties": { "src": { "type": [ "string", "null" ] }, "sck": { "type": [ "string", "null" ] }, "utm_source": { "type": [ "string", "null" ] }, "utm_campaign": { "type": [ "string", "null" ] }, "utm_medium": { "type": [ "string", "null" ] }, "utm_content": { "type": [ "string", "null" ] }, "utm_term": { "type": [ "string", "null" ] } }, "required": [ "src", "sck", "utm_source", "utm_campaign", "utm_medium", "utm_content", "utm_term" ] }, "acquirer": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "slug" ] }, "paid_at": { "type": [ "string", "null" ] }, "expired_at": { "type": [ "string", "null" ] }, "refunded_at": { "type": [ "string", "null" ] }, "chargeback_at": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "fee_snapshot": { "type": "object", "properties": { "pix_pct_bps": { "type": "integer", "minimum": 0 }, "pix_fixed_cents": { "type": "integer", "minimum": 0 }, "reserve_pct_bps": { "type": "integer", "minimum": 0 }, "reserve_days": { "type": "integer", "minimum": 0 } }, "required": [ "pix_pct_bps", "pix_fixed_cents", "reserve_pct_bps", "reserve_days" ] }, "reserve_release_at": { "type": [ "string", "null" ] } }, "required": [ "id", "object", "mode", "status", "payment_method", "amount", "fee", "net", "reserve", "reserve_released_at", "customer", "items", "pix", "postback_url", "metadata", "acquirer", "paid_at", "expired_at", "refunded_at", "chargeback_at", "failure_reason", "end_to_end_id", "created_at", "updated_at" ] } } } }, "400": { "description": "validation_failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/transactions/{id}/refund": { "post": { "tags": [ "transactions" ], "summary": "Estorna integralmente uma cobrança paga (sessão)", "description": "Mesmo efeito de `POST /admin/v1/transactions/{id}/refund` (`spec/05` §4.5): total, só em `paid`, ledger e `transaction.refunded` no mesmo commit. Autenticado por sessão do painel, com o mesmo gate de `POST /v1/me/transactions` (`live` exige seller `active` com PIX habilitado; `test` só recusa `closed`) mais step-up de MFA. Exige `Idempotency-Key` (`^[A-Za-z0-9_\\-:.]{1,255}$`): repetir a mesma key devolve a resposta salva com `Idempotent-Replayed: true`. Corpo opcional: sem corpo, `{}` ou `{ \"reason\": \"…\" }` (3..500 chars, vai para o `audit_log`). Cobrança de outro seller ou de outro `mode` é `404`.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 3, "maxLength": 500 } } } } } }, "responses": { "200": { "description": "cobrança estornada", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "transaction" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string" }, "payment_method": { "type": "string" }, "amount": { "type": "integer" }, "fee": { "type": "integer" }, "net": { "type": "integer" }, "reserve": { "type": "integer" }, "reserve_released_at": { "type": [ "string", "null" ] }, "customer": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "document": { "type": "string" }, "phone": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "quantity": { "type": "number" }, "unit_amount": { "type": "number" } } } }, "pix": { "type": "object", "properties": { "payload": { "type": [ "string", "null" ] }, "qr_base64": { "type": [ "string", "null" ] }, "expires_at": { "type": "string" } }, "required": [ "payload", "qr_base64", "expires_at" ] }, "postback_url": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": {} }, "tracking": { "type": [ "object", "null" ], "properties": { "src": { "type": [ "string", "null" ] }, "sck": { "type": [ "string", "null" ] }, "utm_source": { "type": [ "string", "null" ] }, "utm_campaign": { "type": [ "string", "null" ] }, "utm_medium": { "type": [ "string", "null" ] }, "utm_content": { "type": [ "string", "null" ] }, "utm_term": { "type": [ "string", "null" ] } }, "required": [ "src", "sck", "utm_source", "utm_campaign", "utm_medium", "utm_content", "utm_term" ] }, "acquirer": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "slug" ] }, "paid_at": { "type": [ "string", "null" ] }, "expired_at": { "type": [ "string", "null" ] }, "refunded_at": { "type": [ "string", "null" ] }, "chargeback_at": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "fee_snapshot": { "type": "object", "properties": { "pix_pct_bps": { "type": "integer", "minimum": 0 }, "pix_fixed_cents": { "type": "integer", "minimum": 0 }, "reserve_pct_bps": { "type": "integer", "minimum": 0 }, "reserve_days": { "type": "integer", "minimum": 0 } }, "required": [ "pix_pct_bps", "pix_fixed_cents", "reserve_pct_bps", "reserve_days" ] }, "reserve_release_at": { "type": [ "string", "null" ] } }, "required": [ "id", "object", "mode", "status", "payment_method", "amount", "fee", "net", "reserve", "reserve_released_at", "customer", "items", "pix", "postback_url", "metadata", "acquirer", "paid_at", "expired_at", "refunded_at", "chargeback_at", "failure_reason", "end_to_end_id", "created_at", "updated_at" ] } } } }, "400": { "description": "validation_failed, missing_idempotency_key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "401": { "description": "session_required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "mfa_required, seller_not_allowed, insufficient_role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "409": { "description": "invalid_state, não está `paid` ou já há refund em curso; idempotency_conflict, idempotency_in_progress", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "503": { "description": "acquirer_timeout, acquirer_rejected, acquirer_unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/transactions/{id}/timeline": { "get": { "tags": [ "transactions" ], "summary": "Timeline de uma cobrança do seller da sessão", "description": "Eventos da própria cobrança, lançamentos de ledger que a referenciam (com o valor no sinal de negócio da conta) e cada tentativa de entrega de webhook, em ordem cronológica. `detail.target_url` sai só com o hostname para o seller.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "timeline", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "type": { "type": "string" }, "detail": { "type": [ "object", "null" ], "additionalProperties": {} } }, "required": [ "at", "type", "detail" ] } } }, "required": [ "data" ] } } } }, "400": { "description": "validation_failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/withdrawals": { "post": { "tags": [ "withdrawals" ], "summary": "Solicita um saque (exige o header `Idempotency-Key`)", "requestBody": { "required": true, "content": { "application/json": { "example": { "amount": 5000, "pix_key_id": "pk_01j9x5k8p2q3r4s5t6u7v8w9xy", "description": "Saque semanal" }, "schema": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0 }, "pix_key_id": { "type": "string" }, "description": { "type": "string", "maxLength": 140 } }, "required": [ "amount", "pix_key_id" ] } } } }, "responses": { "201": { "description": "saque criado", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "withdrawal" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string", "enum": [ "awaiting", "approved", "rejected", "processing", "successful", "failed", "cancelled" ] }, "amount": { "type": "integer" }, "fee": { "type": "integer" }, "total": { "type": "integer" }, "pix_key": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "cpf", "cnpj", "email", "phone", "evp" ] }, "key": { "type": "string" } }, "required": [ "id", "type", "key" ] }, "description": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "requested_at": { "type": "string", "format": "date-time" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "processing_at": { "type": [ "string", "null" ], "format": "date-time" }, "settled_at": { "type": [ "string", "null" ], "format": "date-time" }, "failed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "mode", "status", "amount", "fee", "total", "pix_key", "description", "end_to_end_id", "failure_reason", "requested_at", "approved_at", "processing_at", "settled_at", "failed_at", "created_at", "updated_at" ] } } } }, "400": { "description": "validation_failed, amount_too_small, missing_idempotency_key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "seller_not_allowed, kyc_required, payout_locked, mfa_required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "409": { "description": "pix_key_not_verified, insufficient_balance, daily_limit_exceeded, invalid_state, idempotency_conflict, idempotency_in_progress", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "503": { "description": "acquirer_unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "withdrawals" ], "summary": "Lista os saques do seller no mode atual", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "awaiting", "approved", "rejected", "processing", "successful", "failed", "cancelled" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "to", "in": "query" } ], "responses": { "200": { "description": "saques", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "withdrawal" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string", "enum": [ "awaiting", "approved", "rejected", "processing", "successful", "failed", "cancelled" ] }, "amount": { "type": "integer" }, "fee": { "type": "integer" }, "total": { "type": "integer" }, "pix_key": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "cpf", "cnpj", "email", "phone", "evp" ] }, "key": { "type": "string" } }, "required": [ "id", "type", "key" ] }, "description": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "requested_at": { "type": "string", "format": "date-time" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "processing_at": { "type": [ "string", "null" ], "format": "date-time" }, "settled_at": { "type": [ "string", "null" ], "format": "date-time" }, "failed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "mode", "status", "amount", "fee", "total", "pix_key", "description", "end_to_end_id", "failure_reason", "requested_at", "approved_at", "processing_at", "settled_at", "failed_at", "created_at", "updated_at" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "validation_failed, invalid_cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/withdrawals": { "post": { "tags": [ "withdrawals" ], "summary": "Solicita um saque pelo painel (step-up de MFA)", "requestBody": { "required": true, "content": { "application/json": { "example": { "amount": 5000, "pix_key_id": "pk_01j9x5k8p2q3r4s5t6u7v8w9xy", "description": "Saque semanal" }, "schema": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0 }, "pix_key_id": { "type": "string" }, "description": { "type": "string", "maxLength": 140 } }, "required": [ "amount", "pix_key_id" ] } } } }, "responses": { "201": { "description": "saque criado", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "withdrawal" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string", "enum": [ "awaiting", "approved", "rejected", "processing", "successful", "failed", "cancelled" ] }, "amount": { "type": "integer" }, "fee": { "type": "integer" }, "total": { "type": "integer" }, "pix_key": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "cpf", "cnpj", "email", "phone", "evp" ] }, "key": { "type": "string" } }, "required": [ "id", "type", "key" ] }, "description": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "requested_at": { "type": "string", "format": "date-time" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "processing_at": { "type": [ "string", "null" ], "format": "date-time" }, "settled_at": { "type": [ "string", "null" ], "format": "date-time" }, "failed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "mode", "status", "amount", "fee", "total", "pix_key", "description", "end_to_end_id", "failure_reason", "requested_at", "approved_at", "processing_at", "settled_at", "failed_at", "created_at", "updated_at" ] } } } }, "400": { "description": "validation_failed, amount_too_small, missing_idempotency_key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "seller_not_allowed, kyc_required, payout_locked, mfa_required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "409": { "description": "pix_key_not_verified, insufficient_balance, daily_limit_exceeded, invalid_state, idempotency_conflict, idempotency_in_progress", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "503": { "description": "acquirer_unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "withdrawals" ], "summary": "Lista os saques do seller no mode atual", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "awaiting", "approved", "rejected", "processing", "successful", "failed", "cancelled" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "to", "in": "query" } ], "responses": { "200": { "description": "saques", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "withdrawal" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string", "enum": [ "awaiting", "approved", "rejected", "processing", "successful", "failed", "cancelled" ] }, "amount": { "type": "integer" }, "fee": { "type": "integer" }, "total": { "type": "integer" }, "pix_key": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "cpf", "cnpj", "email", "phone", "evp" ] }, "key": { "type": "string" } }, "required": [ "id", "type", "key" ] }, "description": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "requested_at": { "type": "string", "format": "date-time" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "processing_at": { "type": [ "string", "null" ], "format": "date-time" }, "settled_at": { "type": [ "string", "null" ], "format": "date-time" }, "failed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "mode", "status", "amount", "fee", "total", "pix_key", "description", "end_to_end_id", "failure_reason", "requested_at", "approved_at", "processing_at", "settled_at", "failed_at", "created_at", "updated_at" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "validation_failed, invalid_cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/withdrawals/{id}": { "get": { "tags": [ "withdrawals" ], "summary": "Consulta um saque", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "saque", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "withdrawal" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string", "enum": [ "awaiting", "approved", "rejected", "processing", "successful", "failed", "cancelled" ] }, "amount": { "type": "integer" }, "fee": { "type": "integer" }, "total": { "type": "integer" }, "pix_key": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "cpf", "cnpj", "email", "phone", "evp" ] }, "key": { "type": "string" } }, "required": [ "id", "type", "key" ] }, "description": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "requested_at": { "type": "string", "format": "date-time" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "processing_at": { "type": [ "string", "null" ], "format": "date-time" }, "settled_at": { "type": [ "string", "null" ], "format": "date-time" }, "failed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "mode", "status", "amount", "fee", "total", "pix_key", "description", "end_to_end_id", "failure_reason", "requested_at", "approved_at", "processing_at", "settled_at", "failed_at", "created_at", "updated_at" ] } } } }, "400": { "description": "validation_failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/withdrawals/{id}": { "get": { "tags": [ "withdrawals" ], "summary": "Consulta um saque", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "saque", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "withdrawal" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string", "enum": [ "awaiting", "approved", "rejected", "processing", "successful", "failed", "cancelled" ] }, "amount": { "type": "integer" }, "fee": { "type": "integer" }, "total": { "type": "integer" }, "pix_key": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "cpf", "cnpj", "email", "phone", "evp" ] }, "key": { "type": "string" } }, "required": [ "id", "type", "key" ] }, "description": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "requested_at": { "type": "string", "format": "date-time" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "processing_at": { "type": [ "string", "null" ], "format": "date-time" }, "settled_at": { "type": [ "string", "null" ], "format": "date-time" }, "failed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "mode", "status", "amount", "fee", "total", "pix_key", "description", "end_to_end_id", "failure_reason", "requested_at", "approved_at", "processing_at", "settled_at", "failed_at", "created_at", "updated_at" ] } } } }, "400": { "description": "validation_failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/withdrawals/{id}/cancel": { "post": { "tags": [ "withdrawals" ], "summary": "Cancela um saque ainda em `awaiting`", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "saque cancelado", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "withdrawal" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string", "enum": [ "awaiting", "approved", "rejected", "processing", "successful", "failed", "cancelled" ] }, "amount": { "type": "integer" }, "fee": { "type": "integer" }, "total": { "type": "integer" }, "pix_key": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "cpf", "cnpj", "email", "phone", "evp" ] }, "key": { "type": "string" } }, "required": [ "id", "type", "key" ] }, "description": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "requested_at": { "type": "string", "format": "date-time" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "processing_at": { "type": [ "string", "null" ], "format": "date-time" }, "settled_at": { "type": [ "string", "null" ], "format": "date-time" }, "failed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "mode", "status", "amount", "fee", "total", "pix_key", "description", "end_to_end_id", "failure_reason", "requested_at", "approved_at", "processing_at", "settled_at", "failed_at", "created_at", "updated_at" ] } } } }, "400": { "description": "validation_failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "mfa_required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "409": { "description": "invalid_state: o saque já saiu de `awaiting`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/withdrawals/{id}/cancel": { "post": { "tags": [ "withdrawals" ], "summary": "Cancela um saque ainda em `awaiting`", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "saque cancelado", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "withdrawal" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string", "enum": [ "awaiting", "approved", "rejected", "processing", "successful", "failed", "cancelled" ] }, "amount": { "type": "integer" }, "fee": { "type": "integer" }, "total": { "type": "integer" }, "pix_key": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "cpf", "cnpj", "email", "phone", "evp" ] }, "key": { "type": "string" } }, "required": [ "id", "type", "key" ] }, "description": { "type": [ "string", "null" ] }, "end_to_end_id": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "requested_at": { "type": "string", "format": "date-time" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "processing_at": { "type": [ "string", "null" ], "format": "date-time" }, "settled_at": { "type": [ "string", "null" ], "format": "date-time" }, "failed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "mode", "status", "amount", "fee", "total", "pix_key", "description", "end_to_end_id", "failure_reason", "requested_at", "approved_at", "processing_at", "settled_at", "failed_at", "created_at", "updated_at" ] } } } }, "400": { "description": "validation_failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "mfa_required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "409": { "description": "invalid_state: o saque já saiu de `awaiting`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/reports/summary": { "get": { "tags": [ "reports" ], "summary": "Faturamento do seller no período (fuso America/Sao_Paulo)", "parameters": [ { "schema": { "type": "string", "enum": [ "today", "yesterday", "7d", "30d", "month", "last_month" ] }, "required": false, "name": "period", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "required": false, "name": "to", "in": "query" } ], "responses": { "200": { "description": "summary do período", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "tz": { "type": "string", "enum": [ "America/Sao_Paulo" ] } }, "required": [ "from", "to", "tz" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "sales": { "type": "object", "properties": { "created_count": { "type": "integer" }, "paid_count": { "type": "integer" }, "expired_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "conversion_pct": { "type": "number" }, "gross_cents": { "type": "integer" }, "fees_cents": { "type": "integer" }, "net_cents": { "type": "integer" }, "reserve_retained_cents": { "type": "integer" }, "avg_ticket_cents": { "type": "integer" }, "median_ticket_cents": { "type": "integer" } }, "required": [ "created_count", "paid_count", "expired_count", "failed_count", "conversion_pct", "gross_cents", "fees_cents", "net_cents", "reserve_retained_cents", "avg_ticket_cents", "median_ticket_cents" ] }, "buckets": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "enum": [ "<50", "50-100", "100-200", "200-500", ">500" ] }, "count": { "type": "integer" } }, "required": [ "label", "count" ] } }, "reserve": { "type": "object", "properties": { "released_cents": { "type": "integer" }, "retained_now_cents": { "type": "integer" } }, "required": [ "released_cents", "retained_now_cents" ] }, "refunds": { "type": "object", "properties": { "count": { "type": "integer" }, "cents": { "type": "integer" } }, "required": [ "count", "cents" ] }, "chargebacks": { "type": "object", "properties": { "count": { "type": "integer" }, "cents": { "type": "integer" }, "fees_cents": { "type": "integer" }, "rate_pct": { "type": "number" } }, "required": [ "count", "cents", "fees_cents", "rate_pct" ] }, "withdrawals": { "type": "object", "properties": { "requested_count": { "type": "integer" }, "requested_cents": { "type": "integer" }, "settled_count": { "type": "integer" }, "settled_cents": { "type": "integer" }, "fees_cents": { "type": "integer" }, "failed_count": { "type": "integer" } }, "required": [ "requested_count", "requested_cents", "settled_count", "settled_cents", "fees_cents", "failed_count" ] }, "balance_now": { "type": "object", "properties": { "available_cents": { "type": "integer" }, "reserve_cents": { "type": "integer" }, "pending_withdraw_cents": { "type": "integer" } }, "required": [ "available_cents", "reserve_cents", "pending_withdraw_cents" ] }, "daily": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "paid_count": { "type": "integer" }, "gross_cents": { "type": "integer" }, "net_cents": { "type": "integer" } }, "required": [ "date", "paid_count", "gross_cents", "net_cents" ] } } }, "required": [ "period", "mode", "sales", "buckets", "reserve", "refunds", "chargebacks", "withdrawals", "balance_now", "daily" ] } } } }, "400": { "description": "`validation_failed`: período > 366 dias, `period` junto de `from`/`to`, data inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/reports/summary": { "get": { "tags": [ "reports" ], "summary": "Faturamento do seller no período, pelo mode da API key", "parameters": [ { "schema": { "type": "string", "enum": [ "today", "yesterday", "7d", "30d", "month", "last_month" ] }, "required": false, "name": "period", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "required": false, "name": "to", "in": "query" } ], "responses": { "200": { "description": "summary do período", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "tz": { "type": "string", "enum": [ "America/Sao_Paulo" ] } }, "required": [ "from", "to", "tz" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "sales": { "type": "object", "properties": { "created_count": { "type": "integer" }, "paid_count": { "type": "integer" }, "expired_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "conversion_pct": { "type": "number" }, "gross_cents": { "type": "integer" }, "fees_cents": { "type": "integer" }, "net_cents": { "type": "integer" }, "reserve_retained_cents": { "type": "integer" }, "avg_ticket_cents": { "type": "integer" }, "median_ticket_cents": { "type": "integer" } }, "required": [ "created_count", "paid_count", "expired_count", "failed_count", "conversion_pct", "gross_cents", "fees_cents", "net_cents", "reserve_retained_cents", "avg_ticket_cents", "median_ticket_cents" ] }, "buckets": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "enum": [ "<50", "50-100", "100-200", "200-500", ">500" ] }, "count": { "type": "integer" } }, "required": [ "label", "count" ] } }, "reserve": { "type": "object", "properties": { "released_cents": { "type": "integer" }, "retained_now_cents": { "type": "integer" } }, "required": [ "released_cents", "retained_now_cents" ] }, "refunds": { "type": "object", "properties": { "count": { "type": "integer" }, "cents": { "type": "integer" } }, "required": [ "count", "cents" ] }, "chargebacks": { "type": "object", "properties": { "count": { "type": "integer" }, "cents": { "type": "integer" }, "fees_cents": { "type": "integer" }, "rate_pct": { "type": "number" } }, "required": [ "count", "cents", "fees_cents", "rate_pct" ] }, "withdrawals": { "type": "object", "properties": { "requested_count": { "type": "integer" }, "requested_cents": { "type": "integer" }, "settled_count": { "type": "integer" }, "settled_cents": { "type": "integer" }, "fees_cents": { "type": "integer" }, "failed_count": { "type": "integer" } }, "required": [ "requested_count", "requested_cents", "settled_count", "settled_cents", "fees_cents", "failed_count" ] }, "balance_now": { "type": "object", "properties": { "available_cents": { "type": "integer" }, "reserve_cents": { "type": "integer" }, "pending_withdraw_cents": { "type": "integer" } }, "required": [ "available_cents", "reserve_cents", "pending_withdraw_cents" ] }, "daily": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "paid_count": { "type": "integer" }, "gross_cents": { "type": "integer" }, "net_cents": { "type": "integer" } }, "required": [ "date", "paid_count", "gross_cents", "net_cents" ] } } }, "required": [ "period", "mode", "sales", "buckets", "reserve", "refunds", "chargebacks", "withdrawals", "balance_now", "daily" ] } } } }, "400": { "description": "`validation_failed`: período > 366 dias, `period` junto de `from`/`to`, data inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/reports/reserve-schedule": { "get": { "tags": [ "reports" ], "summary": "Reserva ainda presa por dia previsto de liberação (`paid_at + reserve_days`)", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "required": false, "name": "to", "in": "query" } ], "responses": { "200": { "description": "reserva ainda presa, por dia previsto de liberação", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "release_cents": { "type": "integer" } }, "required": [ "date", "release_cents" ] } } }, "required": [ "data" ] } } } }, "400": { "description": "`validation_failed`: data inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/ledger": { "get": { "tags": [ "ledger" ], "summary": "Extrato do ledger do seller", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "required": false, "name": "to", "in": "query" }, { "schema": { "type": "string", "enum": [ "transaction.paid", "reserve.released", "withdrawal.requested", "withdrawal.settled", "withdrawal.failed", "transaction.refunded", "transaction.chargeback", "adjustment" ] }, "required": false, "name": "kind", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "página do extrato, mais recente primeiro", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "transaction.paid", "reserve.released", "withdrawal.requested", "withdrawal.settled", "withdrawal.failed", "transaction.refunded", "transaction.chargeback", "adjustment" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "reverses_entry_id": { "type": [ "string", "null" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "reference": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transaction", "withdrawal", "manual" ] }, "id": { "type": [ "string", "null" ] } }, "required": [ "type", "id" ] }, "memo": { "type": [ "string", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "account": { "type": "string", "enum": [ "available", "reserve", "pending_withdraw" ] }, "amount_cents": { "type": "integer" } }, "required": [ "account", "amount_cents" ] } } }, "required": [ "id", "kind", "mode", "reverses_entry_id", "occurred_at", "reference", "memo", "lines" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`validation_failed` (datas) ou `invalid_cursor`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/ledger": { "get": { "tags": [ "ledger" ], "summary": "Extrato do ledger do seller, pelo mode da API key", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "required": false, "name": "to", "in": "query" }, { "schema": { "type": "string", "enum": [ "transaction.paid", "reserve.released", "withdrawal.requested", "withdrawal.settled", "withdrawal.failed", "transaction.refunded", "transaction.chargeback", "adjustment" ] }, "required": false, "name": "kind", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "página do extrato, mais recente primeiro", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "transaction.paid", "reserve.released", "withdrawal.requested", "withdrawal.settled", "withdrawal.failed", "transaction.refunded", "transaction.chargeback", "adjustment" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "reverses_entry_id": { "type": [ "string", "null" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "reference": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transaction", "withdrawal", "manual" ] }, "id": { "type": [ "string", "null" ] } }, "required": [ "type", "id" ] }, "memo": { "type": [ "string", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "account": { "type": "string", "enum": [ "available", "reserve", "pending_withdraw" ] }, "amount_cents": { "type": "integer" } }, "required": [ "account", "amount_cents" ] } } }, "required": [ "id", "kind", "mode", "reverses_entry_id", "occurred_at", "reference", "memo", "lines" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`validation_failed` (datas) ou `invalid_cursor`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/reports/exports": { "post": { "tags": [ "reports" ], "summary": "Pede um export CSV pela API key", "requestBody": { "required": true, "content": { "application/json": { "example": { "kind": "transactions_csv", "from": "2026-09-01", "to": "2026-09-30" }, "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "transactions_csv", "withdrawals_csv", "ledger_csv", "platform_summary_csv" ] }, "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "filters": { "type": "object", "properties": { "status": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 20 } } } }, "required": [ "kind", "from", "to" ] } } } }, "responses": { "202": { "description": "export enfileirado", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "report_export" ] }, "status": { "type": "string", "enum": [ "queued" ] } }, "required": [ "id", "object", "status" ] } } } }, "400": { "description": "validation_failed: período > 366 dias, data inválida, > 500000 linhas", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "insufficient_role: `platform_summary_csv` é export de admin", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "rate_limited: 5 exports por hora; ver `Retry-After`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "reports" ], "summary": "Lista os exports do seller no mode atual", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "exports", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "report_export" ] }, "kind": { "type": "string", "enum": [ "transactions_csv", "withdrawals_csv", "ledger_csv", "platform_summary_csv" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string", "enum": [ "queued", "running", "ready", "failed", "expired" ] }, "period": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "tz": { "type": "string", "enum": [ "America/Sao_Paulo" ] } }, "required": [ "from", "to", "tz" ] }, "row_count": { "type": [ "integer", "null" ] }, "size_bytes": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "download_url": { "type": "string" }, "error": { "type": "string" }, "scope": { "type": [ "object", "null" ], "properties": { "seller_id": { "type": "string" }, "seller_name": { "type": "string" } }, "required": [ "seller_id", "seller_name" ] } }, "required": [ "id", "object", "kind", "mode", "status", "period", "row_count", "size_bytes", "created_at", "expires_at" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "validation_failed, invalid_cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/reports/exports": { "post": { "tags": [ "reports" ], "summary": "Pede um export CSV pelo painel", "requestBody": { "required": true, "content": { "application/json": { "example": { "kind": "transactions_csv", "from": "2026-09-01", "to": "2026-09-30" }, "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "transactions_csv", "withdrawals_csv", "ledger_csv", "platform_summary_csv" ] }, "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "filters": { "type": "object", "properties": { "status": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 20 } } } }, "required": [ "kind", "from", "to" ] } } } }, "responses": { "202": { "description": "export enfileirado", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "report_export" ] }, "status": { "type": "string", "enum": [ "queued" ] } }, "required": [ "id", "object", "status" ] } } } }, "400": { "description": "validation_failed: período > 366 dias, data inválida, > 500000 linhas", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "403": { "description": "insufficient_role: `platform_summary_csv` é export de admin", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "429": { "description": "rate_limited: 5 exports por hora; ver `Retry-After`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } }, "get": { "tags": [ "reports" ], "summary": "Lista os exports do seller no mode atual", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "exports", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "report_export" ] }, "kind": { "type": "string", "enum": [ "transactions_csv", "withdrawals_csv", "ledger_csv", "platform_summary_csv" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string", "enum": [ "queued", "running", "ready", "failed", "expired" ] }, "period": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "tz": { "type": "string", "enum": [ "America/Sao_Paulo" ] } }, "required": [ "from", "to", "tz" ] }, "row_count": { "type": [ "integer", "null" ] }, "size_bytes": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "download_url": { "type": "string" }, "error": { "type": "string" }, "scope": { "type": [ "object", "null" ], "properties": { "seller_id": { "type": "string" }, "seller_name": { "type": "string" } }, "required": [ "seller_id", "seller_name" ] } }, "required": [ "id", "object", "kind", "mode", "status", "period", "row_count", "size_bytes", "created_at", "expires_at" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "validation_failed, invalid_cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/reports/exports/{id}": { "get": { "tags": [ "reports" ], "summary": "Status do export; `download_url` assinada quando `ready` e dentro da validade", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "export", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "report_export" ] }, "kind": { "type": "string", "enum": [ "transactions_csv", "withdrawals_csv", "ledger_csv", "platform_summary_csv" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string", "enum": [ "queued", "running", "ready", "failed", "expired" ] }, "period": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "tz": { "type": "string", "enum": [ "America/Sao_Paulo" ] } }, "required": [ "from", "to", "tz" ] }, "row_count": { "type": [ "integer", "null" ] }, "size_bytes": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "download_url": { "type": "string" }, "error": { "type": "string" }, "scope": { "type": [ "object", "null" ], "properties": { "seller_id": { "type": "string" }, "seller_name": { "type": "string" } }, "required": [ "seller_id", "seller_name" ] } }, "required": [ "id", "object", "kind", "mode", "status", "period", "row_count", "size_bytes", "created_at", "expires_at" ] } } } }, "400": { "description": "validation_failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } }, "/v1/me/reports/exports/{id}": { "get": { "tags": [ "reports" ], "summary": "Status do export; `download_url` assinada quando `ready` e dentro da validade", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "export", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "report_export" ] }, "kind": { "type": "string", "enum": [ "transactions_csv", "withdrawals_csv", "ledger_csv", "platform_summary_csv" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string", "enum": [ "queued", "running", "ready", "failed", "expired" ] }, "period": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-01" }, "tz": { "type": "string", "enum": [ "America/Sao_Paulo" ] } }, "required": [ "from", "to", "tz" ] }, "row_count": { "type": [ "integer", "null" ] }, "size_bytes": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "download_url": { "type": "string" }, "error": { "type": "string" }, "scope": { "type": [ "object", "null" ], "properties": { "seller_id": { "type": "string" }, "seller_name": { "type": "string" } }, "required": [ "seller_id", "seller_name" ] } }, "required": [ "id", "object", "kind", "mode", "status", "period", "row_count", "size_bytes", "created_at", "expires_at" ] } } } }, "400": { "description": "validation_failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } }, "404": { "description": "resource_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "acquirer_error", "internal_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } }, "required": [ "error" ] } } } } } } } }, "webhooks": { "transaction.paid": { "post": { "summary": "Evento entregue ao endpoint do seller (envelope `ARCHITECTURE.md` §12)", "description": "POST assinado no `url` do webhook endpoint (ou no `postback_url` da transação). Responda `2xx` em menos de 10 s; `3xx` conta como falha (`redirect_not_followed`). Verifique a assinatura sobre o **raw body** antes de desserializar e trate o evento de forma idempotente por `X-Event-Id`. Ver `docs/webhooks.md`.", "parameters": [ { "name": "X-Signature", "in": "header", "required": true, "description": "`t=,v1=`, HMAC-SHA256 de `t + \".\" + rawBody` com o secret do endpoint. Durante as 24 h de rotação vêm dois `v1=` (novo e antigo): aceite se qualquer um bater. Rejeite se `|now - t| > 300`.", "schema": { "type": "string" }, "example": "t=1789041871,v1=5f1e..." }, { "name": "X-Event-Id", "in": "header", "required": true, "description": "Id do evento; use para dedupe.", "schema": { "type": "string" }, "example": "evt_01j9x5k8p2q3r4s5t6u7v8w9xy" }, { "name": "X-Event-Type", "in": "header", "required": true, "description": "Tipo do evento (catálogo §12).", "schema": { "type": "string" }, "example": "transaction.paid" }, { "name": "X-Delivery-Id", "in": "header", "required": true, "description": "Id desta tentativa de entrega.", "schema": { "type": "string" }, "example": "whd_01j9x5k8p2q3r4s5t6u7v8w9xy" }, { "name": "X-Attempt", "in": "header", "required": true, "description": "Número da tentativa, de 1 a 6.", "schema": { "type": "string" }, "example": "1" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Igual ao `X-Event-Id`.", "schema": { "type": "string" }, "example": "evt_01j9x5k8p2q3r4s5t6u7v8w9xy" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "object", "type", "mode", "created_at", "data" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "event" }, "type": { "type": "string" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "object" ], "properties": { "object": { "type": "object" } } } } }, "example": { "id": "evt_01j9x5k8p2q3r4s5t6u7v8w9xy", "object": "event", "type": "transaction.paid", "mode": "live", "created_at": "2026-09-10T12:04:31Z", "data": { "object": { "id": "txn_01j9x5k8p2q3r4s5t6u7v8w9xy", "object": "transaction", "mode": "live", "status": "paid", "payment_method": "pix", "amount": 10000, "fee": 699, "net": 9301, "reserve": 930, "reserve_released_at": null, "customer": { "name": "Maria Silva", "email": "maria@exemplo.com", "document": "12345678909", "phone": "+5511999999999" }, "items": [ { "title": "Curso X", "unit_price": 10000, "quantity": 1, "tangible": false } ], "pix": { "payload": "00020126...", "qr_base64": "iVBORw0...", "expires_at": "2026-09-10T13:00:00Z" }, "postback_url": "https://loja.exemplo.com/webhooks/lm", "metadata": { "order_id": "A123" }, "acquirer": null, "paid_at": "2026-09-10T12:04:30Z", "expired_at": null, "refunded_at": null, "chargeback_at": null, "failure_reason": null, "end_to_end_id": "E1234567820260910120430abcdef123", "created_at": "2026-09-10T12:00:00Z", "updated_at": "2026-09-10T12:04:30Z" } } } } } }, "responses": { "200": { "description": "Recebido. Qualquer 2xx encerra a entrega com `success`." } } } } } }