{"openapi":"3.1.0","info":{"title":"Mainum API","version":"1.0.0","description":"Contrato público v1 para cobranças Pix, consultas financeiras, saques Pix e leitura de casos MED. Valores monetários são inteiros em centavos e a moeda é BRL."},"servers":[{"url":"/","description":"Mesmo host da API"}],"tags":[{"name":"Cobranças"},{"name":"Financeiro"},{"name":"Saques"},{"name":"MED"}],"paths":{"/v1/charges":{"post":{"tags":["Cobranças"],"summary":"Criar cobrança Pix","operationId":"createPixCharge","x-required-api-key-scope":"charges:write","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Identificador único da tentativa, entre 8 e 128 caracteres ASCII visíveis.","schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChargeRequest"}}}},"responses":{"200":{"description":"Cobrança existente recuperada sem artefato Pix disponível","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChargeArtifactUnavailable"}}}},"201":{"description":"Cobrança criada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedCharge"}}}},"202":{"description":"Resultado da criação ainda em conciliação","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChargeCreationPending"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/charges/{chargeId}":{"get":{"tags":["Cobranças"],"summary":"Consultar cobrança","operationId":"getCharge","x-required-api-key-scope":"charges:read","security":[{"apiKeyBearer":[]}],"parameters":[{"$ref":"#/components/parameters/ChargeId"}],"responses":{"200":{"description":"Cobrança encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/transactions":{"get":{"tags":["Financeiro"],"summary":"Listar transações","operationId":"listTransactions","x-required-api-key-scope":"transactions:read","security":[{"apiKeyBearer":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/ChargeStatus"}}],"responses":{"200":{"description":"Página de transações","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionPage"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/balance":{"get":{"tags":["Financeiro"],"summary":"Consultar saldo","operationId":"getBalance","x-required-api-key-scope":"balance:read","security":[{"apiKeyBearer":[]}],"responses":{"200":{"description":"Saldo derivado do livro-caixa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/statement":{"get":{"tags":["Financeiro"],"summary":"Consultar extrato","operationId":"listStatement","x-required-api-key-scope":"statement:read","security":[{"apiKeyBearer":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Página do extrato","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatementPage"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/withdrawals":{"post":{"tags":["Saques"],"summary":"Reservar saque Pix","operationId":"createPixWithdrawal","description":"Cria a reserva local do saque. O processamento posterior é assíncrono.","x-required-api-key-scope":"withdrawals:write","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Identificador único da tentativa, entre 8 e 128 caracteres ASCII visíveis.","schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWithdrawalRequest"}}}},"responses":{"201":{"description":"Saque reservado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Withdrawal"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/withdrawals/{withdrawalId}":{"get":{"tags":["Saques"],"summary":"Consultar saque Pix","operationId":"getWithdrawal","x-required-api-key-scope":"withdrawals:read","security":[{"apiKeyBearer":[]}],"parameters":[{"$ref":"#/components/parameters/WithdrawalId"}],"responses":{"200":{"description":"Saque encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Withdrawal"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/med-cases":{"get":{"tags":["MED"],"summary":"Listar casos MED","operationId":"listMedCases","x-required-api-key-scope":"med:read","security":[{"apiKeyBearer":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/MedStatus"}}],"responses":{"200":{"description":"Página de casos MED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MedCasePage"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/med-cases/{medCaseId}":{"get":{"tags":["MED"],"summary":"Consultar caso MED","operationId":"getMedCase","x-required-api-key-scope":"med:read","security":[{"apiKeyBearer":[]}],"parameters":[{"$ref":"#/components/parameters/MedCaseId"}],"responses":{"200":{"description":"Caso MED encontrado","content":{"application/json":{"schema":{"type":"object","required":["data","request_id"],"properties":{"data":{"$ref":"#/components/schemas/MedCase"},"request_id":{"$ref":"#/components/schemas/RequestId"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"apiKeyBearer":{"type":"http","scheme":"bearer","bearerFormat":"Mainum API key","description":"Chave operacional vinculada a um único estabelecimento e aos escopos declarados em cada operação."}},"parameters":{"ChargeId":{"name":"chargeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"WithdrawalId":{"name":"withdrawalId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"MedCaseId":{"name":"medCaseId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"Limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},"Cursor":{"name":"cursor","in":"query","description":"Cursor opaco devolvido pela página anterior.","schema":{"type":"string","minLength":1,"maxLength":512}}},"responses":{"BadRequest":{"description":"Requisição ou cursor inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Chave ausente, inválida ou sem o escopo exigido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Operação não permitida para o estabelecimento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Recurso não encontrado para o estabelecimento autenticado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflito de identificador externo, idempotência ou operação em andamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"Regra financeira impediu a operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Limite de requisições excedido","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Serviço temporariamente indisponível","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"RequestId":{"type":"string","minLength":1},"Cents":{"type":"integer","format":"int64","minimum":0,"description":"Valor inteiro em centavos."},"PositiveCents":{"type":"integer","format":"int64","minimum":1,"description":"Valor inteiro positivo em centavos."},"SignedCents":{"type":"integer","format":"int64","description":"Valor inteiro assinado em centavos."},"NullableDateTime":{"type":["string","null"],"format":"date-time"},"NullableCursor":{"type":["string","null"]},"ChargeStatus":{"type":"string","enum":["CREATING","PENDING","PAID","FAILED","CANCELED","EXPIRED","UNDER_REVIEW","REVERSED"]},"WithdrawalStatus":{"type":"string","enum":["RESERVED","SUBMITTING","QUEUED","PROCESSING","COMPLETED","FAILED","CANCELED","UNKNOWN","MANUAL_REVIEW"]},"MedStatus":{"type":"string","enum":["WAITING_PSP","ACCEPTED","REJECTED","CANCELLED"]},"Error":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"string"},"request_id":{"$ref":"#/components/schemas/RequestId"}},"additionalProperties":true},"PixArtifact":{"type":"object","required":["copy_paste","qr_code_url","qr_code_base64"],"properties":{"copy_paste":{"type":"string"},"qr_code_url":{"type":["string","null"],"format":"uri"},"qr_code_base64":{"type":["string","null"]}},"additionalProperties":false},"CreateChargeRequest":{"type":"object","required":["external_id","amount_cents","payer","description"],"properties":{"external_id":{"type":"string","minLength":1,"maxLength":128},"amount_cents":{"$ref":"#/components/schemas/PositiveCents"},"payer":{"type":"object","required":["name","document"],"properties":{"name":{"type":"string","minLength":2,"maxLength":120},"document":{"type":"string","pattern":"^[0-9]{11}$","description":"CPF válido, somente dígitos."}},"additionalProperties":false},"description":{"type":"string","minLength":1,"maxLength":255}},"additionalProperties":false},"ChargeFields":{"type":"object","required":["id","external_id","method","status","amount_cents","fee_cents","net_amount_cents"],"properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"string"},"method":{"const":"PIX"},"status":{"$ref":"#/components/schemas/ChargeStatus"},"amount_cents":{"$ref":"#/components/schemas/Cents"},"fee_cents":{"$ref":"#/components/schemas/Cents"},"net_amount_cents":{"$ref":"#/components/schemas/Cents"}}},"CreatedCharge":{"allOf":[{"$ref":"#/components/schemas/ChargeFields"},{"type":"object","required":["pix","request_id"],"properties":{"pix":{"$ref":"#/components/schemas/PixArtifact"},"request_id":{"$ref":"#/components/schemas/RequestId"}}}]},"Charge":{"allOf":[{"$ref":"#/components/schemas/ChargeFields"},{"type":"object","required":["pix","expires_at","paid_at","created_at","updated_at","request_id"],"properties":{"pix":{"oneOf":[{"$ref":"#/components/schemas/PixArtifact"},{"type":"null"}]},"expires_at":{"$ref":"#/components/schemas/NullableDateTime"},"paid_at":{"$ref":"#/components/schemas/NullableDateTime"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"request_id":{"$ref":"#/components/schemas/RequestId"}}}]},"ChargeCreationPending":{"type":"object","required":["id","status","resolution","request_id"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"const":"CREATING"},"resolution":{"const":"PENDING_RECONCILIATION"},"request_id":{"$ref":"#/components/schemas/RequestId"}}},"ChargeArtifactUnavailable":{"type":"object","required":["id","status","pix","warning","request_id"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"const":"PENDING"},"pix":{"type":"null"},"warning":{"const":"payment_artifact_unavailable"},"request_id":{"$ref":"#/components/schemas/RequestId"}}},"Transaction":{"type":"object","required":["id","external_id","type","method","currency","status","amount_cents","fee_cents","net_amount_cents","paid_at","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"string"},"type":{"const":"CASH_IN"},"method":{"const":"PIX"},"currency":{"const":"BRL"},"status":{"$ref":"#/components/schemas/ChargeStatus"},"amount_cents":{"$ref":"#/components/schemas/Cents"},"fee_cents":{"$ref":"#/components/schemas/Cents"},"net_amount_cents":{"$ref":"#/components/schemas/Cents"},"paid_at":{"$ref":"#/components/schemas/NullableDateTime"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"TransactionPage":{"type":"object","required":["data","next_cursor","request_id"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"next_cursor":{"$ref":"#/components/schemas/NullableCursor"},"request_id":{"$ref":"#/components/schemas/RequestId"}}},"Balance":{"type":"object","required":["currency","pending_cents","blocked_cents","reserved_cents","med_reserved_cents","withdrawal_reserved_cents","scheduled_med_reserve_cents","unclassified_cents","available_cents","available_hold_cents","withdrawable_cents","availability_status","request_id"],"properties":{"currency":{"const":"BRL"},"pending_cents":{"$ref":"#/components/schemas/SignedCents"},"blocked_cents":{"$ref":"#/components/schemas/SignedCents"},"reserved_cents":{"$ref":"#/components/schemas/SignedCents"},"med_reserved_cents":{"$ref":"#/components/schemas/SignedCents"},"withdrawal_reserved_cents":{"$ref":"#/components/schemas/SignedCents"},"scheduled_med_reserve_cents":{"$ref":"#/components/schemas/SignedCents"},"unclassified_cents":{"$ref":"#/components/schemas/SignedCents"},"available_cents":{"$ref":"#/components/schemas/SignedCents"},"available_hold_cents":{"$ref":"#/components/schemas/SignedCents"},"withdrawable_cents":{"$ref":"#/components/schemas/SignedCents"},"availability_status":{"const":"ACTIVE"},"request_id":{"$ref":"#/components/schemas/RequestId"}}},"StatementEntry":{"type":"object","required":["id","journal_id","reference_id","reference_type","type","category","amount_cents","occurred_at"],"properties":{"id":{"type":"string","format":"uuid"},"journal_id":{"type":"string","format":"uuid"},"reference_id":{"type":"string","format":"uuid"},"reference_type":{"type":"string"},"type":{"type":"string"},"category":{"type":"string","enum":["PENDING","AVAILABLE","WITHDRAWABLE","BLOCKED","RESERVED","UNCLASSIFIED"]},"amount_cents":{"$ref":"#/components/schemas/SignedCents"},"occurred_at":{"type":"string","format":"date-time"}}},"StatementPage":{"type":"object","required":["currency","data","next_cursor","request_id"],"properties":{"currency":{"const":"BRL"},"data":{"type":"array","items":{"$ref":"#/components/schemas/StatementEntry"}},"next_cursor":{"$ref":"#/components/schemas/NullableCursor"},"request_id":{"$ref":"#/components/schemas/RequestId"}}},"PixKeyType":{"type":"string","enum":["CPF","CNPJ","EMAIL","TELEFONE","CHAVE_ALEATORIA"]},"CreateWithdrawalRequest":{"type":"object","required":["external_id","amount_cents","pix_key","description"],"properties":{"external_id":{"type":"string","minLength":1,"maxLength":128},"amount_cents":{"$ref":"#/components/schemas/PositiveCents"},"pix_key":{"type":"object","required":["type","value"],"properties":{"type":{"$ref":"#/components/schemas/PixKeyType"},"value":{"type":"string","minLength":3,"maxLength":320}},"additionalProperties":false},"description":{"type":"string","minLength":1,"maxLength":255}},"additionalProperties":false},"Withdrawal":{"type":"object","required":["id","external_id","method","status","amount_cents","fee_cents","total_debit_cents","pix_key","created_at","request_id"],"properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"string"},"method":{"const":"PIX"},"status":{"$ref":"#/components/schemas/WithdrawalStatus"},"amount_cents":{"$ref":"#/components/schemas/Cents"},"fee_cents":{"$ref":"#/components/schemas/Cents"},"total_debit_cents":{"$ref":"#/components/schemas/Cents"},"pix_key":{"type":"object","required":["type","masked"],"properties":{"type":{"$ref":"#/components/schemas/PixKeyType"},"masked":{"type":"string"}},"additionalProperties":false},"created_at":{"type":"string","format":"date-time"},"request_id":{"$ref":"#/components/schemas/RequestId"}}},"MedCase":{"type":"object","required":["id","charge_id","charge_external_id","method","currency","status","resolution_state","amount_cents","blocked_amount_cents","exposure_amount_cents","outstanding_exposure_amount_cents","opened_at","observed_at","resolved_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"charge_id":{"type":"string","format":"uuid"},"charge_external_id":{"type":"string"},"method":{"const":"PIX"},"currency":{"const":"BRL"},"status":{"$ref":"#/components/schemas/MedStatus"},"resolution_state":{"type":"string","enum":["OPEN","PROCESSING","RESOLVED"]},"amount_cents":{"$ref":"#/components/schemas/Cents"},"blocked_amount_cents":{"$ref":"#/components/schemas/Cents"},"exposure_amount_cents":{"$ref":"#/components/schemas/Cents"},"outstanding_exposure_amount_cents":{"$ref":"#/components/schemas/Cents"},"opened_at":{"type":"string","format":"date-time"},"observed_at":{"type":"string","format":"date-time"},"resolved_at":{"$ref":"#/components/schemas/NullableDateTime"},"updated_at":{"type":"string","format":"date-time"}}},"MedCasePage":{"type":"object","required":["data","next_cursor","request_id"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MedCase"}},"next_cursor":{"$ref":"#/components/schemas/NullableCursor"},"request_id":{"$ref":"#/components/schemas/RequestId"}}}}}}