{
  "openapi": "3.1.0",
  "info": {
    "title": "SlacePay Public API",
    "version": "1.6.0",
    "description": "Contrato da API pública e sandbox. Rotas administrativas não estão incluídas."
  },
  "servers": [{ "url": "https://api.slacepay.com.br" }],
  "security": [{ "merchantApiKey": [] }],
  "tags": [
    { "name": "Conta" },
    { "name": "Transações" },
    { "name": "Sandbox" },
    { "name": "Webhooks" }
  ],
  "paths": {
    "/v1/account": {
      "get": {
        "tags": ["Conta"],
        "summary": "Consultar conta",
        "responses": {
          "200": { "description": "Cadastro, taxas, limites e saldo", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant": { "$ref": "#/components/schemas/Merchant" } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/v1/transactions": {
      "get": {
        "tags": ["Transações"],
        "summary": "Listar transações",
        "parameters": [
          { "$ref": "#/components/parameters/Page" },
          { "$ref": "#/components/parameters/Limit" },
          { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/TransactionStatus" } },
          { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["CASH_IN", "CASH_OUT"] } },
          { "name": "externalReference", "in": "query", "schema": { "type": "string", "maxLength": 120 } },
          { "name": "dateFrom", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "dateTo", "in": "query", "schema": { "type": "string", "format": "date-time" } }
        ],
        "responses": {
          "200": { "description": "Lista paginada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionList" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/v1/transactions/{transactionId}": {
      "get": {
        "tags": ["Transações"],
        "summary": "Obter uma transação",
        "parameters": [{ "$ref": "#/components/parameters/TransactionId" }],
        "responses": {
          "200": { "$ref": "#/components/responses/TransactionResponse" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/cash-in": {
      "post": {
        "tags": ["Transações"],
        "summary": "Criar cobrança Pix",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashInRequest" }, "example": { "amount": "10.00" } } } },
        "responses": {
          "201": { "$ref": "#/components/responses/TransactionResponse" },
          "202": { "$ref": "#/components/responses/TransactionResponse" },
          "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/TooManyRequests" }
        }
      }
    },
    "/v1/cash-out": {
      "post": {
        "tags": ["Transações"],
        "summary": "Criar saque Pix",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashOutRequest" } } } },
        "responses": {
          "201": { "$ref": "#/components/responses/TransactionResponse" },
          "202": { "$ref": "#/components/responses/TransactionResponse" },
          "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/TooManyRequests" }
        }
      }
    },
    "/v1/sandbox/transactions/{transactionId}/simulate": {
      "post": {
        "tags": ["Sandbox"],
        "summary": "Simular uma transação",
        "description": "Somente para sk_test. Não movimenta saldo real.",
        "parameters": [{ "$ref": "#/components/parameters/TransactionId" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["status"], "properties": { "status": { "type": "string", "enum": ["COMPLETED", "FAILED", "EXPIRED", "CANCELED"] } } } } } },
        "responses": {
          "200": { "$ref": "#/components/responses/TransactionResponse" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      }
    },
    "/v1/splits": {
      "get": {
        "tags": ["Transações"],
        "summary": "Listar splits recebidos",
        "parameters": [
          { "$ref": "#/components/parameters/Page" },
          { "$ref": "#/components/parameters/Limit" },
          { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/TransactionStatus" } }
        ],
        "responses": {
          "200": { "description": "Lista paginada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SplitList" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/v1/webhook-deliveries": {
      "get": {
        "tags": ["Webhooks"],
        "summary": "Listar entregas de webhook",
        "parameters": [
          { "$ref": "#/components/parameters/Page" },
          { "$ref": "#/components/parameters/Limit" },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["PENDING", "PROCESSING", "DELIVERED", "FAILED", "DEAD"] } }
        ],
        "responses": {
          "200": { "description": "Histórico paginado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryList" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "merchantApiKey": { "type": "apiKey", "in": "header", "name": "API-Key", "description": "sk_live_ para produção ou sk_test_ para sandbox." }
    },
    "parameters": {
      "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[A-Za-z0-9._:-]+$" } },
      "TransactionId": { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^txn_[a-f0-9]{32}$" } },
      "Page": { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } },
      "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }
    },
    "schemas": {
      "Money": { "oneOf": [{ "type": "string", "pattern": "^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,2})?$" }, { "type": "number", "exclusiveMinimum": 0, "maximum": 100000000, "multipleOf": 0.01 }] },
      "TransactionStatus": { "type": "string", "enum": ["INITIATED", "PENDING", "COMPLETED", "CANCELED", "WAITING_FOR_REFUND", "REFUNDED", "EXPIRED", "FAILED", "PROVIDER_UNKNOWN"] },
      "Payer": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "document": { "type": "string", "pattern": "^\\d{11}(?:\\d{3})?$" }, "email": { "type": "string", "format": "email", "maxLength": 254 } } },
      "SplitInput": { "type": "object", "additionalProperties": false, "required": ["merchantId", "percentage"], "properties": { "merchantId": { "type": "string", "pattern": "^mrc_[a-f0-9]{32}$" }, "percentage": { "oneOf": [{ "type": "string" }, { "type": "number", "minimum": 0.01, "maximum": 100, "multipleOf": 0.01 }] } } },
      "CashInRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["amount"],
        "properties": {
          "amount": { "$ref": "#/components/schemas/Money" },
          "passFeeToCustomer": { "type": "boolean", "default": false },
          "externalReference": { "type": "string", "minLength": 1, "maxLength": 120 },
          "webhookUrl": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2048 },
          "payer": { "$ref": "#/components/schemas/Payer" },
          "split": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/SplitInput" } }
        }
      },
      "CashOutRequest": { "type": "object", "additionalProperties": false, "required": ["amount", "pixKey", "pixType"], "properties": { "amount": { "$ref": "#/components/schemas/Money" }, "pixKey": { "type": "string", "minLength": 3, "maxLength": 254 }, "pixType": { "type": "string", "enum": ["cpf", "cnpj", "email", "phone", "evp"] }, "externalReference": { "type": "string", "minLength": 1, "maxLength": 120 } } },
      "Transaction": {
        "type": "object",
        "required": ["id", "environment", "livemode", "type", "status", "amount", "chargedAmount", "merchantNetAmount", "merchantFee", "requiresReconciliation", "createdAt", "updatedAt"],
        "properties": {
          "id": { "type": "string", "pattern": "^txn_[a-f0-9]{32}$" },
          "environment": { "type": "string", "enum": ["live", "test"] },
          "livemode": { "type": "boolean" },
          "type": { "type": "string", "enum": ["CASH_IN", "CASH_OUT"] },
          "status": { "$ref": "#/components/schemas/TransactionStatus" },
          "amount": { "type": "string" },
          "chargedAmount": { "type": "string" },
          "merchantNetAmount": { "type": "string" },
          "merchantDebitAmount": { "type": "string", "description": "Somente CASH_OUT." },
          "merchantFee": { "type": "string" },
          "feePassedToCustomer": { "type": "boolean" },
          "externalReference": { "type": ["string", "null"] },
          "endToEndId": { "type": ["string", "null"] },
          "pix": { "type": "object", "additionalProperties": true },
          "payer": { "type": "object", "additionalProperties": true },
          "webhook": { "type": "object", "additionalProperties": true },
          "split": { "type": "object", "additionalProperties": true },
          "failure": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } },
          "requiresReconciliation": { "type": "boolean" },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "Pagination": { "type": "object", "required": ["page", "limit", "total", "pages"], "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" } } },
      "TransactionList": { "type": "object", "required": ["data", "pagination"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } },
      "Merchant": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "environment": { "type": "string", "enum": ["live", "test"] }, "livemode": { "type": "boolean" }, "merchantName": { "type": "string" }, "fees": { "type": "object" }, "limits": { "type": "object" }, "balance": { "type": "object" } } },
      "SplitList": { "type": "object", "required": ["data", "pagination"], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } },
      "WebhookDeliveryList": { "type": "object", "required": ["data", "pagination"], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } },
      "Error": { "type": "object", "required": ["error", "requestId"], "properties": { "error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "requestId": { "type": "string" } } }
    },
    "responses": {
      "TransactionResponse": { "description": "Transação", "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction": { "$ref": "#/components/schemas/Transaction" } } } } } },
      "BadRequest": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unauthorized": { "description": "API key inválida ou inativa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Forbidden": { "description": "Acesso negado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "NotFound": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Conflict": { "description": "Conflito", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unprocessable": { "description": "Regra de negócio não atendida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "TooManyRequests": { "description": "Limite excedido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  }
}