{"openapi":"3.1.0","info":{"title":"Constaia API","version":"1.0.0","description":"Valida, clasifica y extrae datos de documentos con IA. UE y retención cero por defecto.\n\nErrores: `{ error: { type, code, message, param, request_id } }`. Cabecera `X-Request-Id` siempre.\n\nModo test: con una clave `ck_test_…` la respuesta depende del nombre del fichero (`dni_valid.jpg`, `dni_expired.jpg`, `nie.jpg`, `passport.jpg`, `medical_certificate.pdf`, `blurry.jpg`…).","contact":{"name":"Constaia","url":"https://constaia.com","email":"hola@constaia.com"}},"servers":[{"url":"https://api.constaia.com"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"`ck_live_…` (modo real, consume créditos) o `ck_test_…` (modo test, determinista y gratis)."}},"schemas":{"Analysis":{"type":"object","properties":{"id":{"type":"string","example":"an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2"},"object":{"type":"string","enum":["analysis"]},"status":{"type":"string","enum":["queued","processing","completed","failed"]},"livemode":{"type":"boolean"},"batch_id":{"type":"string"},"created_at":{"type":"string"},"completed_at":{"type":["string","null"]},"file":{"type":"object","properties":{"name":{"type":"string"},"mime_type":{"type":["string","null"]},"pages":{"type":"integer"},"size_bytes":{"type":"integer"}},"required":["name","mime_type","pages","size_bytes"]},"document":{"$ref":"#/components/schemas/DetectedDocument"},"verdict":{"$ref":"#/components/schemas/Verdict"},"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Field"}},"checks":{"type":"array","items":{"$ref":"#/components/schemas/CheckResult"}},"warnings":{"type":"array","items":{"type":"string","enum":["low_quality","blurry","cropped","glare","screen_photo_suspected","photocopy_suspected","edited_suspected","multiple_documents","side_missing","language_mismatch"]}},"signature":{"$ref":"#/components/schemas/PdfSignature"},"exports":{"type":"object","additionalProperties":{"type":"string"}},"storage":{"type":"object","properties":{"mode":{"type":"string","enum":["none","temporary","persistent"]},"file_deleted_at":{"type":["string","null"]},"expires_at":{"type":["string","null"]}},"required":["mode","file_deleted_at","expires_at"]},"processing":{"$ref":"#/components/schemas/Processing"},"usage":{"type":"object","properties":{"credits":{"type":"number"},"pages":{"type":"integer"}},"required":["credits","pages"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["id","object","status","livemode","created_at","completed_at","file","document","verdict","fields","checks","warnings","signature","exports","storage","processing","usage","metadata"]},"DetectedDocument":{"type":["object","null"],"properties":{"type":{"type":"string","example":"es_dni"},"label":{"type":"string","example":"DNI (España)"},"confidence":{"type":"number","example":0.97},"side":{"type":["string","null"],"enum":["front","back","both",null]},"country":{"type":["string","null"],"example":"ESP"}},"required":["type","label","confidence","side","country"]},"Verdict":{"type":["object","null"],"properties":{"expected":{"type":"array","items":{"type":"string"}},"match":{"type":"boolean"},"status":{"type":"string","enum":["valid","invalid","review"]},"reasons":{"type":"array","items":{"$ref":"#/components/schemas/Reason"}}},"required":["expected","match","status","reasons"]},"Reason":{"type":"object","properties":{"code":{"type":"string","example":"not_expired"},"severity":{"type":"string","enum":["info","warning","error"]},"message":{"type":"string","example":"Vigente hasta el 12/03/2031."}},"required":["code","severity","message"]},"Field":{"type":"object","properties":{"value":{},"confidence":{"type":"number"},"validated":{"type":["boolean","null"]},"source":{"type":["object","null"],"properties":{"page":{"type":"integer"},"bbox":{"type":["array","null"],"items":{"type":"number"}}},"required":["page","bbox"]}},"required":["confidence","validated","source"]},"CheckResult":{"type":"object","properties":{"code":{"type":"string"},"passed":{"type":"boolean"},"message":{"type":"string"}},"required":["code","passed","message"]},"PdfSignature":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["valid","invalid","missing","untrusted","modified"]},"reasons":{"type":"array","items":{"type":"string"}},"signer":{"type":["string","null"]},"issuer":{"type":["string","null"]},"signed_at":{"type":["string","null"]},"trusted":{"type":"boolean"},"trust_anchor":{"type":["string","null"]},"signatures":{"type":"integer"}},"required":["status","reasons","signer","issuer","signed_at","trusted","trust_anchor","signatures"],"description":"Firma electrónica PAdES del PDF (null si no es un PDF)."},"Processing":{"type":["object","null"],"properties":{"profile":{"type":"string","enum":["sovereign","standard"],"description":"`sovereign`: solo proveedores con sede y operación en la UE; `standard`: Bedrock eu-central-1 / Vertex UE."},"region":{"type":"string","enum":["eu","us"]},"mode":{"type":"string","enum":["vlm","ocr+llm"]},"providers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"openai_compat"},"region":{"type":"string","example":"de-fra"},"role":{"type":"string","enum":["ocr","llm","local"]},"model":{"type":"string"}},"required":["name","region","role"]}}},"required":["profile","region","mode","providers"],"description":"Qué proveedores y en qué región se procesó el documento."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request","authentication","permission","not_found","insufficient_credits","rate_limited","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"request_id":{"type":"string"}},"required":["type","code","message","request_id"]}},"required":["error"]},"AnalyzeMultipartRequest":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"JPEG, PNG, WEBP, HEIC o PDF (máx. 20 MB)."},"options":{"type":"string","description":"Opciones en JSON (ver AnalyzeOptions).","example":"{\"expect\":\"es_dni\"}"}}},"AnalyzeJsonRequest":{"type":"object","properties":{"file_url":{"type":"string","format":"uri","description":"URL https del documento (máx. 20 MB)."},"file_base64":{"type":"string","description":"Documento en base64 (requiere filename)."},"filename":{"type":"string","example":"dni.jpg"},"options":{"$ref":"#/components/schemas/AnalyzeOptions"}}},"AnalyzeOptions":{"type":"object","properties":{"expect":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":20}]},"extract":{"anyOf":[{"type":"boolean"},{"type":"object","additionalProperties":{}}],"default":true},"checks":{"$ref":"#/components/schemas/Checks"},"storage":{"type":"string","enum":["none","temporary","persistent"]},"ttl_hours":{"type":"integer","minimum":1,"maximum":720},"keep_results":{"type":"boolean","default":true},"async":{"type":"boolean","default":false},"export":{"type":"array","items":{"type":"string","enum":["json","csv","xlsx","xml","vcard","pdf"]},"maxItems":6,"default":[]},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"default":{}},"language":{"type":"string","enum":["es","en","pt","fr"],"default":"es"},"processing":{"type":"string","enum":["sovereign","standard"],"description":"Perfil de procesamiento: `sovereign` (solo proveedores con sede y operación en la UE) o `standard` (Bedrock eu-central-1 / Vertex UE). Por defecto, el de la cuenta."},"precise_bboxes":{"type":"boolean","default":false,"description":"Fuerza OCR + LLM para obtener cajas (bbox) finas por campo."}},"additionalProperties":false,"description":"Opciones. También se aceptan en la raíz del cuerpo."},"Checks":{"type":"object","properties":{"not_expired":{"type":"boolean","description":"La fecha de caducidad es posterior a hoy (o a reference_date)."},"reference_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"max_age_days":{"type":"integer","minimum":0,"maximum":36500},"min_age_years":{"type":"integer","minimum":0,"maximum":150},"max_age_years":{"type":"integer","minimum":0,"maximum":150},"holder":{"$ref":"#/components/schemas/HolderCheck"},"require_fields":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":50},"require_signature":{"type":"boolean"},"require_stamp":{"type":"boolean"},"require_valid_signature":{"type":"boolean","description":"El PDF debe llevar una firma electrónica íntegra de un emisor de confianza (certificados PAdES)."},"expected_amount":{"type":"number","description":"payment_receipt / invoice"},"expected_iban":{"type":"string","maxLength":40},"expected_reference":{"type":"string","maxLength":140}},"default":{},"additionalProperties":false},"HolderCheck":{"type":"object","properties":{"full_name":{"type":"string","maxLength":200},"first_name":{"type":"string","maxLength":100},"last_name":{"type":"string","maxLength":150},"document_number":{"type":"string","maxLength":40},"birth_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"additionalProperties":false},"Classification":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["classification"]},"status":{"type":"string","enum":["queued","processing","completed","failed"]},"livemode":{"type":"boolean"},"created_at":{"type":"string"},"completed_at":{"type":["string","null"]},"file":{"type":"object","properties":{"name":{"type":"string"},"mime_type":{"type":["string","null"]},"pages":{"type":"integer"},"size_bytes":{"type":"integer"}},"required":["name","mime_type","pages","size_bytes"]},"document":{"type":["object","null"],"properties":{"type":{"type":"string"},"label":{"type":"string"},"confidence":{"type":"number"}},"required":["type","label","confidence"]},"candidates":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"confidence":{"type":"number"}},"required":["type","confidence"]}},"verdict":{"$ref":"#/components/schemas/Verdict"},"warnings":{"type":"array","items":{"type":"string"}},"processing":{"$ref":"#/components/schemas/Processing"},"usage":{"type":"object","properties":{"credits":{"type":"number"},"pages":{"type":"integer"}},"required":["credits","pages"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["id","object","status","livemode","created_at","completed_at","file","document","candidates","verdict","warnings","processing","usage","metadata"]},"AnalysisList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Analysis"}},"has_more":{"type":"boolean"},"url":{"type":"string"}},"required":["object","data","has_more","url"]},"Batch":{"type":"object","properties":{"id":{"type":"string","example":"bat_01J9Z8Q3K4M5N6P7Q8R9S0T1V2"},"object":{"type":"string","enum":["batch"]},"status":{"type":"string","enum":["processing","completed"]},"livemode":{"type":"boolean"},"total":{"type":"integer"},"counts":{"type":"object","additionalProperties":{"type":"integer"}},"analyses":{"type":"array","items":{"type":"string"}},"exports":{"type":"object","additionalProperties":{"type":"string"}},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"created_at":{"type":"string"},"completed_at":{"type":["string","null"]}},"required":["id","object","status","livemode","total","counts","analyses","exports","metadata","created_at","completed_at"]},"DocumentTypeList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/DocumentType"}},"has_more":{"type":"boolean"},"total":{"type":"integer"},"url":{"type":"string"}},"required":["object","data","has_more","total","url"]},"DocumentType":{"type":"object","properties":{"object":{"type":"string","enum":["document_type"]},"type":{"type":"string","example":"es_dni"},"label":{"type":"string"},"labels":{"type":"object","additionalProperties":{"type":"string"}},"description":{"type":"string"},"descriptions":{"type":"object","additionalProperties":{"type":"string"}},"category":{"type":"string","example":"identity"},"countries":{"type":"array","items":{"type":"string"},"description":"ISO 3166-1 alfa-3 o `*`."},"slug":{"type":"string"},"slugs":{"type":"object","additionalProperties":{"type":"string"}},"fields":{"type":"array","items":{"type":"string"}},"schema":{"type":"object","additionalProperties":{}},"validators":{"type":"array","items":{"type":"string"}},"field_validators":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"scheme":{"type":"string"}},"required":["field","scheme"]}},"checks":{"type":"array","items":{"type":"string"}},"expiry_check_default":{"type":"boolean"},"mrz":{"type":["string","null"],"enum":["TD1","TD2","TD3","any",null]},"signed_pdf":{"type":"boolean"},"i9_lists":{"type":["array","null"],"items":{"type":"string","enum":["A","B","C"]}}},"required":["object","type","label","labels","description","descriptions","category","countries","slug","slugs","fields","schema","validators","field_validators","checks","expiry_check_default","mrz","signed_pdf","i9_lists"]},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string","example":"we_01J9Z8Q3K4M5N6P7Q8R9S0T1V2"},"object":{"type":"string","enum":["webhook_endpoint"]},"url":{"type":"string"},"description":{"type":["string","null"]},"events":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","disabled"]},"enabled":{"type":"boolean"},"mode":{"type":"string","enum":["live","test"],"description":"Solo recibe eventos de este modo."},"created_at":{"type":"string"},"secret":{"type":"string","description":"Solo en la respuesta de creación.","example":"whsec_…"}},"required":["id","object","url","description","events","status","enabled","mode","created_at"]},"WebhookEndpointList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"has_more":{"type":"boolean"},"url":{"type":"string"}},"required":["object","data","has_more","url"]},"Balance":{"type":"object","properties":{"object":{"type":"string","enum":["balance"]},"credits_available":{"type":"number"},"credits_reserved":{"type":"number"},"free_tier_remaining":{"type":"number"},"credits_spendable":{"type":"number","description":"credits_available + free_tier_remaining (lo que se puede gastar)."},"free_tier_resets_at":{"type":"string"}},"required":["object","credits_available","credits_reserved","free_tier_remaining","credits_spendable","free_tier_resets_at"]},"Usage":{"type":"object","properties":{"object":{"type":"string","enum":["usage"]},"from":{"type":"string"},"to":{"type":"string"},"livemode":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"type":{"type":"string"},"kind":{"type":"string"},"count":{"type":"number"},"pages":{"type":"number"},"credits":{"type":"number"}},"required":["date","type","kind","count","pages","credits"]}},"totals":{"type":"object","properties":{"count":{"type":"number"},"pages":{"type":"number"},"credits":{"type":"number"}},"required":["count","pages","credits"]}},"required":["object","from","to","livemode","data","totals"]}},"parameters":{}},"paths":{"/v1/analyze":{"post":{"tags":["Análisis"],"summary":"Analizar un documento","description":"Clasifica, extrae y valida. Con `expect` devuelve veredicto `valid`/`invalid`/`review`. Síncrono hasta 30 s; después pasa a asíncrono (202).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Misma clave + mismo cuerpo en 24 h → misma respuesta, sin doble cobro."},"required":false,"description":"Misma clave + mismo cuerpo en 24 h → misma respuesta, sin doble cobro.","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/AnalyzeMultipartRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/AnalyzeJsonRequest"}}}},"responses":{"200":{"description":"Resultado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Analysis"}}}},"202":{"description":"En cola (async o > 30 s)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Analysis"}}}},"400":{"description":"Petición no válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave de API o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Créditos insuficientes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Parámetros no válidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Demasiadas peticiones","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/classify":{"post":{"tags":["Análisis"],"summary":"Clasificar un documento (0,2 créditos)","description":"Solo clasifica. Acepta `expect` para obtener veredicto de tipo.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Misma clave + mismo cuerpo en 24 h → misma respuesta, sin doble cobro."},"required":false,"description":"Misma clave + mismo cuerpo en 24 h → misma respuesta, sin doble cobro.","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/AnalyzeMultipartRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/AnalyzeJsonRequest"}}}},"responses":{"200":{"description":"Resultado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Classification"}}}},"202":{"description":"En cola (async o > 30 s)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Classification"}}}},"400":{"description":"Petición no válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave de API o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Créditos insuficientes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Parámetros no válidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Demasiadas peticiones","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/analyses":{"get":{"tags":["Análisis"],"summary":"Listar análisis","description":"Paginación por cursor (`starting_after`). Filtros: `status`, `type`, `metadata[clave]=valor`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"starting_after","in":"query"},{"schema":{"type":"string","enum":["queued","processing","completed","failed"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"type","in":"query"}],"responses":{"200":{"description":"Lista","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalysisList"}}}},"400":{"description":"Petición no válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave de API o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Créditos insuficientes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Parámetros no válidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Demasiadas peticiones","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/analyses/{id}":{"get":{"tags":["Análisis"],"summary":"Recuperar un análisis","description":"Solo si se guardaron resultados (`keep_results: true`).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Análisis","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Analysis"}}}},"400":{"description":"Petición no válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave de API o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Créditos insuficientes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Parámetros no válidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Demasiadas peticiones","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Análisis"],"summary":"Borrar un análisis","description":"Borra el fichero, los resultados y las exportaciones.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Borrado","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","object","deleted"]}}}},"400":{"description":"Petición no válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave de API o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Créditos insuficientes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Parámetros no válidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Demasiadas peticiones","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/analyses/{id}/export":{"get":{"tags":["Análisis"],"summary":"Descargar la exportación de un análisis","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["json","csv","xlsx","xml","vcard","pdf"],"default":"json"},"required":false,"name":"format","in":"query"}],"responses":{"200":{"description":"Fichero (json, csv, xlsx, xml, vcard o pdf)"},"400":{"description":"Petición no válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave de API o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Créditos insuficientes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Parámetros no válidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Demasiadas peticiones","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/batches":{"post":{"tags":["Lotes"],"summary":"Crear un lote (hasta 100 documentos, siempre asíncrono)","description":"`multipart/form-data` con `files[]` (y `options` JSON común) o JSON `{ items: [{ file_url | file_base64 + filename, options }], options }`. Se notifica con `batch.completed`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Misma clave + mismo cuerpo en 24 h → misma respuesta, sin doble cobro."},"required":false,"description":"Misma clave + mismo cuerpo en 24 h → misma respuesta, sin doble cobro.","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"files[]":{"type":"array","items":{"type":"string","format":"binary"}},"options":{"type":"string"}},"required":["files[]"]}},"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"file_url":{"type":"string"},"file_base64":{"type":"string"},"filename":{"type":"string"},"options":{"type":"object","additionalProperties":{}}}}},"options":{"type":"object","additionalProperties":{}}},"required":["items"]}}}},"responses":{"202":{"description":"Lote creado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"400":{"description":"Petición no válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave de API o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Créditos insuficientes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Parámetros no válidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Demasiadas peticiones","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/batches/{id}":{"get":{"tags":["Lotes"],"summary":"Recuperar un lote","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"bat_01J9Z8Q3K4M5N6P7Q8R9S0T1V2"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Lote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"400":{"description":"Petición no válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave de API o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Créditos insuficientes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Parámetros no válidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Demasiadas peticiones","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/document-types":{"get":{"tags":["Catálogo"],"summary":"Catálogo de tipos de documento","description":"Campos, validadores y checks aplicables de cada tipo. No requiere autenticación. Filtros: `country` (ISO alfa-3), `category`, `q` (texto libre); paginación con `limit` y `starting_after` (id de tipo).","parameters":[{"schema":{"type":"string","enum":["es","en","pt","fr"],"default":"es"},"required":false,"name":"language","in":"query"},{"schema":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"Incluye los tipos universales (`*`) salvo con `strict=true`."},"required":false,"description":"Incluye los tipos universales (`*`) salvo con `strict=true`.","name":"country","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"strict","in":"query"},{"schema":{"type":"string","enum":["identity","residence","driving","certificate","health","education","employment","tax","finance","address","legal","vehicle","civil","sports","other"]},"required":false,"name":"category","in":"query"},{"schema":{"type":"string","maxLength":100},"required":false,"name":"q","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":500},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","maxLength":100},"required":false,"name":"starting_after","in":"query"}],"responses":{"200":{"description":"Lista de tipos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentTypeList"}}}},"400":{"description":"Petición no válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave de API o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Créditos insuficientes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Parámetros no válidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Demasiadas peticiones","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/document-types/{type}":{"get":{"tags":["Catálogo"],"summary":"Detalle de un tipo de documento","parameters":[{"schema":{"type":"string","example":"es_dni"},"required":true,"name":"type","in":"path"},{"schema":{"type":"string","enum":["es","en","pt","fr"],"default":"es"},"required":false,"name":"language","in":"query"}],"responses":{"200":{"description":"Tipo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentType"}}}},"404":{"description":"No existe","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook-endpoints":{"post":{"tags":["Webhooks"],"summary":"Crear un endpoint de webhook","description":"Devuelve `secret` (`whsec_…`) una sola vez. Firmas Standard Webhooks.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","maxLength":255,"description":"Misma clave + mismo cuerpo en 24 h → misma respuesta, sin doble cobro."},"required":false,"description":"Misma clave + mismo cuerpo en 24 h → misma respuesta, sin doble cobro.","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["analysis.completed","analysis.failed","analysis.review_required","batch.completed","credits.low","*"]},"minItems":1},"description":{"type":"string","maxLength":500}},"required":["url","events"]}}}},"responses":{"201":{"description":"Creado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"Petición no válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave de API o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Créditos insuficientes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Parámetros no válidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Demasiadas peticiones","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Webhooks"],"summary":"Listar endpoints de webhook","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Lista","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointList"}}}},"400":{"description":"Petición no válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave de API o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Créditos insuficientes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Parámetros no válidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Demasiadas peticiones","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook-endpoints/{id}":{"get":{"tags":["Webhooks"],"summary":"Recuperar un endpoint de webhook","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"we_01J9Z8Q3K4M5N6P7Q8R9S0T1V2"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"Petición no válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave de API o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Créditos insuficientes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Parámetros no válidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Demasiadas peticiones","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Webhooks"],"summary":"Borrar un endpoint de webhook","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"we_01J9Z8Q3K4M5N6P7Q8R9S0T1V2"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Borrado","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","object","deleted"]}}}},"400":{"description":"Petición no válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave de API o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Créditos insuficientes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Parámetros no válidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Demasiadas peticiones","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/balance":{"get":{"tags":["Cuenta"],"summary":"Saldo de créditos","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Saldo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"}}}},"400":{"description":"Petición no válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave de API o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Créditos insuficientes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Parámetros no válidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Demasiadas peticiones","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/usage":{"get":{"tags":["Cuenta"],"summary":"Uso agregado por día y tipo","description":"Por defecto, los últimos 30 días. Solo del modo de la clave (real o test).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"Uso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"400":{"description":"Petición no válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la clave de API o no es válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Créditos insuficientes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Parámetros no válidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Demasiadas peticiones","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/verification-links":{"post":{"tags":["Fase 2"],"summary":"Enlace de verificación alojado (próximamente)","description":"Fase 2: enlace para que el usuario final suba el documento desde el móvil. Hoy responde 501.","security":[{"bearerAuth":[]}],"responses":{"501":{"description":"No implementado todavía","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/files/{id}":{"get":{"tags":["Análisis"],"summary":"Descarga firmada de una exportación","description":"URL con caducidad devuelta en `exports`. No requiere clave.","parameters":[{"schema":{"type":"string","example":"exp_01J9Z8Q3K4M5N6P7Q8R9S0T1V2"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"expires","in":"query"},{"schema":{"type":"string"},"required":true,"name":"sig","in":"query"}],"responses":{"200":{"description":"Fichero"},"404":{"description":"No existe o ha caducado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}