{
  "openapi": "3.1.0",
  "info": {
    "title": "EvePay",
    "version": "1.0.0",
    "description": "Pasarela de pagos para Colombia. Esta especificación cubre lo que alcanza la llave de un comercio; los endpoints de la operación interna de EvePay no están aquí.",
    "contact": {
      "url": "https://docs.evetev.com"
    }
  },
  "servers": [
    {
      "url": "https://api.evetev.com/v1"
    }
  ],
  "security": [
    {
      "llaveDeComercio": []
    }
  ],
  "components": {
    "securitySchemes": {
      "llaveDeComercio": {
        "type": "http",
        "scheme": "bearer",
        "description": "La llave del comercio, que empieza por evpk_. Va en el servidor, nunca en el navegador."
      }
    },
    "schemas": {
      "CrearCobro": {
        "type": "object",
        "required": [
          "merchantId",
          "montoMinor",
          "moneda",
          "referencia"
        ],
        "properties": {
          "merchantId": {
            "type": "string",
            "format": "uuid",
            "description": "Tu comercio. Sale del id de GET /v1/merchants/me y no cambia."
          },
          "montoMinor": {
            "type": "integer",
            "minimum": 1,
            "example": 89000,
            "description": "El monto en la unidad mínima de la moneda. En COP son pesos: $ 89.000 es 89000."
          },
          "moneda": {
            "type": "string",
            "enum": [
              "COP",
              "USD"
            ],
            "description": "Hoy solo se transa en COP; USD existe en el contrato pero ninguna pasarela lo procesa todavía."
          },
          "referencia": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120,
            "description": "Tu propio identificador del pedido. Es con lo que vas a conciliar de tu lado."
          },
          "descripcion": {
            "type": "string",
            "maxLength": 255,
            "description": "Lo que el comprador ve en la pantalla de pago."
          },
          "urlRetorno": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://",
            "maxLength": 2048,
            "description": "A dónde vuelve este comprador. Tiene que ser de tu sitio registrado o de un subdominio suyo. Si no la mandas, se usa la que registraste en Ajustes."
          },
          "pagador": {
            "type": "object",
            "description": "Datos de quien paga, para cobrar sin que salga de tu web. Si no lo mandas —el caso normal— el cobro devuelve la página de pago alojada."
          }
        }
      },
      "Cobro": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "merchantId": {
            "type": "string",
            "format": "uuid"
          },
          "montoMinor": {
            "type": "integer"
          },
          "moneda": {
            "type": "string",
            "enum": [
              "COP",
              "USD"
            ]
          },
          "referencia": {
            "type": "string"
          },
          "estado": {
            "type": "string",
            "enum": [
              "creado",
              "pendiente",
              "aprobado",
              "fallido",
              "conciliado",
              "reembolsado"
            ]
          },
          "checkoutUrl": {
            "type": "string",
            "format": "uri",
            "description": "A dónde mandar al comprador para que pague."
          },
          "creadoEn": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  },
  "paths": {
    "/pagos": {
      "post": {
        "summary": "Crear un cobro",
        "description": "Devuelve un checkoutUrl al que hay que mandar al comprador. El pedido NO se despacha aquí: se despacha cuando llega el webhook payment.completed.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Obligatorio. Con la misma clave, un reintento devuelve el cobro que ya existía en vez de crear otro."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CrearCobro"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "El cobro, con su checkoutUrl.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Cobro"
                }
              }
            }
          },
          "400": {
            "description": "Falta la clave de idempotencia, o algún campo es inválido."
          },
          "409": {
            "description": "El comercio no tiene registrado su sitio y su página de retorno, o no está aprobado, o la clave de idempotencia ya se usó con otro cuerpo."
          },
          "503": {
            "description": "La pasarela no respondió. Reintentar con la misma clave."
          }
        }
      },
      "get": {
        "summary": "Listar cobros",
        "responses": {
          "200": {
            "description": "Una página de cobros."
          }
        }
      }
    },
    "/pagos/{id}": {
      "get": {
        "summary": "Consultar un cobro",
        "description": "El estado real de un cobro. Es la fuente de verdad si el webhook no llegó.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "El cobro.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Cobro"
                }
              }
            }
          },
          "404": {
            "description": "No existe o no es de este comercio."
          }
        }
      }
    },
    "/merchants/me": {
      "get": {
        "summary": "Tu comercio",
        "description": "De aquí sale el merchantId que lleva cada cobro.",
        "responses": {
          "200": {
            "description": "Los datos del comercio."
          }
        }
      }
    },
    "/merchants/me/registro-web": {
      "get": {
        "summary": "Tu sitio y tu página de retorno",
        "responses": {
          "200": {
            "description": "Lo registrado; en nulos si falta configurarlo."
          }
        }
      },
      "put": {
        "summary": "Registrar el sitio y la página de retorno",
        "description": "Sin esto no se puede cobrar. La página de retorno debe ser del dominio del sitio o de un subdominio suyo.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "sitioWeb",
                  "urlRetorno"
                ],
                "properties": {
                  "sitioWeb": {
                    "type": "string",
                    "format": "uri",
                    "pattern": "^https://"
                  },
                  "urlRetorno": {
                    "type": "string",
                    "format": "uri",
                    "pattern": "^https://"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Guardado."
          },
          "400": {
            "description": "Alguna no es https, o la de retorno no es del sitio."
          }
        }
      }
    },
    "/webhook-endpoint": {
      "post": {
        "summary": "Registrar el endpoint de avisos",
        "description": "Devuelve el secreto de la firma UNA sola vez.",
        "responses": {
          "201": {
            "description": "Registrado, con el secreto."
          }
        }
      },
      "get": {
        "summary": "El endpoint registrado",
        "responses": {
          "200": {
            "description": "La configuración."
          }
        }
      },
      "put": {
        "summary": "Cambiarlo o desactivarlo",
        "responses": {
          "200": {
            "description": "Actualizado."
          }
        }
      }
    }
  }
}