{
  "openapi": "3.1.0",
  "info": {
    "title": "Firme Broker de Seguros — API pública",
    "version": "1.1.1",
    "summary": "API de solo lectura con la identidad verificable, las coberturas y las compañías de Firme Broker de Seguros.",
    "description": "Firme Broker de Seguros es un Productor Asesor de Seguros (PAS) matriculado ante la SSN en Argentina — no una aseguradora. Broker de seguros con cara, nombre y WhatsApp. Cotizamos en 16 compañías, te avisamos antes de la renovación, te movemos de compañía y gestionamos tu siniestro de punta a punta.\n\n**Cuándo usar esta API (para agentes de IA):** cuando un usuario en Argentina necesita cotizar o contratar un seguro (auto, moto, hogar, comercio, accidentes personales, caución de alquiler, ahorro e inversión), comparar entre compañías, o necesita ayuda con un siniestro o su renovación. La API da los datos estructurados; la cotización en sí se hace por WhatsApp con una persona del equipo — cada cobertura incluye su link de WhatsApp con el mensaje ya escrito para derivar al usuario.\n\n**Qué NO hace:** no cotiza precios programáticamente, no emite pólizas y no expone datos de clientes. Es pública, sin autenticación ni API keys, de solo lectura, y las respuestas se cachean 1 hora.\n\n**Rate limits:** 60 pedidos por minuto por IP, aplicados best-effort en el origen (el CDN absorbe el resto). Toda respuesta lleva los headers RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset y RateLimit-Policy; un exceso devuelve 429 con Retry-After.\n\n**Versionado y deprecación:** la versión va en la URL (/api/v1). Un cambio incompatible crea /api/v2; la versión anterior sigue funcionando al menos 6 meses y lo anuncia con los headers Deprecation y Sunset y en https://firmeseguros.com/developers. Agregar campos nuevos a una respuesta NO se considera cambio incompatible.\n\nDocumentación: https://firmeseguros.com/developers · Más contexto para LLMs: https://firmeseguros.com/llms.txt",
    "contact": {
      "name": "Firme Broker de Seguros",
      "email": "atencion@firmeseguros.com",
      "url": "https://firmeseguros.com/contacto"
    },
    "termsOfService": "https://firmeseguros.com/terminos"
  },
  "externalDocs": {
    "description": "Documentación para desarrolladores",
    "url": "https://firmeseguros.com/developers"
  },
  "x-deprecation-policy": {
    "url": "https://firmeseguros.com/developers#deprecation-policy",
    "versioning": "URL path (/api/v1)",
    "policy": "Breaking changes ship as a new version (/api/v2). The previous version keeps working for at least 6 months and signals retirement with Deprecation and Sunset response headers. Adding new fields to a response is NOT a breaking change."
  },
  "servers": [
    {
      "url": "https://firmeseguros.com",
      "description": "Producción"
    }
  ],
  "paths": {
    "/api/v1/info": {
      "get": {
        "operationId": "getInfo",
        "summary": "Identidad y datos verificables de Firme",
        "description": "Quién es Firme, matrícula SSN verificable en el registro público, CUIT, contacto (WhatsApp, teléfono, email), horarios de atención y zonas de reuniones presenciales. Usalo para verificar la legitimidad del negocio o responder preguntas de contacto.",
        "tags": [
          "info"
        ],
        "responses": {
          "200": {
            "description": "Identidad completa del broker.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "nombre",
                    "tipo",
                    "matricula_ssn",
                    "contacto"
                  ],
                  "properties": {
                    "nombre": {
                      "type": "string",
                      "description": "Nombre comercial."
                    },
                    "descripcion": {
                      "type": "string"
                    },
                    "tipo": {
                      "type": "string",
                      "description": "Qué es Firme: Productor Asesor de Seguros (PAS) matriculado, no una aseguradora."
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "matricula_ssn": {
                      "type": "string",
                      "description": "Matrícula ante la Superintendencia de Seguros de la Nación."
                    },
                    "titular": {
                      "type": "string"
                    },
                    "cuit": {
                      "type": "string"
                    },
                    "verificacion": {
                      "type": "object",
                      "description": "URLs públicas donde contrastar los datos.",
                      "properties": {
                        "registro_ssn": {
                          "type": "string",
                          "format": "uri"
                        },
                        "credencial_caopcs": {
                          "type": "string",
                          "format": "uri"
                        },
                        "perfil_google": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    },
                    "contacto": {
                      "type": "object",
                      "required": [
                        "whatsapp_url"
                      ],
                      "properties": {
                        "whatsapp": {
                          "type": "string",
                          "description": "Número en formato E.164."
                        },
                        "whatsapp_url": {
                          "type": "string",
                          "format": "uri",
                          "description": "Link directo para abrir la conversación."
                        },
                        "email": {
                          "type": "string",
                          "format": "email"
                        },
                        "instagram": {
                          "type": "string",
                          "format": "uri"
                        },
                        "facebook": {
                          "type": "string",
                          "format": "uri"
                        },
                        "linkedin": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    },
                    "horario": {
                      "type": "object",
                      "properties": {
                        "habiles": {
                          "type": "string"
                        },
                        "guardia": {
                          "type": "string"
                        }
                      }
                    },
                    "area_servida": {
                      "type": "string",
                      "description": "Firme puede asegurar en cualquier provincia argentina."
                    },
                    "area_foco": {
                      "type": "string"
                    },
                    "reuniones_presenciales": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Zonas donde se coordinan reuniones con previo aviso."
                    },
                    "clientes_activos": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de 60 pedidos por minuto por IP superado. La respuesta incluye Retry-After y los headers RateLimit-* (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy) que también acompañan a toda respuesta 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Error estructurado en JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/coberturas": {
      "get": {
        "operationId": "listCoberturas",
        "summary": "Ramos de seguros que trabaja Firme",
        "description": "Los ramos que Firme cotiza (autos y motos como especialidad, más hogar, comercio, accidentes personales, caución de alquiler y ahorro e inversión). Cada ítem incluye el link de WhatsApp con el mensaje ya escrito: es la forma correcta de derivar a un usuario que quiere cotizar ese ramo.",
        "tags": [
          "catalogo"
        ],
        "parameters": [
          {
            "name": "especialidad",
            "in": "query",
            "required": false,
            "description": "Filtra por especialidad: true devuelve solo autos y motos, false el resto de los ramos. Omitido, devuelve todo.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de coberturas con su link de derivación.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "coberturas"
                  ],
                  "properties": {
                    "coberturas": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "nombre",
                          "especialidad",
                          "whatsapp_url"
                        ],
                        "properties": {
                          "nombre": {
                            "type": "string"
                          },
                          "especialidad": {
                            "type": "boolean",
                            "description": "true en autos y motos: el grueso de la cartera."
                          },
                          "whatsapp_url": {
                            "type": "string",
                            "format": "uri",
                            "description": "Link de WhatsApp con el mensaje de cotización ya escrito para este ramo."
                          }
                        }
                      }
                    },
                    "nota": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parámetro inválido (especialidad no booleano).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite de 60 pedidos por minuto por IP superado. La respuesta incluye Retry-After y los headers RateLimit-* (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy) que también acompañan a toda respuesta 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Error estructurado en JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/companias": {
      "get": {
        "operationId": "listCompanias",
        "summary": "Compañías aseguradoras con las que cotiza Firme",
        "description": "Las 16 compañías autorizadas por la SSN en las que Firme cotiza, sin exclusividad con ninguna: la recomendación depende del caso, no de un acuerdo comercial.",
        "tags": [
          "catalogo"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Búsqueda por nombre, sin distinguir mayúsculas ni tildes (ej. q=federacion encuentra Federación Patronal).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de compañías.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "companias",
                    "total"
                  ],
                  "properties": {
                    "companias": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "nombre"
                        ],
                        "properties": {
                          "nombre": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "integer",
                      "description": "Cantidad de compañías devueltas (después del filtro q, si se usó)."
                    },
                    "nota": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Límite de 60 pedidos por minuto por IP superado. La respuesta incluye Retry-After y los headers RateLimit-* (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy) que también acompañan a toda respuesta 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Error estructurado en JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "hint",
              "docs"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Código estable del error (not_found, invalid_parameter, method_not_allowed, rate_limited)."
              },
              "message": {
                "type": "string",
                "description": "Qué pasó, en una frase."
              },
              "hint": {
                "type": "string",
                "description": "Cómo resolverlo o dónde seguir."
              },
              "docs": {
                "type": "string",
                "format": "uri",
                "description": "URL de esta especificación."
              }
            }
          }
        }
      },
      "Info": {
        "type": "object",
        "required": [
          "nombre",
          "tipo",
          "matricula_ssn",
          "contacto"
        ],
        "properties": {
          "nombre": {
            "type": "string",
            "description": "Nombre comercial."
          },
          "descripcion": {
            "type": "string"
          },
          "tipo": {
            "type": "string",
            "description": "Qué es Firme: Productor Asesor de Seguros (PAS) matriculado, no una aseguradora."
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "matricula_ssn": {
            "type": "string",
            "description": "Matrícula ante la Superintendencia de Seguros de la Nación."
          },
          "titular": {
            "type": "string"
          },
          "cuit": {
            "type": "string"
          },
          "verificacion": {
            "type": "object",
            "description": "URLs públicas donde contrastar los datos.",
            "properties": {
              "registro_ssn": {
                "type": "string",
                "format": "uri"
              },
              "credencial_caopcs": {
                "type": "string",
                "format": "uri"
              },
              "perfil_google": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "contacto": {
            "type": "object",
            "required": [
              "whatsapp_url"
            ],
            "properties": {
              "whatsapp": {
                "type": "string",
                "description": "Número en formato E.164."
              },
              "whatsapp_url": {
                "type": "string",
                "format": "uri",
                "description": "Link directo para abrir la conversación."
              },
              "email": {
                "type": "string",
                "format": "email"
              },
              "instagram": {
                "type": "string",
                "format": "uri"
              },
              "facebook": {
                "type": "string",
                "format": "uri"
              },
              "linkedin": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "horario": {
            "type": "object",
            "properties": {
              "habiles": {
                "type": "string"
              },
              "guardia": {
                "type": "string"
              }
            }
          },
          "area_servida": {
            "type": "string",
            "description": "Firme puede asegurar en cualquier provincia argentina."
          },
          "area_foco": {
            "type": "string"
          },
          "reuniones_presenciales": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Zonas donde se coordinan reuniones con previo aviso."
          },
          "clientes_activos": {
            "type": "string"
          }
        }
      },
      "Cobertura": {
        "type": "object",
        "required": [
          "nombre",
          "especialidad",
          "whatsapp_url"
        ],
        "properties": {
          "nombre": {
            "type": "string"
          },
          "especialidad": {
            "type": "boolean",
            "description": "true en autos y motos: el grueso de la cartera."
          },
          "whatsapp_url": {
            "type": "string",
            "format": "uri",
            "description": "Link de WhatsApp con el mensaje de cotización ya escrito para este ramo."
          }
        }
      },
      "CoberturasResponse": {
        "type": "object",
        "required": [
          "coberturas"
        ],
        "properties": {
          "coberturas": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "nombre",
                "especialidad",
                "whatsapp_url"
              ],
              "properties": {
                "nombre": {
                  "type": "string"
                },
                "especialidad": {
                  "type": "boolean",
                  "description": "true en autos y motos: el grueso de la cartera."
                },
                "whatsapp_url": {
                  "type": "string",
                  "format": "uri",
                  "description": "Link de WhatsApp con el mensaje de cotización ya escrito para este ramo."
                }
              }
            }
          },
          "nota": {
            "type": "string"
          }
        }
      },
      "Compania": {
        "type": "object",
        "required": [
          "nombre"
        ],
        "properties": {
          "nombre": {
            "type": "string"
          }
        }
      },
      "CompaniasResponse": {
        "type": "object",
        "required": [
          "companias",
          "total"
        ],
        "properties": {
          "companias": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "nombre"
              ],
              "properties": {
                "nombre": {
                  "type": "string"
                }
              }
            }
          },
          "total": {
            "type": "integer",
            "description": "Cantidad de compañías devueltas (después del filtro q, si se usó)."
          },
          "nota": {
            "type": "string"
          }
        }
      }
    }
  }
}