{"info":{"title":"PaydWin API pública","description":"Contrato público PaydWin baseado no formato Monetarie. A API anterior /v1 de integração é desativada por padrão. Rotas internas do painel e administração são separadas.\n\nAutentique com `Authorization: ApiKey cli_...:sk_...` ou HTTP Basic com client_id/client_secret. IP/CIDR autorizado é obrigatório, inclusive para GET. Emita credenciais novas no painel. Nunca envie o client_secret ao navegador do seu cliente.\n\nTodos os POSTs usam HMAC v2 exclusivamente. Canonicalize o JSON ordenando recursivamente as chaves de objetos, preservando a ordem dos arrays e os valores das strings, sem espaços extras, UTF-8. Assine o seguinte texto com HMAC-SHA512 usando client_secret (saída hexadecimal):\n```\nv2\\nTIMESTAMP\\nNONCE\\nPOST\\nPATH\\nIDEMPOTENCY_KEY\\nCANONICAL_BODY\n```\nOs separadores são quebras de linha reais. PATH inclui /api/external, sem domínio nem query string. Assine as chaves originais antes de X-Key-Case. Timestamp Unix em segundos ±300; nonce aleatório; identidade de retry estável. Nunca reenvie um POST financeiro ambíguo com nova identidade.\n\nEnvio: centavos (R$ 1,00 = 100). Resposta/webhook: 10.000 unidades/BRL (R$ 1,00 = 10.000). O ledger interno continua em centavos. external_id é opcional, único por cliente/ambiente entre cash-in e cash-out. Não invente end_to_end_id; ele só aparece após confirmação real.\n\nLimite agregado: 90.000 requisições/minuto por IP, exceto saldo. Respeite Retry-After. Sucessos POST são reproduzidos por 24h e marcados X-Idempotent-Replay. A identidade financeira permanece durável além do cache.\n\nWebhooks: payload plano camelCase. Headers X-Uneplus-Event-Type, X-Uneplus-Event-Id, X-Uneplus-Timestamp e X-Uneplus-Signature. Valide HMAC-SHA256(timestamp + \".\" + corpo bruto), com prefixo sha256=, antes de parsear. Timestamp Unix em segundos. Deduplicate pelo Event-Id. Responda 2xx após persistir. Retentativas: 2, 5, 15, 30, 60, 120 e 300s, depois 300s até 72h. HTTP 4xx é permanente, exceto 408/429. User-Agent Uneplus-Webhook/1.0. GETs podem usar X-Key-Case; webhooks sempre camelCase.\n\nRecursos indisponíveis retornam 422 nominal_resource_not_supported identificando a nominal. Sem MED/infrações. Não há simulação de confirmação em produção. Veja exemplos Node.js e Python para assinatura e verificação de callbacks.","version":"2.0.0"},"openapi":"3.1.0","servers":[{"url":"http://localhost:8080","description":"Desenvolvimento local. Selecione o host da sua API para outros ambientes."}],"security":[{"apiKey":[]},{"basicAuth":[]}],"paths":{"/api/external/ping":{"get":{"operationId":"get_ping","summary":"Verificar credenciais","description":"","tags":["Conta"],"parameters":[{"name":"X-Key-Case","in":"header","required":false,"schema":{"type":"string","enum":["snake_case","camelCase"]},"description":"Assine o JSON original antes de normalizar. Webhooks sempre usam camelCase."}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"worked":{"const":true}},"required":["worked"]}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"401":{"description":"Credencial ou assinatura inválida","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthError"},{"$ref":"#/components/schemas/SignatureError"}]}}}},"403":{"description":"Whitelist, ambiente ou permissão negada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Recurso não encontrado neste cliente/ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"409":{"description":"Conflito de identidade ou operação em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"422":{"description":"Regra de negócio ou nominal_resource_not_supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"429":{"description":"Limite de requisições; respeite Retry-After. Não troque a identidade financeira."},"503":{"description":"Indisponibilidade temporária; reconcilie a mesma identidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}}}}},"/api/external/pix/cash-in":{"post":{"operationId":"post_pix_cash-in","summary":"Criar cobrança Pix","description":"Não gera crédito antes da confirmação e disponibilização no ledger. external_id é opcional e compartilhado entre entradas e saídas por cliente e ambiente.\n\nPermissão: `pix:write`.","tags":["Pix"],"parameters":[{"name":"X-Key-Case","in":"header","required":false,"schema":{"type":"string","enum":["snake_case","camelCase"]},"description":"Assine o JSON original antes de normalizar. Webhooks sempre usam camelCase."},{"name":"X-Signature-Version","in":"header","required":true,"schema":{"type":"string","const":"2"},"description":"Apenas v2 é aceito."},{"name":"X-Request-Timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^[0-9]+$"},"description":"Unix seconds, tolerância de ±300 segundos."},{"name":"X-Request-Nonce","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~-]{16,128}$"},"description":"Nonce criptograficamente aleatório. Mesmo nonce só aceita a mesma requisição assinada."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":256},"description":"Mesma identidade em retries. Devolução: 8..180 caracteres [A-Za-z0-9._:-]. Resposta 2xx armazenada por 24h; comando financeiro possui identidade durável."},{"name":"hmac","in":"header","required":true,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{128}$"},"description":"HMAC-SHA512 hexadecimal, chave client_secret. Veja o texto canônico na introdução."}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashInResponse"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"401":{"description":"Credencial ou assinatura inválida","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthError"},{"$ref":"#/components/schemas/SignatureError"}]}}}},"403":{"description":"Whitelist, ambiente ou permissão negada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Recurso não encontrado neste cliente/ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"409":{"description":"Conflito de identidade ou operação em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"422":{"description":"Regra de negócio ou nominal_resource_not_supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"429":{"description":"Limite de requisições; respeite Retry-After. Não troque a identidade financeira."},"503":{"description":"Indisponibilidade temporária; reconcilie a mesma identidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashInRequest"}}}}}},"/api/external/pix/cash-out":{"post":{"operationId":"post_pix_cash-out","summary":"Enviar pagamento Pix","description":"Exatamente um de pix_key ou emv/codigo_copia_cola. Sandbox não permite saída. Após 202 consulte a transação; não envie novamente com outra identidade.\n\nPermissão: `transfer:write`.","tags":["Pix"],"parameters":[{"name":"X-Key-Case","in":"header","required":false,"schema":{"type":"string","enum":["snake_case","camelCase"]},"description":"Assine o JSON original antes de normalizar. Webhooks sempre usam camelCase."},{"name":"X-Signature-Version","in":"header","required":true,"schema":{"type":"string","const":"2"},"description":"Apenas v2 é aceito."},{"name":"X-Request-Timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^[0-9]+$"},"description":"Unix seconds, tolerância de ±300 segundos."},{"name":"X-Request-Nonce","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~-]{16,128}$"},"description":"Nonce criptograficamente aleatório. Mesmo nonce só aceita a mesma requisição assinada."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":256},"description":"Mesma identidade em retries. Devolução: 8..180 caracteres [A-Za-z0-9._:-]. Resposta 2xx armazenada por 24h; comando financeiro possui identidade durável."},{"name":"hmac","in":"header","required":true,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{128}$"},"description":"HMAC-SHA512 hexadecimal, chave client_secret. Veja o texto canônico na introdução."}],"responses":{"200":{"description":"Liquidação já confirmada (final=true)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashOutResponse"}}}},"202":{"description":"Sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashOutResponse"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"401":{"description":"Credencial ou assinatura inválida","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthError"},{"$ref":"#/components/schemas/SignatureError"}]}}}},"403":{"description":"Whitelist, ambiente ou permissão negada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Recurso não encontrado neste cliente/ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"409":{"description":"Conflito de identidade ou operação em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"422":{"description":"Regra de negócio ou nominal_resource_not_supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"429":{"description":"Limite de requisições; respeite Retry-After. Não troque a identidade financeira."},"503":{"description":"Indisponibilidade temporária; reconcilie a mesma identidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashOutRequest"}}}}}},"/api/external/pix/refund":{"post":{"operationId":"post_pix_refund","summary":"Devolver Pix recebido","description":"Uma referência original é obrigatória. Devolução nativa depende da nominal; nunca é convertida em transferência para uma chave. No sandbox há processamento durável no ledger simulado. Valor parcial não pode exceder o saldo restante da transação original.\n\nPermissão: `payment:write`.","tags":["Pix"],"parameters":[{"name":"X-Key-Case","in":"header","required":false,"schema":{"type":"string","enum":["snake_case","camelCase"]},"description":"Assine o JSON original antes de normalizar. Webhooks sempre usam camelCase."},{"name":"X-Signature-Version","in":"header","required":true,"schema":{"type":"string","const":"2"},"description":"Apenas v2 é aceito."},{"name":"X-Request-Timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^[0-9]+$"},"description":"Unix seconds, tolerância de ±300 segundos."},{"name":"X-Request-Nonce","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~-]{16,128}$"},"description":"Nonce criptograficamente aleatório. Mesmo nonce só aceita a mesma requisição assinada."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":256},"description":"Mesma identidade em retries. Devolução: 8..180 caracteres [A-Za-z0-9._:-]. Resposta 2xx armazenada por 24h; comando financeiro possui identidade durável."},{"name":"hmac","in":"header","required":true,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{128}$"},"description":"HMAC-SHA512 hexadecimal, chave client_secret. Veja o texto canônico na introdução."}],"responses":{"202":{"description":"Sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundAccepted"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"401":{"description":"Credencial ou assinatura inválida","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthError"},{"$ref":"#/components/schemas/SignatureError"}]}}}},"403":{"description":"Whitelist, ambiente ou permissão negada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Recurso não encontrado neste cliente/ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"409":{"description":"Conflito de identidade ou operação em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"422":{"description":"Regra de negócio ou nominal_resource_not_supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"429":{"description":"Limite de requisições; respeite Retry-After. Não troque a identidade financeira."},"503":{"description":"Indisponibilidade temporária; reconcilie a mesma identidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundRequest"}}}}}},"/api/external/pix/refund/{id}":{"get":{"operationId":"get_pix_refund_id","summary":"Consultar devolução","description":"\n\nPermissão: `transfer:read`.","tags":["Pix"],"parameters":[{"name":"X-Key-Case","in":"header","required":false,"schema":{"type":"string","enum":["snake_case","camelCase"]},"description":"Assine o JSON original antes de normalizar. Webhooks sempre usam camelCase."},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"worked":{"const":true},"data":{"$ref":"#/components/schemas/RefundDetail"}}}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"401":{"description":"Credencial ou assinatura inválida","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthError"},{"$ref":"#/components/schemas/SignatureError"}]}}}},"403":{"description":"Whitelist, ambiente ou permissão negada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Recurso não encontrado neste cliente/ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"409":{"description":"Conflito de identidade ou operação em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"422":{"description":"Regra de negócio ou nominal_resource_not_supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"429":{"description":"Limite de requisições; respeite Retry-After. Não troque a identidade financeira."},"503":{"description":"Indisponibilidade temporária; reconcilie a mesma identidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}}}}},"/api/external/balance":{"get":{"operationId":"get_balance","summary":"Consultar saldo","description":"pending representa reservas de saída. Recebimentos não disponibilizados não aumentam available.\n\nPermissão: `account:read`.","tags":["Conta"],"parameters":[{"name":"X-Key-Case","in":"header","required":false,"schema":{"type":"string","enum":["snake_case","camelCase"]},"description":"Assine o JSON original antes de normalizar. Webhooks sempre usam camelCase."}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"401":{"description":"Credencial ou assinatura inválida","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthError"},{"$ref":"#/components/schemas/SignatureError"}]}}}},"403":{"description":"Whitelist, ambiente ou permissão negada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Recurso não encontrado neste cliente/ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"409":{"description":"Conflito de identidade ou operação em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"422":{"description":"Regra de negócio ou nominal_resource_not_supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"429":{"description":"Limite de requisições; respeite Retry-After. Não troque a identidade financeira."},"503":{"description":"Indisponibilidade temporária; reconcilie a mesma identidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}}}}},"/api/external/transactions":{"get":{"operationId":"get_transactions","summary":"Consultar transações","description":"Janela padrão 7 dias, máxima 180 dias. Paginação até 10.000 registros. Datas YYYY-MM-DD ou ISO 8601 UTC.\n\nPermissão: `transfer:read`.","tags":["Conta"],"parameters":[{"name":"X-Key-Case","in":"header","required":false,"schema":{"type":"string","enum":["snake_case","camelCase"]},"description":"Assine o JSON original antes de normalizar. Webhooks sempre usam camelCase."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1,"maximum":100,"default":20}},{"name":"date_from","in":"query","required":false,"schema":{"type":"string"}},{"name":"date_to","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["settled","processing","failed","rejected"]}},{"name":"type","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionPage"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"401":{"description":"Credencial ou assinatura inválida","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthError"},{"$ref":"#/components/schemas/SignatureError"}]}}}},"403":{"description":"Whitelist, ambiente ou permissão negada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Recurso não encontrado neste cliente/ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"409":{"description":"Conflito de identidade ou operação em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"422":{"description":"Regra de negócio ou nominal_resource_not_supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"429":{"description":"Limite de requisições; respeite Retry-After. Não troque a identidade financeira."},"503":{"description":"Indisponibilidade temporária; reconcilie a mesma identidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}}}}},"/api/external/statement":{"get":{"operationId":"get_statement","summary":"Consultar extrato","description":"Janela padrão 7 dias, máxima 180 dias. Paginação até 10.000 registros. Datas YYYY-MM-DD ou ISO 8601 UTC.\n\nPermissão: `statement:read`.","tags":["Conta"],"parameters":[{"name":"X-Key-Case","in":"header","required":false,"schema":{"type":"string","enum":["snake_case","camelCase"]},"description":"Assine o JSON original antes de normalizar. Webhooks sempre usam camelCase."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1,"maximum":100,"default":20}},{"name":"date_from","in":"query","required":false,"schema":{"type":"string"}},{"name":"date_to","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["settled","processing","failed","rejected"]}},{"name":"type","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionPage"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"401":{"description":"Credencial ou assinatura inválida","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthError"},{"$ref":"#/components/schemas/SignatureError"}]}}}},"403":{"description":"Whitelist, ambiente ou permissão negada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Recurso não encontrado neste cliente/ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"409":{"description":"Conflito de identidade ou operação em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"422":{"description":"Regra de negócio ou nominal_resource_not_supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"429":{"description":"Limite de requisições; respeite Retry-After. Não troque a identidade financeira."},"503":{"description":"Indisponibilidade temporária; reconcilie a mesma identidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}}}}},"/api/external/transactions/{id}":{"get":{"operationId":"get_transactions_id","summary":"Consultar transação","description":"\n\nPermissão: `transfer:read`.","tags":["Conta"],"parameters":[{"name":"X-Key-Case","in":"header","required":false,"schema":{"type":"string","enum":["snake_case","camelCase"]},"description":"Assine o JSON original antes de normalizar. Webhooks sempre usam camelCase."},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionResult"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"401":{"description":"Credencial ou assinatura inválida","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthError"},{"$ref":"#/components/schemas/SignatureError"}]}}}},"403":{"description":"Whitelist, ambiente ou permissão negada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Recurso não encontrado neste cliente/ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"409":{"description":"Conflito de identidade ou operação em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"422":{"description":"Regra de negócio ou nominal_resource_not_supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"429":{"description":"Limite de requisições; respeite Retry-After. Não troque a identidade financeira."},"503":{"description":"Indisponibilidade temporária; reconcilie a mesma identidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}}}}},"/api/external/transactions/e2e/{id}":{"get":{"operationId":"get_transactions_e2e_id","summary":"Consultar por end-to-end","description":"\n\nPermissão: `transfer:read`.","tags":["Conta"],"parameters":[{"name":"X-Key-Case","in":"header","required":false,"schema":{"type":"string","enum":["snake_case","camelCase"]},"description":"Assine o JSON original antes de normalizar. Webhooks sempre usam camelCase."},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionResult"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"401":{"description":"Credencial ou assinatura inválida","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthError"},{"$ref":"#/components/schemas/SignatureError"}]}}}},"403":{"description":"Whitelist, ambiente ou permissão negada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Recurso não encontrado neste cliente/ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"409":{"description":"Conflito de identidade ou operação em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"422":{"description":"Regra de negócio ou nominal_resource_not_supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"429":{"description":"Limite de requisições; respeite Retry-After. Não troque a identidade financeira."},"503":{"description":"Indisponibilidade temporária; reconcilie a mesma identidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}}}}},"/api/external/transactions/ref/{id}":{"get":{"operationId":"get_transactions_ref_id","summary":"Consultar por external_id","description":"\n\nPermissão: `transfer:read`.","tags":["Conta"],"parameters":[{"name":"X-Key-Case","in":"header","required":false,"schema":{"type":"string","enum":["snake_case","camelCase"]},"description":"Assine o JSON original antes de normalizar. Webhooks sempre usam camelCase."},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionResult"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"401":{"description":"Credencial ou assinatura inválida","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthError"},{"$ref":"#/components/schemas/SignatureError"}]}}}},"403":{"description":"Whitelist, ambiente ou permissão negada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Recurso não encontrado neste cliente/ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"409":{"description":"Conflito de identidade ou operação em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"422":{"description":"Regra de negócio ou nominal_resource_not_supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"429":{"description":"Limite de requisições; respeite Retry-After. Não troque a identidade financeira."},"503":{"description":"Indisponibilidade temporária; reconcilie a mesma identidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}}}}},"/api/external/transactions/tag/{tag}":{"get":{"operationId":"get_transactions_tag_tag","summary":"Consultar prefixo do identificador","description":"Até 50 transações em estado terminal com o prefixo informado.\n\nPermissão: `transfer:read`.","tags":["Conta"],"parameters":[{"name":"X-Key-Case","in":"header","required":false,"schema":{"type":"string","enum":["snake_case","camelCase"]},"description":"Assine o JSON original antes de normalizar. Webhooks sempre usam camelCase."},{"name":"tag","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"worked":{"const":true},"data":{"type":"array","maxItems":50,"items":{"oneOf":[{"$ref":"#/components/schemas/Transaction"},{"$ref":"#/components/schemas/ProcessingTransaction"},{"$ref":"#/components/schemas/FailedTransaction"}]}}}}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"401":{"description":"Credencial ou assinatura inválida","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthError"},{"$ref":"#/components/schemas/SignatureError"}]}}}},"403":{"description":"Whitelist, ambiente ou permissão negada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Recurso não encontrado neste cliente/ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"409":{"description":"Conflito de identidade ou operação em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"422":{"description":"Regra de negócio ou nominal_resource_not_supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"429":{"description":"Limite de requisições; respeite Retry-After. Não troque a identidade financeira."},"503":{"description":"Indisponibilidade temporária; reconcilie a mesma identidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}}}}},"/api/external/transactions/{id}/receipt":{"get":{"operationId":"get_transactions_id_receipt","summary":"Obter comprovante","description":"Disponível após estado terminal. Dados desconhecidos permanecem null.\n\nPermissão: `transfer:read`.","tags":["Conta"],"parameters":[{"name":"X-Key-Case","in":"header","required":false,"schema":{"type":"string","enum":["snake_case","camelCase"]},"description":"Assine o JSON original antes de normalizar. Webhooks sempre usam camelCase."},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"worked":{"const":true},"receipt":{"$ref":"#/components/schemas/Receipt"}}}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"401":{"description":"Credencial ou assinatura inválida","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthError"},{"$ref":"#/components/schemas/SignatureError"}]}}}},"403":{"description":"Whitelist, ambiente ou permissão negada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Recurso não encontrado neste cliente/ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"409":{"description":"Conflito de identidade ou operação em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"422":{"description":"Regra de negócio ou nominal_resource_not_supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"429":{"description":"Limite de requisições; respeite Retry-After. Não troque a identidade financeira."},"503":{"description":"Indisponibilidade temporária; reconcilie a mesma identidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}}}}},"/api/external/pix/keys":{"get":{"operationId":"get_pix_keys","summary":"Listar chaves Pix","description":"Exige listagem real de chaves pela nominal; indisponibilidade retorna 422 e identifica a nominal.\n\nPermissão: `pix:read`.","tags":["Pix"],"parameters":[{"name":"X-Key-Case","in":"header","required":false,"schema":{"type":"string","enum":["snake_case","camelCase"]},"description":"Assine o JSON original antes de normalizar. Webhooks sempre usam camelCase."}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"worked":{"const":true},"keys":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"created_at":{"type":["string","null"]},"key_type":{"type":"string"},"status":{"type":"string"}}}}}}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"401":{"description":"Credencial ou assinatura inválida","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthError"},{"$ref":"#/components/schemas/SignatureError"}]}}}},"403":{"description":"Whitelist, ambiente ou permissão negada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Recurso não encontrado neste cliente/ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"409":{"description":"Conflito de identidade ou operação em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"422":{"description":"Regra de negócio ou nominal_resource_not_supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"429":{"description":"Limite de requisições; respeite Retry-After. Não troque a identidade financeira."},"503":{"description":"Indisponibilidade temporária; reconcilie a mesma identidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}}}}},"/api/external/cpf/validate":{"post":{"operationId":"post_cpf_validate","summary":"Validar CPF","description":"\n\nPermissão: `account:read`.","tags":["Conta"],"parameters":[{"name":"X-Key-Case","in":"header","required":false,"schema":{"type":"string","enum":["snake_case","camelCase"]},"description":"Assine o JSON original antes de normalizar. Webhooks sempre usam camelCase."},{"name":"X-Signature-Version","in":"header","required":true,"schema":{"type":"string","const":"2"},"description":"Apenas v2 é aceito."},{"name":"X-Request-Timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^[0-9]+$"},"description":"Unix seconds, tolerância de ±300 segundos."},{"name":"X-Request-Nonce","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~-]{16,128}$"},"description":"Nonce criptograficamente aleatório. Mesmo nonce só aceita a mesma requisição assinada."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":256},"description":"Mesma identidade em retries. Devolução: 8..180 caracteres [A-Za-z0-9._:-]. Resposta 2xx armazenada por 24h; comando financeiro possui identidade durável."},{"name":"hmac","in":"header","required":true,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{128}$"},"description":"HMAC-SHA512 hexadecimal, chave client_secret. Veja o texto canônico na introdução."}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"worked":{"const":true},"valid":{"type":"boolean"},"formatted":{"type":"string"},"detail":{"type":"string"}}}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"401":{"description":"Credencial ou assinatura inválida","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthError"},{"$ref":"#/components/schemas/SignatureError"}]}}}},"403":{"description":"Whitelist, ambiente ou permissão negada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Recurso não encontrado neste cliente/ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"409":{"description":"Conflito de identidade ou operação em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"422":{"description":"Regra de negócio ou nominal_resource_not_supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"429":{"description":"Limite de requisições; respeite Retry-After. Não troque a identidade financeira."},"503":{"description":"Indisponibilidade temporária; reconcilie a mesma identidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CpfRequest"}}}}}},"/api/external/webhooks/events":{"get":{"operationId":"get_webhooks_events","summary":"Listar eventos aceitos","description":"pix.charge.cancelled e estados queued/held são reservados. MED/infrações não fazem parte deste contrato. pix.return.received é alias de pix.payout.returned.\n\nPermissão: `account:read`.","tags":["Webhooks"],"parameters":[{"name":"X-Key-Case","in":"header","required":false,"schema":{"type":"string","enum":["snake_case","camelCase"]},"description":"Assine o JSON original antes de normalizar. Webhooks sempre usam camelCase."}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"worked":{"const":true},"events":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"401":{"description":"Credencial ou assinatura inválida","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthError"},{"$ref":"#/components/schemas/SignatureError"}]}}}},"403":{"description":"Whitelist, ambiente ou permissão negada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Recurso não encontrado neste cliente/ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"409":{"description":"Conflito de identidade ou operação em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"422":{"description":"Regra de negócio ou nominal_resource_not_supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"429":{"description":"Limite de requisições; respeite Retry-After. Não troque a identidade financeira."},"503":{"description":"Indisponibilidade temporária; reconcilie a mesma identidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}}}}},"/api/external/webhooks":{"get":{"operationId":"get_webhooks","summary":"Listar webhooks","description":"A lista inclui o segredo. Não exponha esta resposta em logs.\n\nPermissão: `account:read`.","tags":["Webhooks"],"parameters":[{"name":"X-Key-Case","in":"header","required":false,"schema":{"type":"string","enum":["snake_case","camelCase"]},"description":"Assine o JSON original antes de normalizar. Webhooks sempre usam camelCase."}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"401":{"description":"Credencial ou assinatura inválida","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthError"},{"$ref":"#/components/schemas/SignatureError"}]}}}},"403":{"description":"Whitelist, ambiente ou permissão negada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Recurso não encontrado neste cliente/ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"409":{"description":"Conflito de identidade ou operação em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"422":{"description":"Regra de negócio ou nominal_resource_not_supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"429":{"description":"Limite de requisições; respeite Retry-After. Não troque a identidade financeira."},"503":{"description":"Indisponibilidade temporária; reconcilie a mesma identidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}}}},"post":{"operationId":"post_webhooks","summary":"Cadastrar webhook","description":"Eventos em camelCase no payload, valores em unidades de 1/10.000 BRL. O segredo é gerado quando omitido.\n\nPermissão: `account:write`.","tags":["Webhooks"],"parameters":[{"name":"X-Key-Case","in":"header","required":false,"schema":{"type":"string","enum":["snake_case","camelCase"]},"description":"Assine o JSON original antes de normalizar. Webhooks sempre usam camelCase."},{"name":"X-Signature-Version","in":"header","required":true,"schema":{"type":"string","const":"2"},"description":"Apenas v2 é aceito."},{"name":"X-Request-Timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^[0-9]+$"},"description":"Unix seconds, tolerância de ±300 segundos."},{"name":"X-Request-Nonce","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~-]{16,128}$"},"description":"Nonce criptograficamente aleatório. Mesmo nonce só aceita a mesma requisição assinada."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":256},"description":"Mesma identidade em retries. Devolução: 8..180 caracteres [A-Za-z0-9._:-]. Resposta 2xx armazenada por 24h; comando financeiro possui identidade durável."},{"name":"hmac","in":"header","required":true,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{128}$"},"description":"HMAC-SHA512 hexadecimal, chave client_secret. Veja o texto canônico na introdução."}],"responses":{"201":{"description":"Sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreated"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"401":{"description":"Credencial ou assinatura inválida","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthError"},{"$ref":"#/components/schemas/SignatureError"}]}}}},"403":{"description":"Whitelist, ambiente ou permissão negada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Recurso não encontrado neste cliente/ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"409":{"description":"Conflito de identidade ou operação em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"422":{"description":"Regra de negócio ou nominal_resource_not_supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"429":{"description":"Limite de requisições; respeite Retry-After. Não troque a identidade financeira."},"503":{"description":"Indisponibilidade temporária; reconcilie a mesma identidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRequest"}}}}}},"/api/external/webhooks/{id}":{"delete":{"operationId":"delete_webhooks_id","summary":"Excluir webhook","description":"Primeira exclusão retorna 204 sem corpo; as seguintes retornam 404.\n\nPermissão: `account:write`.","tags":["Webhooks"],"parameters":[{"name":"X-Key-Case","in":"header","required":false,"schema":{"type":"string","enum":["snake_case","camelCase"]},"description":"Assine o JSON original antes de normalizar. Webhooks sempre usam camelCase."},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Excluído. Corpo vazio."},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"401":{"description":"Credencial ou assinatura inválida","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthError"},{"$ref":"#/components/schemas/SignatureError"}]}}}},"403":{"description":"Whitelist, ambiente ou permissão negada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Recurso não encontrado neste cliente/ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"409":{"description":"Conflito de identidade ou operação em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"422":{"description":"Regra de negócio ou nominal_resource_not_supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"429":{"description":"Limite de requisições; respeite Retry-After. Não troque a identidade financeira."},"503":{"description":"Indisponibilidade temporária; reconcilie a mesma identidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}}}}},"/health":{"get":{"operationId":"health","summary":"Saúde do serviço","tags":["Conta"],"security":[],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"ok"}}}}}}}}},"/api/external/acquirers":{"get":{"operationId":"list_acquirers","summary":"Listar adquirentes","description":"Adquirentes (nominais) liberados para a conta, com horário e se aceitam cobranças agora. Fora do horário, cobranças novas vão para outro adquirente liberado; QR já emitidos continuam sendo pagos.\n\nPermissão: `account:read`.","tags":["Conta"],"parameters":[{"name":"X-Key-Case","in":"header","required":false,"schema":{"type":"string","enum":["snake_case","camelCase"]},"description":"Assine o JSON original antes de normalizar. Webhooks sempre usam camelCase."}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcquirerList"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"401":{"description":"Credencial ou assinatura inválida","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthError"},{"$ref":"#/components/schemas/SignatureError"}]}}}},"403":{"description":"Whitelist, ambiente ou permissão negada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Recurso não encontrado neste cliente/ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"409":{"description":"Conflito de identidade ou operação em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"422":{"description":"Regra de negócio ou nominal_resource_not_supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"429":{"description":"Limite de requisições; respeite Retry-After. Não troque a identidade financeira."},"503":{"description":"Indisponibilidade temporária; reconcilie a mesma identidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}}}}},"/api/external/acquirers/default":{"post":{"operationId":"set_default_acquirer","summary":"Trocar adquirente padrão","description":"Define o adquirente padrão de produção. Só é aceito um adquirente disponível agora (422 `acquirer_unavailable` fora do horário). Sandbox não tem padrão. Gera o webhook `acquirer.updated`.\n\nPermissão: `account:write`.","tags":["Conta"],"parameters":[{"name":"X-Key-Case","in":"header","required":false,"schema":{"type":"string","enum":["snake_case","camelCase"]},"description":"Assine o JSON original antes de normalizar. Webhooks sempre usam camelCase."},{"name":"X-Signature-Version","in":"header","required":true,"schema":{"type":"string","const":"2"},"description":"Apenas v2 é aceito."},{"name":"X-Request-Timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^[0-9]+$"},"description":"Unix seconds, tolerância de ±300 segundos."},{"name":"X-Request-Nonce","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._~-]{16,128}$"},"description":"Nonce criptograficamente aleatório. Mesmo nonce só aceita a mesma requisição assinada."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":256},"description":"Mesma identidade em retries. Devolução: 8..180 caracteres [A-Za-z0-9._:-]. Resposta 2xx armazenada por 24h; comando financeiro possui identidade durável."},{"name":"hmac","in":"header","required":true,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{128}$"},"description":"HMAC-SHA512 hexadecimal, chave client_secret. Veja o texto canônico na introdução."}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acquirer"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"401":{"description":"Credencial ou assinatura inválida","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthError"},{"$ref":"#/components/schemas/SignatureError"}]}}}},"403":{"description":"Whitelist, ambiente ou permissão negada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Recurso não encontrado neste cliente/ambiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"409":{"description":"Conflito de identidade ou operação em processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"422":{"description":"Regra de negócio ou nominal_resource_not_supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}},"429":{"description":"Limite de requisições; respeite Retry-After. Não troque a identidade financeira."},"503":{"description":"Indisponibilidade temporária; reconcilie a mesma identidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetDefaultAcquirer"}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"ApiKey client_id:client_secret"},"basicAuth":{"type":"http","scheme":"basic"}},"schemas":{"CashInRequest":{"type":"object","properties":{"amount":{"type":"integer","format":"int64","description":"Centavos de BRL. 100 = R$ 1,00.","minimum":1},"external_id":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"},"description":{"type":"string","maxLength":140},"expiration_seconds":{"type":"integer","format":"int64","minimum":3,"maximum":86400,"default":900},"include_image":{"type":"boolean","default":true},"expected_payer_document":{"type":"string","description":"CPF/CNPJ. Exige capacidade EXPECTED_PAYER da nominal; caso contrário 422."},"pix_key":{"type":"string","description":"Chave de recebimento específica. Retorna 422 quando não suportada pela nominal."},"city":{"type":"string","description":"Cidade no QR. Seleção não suportada retorna 422."}},"required":["amount"],"example":{"amount":10000,"external_id":"order-123","description":"Pedido 123","include_image":false}},"CashInResponse":{"type":"object","properties":{"worked":{"const":true},"transaction_id":{"type":"string","description":"txId do QR. A transação liquidada pode ter outro identificador; consulte por external_id."},"qr_code":{"type":"string"},"qr_code_image":{"type":"string","description":"Data URL PNG; vazio se include_image=false."},"external_id":{"type":["string","null"]},"amount":{"type":"integer","format":"int64","description":"Unidades de 1/10.000 BRL. 10.000 = R$ 1,00.","minimum":0},"status":{"const":"active"},"type":{"const":"dynamic"},"location_url":{"type":["string","null"]},"expires_at":{"type":["string","null"]}},"required":["worked","transaction_id","qr_code","qr_code_image","external_id","amount","status","type","location_url","expires_at"]},"CashOutRequest":{"type":"object","properties":{"amount":{"type":"integer","format":"int64","description":"Centavos de BRL. 100 = R$ 1,00.","minimum":1},"pix_key":{"type":"string"},"pix_key_type":{"type":"string"},"emv":{"type":"string","description":"EMV estático com CRC válido. QR dinâmico retorna 422 se não suportado."},"codigo_copia_cola":{"type":"string","description":"Alias de emv."},"external_id":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,128}$"},"description":{"type":"string","maxLength":140},"purpose":{"type":"string","description":"Finalidade sujeita à capacidade da nominal."},"recipient_document":{"type":"string","description":"Controle indisponível: presença retorna 422."},"recipient_ispb":{"type":"string","description":"Roteamento explícito sujeito à capacidade da nominal."},"end_to_end_id":{"type":"string","description":"Roteamento explícito sujeito à capacidade da nominal."}},"required":["amount"],"example":{"amount":3000,"pix_key":"recebedor@example.com","external_id":"payment-123","description":"Pedido 123"}},"CashOutResponse":{"type":"object","properties":{"worked":{"const":true},"final":{"type":"boolean"},"transaction_id":{"type":"string"},"end_to_end_id":{"type":["string","null"]},"external_id":{"type":["string","null"]},"amount":{"type":"integer","format":"int64","description":"Unidades de 1/10.000 BRL. 10.000 = R$ 1,00.","minimum":0},"fee_amount":{"type":"integer","format":"int64","description":"Unidades de 1/10.000 BRL. 10.000 = R$ 1,00.","minimum":0},"net_amount":{"type":"integer","format":"int64","description":"Unidades de 1/10.000 BRL. 10.000 = R$ 1,00.","minimum":0},"status":{"type":"string","enum":["accepted","settled"]},"detail":{"type":"string"}},"required":["worked","final","transaction_id","end_to_end_id","external_id","amount","fee_amount","net_amount","status","detail"]},"RefundRequest":{"type":"object","properties":{"original_transaction_id":{"type":"string"},"original_e2e_id":{"type":"string"},"transaction_id":{"type":"string"},"end_to_end_id":{"type":"string"},"amount":{"type":"integer","format":"int64","description":"Centavos de BRL. 100 = R$ 1,00.","minimum":1},"reason":{"type":"string","enum":["BE08","FR01","MD06","SL02"],"default":"MD06"},"return_code":{"type":"string","enum":["BE08","FR01","MD06","SL02"]},"description":{"type":"string","maxLength":140}},"example":{"original_transaction_id":"PIXIN_id_da_transacao_original","amount":1000,"reason":"MD06"}},"RefundAccepted":{"type":"object","properties":{"worked":{"const":true},"transaction_id":{"type":"string"},"end_to_end_id":{"type":["string","null"]},"original_end_to_end_id":{"type":["string","null"]},"amount":{"type":"integer","format":"int64","description":"Unidades de 1/10.000 BRL. 10.000 = R$ 1,00.","minimum":0},"status":{"const":"held"},"detail":{"type":"string"}},"required":["worked","transaction_id","status","amount"]},"RefundDetail":{"type":"object","properties":{"transaction_id":{"type":"string"},"refund_transaction_id":{"type":"string"},"refund_end_to_end_id":{"type":["string","null"]},"return_id":{"type":["string","null"]},"original_transaction_id":{"type":"string"},"original_end_to_end_id":{"type":["string","null"]},"external_id":{"type":["string","null"]},"original_external_id":{"type":["string","null"]},"amount":{"type":"integer","format":"int64","description":"Unidades de 1/10.000 BRL. 10.000 = R$ 1,00.","minimum":0},"status":{"type":"string","enum":["held","processing","reconciling","settled","failed","quarantined"]},"reason_code":{"type":"string"},"reason_description":{"type":["string","null"]},"requested_at":{"type":"string"},"completed_at":{"type":["string","null"]},"original_payer":{"type":["object","null"]},"original_recipient":{"type":["object","null"]}}},"Balance":{"type":"object","properties":{"worked":{"const":true},"balance":{"type":"integer","format":"int64","description":"Unidades de 1/10.000 BRL. 10.000 = R$ 1,00.","minimum":0},"available":{"type":"integer","format":"int64","description":"Unidades de 1/10.000 BRL. 10.000 = R$ 1,00.","minimum":0},"pending":{"type":"integer","format":"int64","description":"Unidades de 1/10.000 BRL. 10.000 = R$ 1,00.","minimum":0},"currency":{"const":"BRL"}},"required":["worked","balance","available","pending","currency"]},"Transaction":{"type":"object","properties":{"id":{"type":"string"},"transaction_id":{"type":"string"},"end_to_end_id":{"type":["string","null"]},"external_id":{"type":["string","null"]},"type":{"type":"string","enum":["pix","pix_qrcode","tef","fee"]},"direction":{"type":"string","enum":["credit","inbound","outbound"]},"status":{"type":"string","enum":["pending","processing","settled","failed","expired"]},"amount":{"type":"integer","format":"int64","description":"Unidades de 1/10.000 BRL. 10.000 = R$ 1,00.","minimum":0},"fee_amount":{"type":"integer","format":"int64","description":"Unidades de 1/10.000 BRL. 10.000 = R$ 1,00.","minimum":0},"net_amount":{"type":"integer","format":"int64","description":"Unidades de 1/10.000 BRL. 10.000 = R$ 1,00.","minimum":0},"description":{"type":"string"},"counterparty_name":{"type":["string","null"]},"recipient_key":{"type":["string","null"]},"payer_document":{"type":["string","null"]},"recipient_document":{"type":["string","null"]},"payer_ispb":{"type":["string","null"]},"payer_bank_name":{"type":["string","null"]},"created_at":{"type":"string"},"completed_at":{"type":["string","null"]}}},"ProcessingTransaction":{"type":"object","properties":{"status":{"const":"processing"},"transaction_id":{"type":"string"},"end_to_end_id":{"type":["string","null"]},"amount":{"type":"integer","format":"int64","description":"Unidades de 1/10.000 BRL. 10.000 = R$ 1,00.","minimum":0},"fee_amount":{"type":"integer","format":"int64","description":"Unidades de 1/10.000 BRL. 10.000 = R$ 1,00.","minimum":0},"external_id":{"type":["string","null"]},"type":{"const":"pix"},"direction":{"const":"outbound"},"payment_status":{"type":"string"},"description":{"type":"string"},"started_at":{"type":"string"},"recipient":{"type":"object","properties":{"name":{"type":["string","null"]},"key":{"type":["string","null"]},"key_type":{"type":["string","null"]}}},"net_amount":{"type":"integer","format":"int64","description":"Unidades de 1/10.000 BRL. 10.000 = R$ 1,00.","minimum":0},"pix_key":{"type":["string","null"]}}},"FailedTransaction":{"type":"object","properties":{"status":{"const":"failed"},"transaction_id":{"type":"string"},"end_to_end_id":{"type":["string","null"]},"amount":{"type":"integer","format":"int64","description":"Unidades de 1/10.000 BRL. 10.000 = R$ 1,00.","minimum":0},"fee_amount":{"type":"integer","format":"int64","description":"Unidades de 1/10.000 BRL. 10.000 = R$ 1,00.","minimum":0},"external_id":{"type":["string","null"]},"type":{"const":"pix"},"direction":{"const":"outbound"},"payment_status":{"type":"string"},"description":{"type":"string"},"started_at":{"type":"string"},"recipient":{"type":"object","properties":{"name":{"type":["string","null"]},"key":{"type":["string","null"]}}},"failure_reason":{"type":["string","null"]},"failed_at":{"type":["string","null"]},"reason_code":{"type":["string","null"]},"reason_description":{"type":["string","null"]}}},"Receipt":{"type":"object","properties":{"transaction_id":{"type":"string"},"end_to_end_id":{"type":["string","null"]},"external_id":{"type":["string","null"]},"type":{"type":"string"},"direction":{"type":"string"},"status":{"type":"string"},"amount":{"type":"integer","format":"int64","description":"Unidades de 1/10.000 BRL. 10.000 = R$ 1,00.","minimum":0},"amount_formatted":{"type":"string"},"fee_amount":{"type":"integer","format":"int64","description":"Unidades de 1/10.000 BRL. 10.000 = R$ 1,00.","minimum":0},"fee_formatted":{"type":"string"},"net_amount":{"type":"integer","format":"int64","description":"Unidades de 1/10.000 BRL. 10.000 = R$ 1,00.","minimum":0},"description":{"type":"string"},"counterparty_name":{"type":["string","null"]},"recipient_key":{"type":["string","null"]},"created_at":{"type":"string"},"completed_at":{"type":["string","null"]},"institution":{"type":"object","properties":{"name":{"type":"string"},"cnpj":{"type":["string","null"]},"ispb":{"type":["string","null"]}}}}},"WebhookRequest":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","minItems":1,"items":{"type":"string"}},"secret":{"type":"string","minLength":1,"maxLength":1024},"description":{"type":"string"},"allow_insecure":{"type":"boolean","default":false,"description":"Permite HTTP. Destinos privados continuam bloqueados."}},"required":["url","events"],"example":{"url":"https://seu-dominio.com/webhooks/uneplus","events":["pix.charge.paid","pix.payout.confirmed"]}},"Webhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"description":{"type":["string","null"]},"account_id":{"type":"integer","format":"int64"},"is_active":{"type":"boolean"},"allow_insecure":{"type":"boolean"},"status":{"type":"string"},"secret":{"type":"string","description":"Segredo de assinatura. Trate como credencial; não persista em logs."},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"WebhookCreated":{"type":"object","properties":{"worked":{"const":true},"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"secret":{"type":"string"},"description":{"type":["string","null"]},"is_active":{"type":"boolean"},"created_at":{"type":"string"}}},"BusinessError":{"type":"object","properties":{"errors":{"type":"object","additionalProperties":{"type":"string"}}}},"AuthError":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","format":"int64"},"message":{"type":"string"}}}}},"SignatureError":{"type":"object","properties":{"worked":{"const":false},"detail":{"type":"string"}}},"PermissionError":{"type":"object","properties":{"error":{"const":"forbidden"},"message":{"type":"string"}}},"TransactionResult":{"type":"object","properties":{"worked":{"const":true},"data":{"oneOf":[{"$ref":"#/components/schemas/Transaction"},{"$ref":"#/components/schemas/ProcessingTransaction"},{"$ref":"#/components/schemas/FailedTransaction"}]}},"required":["worked","data"]},"TransactionPage":{"type":"object","properties":{"worked":{"const":true},"data":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/Transaction"},{"$ref":"#/components/schemas/ProcessingTransaction"},{"$ref":"#/components/schemas/FailedTransaction"}]}},"page":{"type":"integer","format":"int64"},"per_page":{"type":"integer","format":"int64"}},"required":["worked","data","page","per_page"]},"CpfRequest":{"type":"object","properties":{"cpf":{"type":"string"},"document_number":{"type":"string","description":"Alias de cpf."}},"example":{"cpf":"12345678909"}},"PixPaidWebhook":{"type":"object","properties":{"eventType":{"type":"string"},"status":{"type":"string"},"accountId":{"type":"integer"},"entityId":{"type":"string","format":"uuid"},"amount":{"type":"integer","description":"Unidades de 1/10.000 BRL."},"externalId":{"type":["string","null"]},"transactionId":{"type":["string","null"]},"endToEndId":{"type":["string","null"]},"txId":{"type":["string","null"]},"qrCodeId":{"type":["string","null"]},"counterpartyName":{"type":["string","null"]},"payerDocument":{"type":["string","null"]},"payerIspb":{"type":["string","null"]},"payerBankName":{"type":["string","null"]},"paidAt":{"type":["string","null"]},"recipientKey":{"type":["string","null"]},"recipientKeyType":{"type":["string","null"]},"feeAmount":{"type":"integer"},"receiver":{"type":["object","null"]}},"required":["eventType","status","accountId","entityId","amount","externalId","transactionId","endToEndId","txId","qrCodeId","counterpartyName","payerDocument","payerIspb","payerBankName","paidAt","recipientKey","recipientKeyType","feeAmount","receiver"],"description":"Documento de contraparte completo somente quando disponível na evidência persistida; campos desconhecidos são null."},"PixPayoutWebhook":{"type":"object","properties":{"eventType":{"type":"string"},"status":{"type":"string"},"accountId":{"type":"integer"},"entityId":{"type":"string","format":"uuid"},"amount":{"type":"integer","description":"Unidades de 1/10.000 BRL."},"externalId":{"type":["string","null"]},"transactionId":{"type":["string","null"]},"endToEndId":{"type":["string","null"]},"pixKey":{"type":["string","null"]},"pixKeyType":{"type":["string","null"]},"description":{"type":["string","null"]},"initiatedAt":{"type":["string","null"]},"completedAt":{"type":["string","null"]},"failedAt":{"type":["string","null"]},"reasonCode":{"type":["string","null"]},"reasonDescription":{"type":["string","null"]},"recipient":{"type":["object","null"]},"payer":{"type":["object","null"]},"sender":{"type":["object","null"]},"feeAmount":{"type":"integer"}},"required":["eventType","status","accountId","entityId","amount","externalId","transactionId","endToEndId","pixKey","pixKeyType","description","initiatedAt","completedAt","failedAt","reasonCode","reasonDescription","recipient","payer","sender","feeAmount"]},"PixRefundWebhook":{"type":"object","properties":{"eventType":{"type":"string"},"status":{"type":"string"},"accountId":{"type":"integer"},"entityId":{"type":"string","format":"uuid"},"amount":{"type":"integer","description":"Unidades de 1/10.000 BRL."},"transactionId":{"type":["string","null"]},"endToEndId":{"type":["string","null"]},"originalEndToEndId":{"type":["string","null"]},"reasonCode":{"type":["string","null"]},"reasonDescription":{"type":["string","null"]},"completedAt":{"type":["string","null"]},"originalAmount":{"type":"integer"},"totalRefunded":{"type":"integer"},"remainingRefundable":{"type":"integer"},"isPartial":{"type":"boolean"}},"required":["eventType","status","accountId","entityId","amount","transactionId","endToEndId","originalEndToEndId","reasonCode","reasonDescription","completedAt","originalAmount","totalRefunded","remainingRefundable","isPartial"],"description":"Devolução parcial: amount é somente esta devolução; totalRefunded é o acumulado."},"AcquirerWindow":{"type":"object","properties":{"weekdays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"description":"0 = domingo ... 6 = sábado"},"start":{"type":"string","example":"20:00"},"end":{"type":"string","example":"06:00"}},"required":["weekdays","start","end"]},"Acquirer":{"type":"object","properties":{"acquirerId":{"type":"string"},"displayName":{"type":"string"},"provider":{"type":"string"},"isDefault":{"type":"boolean"},"availableNow":{"type":"boolean","description":"Aceita cobranças novas agora (status e horário)."},"nextChangeAt":{"type":["string","null"],"format":"date-time"},"schedule":{"type":"array","items":{"$ref":"#/components/schemas/AcquirerWindow"},"description":"Faixas no horário de Brasília; vazio = sempre disponível. Uma faixa com fim antes do início vira a noite."},"dailyInLimitCents":{"type":["integer","null"]}},"required":["acquirerId","displayName","provider","isDefault","availableNow","schedule"]},"AcquirerList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Acquirer"}},"defaultAcquirerId":{"type":"string"}},"required":["items","defaultAcquirerId"]},"SetDefaultAcquirer":{"type":"object","properties":{"acquirerId":{"type":"string"}},"required":["acquirerId"]}}},"webhooks":{"pixLifecycle":{"post":{"summary":"Notificação assinada no seu endpoint","description":"Payload depende de eventType. Verifique a assinatura do corpo bruto antes de parsear, persista e deduplique por X-Uneplus-Event-Id. O payload é imutável em retries.","parameters":[{"in":"header","name":"X-Uneplus-Event-Type","required":true,"schema":{"type":"string"}},{"in":"header","name":"X-Uneplus-Event-Id","required":true,"schema":{"type":"string"}},{"in":"header","name":"X-Uneplus-Timestamp","required":true,"schema":{"type":"string"}},{"in":"header","name":"X-Uneplus-Signature","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PixPaidWebhook"},{"$ref":"#/components/schemas/PixPayoutWebhook"},{"$ref":"#/components/schemas/PixRefundWebhook"}]}}}},"responses":{"204":{"description":"Recebido e persistido pelo seu servidor."}}}}}}