{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Vexus Public API","version":"2026-08-15","summary":"API pública de pagamentos e Split Payment.","description":"Integração HTTPS/JSON para os produtos publicados. Esta especificação descreve somente contratos disponíveis no domínio atual; recursos não publicados aparecem na matriz de disponibilidade e não devem ser inferidos.","license":{"name":"Uso proprietário; acesso sujeito a contrato","identifier":"LicenseRef-Vexus-Proprietary"}},"servers":[{"url":"https://api.vexuspayments.com","description":"Ambiente publicado neste domínio"}],"externalDocs":{"description":"Guia de integração e disponibilidade","url":"https://docs.vexuspayments.com/"},"tags":[{"name":"Status","description":"Disponibilidade técnica sem autenticação."},{"name":"PIX","description":"Entrada, saída, leitura e pagamento de QR Code PIX."},{"name":"Boleto","description":"Emissão, consulta e pagamento de boleto."},{"name":"Cripto","description":"Cotação, saque e consulta do saque."},{"name":"Conta","description":"Consulta de saldo conforme o produto habilitado."},{"name":"Split","description":"Regras, execução, consulta, cancelamento, devolução e relatório de Split Payment."}],"security":[{"ClientId":[],"ClientSecret":[]}],"paths":{"/health/live":{"get":{"tags":["Status"],"summary":"Liveness","description":"Verifica se o processo HTTP está ativo.","operationId":"healthLive","security":[],"responses":{"200":{"description":"Serviço disponível.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthLive"}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"503":{"description":"Serviço ainda não está pronto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthLive"}}}}}}},"/health/ready":{"get":{"tags":["Status"],"summary":"Readiness","description":"Valida banco, migrações e dependências internas necessárias para receber tráfego.","operationId":"healthReady","security":[],"responses":{"200":{"description":"Serviço disponível.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthReady"}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"503":{"description":"Serviço ainda não está pronto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthReady"}}}}}}},"/api/v1/cashin":{"post":{"tags":["PIX"],"summary":"Criar cobrança PIX","description":"Cria uma cobrança PIX dinâmica.","operationId":"createPixCashIn","responses":{"200":{"description":"Operação aceita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/Unavailable"}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PixCashInRequest"},"example":{"amount":25.9,"payer_name":"Cliente de Exemplo","payer_document":"52998224725","payer_email":"cliente@example.com","description":"Pedido 1024","external_id":"pedido-1024"}}}},"x-vexus-scope":"cashin","x-vexus-availability":"PUBLISHED"}},"/api/v1/cashout":{"post":{"tags":["PIX"],"summary":"Enviar PIX","description":"Envia um PIX para a chave informada, sujeito a saldo, produto e limites da conta.","operationId":"createPixCashOut","responses":{"200":{"description":"Operação aceita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/Unavailable"}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PixCashOutRequest"},"example":{"amount":20,"pix_key":"<chave-pix-destino>","pix_key_type":"random","description":"Repasse"}}}},"x-vexus-scope":"cashout","x-vexus-availability":"PUBLISHED"}},"/api/v1/pix/qr/decode":{"post":{"tags":["PIX"],"summary":"Ler QR Code PIX","description":"Valida e decodifica um payload EMV PIX sem movimentar saldo.","operationId":"decodePixQr","responses":{"200":{"description":"Operação aceita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PixQrRequest"},"example":{"payload":"00020101021226810014br.gov.bcb.pix2559https://example.invalid/pix/cobranca-exemplo520400005303986540539.905802BR5905VEXUS6009SAO PAULO62070503***6304ABCD"}}}},"x-vexus-scope":"cashout","x-vexus-availability":"PUBLISHED"}},"/api/v1/pix/qr/pay":{"post":{"tags":["PIX"],"summary":"Pagar QR Code PIX","description":"Paga um QR Code PIX após validação do payload e dos limites.","operationId":"payPixQr","responses":{"200":{"description":"Operação aceita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/Unavailable"}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PixQrPaymentRequest"},"example":{"payload":"00020101021226810014br.gov.bcb.pix2559https://example.invalid/pix/cobranca-exemplo520400005303986540539.905802BR5905VEXUS6009SAO PAULO62070503***6304ABCD","amount":39.9,"description":"Fornecedor"}}}},"x-vexus-scope":"cashout","x-vexus-availability":"PUBLISHED"}},"/api/v1/boleto/issue":{"post":{"tags":["Boleto"],"summary":"Emitir boleto","description":"Emite uma cobrança por boleto para um produto habilitado.","operationId":"issueBoleto","responses":{"200":{"description":"Operação aceita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/Unavailable"}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoletoIssueRequest"},"example":{"product_id":"00000000-0000-4000-8000-000000000001","amount":99.9,"buyer_name":"Cliente de Exemplo","buyer_email":"cliente@example.com","buyer_cpf":"52998224725","buyer_address":{"zip_code":"01001000","street_name":"Praça da Sé","street_number":"100","neighborhood":"Sé","city":"São Paulo","state":"SP"}}}}},"x-vexus-scope":"boleto","x-vexus-availability":"PUBLISHED"}},"/api/v1/boleto/info":{"post":{"tags":["Boleto"],"summary":"Consultar boleto","description":"Consulta os dados de um boleto sem movimentar saldo.","operationId":"getBoletoInfo","responses":{"200":{"description":"Operação aceita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoletoInfoRequest"},"example":{"billetCode":"00000000000000000000000000000000000000000000"}}}},"x-vexus-scope":"boleto","x-vexus-availability":"PUBLISHED"}},"/api/v1/boleto/pay":{"post":{"tags":["Boleto"],"summary":"Pagar boleto","description":"Paga um boleto após a aplicação validar código, beneficiário, saldo e limites.","operationId":"payBoleto","responses":{"200":{"description":"Operação aceita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/Unavailable"}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoletoPaymentRequest"},"example":{"billetCode":"00000000000000000000000000000000000000000000","amount":149.9,"beneficiary_name":"Empresa de Exemplo"}}}},"x-vexus-scope":"boleto","x-vexus-availability":"PUBLISHED"}},"/api/v1/crypto/quote":{"post":{"tags":["Cripto"],"summary":"Criar cotação cripto","description":"Obtém uma cotação para o valor em BRL sem efetuar saque.","operationId":"quoteCrypto","responses":{"200":{"description":"Operação aceita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CryptoQuoteRequest"},"example":{"amount_brl":100}}}},"x-vexus-scope":"cashout","x-vexus-availability":"PUBLISHED"}},"/api/v1/crypto/withdraw":{"post":{"tags":["Cripto"],"summary":"Solicitar saque cripto","description":"Solicita o saque usando uma cotação válida e uma carteira de destino.","operationId":"withdrawCrypto","responses":{"200":{"description":"Operação aceita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/Unavailable"}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CryptoWithdrawRequest"},"example":{"quote_id":"<quote-id>","amount_brl":100,"crypto_wallet":"<carteira-destino>"}}}},"x-vexus-scope":"cashout","x-vexus-availability":"PUBLISHED"}},"/api/v1/crypto/status":{"post":{"tags":["Cripto"],"summary":"Consultar saque cripto","description":"Consulta o saque pela identificação retornada na criação.","operationId":"getCryptoWithdrawal","responses":{"200":{"description":"Operação aceita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CryptoStatusRequest"},"example":{"withdrawal_id":"<withdrawal-id>"}}}},"x-vexus-scope":"cashout","x-vexus-availability":"PUBLISHED"}},"/api/v1/balance":{"post":{"tags":["Conta"],"summary":"Consultar saldo","description":"Consulta o saldo exposto pelo contrato da conta. Envie um objeto JSON vazio.","operationId":"getBalance","responses":{"200":{"description":"Operação aceita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyObject"},"example":{}}}},"x-vexus-scope":"cashin","x-vexus-availability":"PUBLISHED"}},"/api/v1/splits/rules":{"get":{"tags":["Split"],"summary":"Listar regras de split","description":"Lista as regras pertencentes à conta autenticada.","operationId":"listSplitRules","responses":{"200":{"description":"Operação aceita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-vexus-scope":"split","x-vexus-availability":"PUBLISHED"},"post":{"tags":["Split"],"summary":"Criar regra de split","description":"Cria uma regra versionada por percentuais ou valores fixos.","operationId":"createSplitRule","responses":{"201":{"description":"Operação aceita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/Unavailable"}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SplitRuleRequest"},"example":{"name":"Parceiros","mode":"PERCENTAGE","currency":"BRL","participants":[{"handle":"conta-parceira","percentage":"20.00"}]}}}},"x-vexus-scope":"split","x-vexus-availability":"PUBLISHED"}},"/api/v1/splits/rules/{ruleId}":{"put":{"tags":["Split"],"summary":"Revisar regra de split","description":"Arquiva a versão anterior e cria uma nova versão da regra.","operationId":"reviseSplitRule","responses":{"200":{"description":"Operação aceita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/Unavailable"}},"parameters":[{"name":"ruleId","in":"path","required":true,"description":"UUID da regra","schema":{"$ref":"#/components/schemas/Uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SplitRuleRequest"},"example":{"name":"Parceiros v2","mode":"PERCENTAGE","currency":"BRL","participants":[{"handle":"conta-parceira","percentage":"25.00"}]}}}},"x-vexus-scope":"split","x-vexus-availability":"PUBLISHED"},"delete":{"tags":["Split"],"summary":"Arquivar regra de split","description":"Arquiva a regra da conta. Esta operação não aceita corpo.","operationId":"archiveSplitRule","responses":{"200":{"description":"Operação aceita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-vexus-scope":"split","x-vexus-availability":"PUBLISHED","parameters":[{"name":"ruleId","in":"path","required":true,"description":"UUID da regra","schema":{"$ref":"#/components/schemas/Uuid"}}]}},"/api/v1/splits":{"post":{"tags":["Split"],"summary":"Criar split","description":"Cria a operação financeira e suas alocações a partir de uma regra ativa.","operationId":"createSplit","responses":{"201":{"description":"Operação aceita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/Unavailable"}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SplitCreateRequest"},"example":{"rule_id":"00000000-0000-4000-8000-000000000001","amount":100,"payer":{"name":"Cliente de Exemplo","document":"52998224725","email":"cliente@example.com"}}}}},"x-vexus-scope":"split","x-vexus-availability":"PUBLISHED"}},"/api/v1/splits/{splitId}":{"get":{"tags":["Split"],"summary":"Consultar split","description":"Retorna a operação e as alocações visíveis à conta proprietária.","operationId":"getSplit","responses":{"200":{"description":"Operação aceita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-vexus-scope":"split","x-vexus-availability":"PUBLISHED","parameters":[{"name":"splitId","in":"path","required":true,"description":"UUID do split","schema":{"$ref":"#/components/schemas/Uuid"}}]}},"/api/v1/splits/{splitId}/cancel":{"post":{"tags":["Split"],"summary":"Cancelar split","description":"Cancela um split somente quando o estado financeiro permitir. Não aceita corpo.","operationId":"cancelSplit","responses":{"200":{"description":"Operação aceita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-vexus-scope":"split","x-vexus-availability":"PUBLISHED","parameters":[{"name":"splitId","in":"path","required":true,"description":"UUID do split","schema":{"$ref":"#/components/schemas/Uuid"}}]}},"/api/v1/splits/{splitId}/refund":{"post":{"tags":["Split"],"summary":"Solicitar devolução do split","description":"Solicita devolução parcial ou total; uma resposta 202 indica processamento assíncrono.","operationId":"refundSplit","responses":{"202":{"description":"Operação aceita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/Unavailable"},"200":{"description":"Devolução confirmada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataResponse"}}}}},"parameters":[{"name":"splitId","in":"path","required":true,"description":"UUID do split","schema":{"$ref":"#/components/schemas/Uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SplitRefundRequest"},"example":{"amount":25,"comment":"Devolução parcial solicitada pelo cliente"}}}},"x-vexus-scope":"split","x-vexus-availability":"PUBLISHED"}},"/api/v1/splits/report":{"get":{"tags":["Split"],"summary":"Relatório de participante","description":"Retorna itens da conta autenticada no intervalo UTC informado.","operationId":"getSplitReport","responses":{"200":{"description":"Operação aceita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-vexus-scope":"split","x-vexus-availability":"PUBLISHED","parameters":[{"name":"from","in":"query","required":false,"description":"Início inclusivo em YYYY-MM-DD.","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"Fim inclusivo em YYYY-MM-DD.","schema":{"type":"string","format":"date"}}]}}},"webhooks":{"checkoutOrderStatusChanged":{"post":{"summary":"Mudança de status de pedido do checkout","description":"Enviado apenas para endpoint HTTPS ativo, configurado no painel e inscrito em `checkout.order.status_changed`. Valide a assinatura sobre o corpo bruto antes de desserializar.","operationId":"receiveCheckoutOrderStatusChanged","security":[],"parameters":[{"name":"X-Vexus-Event","in":"header","required":true,"description":"checkout.order.status_changed","schema":{"type":"string"}},{"name":"X-Vexus-Delivery","in":"header","required":true,"description":"UUID estável da entrega","schema":{"type":"string"}},{"name":"X-Vexus-Timestamp","in":"header","required":true,"description":"Unix timestamp usado na assinatura","schema":{"type":"string"}},{"name":"X-Vexus-Signature","in":"header","required":true,"description":"v1=<HMAC-SHA256(timestamp.corpo-bruto)>","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Chave estável em todas as tentativas","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutWebhookEvent"}}}},"responses":{"200":{"description":"Qualquer resposta 2xx confirma a entrega."},"default":{"description":"408, 409, 425, 429 e 5xx são retentáveis; outros 4xx são definitivos."}}}}},"components":{"securitySchemes":{"ClientId":{"type":"apiKey","in":"header","name":"Apikey","description":"Identificador da credencial. `X-Client-Id` é aceito como alias de compatibilidade."},"ClientSecret":{"type":"apiKey","in":"header","name":"X-Client-Secret","description":"Segredo exibido uma única vez; use somente no servidor."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"Chave estável da tentativa lógica. Reutilize somente com corpo idêntico.","schema":{"type":"string","minLength":8,"maxLength":100},"example":"pedido-1024-tentativa-logica-1"}},"headers":{"RateLimitLimit":{"description":"Máximo efetivo da janela aplicável.","schema":{"type":"integer"}},"RateLimitRemaining":{"description":"Quantidade restante na janela.","schema":{"type":"integer"}},"RateLimitReset":{"description":"Unix timestamp de reinício da janela.","schema":{"type":"integer"}},"RetryAfter":{"description":"Segundos antes de nova tentativa.","schema":{"type":"integer"}}},"responses":{"BadRequest":{"description":"JSON ou solicitação inválida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Credencial ausente, expirada ou inválida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"Escopo, produto, IP ou User-Agent não autorizado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Conflict":{"description":"Conflito de estado ou de idempotência.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unprocessable":{"description":"Campo, saldo, limite ou regra de domínio inválida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimited":{"description":"Política de requisições, valor ou frequência excedida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"ServerError":{"description":"Falha interna sanitizada; use o correlationId no suporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unavailable":{"description":"Dependência necessária indisponível; consulte retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"MethodNotAllowed":{"description":"Método HTTP não permitido para este recurso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"schemas":{"MoneyDecimal":{"type":"number","format":"decimal","exclusiveMinimum":0,"maximum":1000000,"examples":[25.9]},"MinorAmount":{"type":"string","pattern":"^[0-9]+$","description":"Valor inteiro na menor unidade da moeda.","examples":["2590"]},"Uuid":{"type":"string","format":"uuid"},"EmptyObject":{"type":"object","additionalProperties":false},"PixCashInRequest":{"type":"object","additionalProperties":false,"required":["amount","payer_name","payer_document","payer_email"],"properties":{"amount":{"$ref":"#/components/schemas/MoneyDecimal"},"payer_name":{"type":"string","maxLength":150,"description":"Nome do pagador."},"payer_document":{"type":"string","pattern":"^\\d{11}(?:\\d{3})?$"},"payer_email":{"type":"string","format":"email","maxLength":150},"description":{"type":"string","maxLength":255,"description":"Descrição segura para conciliação."},"external_id":{"type":"string","maxLength":120,"description":"Referência única do integrador."}}},"PixCashOutRequest":{"type":"object","additionalProperties":false,"required":["amount","pix_key","pix_key_type"],"properties":{"amount":{"$ref":"#/components/schemas/MoneyDecimal"},"pix_key":{"type":"string","maxLength":180,"description":"Chave PIX do destinatário."},"pix_key_type":{"type":"string","enum":["cpf","cnpj","email","phone","random"]},"description":{"type":"string","maxLength":255,"description":"Descrição da transferência."}}},"PixPayload":{"type":"string","minLength":20,"maxLength":10000},"PixQrRequest":{"type":"object","additionalProperties":false,"required":["payload"],"properties":{"payload":{"$ref":"#/components/schemas/PixPayload"}}},"PixQrPaymentRequest":{"type":"object","additionalProperties":false,"required":["payload","amount"],"properties":{"payload":{"$ref":"#/components/schemas/PixPayload"},"amount":{"$ref":"#/components/schemas/MoneyDecimal"},"description":{"type":"string","maxLength":255,"description":"Descrição do pagamento."}}},"Address":{"type":"object","additionalProperties":false,"required":["zip_code","street_name","street_number","neighborhood","city","state"],"properties":{"zip_code":{"type":"string","pattern":"^\\d{8}$"},"street_name":{"type":"string","maxLength":150,"description":"Logradouro."},"street_number":{"type":"string","maxLength":30,"description":"Número."},"neighborhood":{"type":"string","maxLength":100,"description":"Bairro."},"city":{"type":"string","maxLength":100,"description":"Cidade."},"state":{"type":"string","pattern":"^[A-Z]{2}$"}}},"BoletoIssueRequest":{"type":"object","additionalProperties":true,"required":["product_id","amount","buyer_name","buyer_email","buyer_cpf","buyer_address"],"properties":{"product_id":{"$ref":"#/components/schemas/Uuid"},"amount":{"$ref":"#/components/schemas/MoneyDecimal"},"buyer_name":{"type":"string","maxLength":150,"description":"Nome do pagador."},"buyer_email":{"type":"string","format":"email"},"buyer_cpf":{"type":"string","pattern":"^\\d{11}$"},"buyer_address":{"$ref":"#/components/schemas/Address"},"description":{"type":"string","maxLength":255,"description":"Descrição da cobrança."}}},"BoletoCode":{"type":"string","pattern":"^(?:\\d{44}|\\d{46}|\\d{47}|\\d{48})$"},"BoletoInfoRequest":{"type":"object","additionalProperties":false,"required":["billetCode"],"properties":{"billetCode":{"$ref":"#/components/schemas/BoletoCode"}}},"BoletoPaymentRequest":{"type":"object","additionalProperties":false,"required":["billetCode","amount","beneficiary_name"],"properties":{"billetCode":{"$ref":"#/components/schemas/BoletoCode"},"amount":{"$ref":"#/components/schemas/MoneyDecimal"},"beneficiary_name":{"type":"string","maxLength":150,"description":"Beneficiário confirmado pelo integrador."}}},"CryptoQuoteRequest":{"type":"object","additionalProperties":false,"required":["amount_brl"],"properties":{"amount_brl":{"$ref":"#/components/schemas/MoneyDecimal"}}},"CryptoWithdrawRequest":{"type":"object","additionalProperties":false,"required":["quote_id","amount_brl","crypto_wallet"],"properties":{"quote_id":{"type":"string","maxLength":160,"description":"Identificador opaco da cotação."},"amount_brl":{"$ref":"#/components/schemas/MoneyDecimal"},"crypto_wallet":{"type":"string","minLength":12,"maxLength":180}}},"CryptoStatusRequest":{"type":"object","additionalProperties":false,"required":["withdrawal_id"],"properties":{"withdrawal_id":{"type":"string","maxLength":160,"description":"Identificador opaco do saque."}}},"SplitParticipantInput":{"type":"object","additionalProperties":false,"required":["handle"],"properties":{"handle":{"type":"string","maxLength":100,"description":"Identificador público da conta participante."},"percentage":{"type":"string","pattern":"^\\d+(?:\\.\\d{1,6})?$"},"amount":{"$ref":"#/components/schemas/MoneyDecimal"},"fixed_minor":{"$ref":"#/components/schemas/MinorAmount"}}},"SplitRuleRequest":{"type":"object","additionalProperties":false,"required":["name","mode","participants"],"properties":{"name":{"type":"string","maxLength":120,"description":"Nome da regra."},"mode":{"type":"string","enum":["PERCENTAGE","FIXED"]},"currency":{"type":"string","enum":["BRL"],"default":"BRL"},"participants":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/SplitParticipantInput"}}}},"SplitPayer":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","maxLength":150,"description":"Nome do pagador."},"document":{"type":"string","maxLength":20,"description":"Documento do pagador."},"email":{"type":"string","format":"email"}}},"SplitCreateRequest":{"type":"object","additionalProperties":false,"required":["rule_id"],"anyOf":[{"required":["amount"]},{"required":["amount_minor"]}],"properties":{"rule_id":{"$ref":"#/components/schemas/Uuid"},"amount":{"$ref":"#/components/schemas/MoneyDecimal"},"amount_minor":{"$ref":"#/components/schemas/MinorAmount"},"payer":{"$ref":"#/components/schemas/SplitPayer"}}},"SplitRefundRequest":{"type":"object","additionalProperties":false,"anyOf":[{"required":["amount"]},{"required":["amount_minor"]}],"properties":{"amount":{"$ref":"#/components/schemas/MoneyDecimal"},"amount_minor":{"$ref":"#/components/schemas/MinorAmount"},"comment":{"type":"string","maxLength":500,"description":"Motivo seguro da devolução."}}},"OperationResponse":{"type":"object","required":["statusCode"],"properties":{"statusCode":{"type":"integer","const":200},"ok":{"type":"boolean"},"reference":{"type":"string","maxLength":120,"description":"Referência local para conciliação."},"provider_reference":{"type":"string","maxLength":180,"description":"Referência externa opaca, quando disponível."},"status":{"type":"string"},"data":{"type":["object","array","null"],"additionalProperties":true}},"additionalProperties":true},"DataResponse":{"type":"object","required":["statusCode","data"],"properties":{"statusCode":{"type":"integer"},"data":{"type":["object","array"],"additionalProperties":true}},"additionalProperties":false},"ApiError":{"type":"object","required":["code","message","details","correlationId","retryable"],"properties":{"code":{"type":"string","pattern":"^[A-Z0-9_]+$"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true},"correlationId":{"type":"string"},"retryable":{"type":"boolean"}}},"ErrorEnvelope":{"type":"object","required":["statusCode","message","error"],"properties":{"statusCode":{"type":"integer"},"message":{"type":"string"},"error":{"$ref":"#/components/schemas/ApiError"}}},"HealthLive":{"type":"object","required":["status","service","release","timestamp"],"properties":{"status":{"type":"string","const":"ok"},"service":{"type":"string","const":"vexus-baas"},"release":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"HealthReady":{"type":"object","required":["status","checks","timestamp"],"properties":{"status":{"type":"string","enum":["ready","not_ready"]},"checks":{"type":"object","additionalProperties":true},"timestamp":{"type":"string","format":"date-time"}}},"CheckoutWebhookEvent":{"type":"object","required":["id","type","createdAt","data"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"type":{"type":"string","const":"checkout.order.status_changed"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","required":["orderId","status","method","currency","currencyExponent","amountMinor"],"properties":{"orderId":{"type":"string"},"status":{"type":"string","enum":["CREATED","PROCESSING","PENDING","AUTHORIZED","PAID","FAILED","EXPIRED","CANCELED","REFUNDED","REVIEW"]},"previousStatus":{"type":["string","null"]},"method":{"type":"string"},"currency":{"type":"string"},"currencyExponent":{"type":"integer"},"amountMinor":{"$ref":"#/components/schemas/MinorAmount"}},"additionalProperties":false}},"additionalProperties":false}}},"x-vexus-idempotency":{"required_for":["createPixCashIn","createPixCashOut","payPixQr","issueBoleto","payBoleto","withdrawCrypto","createSplitRule","reviseSplitRule","createSplit","refundSplit"],"rules":"Use de 8 a 100 caracteres e repita a mesma chave somente ao repetir exatamente o mesmo corpo. Corpo divergente com a mesma chave retorna conflito."},"x-vexus-pagination":{"status":"NOT_APPLICABLE_TO_PUBLISHED_LISTS","detail":"A lista de regras é restrita à conta. O relatório de split usa os filtros from/to. Não envie page, cursor ou limit: esses parâmetros ainda não fazem parte do contrato."},"x-vexus-examples":{"classification":"FICTIONAL_DOCUMENTATION_DATA","detail":"Nomes, documentos, identificadores, códigos, endereços e valores dos exemplos não representam dados ou operações de produção."},"x-vexus-availability":[{"capability":"PIX cash-in/cash-out/QR","status":"PUBLISHED","surface":"Public API"},{"capability":"Boleto issue/info/pay","status":"PUBLISHED","surface":"Public API"},{"capability":"Crypto quote/withdraw/status","status":"PUBLISHED","surface":"Public API"},{"capability":"Split rules/create/get/cancel/refund/report","status":"PUBLISHED","surface":"Public API"},{"capability":"Generic transaction query","status":"NOT_PUBLISHED","reason":"Use o painel e a referência retornada; não existe rota pública de consulta genérica nesta versão."},{"capability":"Direct card API","status":"NOT_PUBLISHED","reason":"Cartão permanece disponível somente no checkout hospedado quando habilitado."},{"capability":"Checkout management API","status":"NOT_PUBLISHED","reason":"Produtos e links são administrados no painel autenticado."},{"capability":"Financial operation webhooks","status":"NOT_PUBLISHED","reason":"O único evento de cliente publicado nesta versão é checkout.order.status_changed."},{"capability":"Public MED/dispute API","status":"NOT_PUBLISHED","reason":"Disputas são acompanhadas pelo painel e suporte; nenhuma rota pública deve ser presumida."}],"x-vexus-changelog":[{"date":"2026-08-15","changes":["Contrato OpenAPI 3.1 e coleção Postman derivados da mesma fonte.","Split Payment publicado com idempotência nas mutações financeiras.","Assinatura e política de retry do webhook de checkout documentadas.","Matriz de disponibilidade explícita para recursos ainda não publicados."]}]}