{"openapi":"3.1.0","info":{"title":"Constaia API","version":"1.0.0","description":"API europea para validar, clasificar y extraer datos de documentos. Fichero de EJEMPLO generado a partir de docs/SPEC.md; la referencia oficial es https://api.constaia.com/openapi.json.","contact":{"email":"hola@constaia.com","url":"https://constaia.com"}},"servers":[{"url":"https://api.constaia.com","description":"Producción (UE)"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Analyses"},{"name":"Classification"},{"name":"Batches"},{"name":"Document types"},{"name":"Webhooks"},{"name":"Billing"}],"paths":{"/v1/analyze":{"post":{"tags":["Analyses"],"operationId":"analyze","summary":"Analiza un documento y devuelve veredicto, campos y checks","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Misma clave + mismo cuerpo en 24 h → misma respuesta, sin doble cobro."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"options":{"type":"string","description":"JSON con AnalyzeOptions"}}}},"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AnalyzeOptions"},{"type":"object","properties":{"file_url":{"type":"string","format":"uri"},"file_base64":{"type":"string"},"filename":{"type":"string"}}}]}}}},"responses":{"200":{"description":"Análisis completado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Analysis"}}}},"202":{"description":"En cola (async)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Analysis"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/v1/classify":{"post":{"tags":["Classification"],"operationId":"classify","summary":"Solo clasifica el documento (0,2 créditos)","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Misma clave + mismo cuerpo en 24 h → misma respuesta, sin doble cobro."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"options":{"type":"string","description":"JSON con AnalyzeOptions"}}}},"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AnalyzeOptions"},{"type":"object","properties":{"file_url":{"type":"string","format":"uri"},"file_base64":{"type":"string"},"filename":{"type":"string"}}}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Classification"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/v1/analyses":{"get":{"tags":["Analyses"],"operationId":"listAnalyses","summary":"Lista análisis (paginada)","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Lista","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Analysis"}},"has_more":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/v1/analyses/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Analyses"],"operationId":"getAnalysis","summary":"Recupera un análisis (si keep_results)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Analysis"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Analyses"],"operationId":"deleteAnalysis","summary":"Borra fichero y resultados","responses":{"200":{"description":"Borrado","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"const":true}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/v1/analyses/{id}/export":{"get":{"tags":["Analyses"],"operationId":"exportAnalysis","summary":"Descarga directa de una exportación","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","required":true,"schema":{"type":"string","enum":["json","csv","xlsx","xml","vcard","pdf"]}}],"responses":{"200":{"description":"Fichero"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/v1/batches":{"post":{"tags":["Batches"],"operationId":"createBatch","summary":"Crea un lote de hasta 100 documentos (siempre async)","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Misma clave + mismo cuerpo en 24 h → misma respuesta, sin doble cobro."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"files[]":{"type":"array","items":{"type":"string","format":"binary"}},"options":{"type":"string"}}}},"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","maxItems":100,"items":{"type":"object","properties":{"file_url":{"type":"string","format":"uri"},"options":{"$ref":"#/components/schemas/AnalyzeOptions"}}}}}}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/v1/batches/{id}":{"get":{"tags":["Batches"],"operationId":"getBatch","summary":"Estado de un lote","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/v1/document-types":{"get":{"tags":["Document types"],"operationId":"listDocumentTypes","summary":"Catálogo de tipos con campos y checks","responses":{"200":{"description":"Catálogo"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/v1/document-types/{type}":{"get":{"tags":["Document types"],"operationId":"getDocumentType","summary":"Detalle de un tipo","parameters":[{"name":"type","in":"path","required":true,"schema":{"$ref":"#/components/schemas/DocumentType"}}],"responses":{"200":{"description":"Tipo"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/v1/webhook-endpoints":{"post":{"tags":["Webhooks"],"operationId":"createWebhookEndpoint","summary":"Alta de un endpoint de webhook (devuelve el secret whsec_ una vez)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["analysis.completed","analysis.failed","analysis.review_required","batch.completed","credits.low"]}}}}}}},"responses":{"200":{"description":"Creado"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}},"get":{"tags":["Webhooks"],"operationId":"listWebhookEndpoints","summary":"Lista endpoints","responses":{"200":{"description":"Lista"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/v1/webhook-endpoints/{id}":{"delete":{"tags":["Webhooks"],"operationId":"deleteWebhookEndpoint","summary":"Borra un endpoint","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Borrado"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/v1/balance":{"get":{"tags":["Billing"],"operationId":"getBalance","summary":"Créditos disponibles, reservados y plan gratis","responses":{"200":{"description":"Saldo","content":{"application/json":{"schema":{"type":"object","properties":{"credits_available":{"type":"number"},"credits_reserved":{"type":"number"},"free_tier_remaining":{"type":"number"},"free_tier_resets_at":{"type":"string","format":"date-time"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/v1/usage":{"get":{"tags":["Billing"],"operationId":"getUsage","summary":"Uso agregado por día y tipo","parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Uso"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"ck_live_… (real) o ck_test_… (modo test)"}},"responses":{"Error":{"description":"Error","headers":{"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"DocumentType":{"type":"string","enum":["es_dni","es_nie","passport","eu_id_card","es_driving_license","medical_certificate_sport","es_sexual_offences_certificate","es_criminal_record_certificate","sports_license","coach_qualification","insurance_certificate","payment_receipt","bank_ownership_certificate","invoice","es_disability_certificate","es_census_certificate","es_family_book","generic"]},"AnalyzeOptions":{"type":"object","properties":{"expect":{"oneOf":[{"$ref":"#/components/schemas/DocumentType"},{"type":"array","items":{"$ref":"#/components/schemas/DocumentType"}}]},"extract":{"oneOf":[{"type":"boolean"},{"type":"object","description":"JSON Schema propio"}],"default":true},"checks":{"$ref":"#/components/schemas/Checks"},"storage":{"type":"string","enum":["none","temporary","persistent"],"default":"none"},"ttl_hours":{"type":"integer","minimum":1,"maximum":720,"default":24},"keep_results":{"type":"boolean","default":true},"async":{"type":"boolean","default":false},"export":{"type":"array","items":{"type":"string","enum":["json","csv","xlsx","xml","vcard","pdf"]}},"metadata":{"type":"object","additionalProperties":{"type":"string"},"maxProperties":20},"language":{"type":"string","enum":["es","en","pt","fr"],"default":"es"}}},"Checks":{"type":"object","properties":{"not_expired":{"type":"boolean"},"reference_date":{"type":"string","format":"date"},"max_age_days":{"type":"integer"},"min_age_years":{"type":"integer"},"max_age_years":{"type":"integer"},"holder":{"type":"object","properties":{"full_name":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"document_number":{"type":"string"},"birth_date":{"type":"string","format":"date"}}},"require_fields":{"type":"array","items":{"type":"string"}},"require_signature":{"type":"boolean"},"require_stamp":{"type":"boolean"},"expected_amount":{"type":"number"},"expected_iban":{"type":"string"},"expected_reference":{"type":"string"}}},"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":{"type":"object","properties":{"code":{"type":"string"},"severity":{"type":"string","enum":["info","warning","error"]},"message":{"type":"string"}}}}}},"Field":{"type":"object","properties":{"value":{},"confidence":{"type":"number"},"validated":{"type":["boolean","null"]},"source":{"type":"object","properties":{"page":{"type":"integer"},"bbox":{"type":"array","items":{"type":"number"},"minItems":4,"maxItems":4}}}}},"Analysis":{"type":"object","properties":{"id":{"type":"string","examples":["an_01J…"]},"object":{"const":"analysis"},"status":{"type":"string","enum":["queued","processing","completed","failed"]},"livemode":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"file":{"type":"object","properties":{"name":{"type":"string"},"mime_type":{"type":"string"},"pages":{"type":"integer"},"size_bytes":{"type":"integer"}}},"document":{"type":"object","properties":{"type":{"type":"string"},"label":{"type":"string"},"confidence":{"type":"number"},"side":{"type":"string"},"country":{"type":"string"}}},"verdict":{"$ref":"#/components/schemas/Verdict"},"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Field"}},"checks":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"passed":{"type":"boolean"},"message":{"type":"string"}}}},"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"]}},"exports":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"storage":{"type":"object","properties":{"mode":{"type":"string"},"file_deleted_at":{"type":["string","null"]},"expires_at":{"type":["string","null"]}}},"usage":{"type":"object","properties":{"credits":{"type":"number"},"pages":{"type":"integer"}}},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"Classification":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"classification"},"document":{"type":"object","properties":{"type":{"type":"string"},"label":{"type":"string"},"confidence":{"type":"number"}}},"candidates":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"confidence":{"type":"number"}}}},"verdict":{"$ref":"#/components/schemas/Verdict"}}},"Batch":{"type":"object","properties":{"id":{"type":"string","examples":["bat_01J…"]},"object":{"const":"batch"},"status":{"type":"string"}}},"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"}}}}}}}}