{
  "openapi": "3.1.0",
  "info": {
    "title": "PlacApi API",
    "version": "1.0.0",
    "description": "API REST para consolidar consultas de información vehicular de Colombia (RUNT, SOAT, tecnomecánica, SIMIT, antecedentes, impuestos, FASECOLDA y pico y placa) y licencias de conducción. PlacApi no es una entidad oficial del Gobierno colombiano.",
    "termsOfService": "https://placapi.com/terminos",
    "contact": {
      "name": "Soporte PlacApi",
      "email": "soporte@placapi.com",
      "url": "https://placapi.com/docs"
    },
    "license": {
      "name": "Términos de PlacApi",
      "url": "https://placapi.com/terminos"
    },
    "x-pricing": {
      "model": "prepaid-credits",
      "pricePerQuery": 499,
      "currency": "COP",
      "note": "Se cobra 1 crédito solo cuando la consulta devuelve datos del vehículo."
    }
  },
  "servers": [
    {
      "url": "https://placapi.com/api",
      "description": "Producción"
    }
  ],
  "paths": {
    "/consulta": {
      "post": {
        "operationId": "consulta",
        "summary": "Consulta vehicular",
        "description": "Vehículo, SOAT, tecnomecánica (RTM), antecedentes, multas SIMIT, impuestos, avalúo Fasecolda y pico y placa — en una sola llamada.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "placa",
                  "docType",
                  "docNumber"
                ],
                "properties": {
                  "placa": {
                    "type": "string",
                    "example": "ABC123"
                  },
                  "docType": {
                    "type": "string",
                    "example": "CC"
                  },
                  "docNumber": {
                    "type": "string",
                    "example": "1020304050"
                  }
                }
              },
              "example": {
                "placa": "ABC123",
                "docType": "CC",
                "docNumber": "1020304050"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Consulta ejecutada. Cada fuente reporta su propio status (ok, empty, error).",
            "content": {
              "application/json": {
                "example": {
                  "vehicle": {
                    "source": "RUNT",
                    "status": "ok",
                    "data": {
                      "placa": "ABC123",
                      "marca": "MAZDA",
                      "linea": "CX-30",
                      "modelo": 2023,
                      "cilindraje": 2000,
                      "combustible": "GASOLINA",
                      "servicio": "PARTICULAR",
                      "clase": "CAMIONETA",
                      "estado": "activo"
                    }
                  },
                  "soat": {
                    "status": "ok",
                    "data": {
                      "vigente": true,
                      "aseguradora": "SBS SEGUROS",
                      "fechaVencimiento": "2026-09-19",
                      "diasParaVencer": 71
                    }
                  },
                  "rtm": {
                    "status": "ok",
                    "data": {
                      "vigente": true,
                      "exento": false,
                      "fechaVencimiento": "2026-09-22",
                      "diasParaVencer": 74
                    }
                  },
                  "antecedentes": {
                    "status": "ok",
                    "data": {
                      "prendas": 0,
                      "embargos": 0,
                      "historicoPropietarios": 2
                    }
                  },
                  "simit": {
                    "status": "ok",
                    "data": {
                      "tieneMultas": false,
                      "totalDeuda": 0
                    }
                  },
                  "picoYPlaca": {
                    "status": "ok",
                    "data": {
                      "hoyAplica": false
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "No autenticado o API key inválida."
          },
          "402": {
            "description": "Sin créditos suficientes."
          },
          "422": {
            "description": "Cuerpo inválido (placa o documento con formato incorrecto)."
          },
          "429": {
            "description": "Rate limit excedido."
          },
          "500": {
            "description": "Error interno."
          },
          "503": {
            "description": "Una o más fuentes oficiales no disponibles."
          }
        }
      }
    },
    "/licencia": {
      "post": {
        "operationId": "licencia",
        "summary": "Licencias de conducción",
        "description": "Licencias de conducción por cédula: categorías, vigencias, suspensiones, multas y paz y salvo.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "docType",
                  "docNumber"
                ],
                "properties": {
                  "docType": {
                    "type": "string",
                    "example": "CC"
                  },
                  "docNumber": {
                    "type": "string",
                    "example": "1020304050"
                  }
                }
              },
              "example": {
                "docType": "CC",
                "docNumber": "1020304050"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Consulta ejecutada. Cada fuente reporta su propio status (ok, empty, error).",
            "content": {
              "application/json": {
                "example": {
                  "persona": {
                    "documento": "1020304050",
                    "nombres": "JUAN",
                    "apellidos": "PÉREZ",
                    "estadoConductor": "ACTIVO"
                  },
                  "licencias": [
                    {
                      "numeroLicencia": "1020304050",
                      "organismoExpide": "INSTITUTO DE MOVILIDAD",
                      "estado": "ACTIVA",
                      "suspendida": false,
                      "categorias": [
                        {
                          "categoria": "B1",
                          "fechaVencimiento": "2035-04-23"
                        }
                      ]
                    }
                  ],
                  "multas": {
                    "tieneMultas": false,
                    "pazYSalvo": "885466652067"
                  },
                  "vigente": true
                }
              }
            }
          },
          "401": {
            "description": "No autenticado o API key inválida."
          },
          "402": {
            "description": "Sin créditos suficientes."
          },
          "422": {
            "description": "Cuerpo inválido (placa o documento con formato incorrecto)."
          },
          "429": {
            "description": "Rate limit excedido."
          },
          "500": {
            "description": "Error interno."
          },
          "503": {
            "description": "Una o más fuentes oficiales no disponibles."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ]
}