{"openapi":"3.1.0","info":{"title":"LeztyPay API","version":"sha-01d3120"},"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: <type>` + `data: <envelope>`; `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: <cookie de sessão do painel>' \\\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).","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). 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=<unix>,v1=<hex>`, 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`."}}}}}}