{
  "openapi": "3.1.0",
  "info": {
    "title": "AvalonPay API",
    "version": "1.0.0",
    "description": "Autenticação JWT, depósitos Pix, emissão de boleto e checkout hospedado. Operações financeiras exigem HTTPS. Limites por usuário: 10 operações de criação e 30 consultas de status por minuto; respostas 429 incluem Retry-After."
  },
  "servers": [{ "url": "https://api.avalonpay.com.br" }],
  "tags": [{ "name": "Autenticação" }, { "name": "Pagamentos" }],
  "paths": {
    "/api/auth/login": {
      "post": {
        "tags": ["Autenticação"],
        "summary": "Criar sessão JWT",
        "operationId": "login",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["client_id", "client_secret"],
                "properties": {
                  "client_id": { "type": "string" },
                  "client_secret": { "type": "string", "format": "password" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "JWT criado" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/payments/deposit": {
      "post": {
        "tags": ["Pagamentos"],
        "summary": "Criar depósito Pix",
        "operationId": "createPixDeposit",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["amount", "external_id", "clientCallbackUrl", "payer"],
                "properties": {
                  "amount": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$" },
                  "external_id": { "type": "string", "maxLength": 100 },
                  "clientCallbackUrl": { "type": "string", "format": "uri" },
                  "payer": { "$ref": "#/components/schemas/Payer" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Cobrança Pix criada" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/payments/boleto": {
      "post": {
        "tags": ["Pagamentos"],
        "summary": "Gerar boleto para depósito",
        "operationId": "createBoletoDeposit",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["amount", "external_id", "payer"],
                "properties": {
                  "amount": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$" },
                  "external_id": { "type": "string", "maxLength": 100 },
                  "description": { "type": "string", "maxLength": 250 },
                  "payer": {
                    "allOf": [
                      { "$ref": "#/components/schemas/Payer" },
                      {
                        "type": "object",
                        "required": ["address"],
                        "properties": { "address": { "$ref": "#/components/schemas/BrazilAddress" } }
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Boleto criado; saldo ainda pendente" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "409": { "description": "Referência externa já usada com outro valor" },
          "502": { "description": "Falha ao criar no provedor" }
        }
      }
    },
    "/api/payments/boleto/{external_id}/status": {
      "get": {
        "tags": ["Pagamentos"],
        "summary": "Consultar e sincronizar o status do boleto",
        "operationId": "getBoletoStatus",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{
          "name": "external_id",
          "in": "path",
          "required": true,
          "schema": { "type": "string", "maxLength": 100 }
        }],
        "responses": {
          "200": { "description": "Estado consultado no Mercado Pago" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "404": { "description": "Boleto não encontrado para esta conta" },
          "502": { "description": "Falha ao consultar o provedor" }
        }
      }
    },
    "/api/payments/checkout": {
      "post": {
        "tags": ["Pagamentos"],
        "summary": "Criar checkout hospedado para cartão ou boleto",
        "operationId": "createHostedCheckout",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["amount", "external_id", "clientCallbackUrl", "payer", "payment_method"],
                "properties": {
                  "amount": { "type": "string" },
                  "external_id": { "type": "string" },
                  "clientCallbackUrl": { "type": "string", "format": "uri" },
                  "return_url": { "type": "string", "format": "uri" },
                  "description": { "type": "string" },
                  "payment_method": { "type": "string", "enum": ["card", "boleto"] },
                  "payer": { "$ref": "#/components/schemas/Payer" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Checkout hospedado criado" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "502": { "description": "Falha ao criar checkout" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }
    },
    "schemas": {
      "Payer": {
        "type": "object",
        "required": ["name", "email", "document"],
        "properties": {
          "name": { "type": "string" },
          "email": { "type": "string", "format": "email" },
          "document": { "type": "string", "description": "CPF ou CNPJ, com ou sem pontuação" },
          "address": { "$ref": "#/components/schemas/BrazilAddress" }
        }
      },
      "BrazilAddress": {
        "type": "object",
        "required": ["street_name", "street_number", "neighborhood", "city", "state", "zip_code"],
        "properties": {
          "street_name": { "type": "string" },
          "street_number": { "type": "string" },
          "neighborhood": { "type": "string" },
          "city": { "type": "string" },
          "state": { "type": "string", "minLength": 2, "maxLength": 2 },
          "zip_code": { "type": "string", "pattern": "^\\d{8}$" }
        }
      }
    },
    "responses": {
      "BadRequest": { "description": "Campos inválidos" },
      "Unauthorized": { "description": "JWT ausente ou inválido" },
      "RateLimited": { "description": "Limite por usuário excedido; aguarde o intervalo indicado por Retry-After" }
    }
  }
}