Primeros pasos

Cotiza y emite los productos de tu cuenta desde tus propios sistemas. Todo pedido se autentica con una clave API, opera en sandbox o en producción según la clave, y usa siempre la versión publicada de cada producto.

Claves API

Hay dos tipos de clave y cada una pertenece a un entorno: live (producción) o test (sandbox). La clave completa se muestra una sola vez al crearla; guárdala en un lugar seguro.

Clave	Para qué sirve	Dónde se crea
`sk_live_…` / `sk_test_…`	Integraciones servidor a servidor. Según sus scopes cotiza, emite, lee cotizaciones y pólizas, resuelve condiciones, descarga documentos, reporta consumo o administra la cuenta. Nunca la expongas en un navegador.	En el panel de tu cuenta, sección Claves API.
`pk_live_…` / `pk_test_…`	Widget en sitios públicos (scope `quote`). Cotiza; emite solo sus propias cotizaciones, cada una con el `emissionToken` de un solo uso que trae la cotización (vence a los 30 minutos); sube adjuntos, resuelve campos dinámicos y abre sesiones de embed firmado. El estado de un pago se consulta con su `statusToken`. No puede leer cotizaciones, pólizas ni otros datos de la cuenta.	En el panel de tu cuenta, sección Claves API (tipo Pública).
`pk_…` de intermediario	Clave pública asociada a un intermediario: cotiza como él (su vista y su nivel de comisión) y atribuye la operación.	Las crea la aseguradora para cada intermediario, o el propio intermediario desde su portal.

Scopes de las claves secretas

Scope	Permite
`quote`	Cotizar (`POST /api/quotes`), subir adjuntos (`POST /api/attachments`) y leer cotizaciones y sus documentos (`GET /api/quotes`, `GET /api/quotes/{id}`, `GET /api/quotes/{id}/documents`).
`emit`	Emitir pólizas (`POST /api/policies`) y operar sobre ellas: resolver condiciones, registrar el número de póliza de la aseguradora, reportar consumo y regenerar documentos. Incluye la lectura de pólizas y sus documentos.
`read`	Solo lectura: cotizaciones, pólizas y sus documentos (listar, consultar, descargar y renderizar PDFs).
`admin`	Acceso total: todo lo anterior más la API de administración de la cuenta (productos, recursos compartidos, plantillas de documentos, credenciales de pago, claves API y usuarios).

admin incluye todos los scopes. Una clave puede combinar varios, por ejemplo quote + emit para cotizar y emitir.
Un pedido sin el scope necesario responde 403 con el scope que falta, por ejemplo: La clave API no tiene el scope requerido: "emit" o "admin".
Crea cada clave con los scopes mínimos que necesita tu integración.

Una clave con scope admin da acceso completo a tu cuenta: productos, credenciales de pago y gestión de claves. Nunca la uses en una integración. Las claves que se crean junto con la cuenta (Live key y Test key) tienen scope admin: para integrar, crea claves nuevas con quote, emit o read y guarda las admin solo para administrar la cuenta.

Una clave revocada deja de funcionar al instante (401).
Una clave de intermediario deja de funcionar si el intermediario se desactiva, se bloquea o deja la organización (403).
Solo se guarda un hash de la clave y sus últimos 4 caracteres.

Autenticación

Envía la clave en el header x-api-key en cada pedido. La clave determina la cuenta (tenant) y el entorno: no hace falta indicar ninguno de los dos.

Header de autenticación

curl https://api.quore.app/api/quotes/QUOTE_ID \
  -H "x-api-key: sk_test_…"

401: clave ausente, inválida o revocada.
403: la clave no tiene el scope necesario, es pública y el recurso es de lectura, o pertenece a un intermediario inactivo.

URL base

https://api.quore.app

La URL base es la misma para sandbox y producción: la clave decide el entorno.
Todas las rutas cuelgan de /api, por ejemplo /api/quotes.
Los cuerpos son JSON (Content-Type: application/json), salvo la subida de adjuntos (multipart).
Rutas y claves JSON en inglés; los mensajes de error, en español.

Entornos y numeración

Cada clave pertenece a un entorno: test (sandbox) o live (producción). Una clave solo lee y escribe registros de su entorno.
Un id de otro entorno responde 404; pedir un listado con environment del otro entorno responde 400.
Las pólizas de sandbox se numeran en su propia serie, TEST-POL-0001, TEST-POL-0002…, sin consumir números de producción.
Los cobros de sandbox usan las credenciales de prueba de cada proveedor; nunca las de producción.
Los webhooks también se envían en sandbox: el campo environment del evento indica de cuál se trata.

Límites de pedidos

Las claves públicas (widget y claves de intermediario) tienen límites por IP y por cuenta. Valores por defecto:

Operación	Por IP cada 10 min	Por IP por día	Por cuenta por día
Cotizar (`POST /api/quotes`)	150	1.500	50.000
Emitir (`POST /api/policies`)	30	300	10.000
Resolver campos (`POST /api/products/{id}/field-resolve`)	600	6.000	200.000

Al superar un límite la API responde 429 con el header Retry-After (segundos a esperar).
El widget embebido con identidad firmada se limita por usuario: 30 emisiones cada 10 minutos y 300 por día.
Las subidas de adjuntos con clave pública también tienen su propio límite por IP.
Las claves secretas no usan estos límites del widget: se limitan por clave en el gateway de la API, con un margen amplio pensado para integraciones servidor a servidor.
Los valores pueden ajustarse por instalación. Integra siempre reintentos con espera ante 429.

Versionado

La API cotiza y emite siempre con la versión publicada de cada producto. Los cambios en borrador no afectan a la API hasta que se publican.
Cada cotización queda ligada a la versión con la que se calculó, y se emite con esa misma versión aunque después se publique otra.
La referencia de cada producto se genera en el momento a partir de la versión publicada: se actualiza sola al publicar.
Las rutas de la API no llevan número de versión; los cambios se hacen de forma compatible (se agregan campos, no se quitan).