{ "openapi": "3.1.0", "info": { "title": "RipsCloud integration API", "version": "1.0.0", "description": "Production integration contract. This curated view retains production operations that accept personal access tokens plus the public health check. Interactive administration and upstream diagnostics are excluded. Read https://developers.ripscloud.com/guides/quickstart/ before using production. Original production contract: https://api.ripscloud.com/doc" }, "servers": [ { "url": "https://api.ripscloud.com", "description": "Producción" } ], "tags": [ { "name": "Paquetes RIPS", "description": "Guardar, validar y enviar RIPS al Ministerio de Salud. El resultado trae el CUV o las validaciones del Ministerio; un resultado incierto se concilia antes de reenviar." }, { "name": "Facturas de salud", "description": "Emitir por PahFacturar la factura electrónica de salud que acompaña un RIPS y preparar su paquete." }, { "name": "Notas crédito", "description": "Emitir notas crédito de salud por PahFacturar y preparar su RIPS." }, { "name": "Notas débito", "description": "Emitir notas débito de salud por PahFacturar, con servicios RIPS adicionales explícitos, y preparar su paquete ND." }, { "name": "Pacientes", "description": "Pacientes del espacio que se reportan en los RIPS." }, { "name": "Profesionales", "description": "Profesionales de salud que prestan los servicios." }, { "name": "Servicios", "description": "Servicios guardados para reutilizar al armar RIPS." }, { "name": "Pagadores", "description": "Entidades responsables de pago a quienes se emiten las facturas." }, { "name": "Resoluciones", "description": "Resoluciones de numeración de la DIAN para facturas y notas crédito/débito." }, { "name": "Catálogo de medicamentos", "description": "Consulta de los catálogos de medicamentos (CUM e IUM) vigentes." }, { "name": "Espacio", "description": "Datos y resumen del espacio de trabajo." }, { "name": "Mi cuenta", "description": "Perfil del usuario y espacios a los que pertenece." }, { "name": "Estado", "description": "Disponibilidad de la API y conectividad con FEV RIPS y PahFacturar." } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "PAT o JWT", "description": "Para integraciones, cree un PAT en Configuración → Tokens de acceso del portal y envíelo como Authorization: Bearer rc_pat_…. El secreto se muestra una sola vez. El PAT tiene vencimiento, espacios seleccionados y permisos limitados por los del usuario actual. La administración de tokens y del espacio requiere una sesión interactiva OpenAuth; un PAT no sustituye esas funciones." } }, "headers": { "RequestId": { "description": "Identificador de esta solicitud. Inclúyalo al solicitar soporte.", "schema": { "type": "string" }, "example": "11111111-1111-4111-8111-111111111111" }, "CorrelationId": { "description": "Identificador de correlación propagado por el servidor.", "schema": { "type": "string" }, "example": "22222222-2222-4222-8222-222222222222" }, "OperationId": { "description": "Identificador estable del caso de uso ejecutado (operationId).", "schema": { "type": "string" } }, "NoStore": { "description": "Las respuestas de negocio no se deben almacenar en cachés compartidas.", "schema": { "type": "string", "enum": [ "no-store" ] } }, "BearerChallenge": { "description": "Se requiere autenticación Bearer.", "schema": { "type": "string", "enum": [ "Bearer" ] } }, "ResourceRevision": { "description": "Revisión vigente del recurso. Envíe este valor sin cambios en If-Match al crear una revisión. Ejemplo: \"3\".", "schema": { "type": "string", "pattern": "^\"[0-9]+\"$" }, "example": "\"3\"" } }, "schemas": { "Health": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "module": { "type": "string", "enum": [ "ripscloud" ] }, "deployment": { "type": "string", "enum": [ "sandbox", "production" ] }, "fevrips": { "type": "string", "description": "Origen FEV RIPS configurado y verificado para este entorno." }, "pahfacturar": { "type": "string", "description": "Origen PahFacturar configurado y verificado para este entorno." }, "contractVersion": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "status", "module", "deployment", "fevrips", "pahfacturar", "contractVersion", "timestamp" ] }, "ApiError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_json", "duplicate_key", "json_syntax", "json_depth", "json_type", "numeric_value_loss", "numeric_overflow", "conflicting_alias", "request_too_large", "unsupported_media_type", "invalid_request", "invalid_query", "invalid_path", "server_owned_field", "route_not_found", "method_not_allowed", "unauthenticated", "personal_access_token_limit_reached", "personal_access_token_not_allowed", "personal_access_token_scope_required", "personal_access_token_workspace_forbidden", "account_disabled", "phone_identity_retired", "platform_admin_required", "workspace_membership_required", "workspace_admin_required", "global_identity_admin_required", "migration_not_allowed", "authorization_changed", "idempotency_key_required", "idempotency_key_reused", "idempotency_in_progress", "revision_required", "revision_conflict", "workspace_not_found", "not_found", "resource_archived", "duplicate_resource", "invalid_environment", "sandbox_requires_habilitacion", "invalid_phone", "phone_in_use", "user_not_in_workspace", "global_user_disabled", "cannot_remove_last_admin", "membership_update_failed", "invalid_nit", "tenant_nit_mismatch", "sispro_login_failed", "invalid_sispro_token", "sispro_unavailable", "sispro_credentials_missing", "invoice_provider_not_configured", "invoice_provider_company_mismatch", "invoice_provider_unavailable", "upstream_configuration_invalid", "invalid_service_category", "invalid_medication_code", "resolution_number_regression", "invalid_resolution_range", "invalid_input_provenance", "invalid_xlsx_file", "invalid_rips_input", "invalid_package_kind", "attached_document_kind_mismatch", "attached_document_not_found", "attached_document_too_large", "package_validation_failed", "validation_required", "validation_outdated", "reference_not_accepted", "source_package_not_accepted", "source_invoice_mismatch", "credit_balance_exceeded", "credit_total_mismatch", "dispatch_in_progress", "dispatch_conflict", "submission_outcome_unknown", "package_already_accepted", "submission_receipt_missing", "reconciliation_not_applicable", "reconciliation_inconclusive", "invalid_field_profile", "health_document_invalid", "health_document_not_emittable", "health_document_locked", "provider_dispatch_in_progress", "provider_outcome_unknown", "resolution_unavailable", "source_invoice_not_accepted", "source_customer_missing", "source_rips_missing", "debit_note_rips_required", "debit_note_rips_invalid", "debit_note_patient_mismatch", "credit_note_selection_invalid", "document_not_available", "artifact_context_unverified", "artifact_download_failed", "email_disabled", "email_not_configured", "recipient_email_missing", "email_attachment_too_large", "email_outcome_unknown", "email_send_failed", "invalid_catalog", "invalid_catalog_cursor", "internal_error" ] }, "message": { "type": "string" }, "field": { "type": "string" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ApiIssue" } } }, "required": [ "code", "message" ] }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "description": "Rechazo con código estable. Los rechazos previos al efecto no modifican el estado de negocio." }, "ApiIssue": { "type": "object", "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string", "enum": [ "error", "notification", "unresolved" ] } }, "required": [ "code", "message" ], "description": "Hallazgo con código estable y ubicación de campo." }, "AccountProfile": { "type": "object", "properties": { "subject": { "type": "string" }, "phone": { "type": "string" }, "platformRole": { "type": "string", "enum": [ "admin", "user" ] }, "user": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "isActive": { "type": "boolean" } }, "required": [ "id", "email", "firstName", "lastName", "isActive" ] } }, "required": [ "subject", "phone", "platformRole", "user" ], "example": { "subject": "user-demo-001", "phone": "+573000000000", "platformRole": "user", "user": { "id": "user-demo-001", "email": null, "firstName": "Persona", "lastName": "Ejemplo", "isActive": true } } }, "MyWorkspaces": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } } }, "required": [ "items" ] }, "Workspace": { "type": "object", "properties": { "id": { "type": "string" }, "companyName": { "type": "string" }, "displayName": { "type": "string" }, "nit": { "type": "string" }, "verificationDigit": { "type": "string" }, "environment": { "$ref": "#/components/schemas/WorkspaceEnvironment" }, "isActive": { "type": "boolean" }, "role": { "type": "string", "description": "Rol del usuario en el espacio." } }, "required": [ "id", "companyName", "displayName", "nit", "verificationDigit", "environment", "isActive", "role" ] }, "WorkspaceEnvironment": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] } ], "description": "1 = Producción, 2 = Habilitación." }, "Dashboard": { "type": "object", "properties": { "financial": { "type": "object", "properties": { "totalInvoiced": { "type": "number" }, "totalCredited": { "type": "number" }, "totalDebited": { "type": "number" }, "netRevenue": { "type": "number" }, "invoiceCount": { "type": "integer" }, "creditNoteCount": { "type": "integer" }, "debitNoteCount": { "type": "integer" } }, "required": [ "totalInvoiced", "totalCredited", "totalDebited", "netRevenue", "invoiceCount", "creditNoteCount", "debitNoteCount" ] }, "rips": { "type": "object", "properties": { "accepted": { "type": "integer" }, "rejected": { "type": "integer" }, "pending": { "type": "integer" }, "unknown": { "type": "integer" } }, "required": [ "accepted", "rejected", "pending", "unknown" ] }, "recentDocuments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "documentType": { "type": "string", "enum": [ "Invoice", "CreditNote", "DebitNote" ] }, "number": { "type": "string" }, "clientName": { "type": "string" }, "totalAmount": { "type": "number" }, "status": { "type": "string" } }, "required": [ "id", "date", "documentType", "number", "clientName", "totalAmount", "status" ] } } }, "required": [ "financial", "rips", "recentDocuments" ], "description": "Resumen del mes en curso (UTC)." }, "PatientList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Patient" } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "description": "Página de resultados del espacio verificado. Predeterminados: limit=100, offset=0. total es el número de coincidencias; termine cuando offset + items.length >= total. Los cambios concurrentes pueden desplazar filas entre páginas." }, "Patient": { "type": "object", "properties": { "id": { "type": "string" }, "documentType": { "type": "string" }, "documentNumber": { "type": "string" }, "userType": { "type": [ "string", "null" ] }, "birthDate": { "type": [ "string", "null" ] }, "sexCode": { "type": [ "string", "null" ] }, "countryResidenceCode": { "type": [ "string", "null" ] }, "countryOriginCode": { "type": [ "string", "null" ] }, "municipalityResidenceCode": { "type": [ "string", "null" ] }, "territorialZoneCode": { "type": [ "string", "null" ] }, "disabilityFlag": { "type": [ "string", "null" ] }, "incapacityCertificate": { "type": [ "string", "null" ], "enum": [ "SI", "NO", null ] }, "registroSiras": { "type": [ "string", "null" ] }, "firstName": { "type": "string" }, "middleName": { "type": [ "string", "null" ] }, "lastName": { "type": "string" }, "secondLastName": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "updatedAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" } }, "required": [ "id", "documentType", "documentNumber", "userType", "birthDate", "sexCode", "countryResidenceCode", "countryOriginCode", "municipalityResidenceCode", "territorialZoneCode", "disabilityFlag", "incapacityCertificate", "registroSiras", "firstName", "middleName", "lastName", "secondLastName", "isActive", "createdAt", "updatedAt" ] }, "PatientInput": { "type": "object", "properties": { "documentType": { "type": "string", "minLength": 1, "maxLength": 5 }, "documentNumber": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^\\S+$" }, "userType": { "type": [ "string", "null" ], "maxLength": 5 }, "birthDate": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Fecha AAAA-MM-DD.", "example": "2026-10-15" }, "sexCode": { "type": [ "string", "null" ], "maxLength": 2 }, "countryResidenceCode": { "type": [ "string", "null" ], "maxLength": 5 }, "countryOriginCode": { "type": [ "string", "null" ], "maxLength": 5 }, "municipalityResidenceCode": { "type": [ "string", "null" ], "maxLength": 8 }, "territorialZoneCode": { "type": [ "string", "null" ], "maxLength": 4 }, "disabilityFlag": { "type": [ "string", "null" ], "maxLength": 4 }, "incapacityCertificate": { "type": [ "string", "null" ], "enum": [ "SI", "NO", null ], "description": "Certificado de incapacidad: SI, NO o null." }, "registroSiras": { "type": [ "string", "null" ], "maxLength": 20 }, "firstName": { "type": "string", "minLength": 1, "maxLength": 60 }, "middleName": { "type": [ "string", "null" ], "maxLength": 60 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 60 }, "secondLastName": { "type": [ "string", "null" ], "maxLength": 60 } }, "required": [ "documentType", "documentNumber", "firstName", "lastName" ], "additionalProperties": false, "description": "Ejemplo sintético. Use los datos reales del paciente autorizado y los códigos de su catálogo.", "example": { "documentType": "CC", "documentNumber": "1000000002", "firstName": "Paciente", "lastName": "Ejemplo", "birthDate": "1990-01-01", "userType": "01", "sexCode": "F", "countryResidenceCode": "170", "countryOriginCode": "170", "municipalityResidenceCode": "11001", "territorialZoneCode": "01", "incapacityCertificate": "NO" } }, "PatientPatch": { "type": "object", "properties": { "documentType": { "type": "string", "minLength": 1, "maxLength": 5 }, "documentNumber": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^\\S+$" }, "userType": { "type": [ "string", "null" ], "maxLength": 5 }, "birthDate": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Fecha AAAA-MM-DD.", "example": "2026-10-15" }, "sexCode": { "type": [ "string", "null" ], "maxLength": 2 }, "countryResidenceCode": { "type": [ "string", "null" ], "maxLength": 5 }, "countryOriginCode": { "type": [ "string", "null" ], "maxLength": 5 }, "municipalityResidenceCode": { "type": [ "string", "null" ], "maxLength": 8 }, "territorialZoneCode": { "type": [ "string", "null" ], "maxLength": 4 }, "disabilityFlag": { "type": [ "string", "null" ], "maxLength": 4 }, "incapacityCertificate": { "type": [ "string", "null" ], "enum": [ "SI", "NO", null ], "description": "Certificado de incapacidad: SI, NO o null." }, "registroSiras": { "type": [ "string", "null" ], "maxLength": 20 }, "firstName": { "type": "string", "minLength": 1, "maxLength": 60 }, "middleName": { "type": [ "string", "null" ], "maxLength": 60 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 60 }, "secondLastName": { "type": [ "string", "null" ], "maxLength": 60 } }, "additionalProperties": false, "description": "Solo los campos que se cambian; omitir conserva el valor. null borra un campo nullable. Ejemplo sintético.", "example": { "municipalityResidenceCode": "05001", "middleName": null } }, "SpecialistList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Specialist" } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "description": "Página de resultados del espacio verificado. Predeterminados: limit=100, offset=0. total es el número de coincidencias; termine cuando offset + items.length >= total. Los cambios concurrentes pueden desplazar filas entre páginas." }, "Specialist": { "type": "object", "properties": { "id": { "type": "string" }, "documentType": { "type": "string" }, "documentNumber": { "type": "string" }, "professionalType": { "type": [ "string", "null" ] }, "registrationNumber": { "type": [ "string", "null" ] }, "birthDate": { "type": [ "string", "null" ] }, "sexCode": { "type": [ "string", "null" ] }, "countryResidenceCode": { "type": [ "string", "null" ] }, "municipalityResidenceCode": { "type": [ "string", "null" ] }, "territorialZoneCode": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "updatedAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" } }, "required": [ "id", "documentType", "documentNumber", "professionalType", "registrationNumber", "birthDate", "sexCode", "countryResidenceCode", "municipalityResidenceCode", "territorialZoneCode", "firstName", "lastName", "isActive", "createdAt", "updatedAt" ], "description": "Profesional de salud que presta servicios RIPS." }, "SpecialistInput": { "type": "object", "properties": { "documentType": { "type": "string", "minLength": 1, "maxLength": 5 }, "documentNumber": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^\\S+$" }, "professionalType": { "type": [ "string", "null" ], "maxLength": 10 }, "registrationNumber": { "type": [ "string", "null" ], "maxLength": 30 }, "birthDate": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Fecha AAAA-MM-DD.", "example": "2026-10-15" }, "sexCode": { "type": [ "string", "null" ], "maxLength": 2 }, "countryResidenceCode": { "type": [ "string", "null" ], "maxLength": 5 }, "municipalityResidenceCode": { "type": [ "string", "null" ], "maxLength": 8 }, "territorialZoneCode": { "type": [ "string", "null" ], "maxLength": 4 }, "firstName": { "type": [ "string", "null" ], "maxLength": 60 }, "lastName": { "type": [ "string", "null" ], "maxLength": 60 } }, "required": [ "documentType", "documentNumber" ], "additionalProperties": false, "description": "Profesional que presta el servicio, distinto del paciente. Ejemplo sintético; reemplace la identificación y el registro profesional.", "example": { "documentType": "CC", "documentNumber": "1000000001", "firstName": "Profesional", "lastName": "Ejemplo", "registrationNumber": "REG-DEMO-001" } }, "SpecialistPatch": { "type": "object", "properties": { "documentType": { "type": "string", "minLength": 1, "maxLength": 5 }, "documentNumber": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^\\S+$" }, "professionalType": { "type": [ "string", "null" ], "maxLength": 10 }, "registrationNumber": { "type": [ "string", "null" ], "maxLength": 30 }, "birthDate": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Fecha AAAA-MM-DD.", "example": "2026-10-15" }, "sexCode": { "type": [ "string", "null" ], "maxLength": 2 }, "countryResidenceCode": { "type": [ "string", "null" ], "maxLength": 5 }, "municipalityResidenceCode": { "type": [ "string", "null" ], "maxLength": 8 }, "territorialZoneCode": { "type": [ "string", "null" ], "maxLength": 4 }, "firstName": { "type": [ "string", "null" ], "maxLength": 60 }, "lastName": { "type": [ "string", "null" ], "maxLength": 60 } }, "additionalProperties": false, "description": "Actualización parcial del profesional. Omitir conserva el valor. Ejemplo sintético.", "example": { "registrationNumber": "REG-DEMO-002" } }, "ServiceList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "description": "Página de resultados del espacio verificado. Predeterminados: limit=100, offset=0. total es el número de coincidencias; termine cuando offset + items.length >= total. Los cambios concurrentes pueden desplazar filas entre páginas." }, "Service": { "type": "object", "properties": { "id": { "type": "string" }, "category": { "$ref": "#/components/schemas/ServiceCategory" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "payload": { "$ref": "#/components/schemas/RipsServiceTemplate" }, "inputProvenance": { "$ref": "#/components/schemas/JsonObject" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "updatedAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" } }, "required": [ "id", "category", "name", "description", "payload", "inputProvenance", "isActive", "createdAt", "updatedAt" ] }, "ServiceCategory": { "type": "integer", "minimum": 1, "maximum": 7, "description": "1 consultas, 2 procedimientos, 3 urgencias, 4 hospitalización, 5 recién nacidos, 6 medicamentos, 7 otros servicios." }, "RipsServiceTemplate": { "anyOf": [ { "$ref": "#/components/schemas/DraftConsultaDTO" }, { "$ref": "#/components/schemas/DraftProcedimientoDTO" }, { "$ref": "#/components/schemas/DraftUrgenciaDTO" }, { "$ref": "#/components/schemas/DraftHospitalizacionDTO" }, { "$ref": "#/components/schemas/DraftRecienNacidoDTO" }, { "$ref": "#/components/schemas/DraftMedicamentoDTO" }, { "$ref": "#/components/schemas/DraftOtrosServicioDTO" } ], "description": "Plantilla parcial del servicio indicado por category: 1 ConsultaDTO, 2 ProcedimientoDTO, 3 UrgenciaDTO, 4 HospitalizacionDTO, 5 RecienNacidoDTO, 6 MedicamentoDTO, 7 OtrosServicioDTO. No es un paquete enviable por sí solo." }, "DraftConsultaDTO": { "type": "object", "properties": { "codPrestador": { "type": [ "string", "null" ], "description": "Código verificado del prestador o sede: use providerCodes de GET /rips-packages/context. No es el documento del profesional. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "fechaInicioAtencion": { "type": [ "string", "null" ], "description": "Hora local clínica en formato AAAA-MM-DD HH:mm. No convertir este campo a una marca UTC. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "numAutorizacion": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codConsulta": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "modalidadGrupoServicioTecSal": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "grupoServicios": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codServicio": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "finalidadTecnologiaSalud": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "causaMotivoAtencion": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoPrincipal": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoRelacionado1": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoRelacionado2": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoRelacionado3": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "tipoDiagnosticoPrincipal": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "tipoDocumentoIdentificacion": { "type": [ "string", "null" ], "description": "Identificación del profesional que prestó el servicio; no es la identificación del paciente. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "numDocumentoIdentificacion": { "type": [ "string", "null" ], "description": "Identificación del profesional que prestó el servicio; no es la identificación del paciente. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "vrServicio": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "conceptoRecaudo": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "valorPagoModerador": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "numFEVPagoModerador": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codigoVIDA": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoPrincipalCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoPrincipalCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoPrincipalECIE11": { "type": [ "string", "null" ], "description": "Alias de entrada nativo; el envío usa el campo canónico. No envíe ambos con valores diferentes. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoPrincipalECIE11": { "type": [ "string", "null" ], "description": "Alias de entrada nativo; el envío usa el campo canónico. No envíe ambos con valores diferentes. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoRelacionado1CIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoRelacionado1CIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoRelacionado2CIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoRelacionado2CIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoRelacionado3CIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoRelacionado3CIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "consecutivo": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." } }, "additionalProperties": {}, "description": "Campos del contrato nativo; admite borradores incompletos y conserva campos de origen adicionales. Guardar no autoriza el envío." }, "DraftProcedimientoDTO": { "type": "object", "properties": { "codPrestador": { "type": [ "string", "null" ], "description": "Código verificado del prestador o sede: use providerCodes de GET /rips-packages/context. No es el documento del profesional. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "fechaInicioAtencion": { "type": [ "string", "null" ], "description": "Hora local clínica en formato AAAA-MM-DD HH:mm. No convertir este campo a una marca UTC. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "idMIPRES": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "numAutorizacion": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codProcedimiento": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "viaIngresoServicioSalud": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "modalidadGrupoServicioTecSal": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "grupoServicios": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codServicio": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "finalidadTecnologiaSalud": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "tipoDocumentoIdentificacion": { "type": [ "string", "null" ], "description": "Identificación del profesional que prestó el servicio; no es la identificación del paciente. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "numDocumentoIdentificacion": { "type": [ "string", "null" ], "description": "Identificación del profesional que prestó el servicio; no es la identificación del paciente. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoPrincipal": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoRelacionado": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codComplicacion": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "vrServicio": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "conceptoRecaudo": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "valorPagoModerador": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "numFEVPagoModerador": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoPrincipalCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoPrincipalCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoRelacionadoCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoRelacionadoCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codComplicacionCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodComplicacionCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codigoVIDA": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "consecutivo": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." } }, "additionalProperties": {}, "description": "Campos del contrato nativo; admite borradores incompletos y conserva campos de origen adicionales. Guardar no autoriza el envío." }, "DraftUrgenciaDTO": { "type": "object", "properties": { "codPrestador": { "type": [ "string", "null" ], "description": "Código verificado del prestador o sede: use providerCodes de GET /rips-packages/context. No es el documento del profesional. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "fechaInicioAtencion": { "type": [ "string", "null" ], "description": "Hora local clínica en formato AAAA-MM-DD HH:mm. No convertir este campo a una marca UTC. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "causaMotivoAtencion": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoPrincipal": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoPrincipalE": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoRelacionadoE1": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoRelacionadoE2": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoRelacionadoE3": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "condicionDestinoUsuarioEgreso": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoCausaMuerte": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "fechaEgreso": { "type": [ "string", "null" ], "description": "Hora local clínica en formato AAAA-MM-DD HH:mm. No convertir este campo a una marca UTC. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoPrincipalCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoPrincipalCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoPrincipalECIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoPrincipalECIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoRelacionadoE1CIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoRelacionadoE1CIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoRelacionadoE2CIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoRelacionadoE2CIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoRelacionadoE3CIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoRelacionadoE3CIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoCausaMuerteCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoCausaMuerteCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codigoVIDA": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "consecutivo": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." } }, "additionalProperties": {}, "description": "Campos del contrato nativo; admite borradores incompletos y conserva campos de origen adicionales. Guardar no autoriza el envío." }, "DraftHospitalizacionDTO": { "type": "object", "properties": { "codPrestador": { "type": [ "string", "null" ], "description": "Código verificado del prestador o sede: use providerCodes de GET /rips-packages/context. No es el documento del profesional. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "viaIngresoServicioSalud": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "fechaInicioAtencion": { "type": [ "string", "null" ], "description": "Hora local clínica en formato AAAA-MM-DD HH:mm. No convertir este campo a una marca UTC. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "numAutorizacion": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "causaMotivoAtencion": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoPrincipal": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoPrincipalE": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoRelacionadoE1": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoRelacionadoE2": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoRelacionadoE3": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codComplicacion": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "condicionDestinoUsuarioEgreso": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoCausaMuerte": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "fechaEgreso": { "type": [ "string", "null" ], "description": "Hora local clínica en formato AAAA-MM-DD HH:mm. No convertir este campo a una marca UTC. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoPrincipalECIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoPrincipalECIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoPrincipalCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoPrincipalCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoRelacionadoE1CIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoRelacionadoE1CIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoRelacionadoE2CIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoRelacionadoE2CIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoRelacionadoE3CIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoRelacionadoE3CIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codComplicacionCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodComplicacionCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoCausaMuerteCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoCausaMuerteCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codigoVIDA": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "consecutivo": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." } }, "additionalProperties": {}, "description": "Campos del contrato nativo; admite borradores incompletos y conserva campos de origen adicionales. Guardar no autoriza el envío." }, "DraftRecienNacidoDTO": { "type": "object", "properties": { "codPrestador": { "type": [ "string", "null" ], "description": "Código verificado del prestador o sede: use providerCodes de GET /rips-packages/context. No es el documento del profesional. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "tipoDocumentoIdentificacion": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "numDocumentoIdentificacion": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "fechaNacimiento": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "edadGestacional": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "numConsultasCPrenatal": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codSexoBiologico": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "peso": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoPrincipal": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "condicionDestinoUsuarioEgreso": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoCausaMuerte": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "fechaEgreso": { "type": [ "string", "null" ], "description": "Hora local clínica en formato AAAA-MM-DD HH:mm. No convertir este campo a una marca UTC. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoPrincipalCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoPrincipalCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoPrincipalECIE11": { "type": [ "string", "null" ], "description": "Alias de entrada nativo; el envío usa el campo canónico. No envíe ambos con valores diferentes. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoPrincipalECIE11": { "type": [ "string", "null" ], "description": "Alias de entrada nativo; el envío usa el campo canónico. No envíe ambos con valores diferentes. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoCausaMuerteCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoCausaMuerteCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codigoVIDA": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "consecutivo": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." } }, "additionalProperties": {}, "description": "Campos del contrato nativo; admite borradores incompletos y conserva campos de origen adicionales. Guardar no autoriza el envío." }, "DraftMedicamentoDTO": { "type": "object", "properties": { "codPrestador": { "type": [ "string", "null" ], "description": "Código verificado del prestador o sede: use providerCodes de GET /rips-packages/context. No es el documento del profesional. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "numAutorizacion": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "idMIPRES": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "fechaDispensAdmon": { "type": [ "string", "null" ], "description": "Hora local clínica en formato AAAA-MM-DD HH:mm. No convertir este campo a una marca UTC. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoPrincipal": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoRelacionado": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "tipoMedicamento": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codTecnologiaSalud": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomTecnologiaSalud": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "concentracionMedicamento": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "unidadMedida": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "formaFarmaceutica": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "unidadMinDispensa": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "cantidadMedicamento": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "diasTratamiento": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "tipoDocumentoIdentificacion": { "type": [ "string", "null" ], "description": "Identificación del profesional que prestó el servicio; no es la identificación del paciente. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "numDocumentoIdentificacion": { "type": [ "string", "null" ], "description": "Identificación del profesional que prestó el servicio; no es la identificación del paciente. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "vrUnitMedicamento": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "vrServicio": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "vrDispensacion": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "conceptoRecaudo": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "valorPagoModerador": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "numFEVPagoModerador": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoPrincipalECIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoPrincipalECIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoPrincipalCIE11": { "type": [ "string", "null" ], "description": "Alias de entrada nativo; el envío usa el campo canónico. No envíe ambos con valores diferentes. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoPrincipalCIE11": { "type": [ "string", "null" ], "description": "Alias de entrada nativo; el envío usa el campo canónico. No envíe ambos con valores diferentes. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codDiagnosticoRelacionadoCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomCodDiagnosticoRelacionadoCIE11": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codigoVIDA": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "consecutivo": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." } }, "additionalProperties": {}, "description": "Campos del contrato nativo; admite borradores incompletos y conserva campos de origen adicionales. Guardar no autoriza el envío." }, "DraftOtrosServicioDTO": { "type": "object", "properties": { "codPrestador": { "type": [ "string", "null" ], "description": "Código verificado del prestador o sede: use providerCodes de GET /rips-packages/context. No es el documento del profesional. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "numAutorizacion": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "idMIPRES": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "fechaSuministroTecnologia": { "type": [ "string", "null" ], "description": "Hora local clínica en formato AAAA-MM-DD HH:mm. No convertir este campo a una marca UTC. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "tipoOS": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codTecnologiaSalud": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "nomTecnologiaSalud": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "cantidadOS": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "tipoDocumentoIdentificacion": { "type": [ "string", "null" ], "description": "Identificación del profesional que prestó el servicio; no es la identificación del paciente. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "numDocumentoIdentificacion": { "type": [ "string", "null" ], "description": "Identificación del profesional que prestó el servicio; no es la identificación del paciente. Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "vrUnitOS": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "vrServicio": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "conceptoRecaudo": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "valorPagoModerador": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "numFEVPagoModerador": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codigoVIDA": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "vrDispensacion": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "consecutivo": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." } }, "additionalProperties": {}, "description": "Campos del contrato nativo; admite borradores incompletos y conserva campos de origen adicionales. Guardar no autoriza el envío." }, "JsonObject": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Objeto JSON." }, "ServiceInput": { "type": "object", "properties": { "category": { "$ref": "#/components/schemas/ServiceCategory" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "payload": { "$ref": "#/components/schemas/RipsServiceTemplate" }, "inputProvenance": { "type": "object", "additionalProperties": {}, "description": "Procedencia de prellenados y ediciones explícitas. Se verifica contra la configuración del espacio." } }, "required": [ "category", "name", "payload" ], "additionalProperties": false, "description": "Plantilla de servicio. Sustituya los datos sintéticos de prestador, profesional y códigos antes de usarla en un RIPS.", "example": { "category": 1, "name": "Consulta de ejemplo", "payload": { "codPrestador": "110010000101", "fechaInicioAtencion": "2026-09-01 10:00", "numAutorizacion": null, "codConsulta": "890201", "modalidadGrupoServicioTecSal": "01", "grupoServicios": "01", "codServicio": 325, "finalidadTecnologiaSalud": "44", "causaMotivoAtencion": "38", "codDiagnosticoPrincipal": "Z000", "codDiagnosticoRelacionado1": null, "codDiagnosticoRelacionado2": null, "codDiagnosticoRelacionado3": null, "tipoDiagnosticoPrincipal": "01", "tipoDocumentoIdentificacion": "CC", "numDocumentoIdentificacion": "1000000001", "vrServicio": 100000, "conceptoRecaudo": "05", "valorPagoModerador": 0, "numFEVPagoModerador": null, "consecutivo": 1 } } }, "ServicePatch": { "type": "object", "properties": { "category": { "$ref": "#/components/schemas/ServiceCategory" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "payload": { "$ref": "#/components/schemas/RipsServiceTemplate" }, "inputProvenance": { "type": "object", "additionalProperties": {}, "description": "Procedencia de prellenados y ediciones explícitas. Se verifica contra la configuración del espacio." } }, "additionalProperties": false, "description": "Actualización parcial de la plantilla. Si envía payload, envíe el objeto de plantilla que desea guardar.", "example": { "name": "Consulta de medicina general", "description": "Plantilla revisada de ejemplo" } }, "ClientList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Client" } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "description": "Página de resultados del espacio verificado. Predeterminados: limit=100, offset=0. total es el número de coincidencias; termine cuando offset + items.length >= total. Los cambios concurrentes pueden desplazar filas entre páginas." }, "Client": { "type": "object", "properties": { "id": { "type": "string" }, "nit": { "type": "string" }, "verificationDigit": { "type": [ "string", "null" ] }, "companyName": { "type": "string" }, "commercialName": { "type": [ "string", "null" ] }, "displayName": { "type": "string" }, "taxRegime": { "type": [ "string", "null" ] }, "economicActivityCode": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "departmentCode": { "type": [ "string", "null" ] }, "municipalityCode": { "type": [ "string", "null" ] }, "phoneNumber": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "typeOrganizationId": { "type": "integer" }, "typeDocumentIdentificationId": { "type": "integer" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "updatedAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" } }, "required": [ "id", "nit", "verificationDigit", "companyName", "commercialName", "displayName", "taxRegime", "economicActivityCode", "address", "departmentCode", "municipalityCode", "phoneNumber", "email", "typeOrganizationId", "typeDocumentIdentificationId", "isActive", "createdAt", "updatedAt" ], "description": "Pagador o entidad responsable a quien se emite la factura de salud." }, "ClientInput": { "type": "object", "properties": { "nit": { "type": "string", "pattern": "^\\d{3,20}$", "description": "NIT sin dígito de verificación." }, "verificationDigit": { "type": [ "string", "null" ], "pattern": "^\\d$" }, "companyName": { "type": "string", "minLength": 1, "maxLength": 200 }, "commercialName": { "type": [ "string", "null" ], "maxLength": 200 }, "taxRegime": { "type": [ "string", "null" ], "maxLength": 40 }, "economicActivityCode": { "type": [ "string", "null" ], "maxLength": 20 }, "address": { "type": [ "string", "null" ], "maxLength": 300 }, "departmentCode": { "type": [ "string", "null" ], "maxLength": 5 }, "municipalityCode": { "type": [ "string", "null" ], "maxLength": 8 }, "phoneNumber": { "type": [ "string", "null" ], "maxLength": 30 }, "email": { "type": [ "string", "null" ], "maxLength": 254, "format": "email" }, "typeOrganizationId": { "type": "integer", "minimum": 1, "maximum": 9 }, "typeDocumentIdentificationId": { "type": "integer", "minimum": 1, "maximum": 20 } }, "required": [ "nit", "companyName" ], "additionalProperties": false, "description": "Entidad pagadora, distinta del paciente y del prestador. Ejemplo sintético.", "example": { "nit": "900123456", "companyName": "Entidad pagadora de ejemplo", "address": "Calle de ejemplo 1", "departmentCode": "11", "municipalityCode": "11001", "email": "pagador@example.invalid" } }, "ClientPatch": { "type": "object", "properties": { "nit": { "type": "string", "pattern": "^\\d{3,20}$", "description": "NIT sin dígito de verificación." }, "verificationDigit": { "type": [ "string", "null" ], "pattern": "^\\d$" }, "companyName": { "type": "string", "minLength": 1, "maxLength": 200 }, "commercialName": { "type": [ "string", "null" ], "maxLength": 200 }, "taxRegime": { "type": [ "string", "null" ], "maxLength": 40 }, "economicActivityCode": { "type": [ "string", "null" ], "maxLength": 20 }, "address": { "type": [ "string", "null" ], "maxLength": 300 }, "departmentCode": { "type": [ "string", "null" ], "maxLength": 5 }, "municipalityCode": { "type": [ "string", "null" ], "maxLength": 8 }, "phoneNumber": { "type": [ "string", "null" ], "maxLength": 30 }, "email": { "type": [ "string", "null" ], "maxLength": 254, "format": "email" }, "typeOrganizationId": { "type": "integer", "minimum": 1, "maximum": 9 }, "typeDocumentIdentificationId": { "type": "integer", "minimum": 1, "maximum": 20 } }, "additionalProperties": false, "description": "Solo cambia los campos presentes. Ejemplo sintético; un campo nullable se puede limpiar con null.", "example": { "address": "Calle de ejemplo 2", "commercialName": null } }, "InvoiceResolutionList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Resolution" } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "description": "Página de resultados del espacio verificado. Predeterminados: limit=100, offset=0. total es el número de coincidencias; termine cuando offset + items.length >= total. Los cambios concurrentes pueden desplazar filas entre páginas." }, "Resolution": { "type": "object", "properties": { "id": { "type": "string" }, "resolutionNumber": { "type": "string" }, "prefix": { "type": "string" }, "nextNumber": { "type": "integer" }, "fromNumber": { "type": "integer" }, "toNumber": { "type": "integer" }, "validFrom": { "type": "string" }, "validTo": { "type": "string" }, "environment": { "$ref": "#/components/schemas/WorkspaceEnvironment" }, "hasTechnicalKey": { "type": "boolean", "description": "Indica si existe una clave técnica guardada, sin revelar su valor." }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "updatedAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" } }, "required": [ "id", "resolutionNumber", "prefix", "nextNumber", "fromNumber", "toNumber", "validFrom", "validTo", "environment", "hasTechnicalKey", "isActive", "createdAt", "updatedAt" ], "description": "Resolución de numeración DIAN del espacio." }, "CreditNoteResolutionList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Resolution" } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "description": "Página de resultados del espacio verificado. Predeterminados: limit=100, offset=0. total es el número de coincidencias; termine cuando offset + items.length >= total. Los cambios concurrentes pueden desplazar filas entre páginas." }, "XlsxUpload": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ] }, "RipsContext": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "nit": { "type": "string" }, "companyName": { "type": "string" }, "environment": { "$ref": "#/components/schemas/WorkspaceEnvironment" }, "providerCodes": { "type": "array", "items": { "type": "string" }, "description": "Código de prestador y códigos de habilitación de sedes verificados." }, "invoiceProvider": { "type": "string", "enum": [ "pahfacturar" ] } }, "required": [ "workspaceId", "nit", "companyName", "environment", "providerCodes", "invoiceProvider" ] }, "HealthInvoiceContext": { "type": "object", "properties": { "provider": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "pahfacturar" ] }, "hasToken": { "type": "boolean" }, "configured": { "type": "boolean" } }, "required": [ "name", "hasToken", "configured" ] }, "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "companyName": { "type": "string" }, "nit": { "type": "string" }, "verificationDigit": { "type": "string" }, "environment": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] } ] }, "serviceCode": { "type": [ "string", "null" ] }, "providerCodes": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "companyName", "nit", "verificationDigit", "environment", "serviceCode", "providerCodes" ] }, "clients": { "type": "array", "items": { "$ref": "#/components/schemas/Client" } }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } }, "resolutions": { "type": "array", "items": { "$ref": "#/components/schemas/Resolution" } } }, "required": [ "provider", "workspace", "clients", "locations", "resolutions" ] }, "Location": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "address": { "type": [ "string", "null" ] }, "departmentCode": { "type": [ "string", "null" ] }, "municipalityCode": { "type": [ "string", "null" ] }, "phoneNumber": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "habilitationCode": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean" } }, "required": [ "id", "name", "address", "departmentCode", "municipalityCode", "phoneNumber", "email", "habilitationCode", "isActive" ], "description": "Sede del prestador. El código de habilitación identifica la sede ante SISPRO." }, "DebitNoteResolutionList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Resolution" } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "description": "Página de resultados del espacio verificado. Predeterminados: limit=100, offset=0. total es el número de coincidencias; termine cuando offset + items.length >= total. Los cambios concurrentes pueden desplazar filas entre páginas." }, "RipsPackageKind": { "type": "string", "enum": [ "rips_sin_factura", "fev_rips", "nc_parcial", "nc_total", "nd", "nota_ajuste", "capita_inicial", "capita_periodo", "capita_final", "nc_acuerdo_voluntades", "nc_capita" ], "description": "Uno de los once tipos de paquete FEV RIPS fijados en el contrato nativo." }, "RipsPackageStatus": { "type": "string", "enum": [ "Draft", "Dispatching", "Accepted", "Rejected", "Unknown" ], "description": "Draft: editable. Dispatching: intento registrado, en curso. Accepted: recibo verificado. Rejected: rechazo terminal; se corrige con una revisión nueva. Unknown: resultado incierto; solo se resuelve conciliando con evidencia." }, "RipsPackageList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RipsPackageSummary" } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "description": "Página de resultados del espacio verificado. Predeterminados: limit=100, offset=0. total es el número de coincidencias; termine cuando offset + items.length >= total. Los cambios concurrentes pueden desplazar filas entre páginas." }, "RipsPackageSummary": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/RipsPackageKind" }, "status": { "$ref": "#/components/schemas/RipsPackageStatus" }, "revision": { "type": "integer", "minimum": 1 }, "isActive": { "type": "boolean" }, "statusMessage": { "type": [ "string", "null" ] }, "numFactura": { "type": [ "string", "null" ] }, "numNota": { "type": [ "string", "null" ] }, "tipoNota": { "type": [ "string", "null" ] }, "cufeOrCude": { "type": [ "string", "null" ] }, "attachedDocument": { "$ref": "#/components/schemas/AttachedDocument" }, "sourceInvoiceId": { "type": [ "string", "null" ] }, "sourceCreditNoteId": { "type": [ "string", "null" ] }, "sourceDebitNoteId": { "type": [ "string", "null" ] }, "sourcePackageId": { "type": [ "string", "null" ] }, "procesoId": { "type": [ "string", "null" ] }, "cuv": { "type": [ "string", "null" ], "description": "Solo con estado Accepted." }, "validation": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "revision": { "type": "integer" }, "outcome": { "type": "string", "enum": [ "valid", "invalid" ] }, "current": { "type": "boolean", "description": "true si corresponde a la revisión y al contexto vigentes." }, "contentDigest": { "type": "string" }, "attachedDocumentSha256": { "type": [ "string", "null" ], "description": "sha256 del AttachedDocument leído del sistema de facturación para esta validación; null si el paquete no envía XML o no se pudo leer." }, "rulesVersion": { "type": "string" }, "contextDigest": { "type": "string" }, "referencesDigest": { "type": "string" }, "validatedAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" } }, "required": [ "id", "revision", "outcome", "current", "contentDigest", "attachedDocumentSha256", "rulesVersion", "contextDigest", "referencesDigest", "validatedAt" ] }, "lastAttempt": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "revision": { "type": "integer" }, "outcome": { "$ref": "#/components/schemas/DispatchOutcome" }, "environment": { "$ref": "#/components/schemas/WorkspaceEnvironment" }, "attemptedAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "completedAt": { "type": [ "string", "null" ], "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "procesoId": { "type": [ "string", "null" ] }, "cuv": { "type": [ "string", "null" ], "description": "Solo presente si el recibo es aceptado y verificado." }, "message": { "type": [ "string", "null" ] }, "requestDigest": { "type": "string" }, "reconciliation": { "type": [ "object", "null" ], "properties": { "evidenceCuv": { "type": "string" }, "outcome": { "type": "string", "enum": [ "accepted", "inconclusive" ] }, "reconciledAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" } }, "required": [ "evidenceCuv", "outcome", "reconciledAt" ] } }, "required": [ "id", "revision", "outcome", "environment", "attemptedAt", "completedAt", "procesoId", "cuv", "message", "requestDigest", "reconciliation" ] }, "createdByUserId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "updatedAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" } }, "required": [ "id", "kind", "status", "revision", "isActive", "statusMessage", "numFactura", "numNota", "tipoNota", "cufeOrCude", "attachedDocument", "sourceInvoiceId", "sourceCreditNoteId", "sourceDebitNoteId", "sourcePackageId", "procesoId", "cuv", "validation", "lastAttempt", "createdByUserId", "createdAt", "updatedAt" ] }, "AttachedDocument": { "type": [ "object", "null" ], "properties": { "source": { "type": "string", "enum": [ "pahfacturar" ] }, "documentKind": { "$ref": "#/components/schemas/AttachedDocumentKind" }, "providerDocumentId": { "type": "string" }, "number": { "type": "string" }, "cufe": { "type": "string", "description": "CUFE o CUDE que informa el sistema de facturación." } }, "required": [ "source", "documentKind", "providerDocumentId", "number", "cufe" ], "description": "Documento referenciado. El XML vigente se lee del sistema de facturación al guardar, validar y enviar." }, "AttachedDocumentKind": { "type": "string", "enum": [ "invoice", "credit-note", "debit-note" ], "description": "invoice para FEV y cápita, credit-note para las acciones NC, debit-note para ND." }, "DispatchOutcome": { "type": "string", "enum": [ "pending", "accepted", "rejected", "unknown", "not_sent" ], "description": "pending: intento en curso. not_sent: falló antes del efecto externo (sin envío). unknown: la llamada pudo ocurrir y no hay evidencia concluyente." }, "CreateRipsPackageInput": { "type": "object", "properties": { "kind": { "$ref": "#/components/schemas/RipsPackageKind" }, "origin": { "type": "string", "enum": [ "upload", "guided" ], "default": "upload", "description": "guided usa el contrato guiado del portal (perfil nativo); upload conserva la declaración de origen." }, "guidedContractVersion": { "type": "number", "enum": [ 1 ] }, "rips": { "$ref": "#/components/schemas/RipsDraftPayload" }, "attachedDocument": { "$ref": "#/components/schemas/AttachedDocumentInput" }, "sourcePackageId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Paquete aceptado de referencia para notas de ajuste o débito." }, "ripsSourceProfile": { "type": "string", "enum": [ "history", "native-d558206", "ministry-v003-20260715" ] }, "ripsImportSource": { "$ref": "#/components/schemas/RipsImportSource" }, "inputProvenance": { "$ref": "#/components/schemas/RipsInputProvenance" } }, "required": [ "kind" ], "additionalProperties": false }, "RipsDraftPayload": { "anyOf": [ { "$ref": "#/components/schemas/DraftRipsDTO" }, { "type": "string", "maxLength": 25000000, "description": "Texto JSON UTF-8 original. Se conserva sin reformatear. Use esta opción para importar un origen que todavía necesita correcciones; valide antes de enviar." }, { "type": "null" } ], "description": "Objeto RIPS tipado e incompleto, texto JSON exacto o null. Las acciones solo XML exigen null al enviar. El sobre externo de esta API nunca acepta xmlFevFile." }, "DraftRipsDTO": { "type": "object", "properties": { "numDocumentoIdObligado": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "numFactura": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "tipoNota": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "numNota": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "usuarios": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/DraftUsuarioDTO" }, "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." } }, "additionalProperties": {}, "description": "Campos del contrato nativo; admite borradores incompletos y conserva campos de origen adicionales. Guardar no autoriza el envío." }, "DraftUsuarioDTO": { "type": "object", "properties": { "tipoDocumentoIdentificacion": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "numDocumentoIdentificacion": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "tipoUsuario": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "fechaNacimiento": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codSexo": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codPaisResidencia": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codPaisOrigen": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codMunicipioResidencia": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "codZonaTerritorialResidencia": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "incapacidad": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "consecutivo": { "type": [ "number", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "registroSIRAS": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "servicios": { "type": [ "object", "null" ], "properties": { "consultas": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/DraftConsultaDTO" }, "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "procedimientos": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/DraftProcedimientoDTO" }, "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "urgencias": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/DraftUrgenciaDTO" }, "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "hospitalizacion": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/DraftHospitalizacionDTO" }, "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "recienNacidos": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/DraftRecienNacidoDTO" }, "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "medicamentos": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/DraftMedicamentoDTO" }, "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "otrosServicios": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/DraftOtrosServicioDTO" }, "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." } }, "additionalProperties": {}, "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." } }, "additionalProperties": {}, "description": "Campos del contrato nativo; admite borradores incompletos y conserva campos de origen adicionales. Guardar no autoriza el envío." }, "AttachedDocumentInput": { "type": [ "object", "null" ], "properties": { "documentKind": { "$ref": "#/components/schemas/AttachedDocumentKind" }, "number": { "type": "string", "minLength": 1, "maxLength": 40, "description": "Número del documento en el sistema de facturación, por ejemplo SETP990000001." } }, "required": [ "documentKind", "number" ], "additionalProperties": false, "description": "Documento del sistema de facturación cuyo AttachedDocument acompaña el paquete. RipsCloud no recibe ni guarda el XML: lo lee del sistema de facturación en cada operación. null quita la referencia." }, "RipsImportSource": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "csv" ] }, "text": { "type": "string", "maxLength": 10000000 }, "fileName": { "type": "string", "maxLength": 255 }, "cells": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "text": { "type": "string", "maxLength": 10000 }, "row": { "type": "integer", "minimum": 1 }, "column": { "type": "integer", "minimum": 1 } }, "required": [ "name", "text", "row" ], "additionalProperties": false }, "maxItems": 200000 } }, "required": [ "format", "text", "cells" ], "additionalProperties": false, "description": "Evidencia exacta de una importación CSV. Se conserva y se valida; no sustituye la configuración del espacio." }, "RipsInputProvenance": { "type": "object", "properties": { "profile": { "type": "string", "enum": [ "native-d558206" ] }, "prefills": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "codPrestador" ] }, "kind": { "type": "string", "enum": [ "company-context" ] }, "value": { "type": "string", "maxLength": 20 }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." } }, "required": [ "field", "kind", "value", "sourceId" ], "additionalProperties": false }, "maxItems": 500 }, "edits": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9]*$" }, "kind": { "type": "string", "enum": [ "explicit-user-entry" ] }, "text": { "type": "string", "maxLength": 500 } }, "required": [ "field", "kind", "text" ], "additionalProperties": false }, "maxItems": 5000 } }, "additionalProperties": false, "description": "Prellenados desde la empresa verificada y ediciones explícitas. No otorgan autoridad de envío." }, "RipsPackage": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/RipsPackageKind" }, "status": { "$ref": "#/components/schemas/RipsPackageStatus" }, "revision": { "type": "integer", "minimum": 1 }, "isActive": { "type": "boolean" }, "statusMessage": { "type": [ "string", "null" ] }, "numFactura": { "type": [ "string", "null" ] }, "numNota": { "type": [ "string", "null" ] }, "tipoNota": { "type": [ "string", "null" ] }, "cufeOrCude": { "type": [ "string", "null" ] }, "attachedDocument": { "$ref": "#/components/schemas/AttachedDocument" }, "sourceInvoiceId": { "type": [ "string", "null" ] }, "sourceCreditNoteId": { "type": [ "string", "null" ] }, "sourceDebitNoteId": { "type": [ "string", "null" ] }, "sourcePackageId": { "type": [ "string", "null" ] }, "procesoId": { "type": [ "string", "null" ] }, "cuv": { "type": [ "string", "null" ], "description": "Solo con estado Accepted." }, "validation": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "revision": { "type": "integer" }, "outcome": { "type": "string", "enum": [ "valid", "invalid" ] }, "current": { "type": "boolean", "description": "true si corresponde a la revisión y al contexto vigentes." }, "contentDigest": { "type": "string" }, "attachedDocumentSha256": { "type": [ "string", "null" ], "description": "sha256 del AttachedDocument leído del sistema de facturación para esta validación; null si el paquete no envía XML o no se pudo leer." }, "rulesVersion": { "type": "string" }, "contextDigest": { "type": "string" }, "referencesDigest": { "type": "string" }, "validatedAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" } }, "required": [ "id", "revision", "outcome", "current", "contentDigest", "attachedDocumentSha256", "rulesVersion", "contextDigest", "referencesDigest", "validatedAt" ] }, "lastAttempt": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "revision": { "type": "integer" }, "outcome": { "$ref": "#/components/schemas/DispatchOutcome" }, "environment": { "$ref": "#/components/schemas/WorkspaceEnvironment" }, "attemptedAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "completedAt": { "type": [ "string", "null" ], "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "procesoId": { "type": [ "string", "null" ] }, "cuv": { "type": [ "string", "null" ], "description": "Solo presente si el recibo es aceptado y verificado." }, "message": { "type": [ "string", "null" ] }, "requestDigest": { "type": "string" }, "reconciliation": { "type": [ "object", "null" ], "properties": { "evidenceCuv": { "type": "string" }, "outcome": { "type": "string", "enum": [ "accepted", "inconclusive" ] }, "reconciledAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" } }, "required": [ "evidenceCuv", "outcome", "reconciledAt" ] } }, "required": [ "id", "revision", "outcome", "environment", "attemptedAt", "completedAt", "procesoId", "cuv", "message", "requestDigest", "reconciliation" ] }, "createdByUserId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "updatedAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "ripsPayloadJson": { "type": [ "string", "null" ], "description": "Texto RIPS original exacto de la primera revisión." }, "workingPayloadJson": { "type": [ "string", "null" ], "description": "RIPS de trabajo de la revisión vigente." }, "provenance": { "$ref": "#/components/schemas/RipsPackageProvenance" } }, "required": [ "id", "kind", "status", "revision", "isActive", "statusMessage", "numFactura", "numNota", "tipoNota", "cufeOrCude", "attachedDocument", "sourceInvoiceId", "sourceCreditNoteId", "sourceDebitNoteId", "sourcePackageId", "procesoId", "cuv", "validation", "lastAttempt", "createdByUserId", "createdAt", "updatedAt", "ripsPayloadJson", "workingPayloadJson", "provenance" ] }, "RipsPackageProvenance": { "type": [ "object", "null" ], "properties": { "sourceProfile": { "type": "string" }, "declaration": { "type": [ "string", "null" ], "enum": [ "user-declared", "server-guided", null ] }, "inputFormat": { "type": [ "string", "null" ], "enum": [ "json", "csv", null ] }, "changeCount": { "type": "integer" }, "inputCount": { "type": "integer" } }, "required": [ "sourceProfile", "declaration", "inputFormat", "changeCount", "inputCount" ] }, "MedicationCatalogMetadata": { "type": "object", "properties": { "pins": { "$ref": "#/components/schemas/MedicationCatalogPins" }, "scope": { "type": "string" } }, "required": [ "pins", "scope" ] }, "MedicationCatalogPins": { "type": "object", "properties": { "schemaVersion": { "type": "integer" }, "cacheVersion": { "type": "integer" }, "adapterVersion": { "type": "integer" }, "catalogRevision": { "type": "string" }, "CUM": { "type": "object", "properties": { "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "recordCount": { "type": "integer" } }, "required": [ "bytes", "sha256" ] }, "IUM": { "type": "object", "properties": { "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "recordCount": { "type": "integer" } }, "required": [ "bytes", "sha256" ] }, "compactAuthority": { "type": "object", "properties": { "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "recordCount": { "type": "integer" } }, "required": [ "bytes", "sha256" ] }, "assetManifest": { "type": "object", "properties": { "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "recordCount": { "type": "integer" } }, "required": [ "bytes", "sha256" ] }, "enrichment": { "type": "object", "properties": { "sha256": { "type": "string" }, "recordCount": { "type": "integer" }, "rawSha256": { "type": "string" }, "provenanceSha256": { "type": "string" } }, "required": [ "sha256", "recordCount", "rawSha256", "provenanceSha256" ] } }, "required": [ "schemaVersion", "cacheVersion", "adapterVersion", "catalogRevision", "CUM", "IUM", "compactAuthority", "assetManifest", "enrichment" ], "description": "Versión y hashes del catálogo autorizado. Fije estos datos con su importación; no equivalen a un catálogo clínico completo." }, "MedicationSearchResult": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MedicationRow" } }, "next": { "type": [ "string", "null" ] }, "catalog": { "type": "string", "enum": [ "CUM", "IUM" ] }, "pins": { "$ref": "#/components/schemas/MedicationCatalogPins" } }, "required": [ "items", "next", "catalog", "pins" ] }, "MedicationRow": { "type": "object", "properties": { "code": { "type": "string", "description": "Código exacto para codTecnologiaSalud. Conservar ceros, guiones y mayúsculas.", "example": "19983100-1" }, "catalog": { "type": "string", "enum": [ "CUM", "IUM" ] }, "admission": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "catalog": { "type": "string", "enum": [ "CUM", "IUM" ] }, "code": { "type": "string" }, "habilitado": { "type": "boolean", "enum": [ true ] }, "estadoEntidad": { "type": "boolean" } }, "required": [ "ok", "catalog", "code", "habilitado", "estadoEntidad" ] }, "nameState": { "type": "string", "enum": [ "reviewed", "missing" ] }, "name": { "type": [ "string", "null" ] }, "enrichment": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Datos opcionales de presentación. No determinan dosis, vía, concentración ni otros campos clínicos." }, "enrichmentProvenance": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Evidencia del origen del enriquecimiento; puede faltar sin invalidar el código." } }, "required": [ "code", "catalog", "admission", "nameState", "name", "enrichment", "enrichmentProvenance" ], "description": "Código admitido por la versión fijada. La ausencia de nombre no implica código inválido. estadoEntidad y habilitado son conceptos distintos." }, "MedicationDetail": { "type": "object", "properties": { "code": { "type": "string", "description": "Código exacto para codTecnologiaSalud. Conservar ceros, guiones y mayúsculas.", "example": "19983100-1" }, "catalog": { "type": "string", "enum": [ "CUM", "IUM" ] }, "admission": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "catalog": { "type": "string", "enum": [ "CUM", "IUM" ] }, "code": { "type": "string" }, "habilitado": { "type": "boolean", "enum": [ true ] }, "estadoEntidad": { "type": "boolean" } }, "required": [ "ok", "catalog", "code", "habilitado", "estadoEntidad" ] }, "nameState": { "type": "string", "enum": [ "reviewed", "missing" ] }, "name": { "type": [ "string", "null" ] }, "enrichment": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Datos opcionales de presentación. No determinan dosis, vía, concentración ni otros campos clínicos." }, "enrichmentProvenance": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Evidencia del origen del enriquecimiento; puede faltar sin invalidar el código." }, "pins": { "$ref": "#/components/schemas/MedicationCatalogPins" } }, "required": [ "code", "catalog", "admission", "nameState", "name", "enrichment", "enrichmentProvenance", "pins" ] }, "ReviseRipsPackageInput": { "type": "object", "properties": { "rips": { "$ref": "#/components/schemas/RipsDraftPayload" }, "attachedDocument": { "$ref": "#/components/schemas/AttachedDocumentInput" }, "sourcePackageId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "ripsImportSource": { "$ref": "#/components/schemas/RipsImportSource" }, "inputProvenance": { "$ref": "#/components/schemas/RipsInputProvenance" } }, "additionalProperties": false, "description": "Crea una revisión nueva. Invalida la validación de la revisión anterior." }, "RevisionInput": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 1, "description": "Revisión exacta que se valida o envía." } }, "required": [ "revision" ], "additionalProperties": false }, "RipsValidationResult": { "type": "object", "properties": { "validation": { "$ref": "#/components/schemas/ValidationEvidence" }, "payload": { "type": [ "object", "null" ], "properties": { "rips": { "$ref": "#/components/schemas/NativeRipsDTO" }, "xmlFevFile": { "type": [ "string", "null" ] } }, "required": [ "rips", "xmlFevFile" ], "description": "Cuerpo exacto que se enviaría con esta revisión, si es válida. xmlFevFile es el AttachedDocument leído del sistema de facturación." }, "fieldConditions": { "type": [ "object", "null" ], "properties": { "native": { "type": "object", "properties": { "profile": { "type": "string", "enum": [ "native-d558206" ] }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/FieldConditionIssue" } } }, "required": [ "profile", "issues" ] }, "ministry": { "type": "object", "properties": { "ministryProfile": { "type": "string", "enum": [ "ministry-v003-20260715" ] }, "signatureStatus": { "type": "string" }, "attachedDocumentSha256": { "type": "string" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/FieldConditionIssue" } } }, "required": [ "ministryProfile", "signatureStatus", "issues" ] } }, "required": [ "native", "ministry" ] } }, "required": [ "validation", "payload", "fieldConditions" ] }, "ValidationEvidence": { "type": "object", "properties": { "id": { "type": "string" }, "revision": { "type": "integer" }, "outcome": { "type": "string", "enum": [ "valid", "invalid" ] }, "current": { "type": "boolean", "description": "true si corresponde a la revisión y al contexto vigentes." }, "contentDigest": { "type": "string" }, "attachedDocumentSha256": { "type": [ "string", "null" ], "description": "sha256 del AttachedDocument leído del sistema de facturación para esta validación; null si el paquete no envía XML o no se pudo leer." }, "rulesVersion": { "type": "string" }, "contextDigest": { "type": "string" }, "referencesDigest": { "type": "string" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ApiIssue" } }, "validatedAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" } }, "required": [ "id", "revision", "outcome", "current", "contentDigest", "attachedDocumentSha256", "rulesVersion", "contextDigest", "referencesDigest", "issues", "validatedAt" ], "description": "Evidencia de validación de una revisión exacta: contenido, reglas, referencias y contexto usados." }, "NativeRipsDTO": { "type": [ "object", "null" ], "properties": { "numDocumentoIdObligado": { "type": "string", "minLength": 3, "maxLength": 12 }, "numFactura": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20 }, "tipoNota": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 2, "pattern": "^(?:\"|NC|ND|NA|RS)$" }, { "type": "null" } ] }, "numNota": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 20 }, { "type": "null" } ] }, "usuarios": { "type": "array", "items": { "$ref": "#/components/schemas/NativeUsuarioDTO" }, "minItems": 1 } }, "required": [ "numDocumentoIdObligado", "usuarios" ], "description": "Estructura del perfil native-d558206. Las reglas clínicas, referencias y catálogos se verifican por separado." }, "NativeUsuarioDTO": { "type": "object", "properties": { "tipoDocumentoIdentificacion": { "type": "string", "minLength": 2, "maxLength": 2 }, "numDocumentoIdentificacion": { "type": "string", "minLength": 2, "maxLength": 20, "pattern": "^[a-zA-Z0-9]+$" }, "tipoUsuario": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 }, "fechaNacimiento": { "type": "string", "minLength": 10, "maxLength": 10, "pattern": "[1-2]{1}[9|0]{1}[0-9]{2}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])" }, "codSexo": { "type": "string", "pattern": "^(M|F|I)$" }, "codPaisResidencia": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 }, "codPaisOrigen": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 }, "codMunicipioResidencia": { "type": [ "string", "null" ], "minLength": 5, "maxLength": 5 }, "codZonaTerritorialResidencia": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 }, "incapacidad": { "type": "string", "pattern": "^(SI|NO)$" }, "consecutivo": { "type": "integer" }, "registroSIRAS": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 60 }, { "type": "null" } ] }, "servicios": { "$ref": "#/components/schemas/NativeServiciosDTO" } }, "required": [ "tipoDocumentoIdentificacion", "numDocumentoIdentificacion", "fechaNacimiento", "codSexo", "incapacidad", "consecutivo", "servicios" ], "description": "Estructura del perfil native-d558206. Las reglas clínicas, referencias y catálogos se verifican por separado." }, "NativeServiciosDTO": { "type": "object", "properties": { "consultas": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/NativeConsultaDTO" } }, "procedimientos": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/NativeProcedimientoDTO" } }, "urgencias": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/NativeUrgenciaDTO" } }, "hospitalizacion": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/NativeHospitalizacionDTO" } }, "recienNacidos": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/NativeRecienNacidoDTO" } }, "medicamentos": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/NativeMedicamentoDTO" } }, "otrosServicios": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/NativeOtrosServicioDTO" } } }, "description": "Estructura del perfil native-d558206. Las reglas clínicas, referencias y catálogos se verifican por separado." }, "NativeConsultaDTO": { "type": "object", "properties": { "codPrestador": { "type": "string", "minLength": 12, "maxLength": 12, "description": "Código verificado del prestador o sede: use providerCodes de GET /rips-packages/context. No es el documento del profesional." }, "fechaInicioAtencion": { "type": "string", "pattern": "[1-2]{1}[9|0]{1}[0-9]{2}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1]) (2[0-3]|[01][0-9]):[0-5][0-9]", "description": "Hora local clínica en formato AAAA-MM-DD HH:mm. No convertir este campo a una marca UTC." }, "numAutorizacion": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 30 }, { "type": "null" } ] }, "codConsulta": { "type": [ "string", "null" ], "minLength": 6, "maxLength": 6 }, "modalidadGrupoServicioTecSal": { "type": "string", "minLength": 2, "maxLength": 2 }, "grupoServicios": { "type": "string", "minLength": 2, "maxLength": 2 }, "codServicio": { "type": "integer", "minimum": 100, "maximum": 9999 }, "finalidadTecnologiaSalud": { "type": "string", "minLength": 2, "maxLength": 2 }, "causaMotivoAtencion": { "type": "string", "minLength": 2, "maxLength": 2 }, "codDiagnosticoPrincipal": { "type": "string", "minLength": 4, "maxLength": 4 }, "codDiagnosticoRelacionado1": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 4, "maxLength": 4, "pattern": "^\\S+$" }, { "type": "null" } ] }, "codDiagnosticoRelacionado2": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 4, "maxLength": 4 }, { "type": "null" } ] }, "codDiagnosticoRelacionado3": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 4, "maxLength": 4 }, { "type": "null" } ] }, "tipoDiagnosticoPrincipal": { "type": "string", "minLength": 2, "maxLength": 2 }, "tipoDocumentoIdentificacion": { "type": "string", "enum": [ "CC", "CE", "CD", "PA", "SC", "PE", "DE", "PT" ], "description": "Identificación del profesional que prestó el servicio; no es la identificación del paciente." }, "numDocumentoIdentificacion": { "type": "string", "minLength": 2, "maxLength": 20, "pattern": "^[a-zA-Z0-9]+$", "description": "Identificación del profesional que prestó el servicio; no es la identificación del paciente." }, "vrServicio": { "type": "number", "minimum": 0, "maximum": 999999999999 }, "conceptoRecaudo": { "type": "string" }, "valorPagoModerador": { "type": "number", "minimum": 0, "maximum": 999999999999 }, "numFEVPagoModerador": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 30 }, { "type": "null" } ] }, "codigoVIDA": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "codDiagnosticoPrincipalCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodDiagnosticoPrincipalCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codDiagnosticoPrincipalECIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ], "description": "Alias de entrada nativo; el envío usa el campo canónico. No envíe ambos con valores diferentes." }, "nomCodDiagnosticoPrincipalECIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ], "description": "Alias de entrada nativo; el envío usa el campo canónico. No envíe ambos con valores diferentes." }, "codDiagnosticoRelacionado1CIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodDiagnosticoRelacionado1CIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codDiagnosticoRelacionado2CIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodDiagnosticoRelacionado2CIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codDiagnosticoRelacionado3CIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodDiagnosticoRelacionado3CIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "consecutivo": { "type": "integer", "minimum": 1, "maximum": 999999 } }, "required": [ "codPrestador", "fechaInicioAtencion", "modalidadGrupoServicioTecSal", "grupoServicios", "codServicio", "finalidadTecnologiaSalud", "causaMotivoAtencion", "codDiagnosticoPrincipal", "tipoDiagnosticoPrincipal", "tipoDocumentoIdentificacion", "numDocumentoIdentificacion", "vrServicio", "conceptoRecaudo", "valorPagoModerador", "consecutivo" ], "description": "Estructura del perfil native-d558206. Las reglas clínicas, referencias y catálogos se verifican por separado." }, "NativeProcedimientoDTO": { "type": "object", "properties": { "codPrestador": { "type": "string", "minLength": 12, "maxLength": 12, "description": "Código verificado del prestador o sede: use providerCodes de GET /rips-packages/context. No es el documento del profesional." }, "fechaInicioAtencion": { "type": "string", "pattern": "[1-2]{1}[9|0]{1}[0-9]{2}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1]) (2[0-3]|[01][0-9]):[0-5][0-9]", "description": "Hora local clínica en formato AAAA-MM-DD HH:mm. No convertir este campo a una marca UTC." }, "idMIPRES": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^[0-9]{1,19}$" }, { "type": "null" } ] }, "numAutorizacion": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 30 }, { "type": "null" } ] }, "codProcedimiento": { "type": [ "string", "null" ], "minLength": 6, "maxLength": 6 }, "viaIngresoServicioSalud": { "type": "string", "minLength": 2, "maxLength": 2 }, "modalidadGrupoServicioTecSal": { "type": "string", "minLength": 2, "maxLength": 2 }, "grupoServicios": { "type": "string", "minLength": 2, "maxLength": 2 }, "codServicio": { "type": "integer", "minimum": 100, "maximum": 9999 }, "finalidadTecnologiaSalud": { "type": "string", "minLength": 2, "maxLength": 2 }, "tipoDocumentoIdentificacion": { "type": "string", "enum": [ "CC", "CE", "CD", "PA", "SC", "PE", "DE", "PT" ], "description": "Identificación del profesional que prestó el servicio; no es la identificación del paciente." }, "numDocumentoIdentificacion": { "type": "string", "minLength": 2, "maxLength": 20, "pattern": "^[a-zA-Z0-9]+$", "description": "Identificación del profesional que prestó el servicio; no es la identificación del paciente." }, "codDiagnosticoPrincipal": { "type": "string", "minLength": 4, "maxLength": 6 }, "codDiagnosticoRelacionado": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 4, "maxLength": 4 }, { "type": "null" } ] }, "codComplicacion": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 4, "maxLength": 4 }, { "type": "null" } ] }, "vrServicio": { "type": "number", "minimum": 0, "maximum": 999999999999 }, "conceptoRecaudo": { "type": "string" }, "valorPagoModerador": { "type": "number", "minimum": 0, "maximum": 999999999999 }, "numFEVPagoModerador": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 30 }, { "type": "null" } ] }, "codDiagnosticoPrincipalCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodDiagnosticoPrincipalCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codDiagnosticoRelacionadoCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodDiagnosticoRelacionadoCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codComplicacionCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodComplicacionCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codigoVIDA": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "consecutivo": { "type": "integer", "minimum": 1, "maximum": 999999 } }, "required": [ "codPrestador", "fechaInicioAtencion", "viaIngresoServicioSalud", "modalidadGrupoServicioTecSal", "grupoServicios", "codServicio", "finalidadTecnologiaSalud", "tipoDocumentoIdentificacion", "numDocumentoIdentificacion", "codDiagnosticoPrincipal", "vrServicio", "conceptoRecaudo", "valorPagoModerador", "consecutivo" ], "description": "Estructura del perfil native-d558206. Las reglas clínicas, referencias y catálogos se verifican por separado." }, "NativeUrgenciaDTO": { "type": "object", "properties": { "codPrestador": { "type": "string", "minLength": 3, "maxLength": 12, "description": "Código verificado del prestador o sede: use providerCodes de GET /rips-packages/context. No es el documento del profesional." }, "fechaInicioAtencion": { "type": "string", "pattern": "[1-2]{1}[9|0]{1}[0-9]{2}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1]) (2[0-3]|[01][0-9]):[0-5][0-9]", "description": "Hora local clínica en formato AAAA-MM-DD HH:mm. No convertir este campo a una marca UTC." }, "causaMotivoAtencion": { "type": "string", "minLength": 2, "maxLength": 2 }, "codDiagnosticoPrincipal": { "type": "string", "minLength": 4, "maxLength": 6 }, "codDiagnosticoPrincipalE": { "type": "string", "minLength": 4, "maxLength": 6 }, "codDiagnosticoRelacionadoE1": { "type": [ "string", "null" ], "minLength": 4, "maxLength": 6 }, "codDiagnosticoRelacionadoE2": { "type": [ "string", "null" ], "minLength": 4, "maxLength": 6 }, "codDiagnosticoRelacionadoE3": { "type": [ "string", "null" ], "minLength": 4, "maxLength": 6 }, "condicionDestinoUsuarioEgreso": { "type": "string", "minLength": 2, "maxLength": 2 }, "codDiagnosticoCausaMuerte": { "type": [ "string", "null" ], "minLength": 4, "maxLength": 6 }, "fechaEgreso": { "type": "string", "pattern": "[1-2]{1}[9|0]{1}[0-9]{2}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1]) (2[0-3]|[01][0-9]):[0-5][0-9]", "description": "Hora local clínica en formato AAAA-MM-DD HH:mm. No convertir este campo a una marca UTC." }, "codDiagnosticoPrincipalCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodDiagnosticoPrincipalCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codDiagnosticoPrincipalECIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodDiagnosticoPrincipalECIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codDiagnosticoRelacionadoE1CIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodDiagnosticoRelacionadoE1CIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codDiagnosticoRelacionadoE2CIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodDiagnosticoRelacionadoE2CIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codDiagnosticoRelacionadoE3CIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodDiagnosticoRelacionadoE3CIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codDiagnosticoCausaMuerteCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodDiagnosticoCausaMuerteCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codigoVIDA": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "consecutivo": { "type": "integer", "minimum": 1, "maximum": 999999 } }, "required": [ "codPrestador", "fechaInicioAtencion", "causaMotivoAtencion", "codDiagnosticoPrincipal", "codDiagnosticoPrincipalE", "condicionDestinoUsuarioEgreso", "fechaEgreso", "consecutivo" ], "description": "Estructura del perfil native-d558206. Las reglas clínicas, referencias y catálogos se verifican por separado." }, "NativeHospitalizacionDTO": { "type": "object", "properties": { "codPrestador": { "type": "string", "minLength": 3, "maxLength": 12, "description": "Código verificado del prestador o sede: use providerCodes de GET /rips-packages/context. No es el documento del profesional." }, "viaIngresoServicioSalud": { "type": "string", "minLength": 2, "maxLength": 2 }, "fechaInicioAtencion": { "type": "string", "pattern": "[1-2]{1}[9|0]{1}[0-9]{2}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1]) (2[0-3]|[01][0-9]):[0-5][0-9]", "description": "Hora local clínica en formato AAAA-MM-DD HH:mm. No convertir este campo a una marca UTC." }, "numAutorizacion": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 30 }, { "type": "null" } ] }, "causaMotivoAtencion": { "type": "string", "minLength": 2, "maxLength": 2 }, "codDiagnosticoPrincipal": { "type": "string", "minLength": 4, "maxLength": 4 }, "codDiagnosticoPrincipalE": { "type": "string", "minLength": 4, "maxLength": 4 }, "codDiagnosticoRelacionadoE1": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 4, "maxLength": 4 }, { "type": "null" } ] }, "codDiagnosticoRelacionadoE2": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 4, "maxLength": 4 }, { "type": "null" } ] }, "codDiagnosticoRelacionadoE3": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 4, "maxLength": 4 }, { "type": "null" } ] }, "codComplicacion": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 4, "maxLength": 4 }, { "type": "null" } ] }, "condicionDestinoUsuarioEgreso": { "type": "string", "minLength": 2, "maxLength": 2 }, "codDiagnosticoCausaMuerte": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 4, "maxLength": 4 }, { "type": "null" } ] }, "fechaEgreso": { "type": "string", "pattern": "[1-2]{1}[9|0]{1}[0-9]{2}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1]) (2[0-3]|[01][0-9]):[0-5][0-9]", "description": "Hora local clínica en formato AAAA-MM-DD HH:mm. No convertir este campo a una marca UTC." }, "codDiagnosticoPrincipalECIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodDiagnosticoPrincipalECIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codDiagnosticoPrincipalCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodDiagnosticoPrincipalCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codDiagnosticoRelacionadoE1CIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodDiagnosticoRelacionadoE1CIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codDiagnosticoRelacionadoE2CIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodDiagnosticoRelacionadoE2CIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codDiagnosticoRelacionadoE3CIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodDiagnosticoRelacionadoE3CIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codComplicacionCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodComplicacionCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codDiagnosticoCausaMuerteCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodDiagnosticoCausaMuerteCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codigoVIDA": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "consecutivo": { "type": "integer", "minimum": 1, "maximum": 999999 } }, "required": [ "codPrestador", "viaIngresoServicioSalud", "fechaInicioAtencion", "causaMotivoAtencion", "codDiagnosticoPrincipal", "codDiagnosticoPrincipalE", "condicionDestinoUsuarioEgreso", "fechaEgreso", "consecutivo" ], "description": "Estructura del perfil native-d558206. Las reglas clínicas, referencias y catálogos se verifican por separado." }, "NativeRecienNacidoDTO": { "type": "object", "properties": { "codPrestador": { "type": "string", "minLength": 3, "maxLength": 12, "description": "Código verificado del prestador o sede: use providerCodes de GET /rips-packages/context. No es el documento del profesional." }, "tipoDocumentoIdentificacion": { "type": "string", "enum": [ "CN", "RC", "MS" ] }, "numDocumentoIdentificacion": { "type": "string", "minLength": 2, "maxLength": 20, "pattern": "^[a-zA-Z0-9]+$" }, "fechaNacimiento": { "type": "string", "pattern": "[1-2]{1}[9|0]{1}[0-9]{2}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1]) (2[0-3]|[01][0-9]):[0-5][0-9]" }, "edadGestacional": { "type": "integer" }, "numConsultasCPrenatal": { "type": "integer", "minimum": 0, "maximum": 99 }, "codSexoBiologico": { "type": "string", "minLength": 2, "maxLength": 2 }, "peso": { "type": "number" }, "codDiagnosticoPrincipal": { "type": "string", "minLength": 4, "maxLength": 4 }, "condicionDestinoUsuarioEgreso": { "type": "string", "minLength": 2, "maxLength": 2 }, "codDiagnosticoCausaMuerte": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 4, "maxLength": 4 }, { "type": "null" } ] }, "fechaEgreso": { "type": "string", "pattern": "[1-2]{1}[9|0]{1}[0-9]{2}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1]) (2[0-3]|[01][0-9]):[0-5][0-9]", "description": "Hora local clínica en formato AAAA-MM-DD HH:mm. No convertir este campo a una marca UTC." }, "codDiagnosticoPrincipalCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodDiagnosticoPrincipalCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codDiagnosticoPrincipalECIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ], "description": "Alias de entrada nativo; el envío usa el campo canónico. No envíe ambos con valores diferentes." }, "nomCodDiagnosticoPrincipalECIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ], "description": "Alias de entrada nativo; el envío usa el campo canónico. No envíe ambos con valores diferentes." }, "codDiagnosticoCausaMuerteCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodDiagnosticoCausaMuerteCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codigoVIDA": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "consecutivo": { "type": "integer", "minimum": 1, "maximum": 999999 } }, "required": [ "codPrestador", "tipoDocumentoIdentificacion", "numDocumentoIdentificacion", "fechaNacimiento", "codSexoBiologico", "codDiagnosticoPrincipal", "condicionDestinoUsuarioEgreso", "fechaEgreso", "consecutivo" ], "description": "Estructura del perfil native-d558206. Las reglas clínicas, referencias y catálogos se verifican por separado." }, "NativeMedicamentoDTO": { "type": "object", "properties": { "codPrestador": { "type": "string", "minLength": 3, "maxLength": 12, "description": "Código verificado del prestador o sede: use providerCodes de GET /rips-packages/context. No es el documento del profesional." }, "numAutorizacion": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string" }, { "type": "null" } ] }, "idMIPRES": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^[0-9]{1,19}$" }, { "type": "null" } ] }, "fechaDispensAdmon": { "type": "string", "pattern": "[1-2]{1}[9|0]{1}[0-9]{2}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1]) (2[0-3]|[01][0-9]):[0-5][0-9]", "description": "Hora local clínica en formato AAAA-MM-DD HH:mm. No convertir este campo a una marca UTC." }, "codDiagnosticoPrincipal": { "type": "string", "minLength": 4, "maxLength": 4 }, "codDiagnosticoRelacionado": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 4, "maxLength": 4 }, { "type": "null" } ] }, "tipoMedicamento": { "type": "string", "minLength": 2, "maxLength": 2 }, "codTecnologiaSalud": { "type": "string", "minLength": 1, "maxLength": 20 }, "nomTecnologiaSalud": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 128 }, { "type": "null" } ] }, "concentracionMedicamento": { "type": "integer", "minimum": 0, "maximum": 999 }, "unidadMedida": { "type": "integer", "minimum": 0, "maximum": 9999 }, "formaFarmaceutica": { "type": [ "string", "null" ], "minLength": 6, "maxLength": 8 }, "unidadMinDispensa": { "type": "integer", "minimum": 1, "maximum": 999 }, "cantidadMedicamento": { "type": "integer", "minimum": 0, "maximum": 9999999999 }, "diasTratamiento": { "type": "integer", "minimum": 0, "maximum": 999 }, "tipoDocumentoIdentificacion": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "enum": [ "", "CC", "CE", "CD", "PA", "SC", "PE", "DE", "PT" ] }, { "type": "null" } ], "description": "Identificación del profesional que prestó el servicio; no es la identificación del paciente." }, "numDocumentoIdentificacion": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 4, "maxLength": 20, "pattern": "^[a-zA-Z0-9]+$" }, { "type": "null" } ], "description": "Identificación del profesional que prestó el servicio; no es la identificación del paciente." }, "vrUnitMedicamento": { "type": "number", "minimum": 0, "maximum": 999999999999 }, "vrServicio": { "type": "number", "minimum": 0, "maximum": 999999999999 }, "vrDispensacion": { "type": "number", "minimum": 0, "maximum": 999999999999 }, "conceptoRecaudo": { "type": "string" }, "valorPagoModerador": { "type": "number", "minimum": 0, "maximum": 999999999999 }, "numFEVPagoModerador": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 30 }, { "type": "null" } ] }, "codDiagnosticoPrincipalECIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodDiagnosticoPrincipalECIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codDiagnosticoPrincipalCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ], "description": "Alias de entrada nativo; el envío usa el campo canónico. No envíe ambos con valores diferentes." }, "nomCodDiagnosticoPrincipalCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ], "description": "Alias de entrada nativo; el envío usa el campo canónico. No envíe ambos con valores diferentes." }, "codDiagnosticoRelacionadoCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "nomCodDiagnosticoRelacionadoCIE11": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 1000 }, { "type": "null" } ] }, "codigoVIDA": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "consecutivo": { "type": "integer", "minimum": 1, "maximum": 999999 } }, "required": [ "codPrestador", "fechaDispensAdmon", "codDiagnosticoPrincipal", "tipoMedicamento", "codTecnologiaSalud", "vrUnitMedicamento", "vrServicio", "vrDispensacion", "conceptoRecaudo", "valorPagoModerador", "consecutivo" ], "description": "Estructura del perfil native-d558206. Las reglas clínicas, referencias y catálogos se verifican por separado." }, "NativeOtrosServicioDTO": { "type": "object", "properties": { "codPrestador": { "type": "string", "minLength": 3, "maxLength": 12, "description": "Código verificado del prestador o sede: use providerCodes de GET /rips-packages/context. No es el documento del profesional." }, "numAutorizacion": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 30 }, { "type": "null" } ] }, "idMIPRES": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^[0-9]{1,19}$" }, { "type": "null" } ] }, "fechaSuministroTecnologia": { "type": "string", "pattern": "[1-2]{1}[9|0]{1}[0-9]{2}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1]) (2[0-3]|[01][0-9]):[0-5][0-9]", "description": "Hora local clínica en formato AAAA-MM-DD HH:mm. No convertir este campo a una marca UTC." }, "tipoOS": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^(01|02|03|04|05|06)$" }, "codTecnologiaSalud": { "type": "string", "minLength": 1, "maxLength": 20 }, "nomTecnologiaSalud": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 128 }, { "type": "null" } ] }, "cantidadOS": { "type": "integer", "minimum": 1, "maximum": 99999 }, "tipoDocumentoIdentificacion": { "type": [ "string", "null" ], "enum": [ "CC", "CE", "CD", "PA", "SC", "PE", "DE", "PT", null ], "description": "Identificación del profesional que prestó el servicio; no es la identificación del paciente." }, "numDocumentoIdentificacion": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 20, "pattern": "^[a-zA-Z0-9]+$", "description": "Identificación del profesional que prestó el servicio; no es la identificación del paciente." }, "vrUnitOS": { "type": "number", "minimum": 0, "maximum": 999999999999999 }, "vrServicio": { "type": "number", "minimum": 0, "maximum": 999999999999 }, "conceptoRecaudo": { "type": "string" }, "valorPagoModerador": { "type": "number", "minimum": 0, "maximum": 999999999999 }, "numFEVPagoModerador": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 30 }, { "type": "null" } ] }, "codigoVIDA": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 0, "maxLength": 256 }, { "type": "null" } ] }, "vrDispensacion": { "type": "number", "minimum": 0, "maximum": 999999999999 }, "consecutivo": { "type": "integer", "minimum": 1, "maximum": 999999 } }, "required": [ "codPrestador", "fechaSuministroTecnologia", "tipoOS", "codTecnologiaSalud", "vrUnitOS", "vrServicio", "conceptoRecaudo", "valorPagoModerador", "consecutivo" ], "description": "Estructura del perfil native-d558206. Las reglas clínicas, referencias y catálogos se verifican por separado." }, "FieldConditionIssue": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "severity": { "type": "string", "enum": [ "error", "notification", "unresolved" ] }, "message": { "type": "string" }, "source": { "type": "object", "additionalProperties": {} } }, "required": [ "path", "code", "severity", "message", "source" ] }, "DispatchAttemptList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DispatchAttempt" } } }, "required": [ "items" ] }, "DispatchAttempt": { "type": "object", "properties": { "id": { "type": "string" }, "revision": { "type": "integer" }, "outcome": { "$ref": "#/components/schemas/DispatchOutcome" }, "environment": { "$ref": "#/components/schemas/WorkspaceEnvironment" }, "attemptedAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "completedAt": { "type": [ "string", "null" ], "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "procesoId": { "type": [ "string", "null" ] }, "cuv": { "type": [ "string", "null" ], "description": "Solo presente si el recibo es aceptado y verificado." }, "message": { "type": [ "string", "null" ] }, "requestDigest": { "type": "string" }, "validations": { "type": "array", "items": { "$ref": "#/components/schemas/MinistryValidation" } }, "requestJson": { "type": [ "string", "null" ], "description": "Cuerpo exacto enviado (snapshot inmutable)." }, "responseJson": { "type": [ "string", "null" ], "description": "Respuesta exacta recibida, si existe." }, "reconciliation": { "type": [ "object", "null" ], "properties": { "evidenceCuv": { "type": "string" }, "outcome": { "type": "string", "enum": [ "accepted", "inconclusive" ] }, "reconciledAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" } }, "required": [ "evidenceCuv", "outcome", "reconciledAt" ] } }, "required": [ "id", "revision", "outcome", "environment", "attemptedAt", "completedAt", "procesoId", "cuv", "message", "requestDigest", "validations", "reconciliation" ], "description": "Intento inmutable registrado antes de la llamada externa." }, "MinistryValidation": { "type": "object", "properties": { "class": { "type": "string" }, "code": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "observations": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ] } }, "required": [ "class", "code", "description", "observations", "path" ] }, "RipsDispatchResult": { "type": "object", "properties": { "attempt": { "$ref": "#/components/schemas/DispatchAttempt" }, "package": { "$ref": "#/components/schemas/RipsPackage" }, "replayed": { "type": "boolean", "description": "true si se devolvió el resultado guardado de la misma clave e intención." } }, "required": [ "attempt", "package", "replayed" ], "description": "El intento no repite el cuerpo enviado: GET …/dispatches devuelve requestJson con cada intento." }, "ReconcileDispatchInput": { "type": "object", "properties": { "attemptId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "evidence": { "type": "object", "properties": { "cuv": { "type": "string", "pattern": "^[a-f0-9]{96}$", "description": "CUV informado por el Ministerio para el intento incierto." } }, "required": [ "cuv" ], "additionalProperties": false } }, "required": [ "attemptId", "evidence" ], "additionalProperties": false }, "HealthInvoicePage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/HealthInvoiceSummary" } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalCount": { "type": "integer" } }, "required": [ "items", "page", "pageSize", "totalCount" ] }, "HealthInvoiceSummary": { "type": "object", "properties": { "id": { "type": "string" }, "clientId": { "type": "string" }, "clientName": { "type": "string" }, "locationId": { "type": [ "string", "null" ] }, "totalAmount": { "type": "number" }, "creditedAmount": { "type": "number", "description": "Suma de notas crédito aceptadas o en curso." }, "status": { "$ref": "#/components/schemas/HealthDocumentStatus" }, "statusMessage": { "type": [ "string", "null" ] }, "assignedInvoiceNumber": { "type": [ "string", "null" ] }, "cufe": { "type": [ "string", "null" ] }, "dianStatusCode": { "type": [ "string", "null" ] }, "submittedByUserId": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "updatedAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" } }, "required": [ "id", "clientId", "clientName", "locationId", "totalAmount", "creditedAmount", "status", "statusMessage", "assignedInvoiceNumber", "cufe", "dianStatusCode", "submittedByUserId", "isActive", "createdAt", "updatedAt" ] }, "HealthDocumentStatus": { "type": "string", "enum": [ "Pending", "Emitting", "Accepted", "Failed", "Unknown", "Historical" ], "description": "Pending: sin emisión iniciada. Emitting: emisión en curso. Accepted: recibo de PahFacturar y validación DIAN. Failed: falló antes del proveedor o fue rechazado; un reintento crea una emisión nueva. Unknown: resultado incierto. Historical: registro importado sin recibo de este servidor; solo lectura." }, "EmitHealthInvoiceInput": { "type": "object", "properties": { "clientId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "invoiceResolutionId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "invoicePayload": { "$ref": "#/components/schemas/HealthInvoicePayload" }, "rips": { "anyOf": [ { "$ref": "#/components/schemas/DraftRipsDTO" }, { "type": "string", "maxLength": 25000000, "description": "Texto JSON UTF-8 original. Se conserva sin reformatear. Use esta opción para importar un origen que todavía necesita correcciones; valide antes de enviar." }, { "type": "null" } ], "description": "RIPS de la factura (sin numFactura). Se conserva para preparar el paquete fev_rips." } }, "required": [ "clientId", "invoiceResolutionId", "invoicePayload" ], "additionalProperties": false }, "HealthInvoicePayload": { "type": "object", "properties": { "type_document_id": { "type": "integer", "minimum": 1, "maximum": 5 }, "invoice_lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "code": { "type": "string", "maxLength": 60 }, "invoiced_quantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "price_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "line_extension_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "base_quantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "unit_measure_id": { "type": "integer" }, "type_item_identification_id": { "type": "integer" }, "free_of_charge_indicator": { "type": "boolean" }, "notes": { "type": "string", "maxLength": 500 }, "allowance_total": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "charge_total": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "tax_totals": { "type": "array", "items": { "type": "object", "properties": { "tax_id": { "type": "integer", "minimum": 1, "maximum": 4 }, "tax_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "percent": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "taxable_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" } }, "required": [ "tax_id", "tax_amount", "percent", "taxable_amount" ], "additionalProperties": false }, "maxItems": 4 } }, "required": [ "description", "invoiced_quantity", "price_amount", "line_extension_amount" ], "additionalProperties": false }, "minItems": 1, "maxItems": 5000 }, "legal_monetary_totals": { "type": "object", "properties": { "line_extension_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "tax_exclusive_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "tax_inclusive_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "payable_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "allowance_total_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "charge_total_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" } }, "required": [ "line_extension_amount", "tax_exclusive_amount", "tax_inclusive_amount", "payable_amount" ], "additionalProperties": false }, "tax_totals": { "type": "array", "items": { "type": "object", "properties": { "tax_id": { "type": "integer", "minimum": 1, "maximum": 4 }, "tax_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "percent": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "taxable_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" } }, "required": [ "tax_id", "tax_amount", "percent", "taxable_amount" ], "additionalProperties": false }, "maxItems": 4 }, "payment_form": { "type": "object", "properties": { "payment_form_id": { "type": "integer", "minimum": 1, "maximum": 2 }, "payment_method_id": { "type": "integer", "minimum": 1, "maximum": 100 }, "payment_due_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Fecha AAAA-MM-DD.", "example": "2026-10-15" }, "duration_measure": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "required": [ "payment_form_id", "payment_method_id" ], "additionalProperties": false }, "health_fields": { "$ref": "#/components/schemas/HealthFields" } }, "required": [ "invoice_lines", "legal_monetary_totals", "payment_form", "health_fields" ], "additionalProperties": false, "description": "Contenido de negocio de la factura. El cliente, el prefijo, el número, la resolución, la fecha y la hora los asigna el servidor desde recursos verificados." }, "HealthFields": { "type": "object", "properties": { "invoice_period_start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Fecha AAAA-MM-DD.", "example": "2026-10-15" }, "invoice_period_end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Fecha AAAA-MM-DD.", "example": "2026-10-15" }, "health_type_operation_id": { "type": "string", "minLength": 1, "maxLength": 12 }, "users_info": { "type": "array", "items": { "type": "object", "properties": { "provider_code": { "type": "string", "pattern": "^\\d{10,12}$", "description": "Debe ser un código de prestador o de sede verificado del espacio." }, "health_coverage_id": { "type": "string", "minLength": 1, "maxLength": 4 }, "health_contracting_payment_method_id": { "type": "string", "minLength": 1, "maxLength": 4 }, "contract_number": { "type": "string", "maxLength": 60 }, "policy_number": { "type": "string", "maxLength": 60 }, "invoice_without_contract_reason": { "type": "string", "maxLength": 4 }, "co_payment": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "moderating_fee": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "recovery_fee": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "shared_payment": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" } }, "required": [ "provider_code", "health_coverage_id", "health_contracting_payment_method_id" ], "additionalProperties": false }, "minItems": 1, "maxItems": 1 } }, "required": [ "invoice_period_start_date", "invoice_period_end_date", "health_type_operation_id", "users_info" ], "additionalProperties": false, "description": "Campos del sector salud. Obligatorios en la factura de salud." }, "HealthInvoice": { "type": "object", "properties": { "id": { "type": "string" }, "clientId": { "type": "string" }, "clientName": { "type": "string" }, "locationId": { "type": [ "string", "null" ] }, "totalAmount": { "type": "number" }, "creditedAmount": { "type": "number", "description": "Suma de notas crédito aceptadas o en curso." }, "status": { "$ref": "#/components/schemas/HealthDocumentStatus" }, "statusMessage": { "type": [ "string", "null" ] }, "assignedInvoiceNumber": { "type": [ "string", "null" ] }, "cufe": { "type": [ "string", "null" ] }, "dianStatusCode": { "type": [ "string", "null" ] }, "submittedByUserId": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "updatedAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "dianStatusDescription": { "type": [ "string", "null" ] }, "invoiceResolutionId": { "type": [ "string", "null" ] }, "invoicePayloadJson": { "type": [ "string", "null" ] }, "workingRipsJson": { "type": [ "string", "null" ] }, "invoiceDispatchHistory": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentAttempt" } }, "ripsPackages": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedRipsPackage" } }, "documentAvailability": { "type": "array", "items": { "$ref": "#/components/schemas/ArtifactAvailability" } } }, "required": [ "id", "clientId", "clientName", "locationId", "totalAmount", "creditedAmount", "status", "statusMessage", "assignedInvoiceNumber", "cufe", "dianStatusCode", "submittedByUserId", "isActive", "createdAt", "updatedAt", "dianStatusDescription", "invoiceResolutionId", "invoicePayloadJson", "workingRipsJson", "invoiceDispatchHistory", "ripsPackages", "documentAvailability" ], "description": "Factura de salud emitida por PahFacturar." }, "DocumentAttempt": { "type": "object", "properties": { "attemptedAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "succeeded": { "type": "boolean" }, "errorMessage": { "type": [ "string", "null" ] }, "requestPayload": { "type": "string" }, "responsePayload": { "type": [ "string", "null" ] }, "source": { "type": "string" } }, "required": [ "attemptedAt", "succeeded", "errorMessage", "requestPayload", "responsePayload", "source" ] }, "LinkedRipsPackage": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "status": { "type": "string" }, "cuv": { "type": [ "string", "null" ] } }, "required": [ "id", "kind", "status", "cuv" ] }, "ArtifactAvailability": { "type": "object", "properties": { "documentType": { "type": "string", "enum": [ "pdf", "xml", "attached" ] }, "isSupported": { "type": "boolean" }, "canDownload": { "type": "boolean" } }, "required": [ "documentType", "isSupported", "canDownload" ] }, "ReconcileHealthDocumentInput": { "type": "object", "properties": { "providerDocumentId": { "type": "string", "format": "uuid", "description": "Identificador del documento en PahFacturar informado por el proveedor." } }, "required": [ "providerDocumentId" ], "additionalProperties": false, "description": "Requiere el UUID que ya conoce en PahFacturar. No busca documentos por número ni recupera un UUID perdido. Sin ese dato, conserve Unknown y solicite recuperación; nunca cree otra emisión como consulta." }, "EmailResult": { "type": "object", "properties": { "sent": { "type": "boolean", "enum": [ true ] }, "to": { "type": "string" }, "cc": { "type": [ "string", "null" ] }, "subject": { "type": "string" }, "attachmentName": { "type": "string" }, "attachmentSize": { "type": "integer" } }, "required": [ "sent", "to", "cc", "subject", "attachmentName", "attachmentSize" ] }, "CreditNotePage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNoteSummary" } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalCount": { "type": "integer" } }, "required": [ "items", "page", "pageSize", "totalCount" ] }, "CreditNoteSummary": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "originalInvoiceNumber": { "type": [ "string", "null" ] }, "clientId": { "type": "string" }, "clientName": { "type": "string" }, "totalAmount": { "type": "number" }, "status": { "$ref": "#/components/schemas/HealthDocumentStatus" }, "statusMessage": { "type": [ "string", "null" ] }, "assignedCreditNoteNumber": { "type": [ "string", "null" ] }, "cude": { "type": [ "string", "null" ] }, "discrepancyResponseCode": { "type": "integer" }, "discrepancyResponseDescription": { "type": "string" }, "ripsPackageKind": { "type": "string", "enum": [ "nc_total", "nc_parcial" ] }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "updatedAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" } }, "required": [ "id", "invoiceId", "originalInvoiceNumber", "clientId", "clientName", "totalAmount", "status", "statusMessage", "assignedCreditNoteNumber", "cude", "discrepancyResponseCode", "discrepancyResponseDescription", "ripsPackageKind", "isActive", "createdAt", "updatedAt" ] }, "EmitCreditNoteInput": { "type": "object", "properties": { "invoiceId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "creditNoteResolutionId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "locationId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "discrepancyResponseCode": { "type": "integer", "minimum": 1, "maximum": 6, "description": "Código DIAN de concepto. 2 = anulación total." }, "discrepancyResponseDescription": { "type": "string", "minLength": 1, "maxLength": 500 }, "selectedItems": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNoteSelection" }, "maxItems": 5000 }, "creditNotePayload": { "$ref": "#/components/schemas/CreditNotePayload" } }, "required": [ "invoiceId", "creditNoteResolutionId", "discrepancyResponseCode", "discrepancyResponseDescription", "creditNotePayload" ], "additionalProperties": false }, "CreditNoteSelection": { "type": "object", "properties": { "patientConsecutivo": { "type": "integer", "minimum": 0 }, "includeAllServices": { "type": "boolean" }, "selectedServices": { "type": "array", "items": { "type": "object", "properties": { "serviceCategory": { "type": "string", "enum": [ "consultas", "procedimientos", "urgencias", "hospitalizacion", "recienNacidos", "medicamentos", "otrosServicios" ] }, "serviceConsecutivo": { "type": "integer", "minimum": 0 } }, "required": [ "serviceCategory", "serviceConsecutivo" ], "additionalProperties": false }, "maxItems": 5000 } }, "required": [ "patientConsecutivo" ], "additionalProperties": false }, "CreditNotePayload": { "type": "object", "properties": { "credit_note_lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "code": { "type": "string", "maxLength": 60 }, "invoiced_quantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "price_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "line_extension_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "base_quantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "unit_measure_id": { "type": "integer" }, "type_item_identification_id": { "type": "integer" }, "free_of_charge_indicator": { "type": "boolean" }, "notes": { "type": "string", "maxLength": 500 }, "allowance_total": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "charge_total": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "tax_totals": { "type": "array", "items": { "type": "object", "properties": { "tax_id": { "type": "integer", "minimum": 1, "maximum": 4 }, "tax_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "percent": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "taxable_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" } }, "required": [ "tax_id", "tax_amount", "percent", "taxable_amount" ], "additionalProperties": false }, "maxItems": 4 } }, "required": [ "description", "invoiced_quantity", "price_amount", "line_extension_amount" ], "additionalProperties": false }, "minItems": 1, "maxItems": 5000 }, "legal_monetary_totals": { "type": "object", "properties": { "line_extension_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "tax_exclusive_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "tax_inclusive_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "payable_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "allowance_total_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "charge_total_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" } }, "required": [ "line_extension_amount", "tax_exclusive_amount", "tax_inclusive_amount", "payable_amount" ], "additionalProperties": false }, "tax_totals": { "type": "array", "items": { "type": "object", "properties": { "tax_id": { "type": "integer", "minimum": 1, "maximum": 4 }, "tax_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "percent": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "taxable_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" } }, "required": [ "tax_id", "tax_amount", "percent", "taxable_amount" ], "additionalProperties": false }, "maxItems": 4 }, "payment_form": { "type": "object", "properties": { "payment_form_id": { "type": "integer", "minimum": 1, "maximum": 2 }, "payment_method_id": { "type": "integer", "minimum": 1, "maximum": 100 }, "payment_due_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Fecha AAAA-MM-DD.", "example": "2026-10-15" }, "duration_measure": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "required": [ "payment_form_id", "payment_method_id" ], "additionalProperties": false } }, "required": [ "credit_note_lines", "legal_monetary_totals" ], "additionalProperties": false, "description": "Líneas y totales de la nota. Cliente, referencia a la factura, campos de salud y numeración los deriva el servidor de la factura aceptada." }, "CreditNote": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "originalInvoiceNumber": { "type": [ "string", "null" ] }, "clientId": { "type": "string" }, "clientName": { "type": "string" }, "totalAmount": { "type": "number" }, "status": { "$ref": "#/components/schemas/HealthDocumentStatus" }, "statusMessage": { "type": [ "string", "null" ] }, "assignedCreditNoteNumber": { "type": [ "string", "null" ] }, "cude": { "type": [ "string", "null" ] }, "discrepancyResponseCode": { "type": "integer" }, "discrepancyResponseDescription": { "type": "string" }, "ripsPackageKind": { "type": "string", "enum": [ "nc_total", "nc_parcial" ] }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "updatedAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "originalInvoiceCufe": { "type": [ "string", "null" ] }, "dianStatusCode": { "type": [ "string", "null" ] }, "dianStatusDescription": { "type": [ "string", "null" ] }, "submittedByUserId": { "type": [ "string", "null" ] }, "creditNotePayloadJson": { "type": [ "string", "null" ] }, "workingRipsJson": { "type": [ "string", "null" ] }, "dispatchHistory": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentAttempt" } }, "ripsPackages": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedRipsPackage" } }, "documentAvailability": { "type": "array", "items": { "$ref": "#/components/schemas/ArtifactAvailability" } } }, "required": [ "id", "invoiceId", "originalInvoiceNumber", "clientId", "clientName", "totalAmount", "status", "statusMessage", "assignedCreditNoteNumber", "cude", "discrepancyResponseCode", "discrepancyResponseDescription", "ripsPackageKind", "isActive", "createdAt", "updatedAt", "originalInvoiceCufe", "dianStatusCode", "dianStatusDescription", "submittedByUserId", "creditNotePayloadJson", "workingRipsJson", "dispatchHistory", "ripsPackages", "documentAvailability" ], "description": "Nota crédito de salud emitida por PahFacturar." }, "CreditNoteContext": { "type": "object", "properties": { "invoice": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "invoiceNumber": { "type": [ "string", "null" ] }, "cufe": { "type": [ "string", "null" ] }, "issueDate": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "totalAmount": { "type": "number" }, "creditedAmount": { "type": "number" }, "availableAmount": { "type": "number" }, "clientName": { "type": "string" }, "clientId": { "type": "string" }, "locationId": { "type": [ "string", "null" ] } }, "required": [ "id", "invoiceNumber", "cufe", "issueDate", "totalAmount", "creditedAmount", "availableAmount", "clientName", "clientId", "locationId" ] }, "patients": { "type": "array", "items": { "type": "object", "properties": { "consecutivo": { "type": "number" }, "tipoDocumentoIdentificacion": { "type": "string" }, "numDocumentoIdentificacion": { "type": "string" }, "patientName": { "type": [ "string", "null" ] }, "totalAmount": { "type": "number" }, "services": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "consecutivo": { "type": "number" }, "description": { "type": "string" }, "amount": { "type": "number" }, "serviceDate": { "type": [ "string", "null" ] } }, "required": [ "category", "consecutivo", "description", "amount", "serviceDate" ] } } }, "required": [ "consecutivo", "tipoDocumentoIdentificacion", "numDocumentoIdentificacion", "patientName", "totalAmount", "services" ] } }, "availableResolutions": { "type": "array", "items": { "$ref": "#/components/schemas/Resolution" } }, "canCreateCreditNote": { "type": "boolean" }, "validationMessage": { "type": [ "string", "null" ] } }, "required": [ "invoice", "patients", "availableResolutions", "canCreateCreditNote", "validationMessage" ] }, "DebitNotePage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DebitNoteSummary" } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalCount": { "type": "integer" } }, "required": [ "items", "page", "pageSize", "totalCount" ] }, "DebitNoteSummary": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "originalInvoiceNumber": { "type": [ "string", "null" ] }, "clientId": { "type": "string" }, "clientName": { "type": "string" }, "totalAmount": { "type": "number" }, "status": { "$ref": "#/components/schemas/HealthDocumentStatus" }, "statusMessage": { "type": [ "string", "null" ] }, "assignedDebitNoteNumber": { "type": [ "string", "null" ] }, "cude": { "type": [ "string", "null" ] }, "discrepancyResponseCode": { "$ref": "#/components/schemas/DebitNoteReasonCode" }, "discrepancyResponseDescription": { "type": "string" }, "ripsPackageKind": { "type": "string", "enum": [ "nd" ] }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "updatedAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" } }, "required": [ "id", "invoiceId", "originalInvoiceNumber", "clientId", "clientName", "totalAmount", "status", "statusMessage", "assignedDebitNoteNumber", "cude", "discrepancyResponseCode", "discrepancyResponseDescription", "ripsPackageKind", "isActive", "createdAt", "updatedAt" ] }, "DebitNoteReasonCode": { "type": "integer", "minimum": 1, "maximum": 4, "description": "DIAN catálogo 89: 1 Intereses; 2 Gastos por cobrar; 3 Cambio del valor; 4 Otros. No son los conceptos de nota crédito.", "example": 3 }, "EmitDebitNoteInput": { "type": "object", "properties": { "invoiceId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "debitNoteResolutionId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "discrepancyResponseCode": { "$ref": "#/components/schemas/DebitNoteReasonCode" }, "discrepancyResponseDescription": { "type": "string", "minLength": 1, "maxLength": 500 }, "debitNotePayload": { "$ref": "#/components/schemas/DebitNotePayload" }, "rips": { "$ref": "#/components/schemas/SupplementalDebitRips" } }, "required": [ "invoiceId", "debitNoteResolutionId", "discrepancyResponseCode", "discrepancyResponseDescription", "debitNotePayload", "rips" ], "additionalProperties": false, "description": "Emite una nota débito de salud a partir de una factura aceptada, con sus servicios RIPS adicionales. El importe no se limita por el saldo de notas crédito. Requiere datos adicionales explícitos; nunca reutiliza automáticamente los servicios facturados." }, "DebitNotePayload": { "type": "object", "properties": { "debit_note_lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "code": { "type": "string", "maxLength": 60 }, "invoiced_quantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "price_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "line_extension_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "base_quantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "unit_measure_id": { "type": "integer" }, "type_item_identification_id": { "type": "integer" }, "free_of_charge_indicator": { "type": "boolean" }, "notes": { "type": "string", "maxLength": 500 }, "allowance_total": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "charge_total": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "tax_totals": { "type": "array", "items": { "type": "object", "properties": { "tax_id": { "type": "integer", "minimum": 1, "maximum": 4 }, "tax_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "percent": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "taxable_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" } }, "required": [ "tax_id", "tax_amount", "percent", "taxable_amount" ], "additionalProperties": false }, "maxItems": 4 } }, "required": [ "description", "invoiced_quantity", "price_amount", "line_extension_amount" ], "additionalProperties": false }, "minItems": 1, "maxItems": 5000 }, "legal_monetary_totals": { "type": "object", "properties": { "line_extension_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "tax_exclusive_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "tax_inclusive_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "payable_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "allowance_total_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "charge_total_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" } }, "required": [ "line_extension_amount", "tax_exclusive_amount", "tax_inclusive_amount", "payable_amount" ], "additionalProperties": false }, "tax_totals": { "type": "array", "items": { "type": "object", "properties": { "tax_id": { "type": "integer", "minimum": 1, "maximum": 4 }, "tax_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "percent": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" }, "taxable_amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(?:\\.\\d{1,6})?$" }, { "type": "number" } ], "description": "Valor decimal como texto (\"100.00\") o número JSON. Use punto decimal, sin separador de miles; se admiten hasta 6 decimales.", "example": "100000.00" } }, "required": [ "tax_id", "tax_amount", "percent", "taxable_amount" ], "additionalProperties": false }, "maxItems": 4 }, "payment_form": { "type": "object", "properties": { "payment_form_id": { "type": "integer", "minimum": 1, "maximum": 2 }, "payment_method_id": { "type": "integer", "minimum": 1, "maximum": 100 }, "payment_due_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Fecha AAAA-MM-DD.", "example": "2026-10-15" }, "duration_measure": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "required": [ "payment_form_id", "payment_method_id" ], "additionalProperties": false } }, "required": [ "debit_note_lines", "legal_monetary_totals" ], "additionalProperties": false, "description": "Valores adicionales de la nota débito. El servidor deriva cliente, factura referenciada, campos de salud y numeración. No envíe billing_reference, customer, número ni fecha. El total debe ser positivo y corresponder a los servicios RIPS adicionales." }, "SupplementalDebitRips": { "anyOf": [ { "$ref": "#/components/schemas/DraftRipsDTO" }, { "type": "string", "minLength": 1, "maxLength": 25000000, "description": "JSON exacto de los servicios adicionales. Se conserva para preparar el paquete ND." } ], "description": "RIPS adicional obligatorio, escrito expresamente por el cliente. No se copian los servicios de la factura. Los pacientes deben pertenecer a la factura de origen y los valores adicionales deben coincidir con la nota. El servidor fija numFactura, tipoNota=ND y numNota desde la factura y la nota emitidas." }, "DebitNote": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "originalInvoiceNumber": { "type": [ "string", "null" ] }, "clientId": { "type": "string" }, "clientName": { "type": "string" }, "totalAmount": { "type": "number" }, "status": { "$ref": "#/components/schemas/HealthDocumentStatus" }, "statusMessage": { "type": [ "string", "null" ] }, "assignedDebitNoteNumber": { "type": [ "string", "null" ] }, "cude": { "type": [ "string", "null" ] }, "discrepancyResponseCode": { "$ref": "#/components/schemas/DebitNoteReasonCode" }, "discrepancyResponseDescription": { "type": "string" }, "ripsPackageKind": { "type": "string", "enum": [ "nd" ] }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "updatedAt": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "originalInvoiceCufe": { "type": [ "string", "null" ] }, "dianStatusCode": { "type": [ "string", "null" ] }, "dianStatusDescription": { "type": [ "string", "null" ] }, "submittedByUserId": { "type": [ "string", "null" ] }, "debitNotePayloadJson": { "type": [ "string", "null" ] }, "workingRipsJson": { "type": [ "string", "null" ] }, "dispatchHistory": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentAttempt" } }, "ripsPackages": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedRipsPackage" } }, "documentAvailability": { "type": "array", "items": { "$ref": "#/components/schemas/ArtifactAvailability" } } }, "required": [ "id", "invoiceId", "originalInvoiceNumber", "clientId", "clientName", "totalAmount", "status", "statusMessage", "assignedDebitNoteNumber", "cude", "discrepancyResponseCode", "discrepancyResponseDescription", "ripsPackageKind", "isActive", "createdAt", "updatedAt", "originalInvoiceCufe", "dianStatusCode", "dianStatusDescription", "submittedByUserId", "debitNotePayloadJson", "workingRipsJson", "dispatchHistory", "ripsPackages", "documentAvailability" ], "description": "Nota débito de salud emitida por PahFacturar. Su CUDE no es el CUFE de la factura original. Emitir la nota no envía su RIPS al Ministerio." }, "DebitNoteContext": { "type": "object", "properties": { "invoice": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "invoiceNumber": { "type": [ "string", "null" ] }, "cufe": { "type": [ "string", "null" ] }, "issueDate": { "type": "string", "description": "Fecha y hora ISO 8601 (UTC).", "example": "2026-10-15T12:00:00.000Z" }, "totalAmount": { "type": "number" }, "clientName": { "type": "string" }, "clientId": { "type": "string" }, "locationId": { "type": [ "string", "null" ] } }, "required": [ "id", "invoiceNumber", "cufe", "issueDate", "totalAmount", "clientName", "clientId", "locationId" ] }, "patients": { "type": "array", "items": { "type": "object", "properties": { "consecutivo": { "type": "number" }, "tipoDocumentoIdentificacion": { "type": "string" }, "numDocumentoIdentificacion": { "type": "string" }, "patientName": { "type": [ "string", "null" ] }, "totalAmount": { "type": "number" }, "services": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "consecutivo": { "type": "number" }, "description": { "type": "string" }, "amount": { "type": "number" }, "serviceDate": { "type": [ "string", "null" ] } }, "required": [ "category", "consecutivo", "description", "amount", "serviceDate" ] } } }, "required": [ "consecutivo", "tipoDocumentoIdentificacion", "numDocumentoIdentificacion", "patientName", "totalAmount", "services" ] } }, "rips": { "type": [ "object", "null" ], "properties": { "numDocumentoIdObligado": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "numFactura": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "tipoNota": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "numNota": { "type": [ "string", "null" ], "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." }, "usuarios": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/DraftUsuarioDTO" }, "description": "Opcional en borrador. Su presencia, formato y condiciones para envío se verifican al validar la revisión." } }, "additionalProperties": {}, "description": "Demografía autorizada de los pacientes de la factura, con todas las listas de servicios vacías. Seleccione los pacientes y agregue los servicios adicionales. null impide preparar una nota con origen RIPS verificado." }, "availableResolutions": { "type": "array", "items": { "$ref": "#/components/schemas/Resolution" } }, "canCreateDebitNote": { "type": "boolean" }, "validationMessage": { "type": [ "string", "null" ] } }, "required": [ "invoice", "patients", "rips", "availableResolutions", "canCreateDebitNote", "validationMessage" ], "description": "Factura aceptada, pacientes originales y resoluciones para una nota débito. Los servicios se muestran como referencia, no se copian: capture los servicios adicionales en rips. No aplica el saldo de notas crédito." } } }, "paths": { "/health": { "get": { "operationId": "system.getHealth", "tags": [ "Estado" ], "summary": "Estado de la API", "description": "Comprueba que la configuración de orígenes externos sea válida para el entorno. No llama a servicios externos. Pública.", "security": [], "x-ripscloud-auth": "public", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": null, "responses": { "200": { "description": "Configuración válida.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "400": { "description": "Rechazo: invalid_request, invalid_query.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "503": { "description": "Rechazo: upstream_configuration_invalid.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "upstream_configuration_invalid": { "summary": "La conexión con el servicio externo no está configurada para este entorno.", "value": { "error": { "code": "upstream_configuration_invalid", "message": "La conexión con el servicio externo no está configurada para este entorno." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/me": { "get": { "operationId": "account.getProfile", "tags": [ "Mi cuenta" ], "summary": "Consultar mi perfil", "description": "Requiere un token de acceso. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "user", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "responses": { "200": { "description": "Perfil verificado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountProfile" } } } }, "400": { "description": "Rechazo: invalid_request, invalid_query.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/me/workspaces": { "get": { "operationId": "account.listWorkspaces", "tags": [ "Mi cuenta" ], "summary": "Listar mis espacios activos", "description": "Solo membresías activas en espacios activos. Un administrador de la plataforma sin membresías ve los espacios activos en modo operador. Requiere un token de acceso. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "user", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "responses": { "200": { "description": "Espacios del usuario.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MyWorkspaces" } } } }, "400": { "description": "Rechazo: invalid_request, invalid_query.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}": { "get": { "operationId": "workspace.get", "tags": [ "Espacio" ], "summary": "Consultar el espacio", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Espacio y rol del usuario.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/dashboard": { "get": { "operationId": "workspace.getDashboard", "tags": [ "Espacio" ], "summary": "Resumen del espacio", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Resumen.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dashboard" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/patients": { "get": { "operationId": "patients.list", "tags": [ "Pacientes" ], "summary": "Listar pacientes", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "q", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Incluir registros archivados." }, "required": false, "description": "Incluir registros archivados.", "name": "includeArchived", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Tamaño máximo de página. Predeterminado: 100; máximo: 500.", "example": 100 }, "required": false, "description": "Tamaño máximo de página. Predeterminado: 100; máximo: 500.", "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000, "description": "Registros que se omiten. Predeterminado: 0. Para avanzar use offset + items.length.", "example": 0 }, "required": false, "description": "Registros que se omiten. Predeterminado: 0. Para avanzar use offset + items.length.", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Página de registros activos (o archivados si se solicita).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientList" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } }, "post": { "operationId": "patients.create", "tags": [ "Pacientes" ], "summary": "Crear un paciente", "description": "Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. PAT: requiere el permiso write y acceso al espacio de la ruta, cuando exista. Límite del cuerpo HTTP: 1000000 bytes, antes de interpretar el contenido.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "write", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientInput" } } } }, "responses": { "201": { "description": "Registro creado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Patient" } } } }, "400": { "description": "Rechazo: invalid_json, duplicate_key, json_syntax, json_depth, json_type, numeric_value_loss, numeric_overflow, conflicting_alias, invalid_request, server_owned_field, invalid_query, invalid_path.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_json": { "summary": "El cuerpo no es JSON válido.", "value": { "error": { "code": "invalid_json", "message": "El cuerpo no es JSON válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_key": { "summary": "El cuerpo repite una clave JSON.", "value": { "error": { "code": "duplicate_key", "message": "El cuerpo repite una clave JSON." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "json_syntax": { "summary": "El JSON tiene un error de sintaxis.", "value": { "error": { "code": "json_syntax", "message": "El JSON tiene un error de sintaxis." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, duplicate_resource.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_resource": { "summary": "Ya existe un recurso con la misma identificación.", "value": { "error": { "code": "duplicate_resource", "message": "Ya existe un recurso con la misma identificación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: request_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "request_too_large": { "summary": "El cuerpo supera el tamaño permitido.", "value": { "error": { "code": "request_too_large", "message": "El cuerpo supera el tamaño permitido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "415": { "description": "Rechazo: unsupported_media_type.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported_media_type": { "summary": "El tipo de contenido no es compatible con esta operación.", "value": { "error": { "code": "unsupported_media_type", "message": "El tipo de contenido no es compatible con esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/patients/{patientId}": { "get": { "operationId": "patients.get", "tags": [ "Pacientes" ], "summary": "Consultar un paciente", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "patientId", "in": "path" } ], "responses": { "200": { "description": "Registro.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Patient" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } }, "patch": { "operationId": "patients.update", "tags": [ "Pacientes" ], "summary": "Actualizar un paciente", "description": "Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. PAT: requiere el permiso write y acceso al espacio de la ruta, cuando exista. Límite del cuerpo HTTP: 1000000 bytes, antes de interpretar el contenido.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "write", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "patientId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientPatch" } } } }, "responses": { "200": { "description": "Registro actualizado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Patient" } } } }, "400": { "description": "Rechazo: invalid_json, duplicate_key, json_syntax, json_depth, json_type, numeric_value_loss, numeric_overflow, conflicting_alias, invalid_request, server_owned_field, invalid_query, invalid_path.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_json": { "summary": "El cuerpo no es JSON válido.", "value": { "error": { "code": "invalid_json", "message": "El cuerpo no es JSON válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_key": { "summary": "El cuerpo repite una clave JSON.", "value": { "error": { "code": "duplicate_key", "message": "El cuerpo repite una clave JSON." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "json_syntax": { "summary": "El JSON tiene un error de sintaxis.", "value": { "error": { "code": "json_syntax", "message": "El JSON tiene un error de sintaxis." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, resource_archived, duplicate_resource.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "resource_archived": { "summary": "El recurso está archivado.", "value": { "error": { "code": "resource_archived", "message": "El recurso está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: request_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "request_too_large": { "summary": "El cuerpo supera el tamaño permitido.", "value": { "error": { "code": "request_too_large", "message": "El cuerpo supera el tamaño permitido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "415": { "description": "Rechazo: unsupported_media_type.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported_media_type": { "summary": "El tipo de contenido no es compatible con esta operación.", "value": { "error": { "code": "unsupported_media_type", "message": "El tipo de contenido no es compatible con esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } }, "delete": { "operationId": "patients.archive", "tags": [ "Pacientes" ], "summary": "Archivar un paciente", "description": "Borrado lógico. El registro se conserva para auditoría y se puede reactivar. Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. PAT: requiere el permiso write y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "write", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "patientId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Registro archivado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Patient" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/patients/{patientId}/restore": { "post": { "operationId": "patients.restore", "tags": [ "Pacientes" ], "summary": "Reactivar un paciente", "description": "Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. PAT: requiere el permiso write y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "write", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "patientId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Registro reactivado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Patient" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, duplicate_resource.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_resource": { "summary": "Ya existe un recurso con la misma identificación.", "value": { "error": { "code": "duplicate_resource", "message": "Ya existe un recurso con la misma identificación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/specialists": { "get": { "operationId": "specialists.list", "tags": [ "Profesionales" ], "summary": "Listar profesionales", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "q", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Incluir registros archivados." }, "required": false, "description": "Incluir registros archivados.", "name": "includeArchived", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Tamaño máximo de página. Predeterminado: 100; máximo: 500.", "example": 100 }, "required": false, "description": "Tamaño máximo de página. Predeterminado: 100; máximo: 500.", "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000, "description": "Registros que se omiten. Predeterminado: 0. Para avanzar use offset + items.length.", "example": 0 }, "required": false, "description": "Registros que se omiten. Predeterminado: 0. Para avanzar use offset + items.length.", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Página de registros activos (o archivados si se solicita).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecialistList" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } }, "post": { "operationId": "specialists.create", "tags": [ "Profesionales" ], "summary": "Crear un profesional", "description": "Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. PAT: requiere el permiso write y acceso al espacio de la ruta, cuando exista. Límite del cuerpo HTTP: 1000000 bytes, antes de interpretar el contenido.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "write", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecialistInput" } } } }, "responses": { "201": { "description": "Registro creado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Specialist" } } } }, "400": { "description": "Rechazo: invalid_json, duplicate_key, json_syntax, json_depth, json_type, numeric_value_loss, numeric_overflow, conflicting_alias, invalid_request, server_owned_field, invalid_query, invalid_path.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_json": { "summary": "El cuerpo no es JSON válido.", "value": { "error": { "code": "invalid_json", "message": "El cuerpo no es JSON válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_key": { "summary": "El cuerpo repite una clave JSON.", "value": { "error": { "code": "duplicate_key", "message": "El cuerpo repite una clave JSON." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "json_syntax": { "summary": "El JSON tiene un error de sintaxis.", "value": { "error": { "code": "json_syntax", "message": "El JSON tiene un error de sintaxis." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, duplicate_resource.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_resource": { "summary": "Ya existe un recurso con la misma identificación.", "value": { "error": { "code": "duplicate_resource", "message": "Ya existe un recurso con la misma identificación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: request_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "request_too_large": { "summary": "El cuerpo supera el tamaño permitido.", "value": { "error": { "code": "request_too_large", "message": "El cuerpo supera el tamaño permitido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "415": { "description": "Rechazo: unsupported_media_type.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported_media_type": { "summary": "El tipo de contenido no es compatible con esta operación.", "value": { "error": { "code": "unsupported_media_type", "message": "El tipo de contenido no es compatible con esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/specialists/{specialistId}": { "get": { "operationId": "specialists.get", "tags": [ "Profesionales" ], "summary": "Consultar un profesional", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "specialistId", "in": "path" } ], "responses": { "200": { "description": "Registro.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Specialist" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } }, "patch": { "operationId": "specialists.update", "tags": [ "Profesionales" ], "summary": "Actualizar un profesional", "description": "Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. PAT: requiere el permiso write y acceso al espacio de la ruta, cuando exista. Límite del cuerpo HTTP: 1000000 bytes, antes de interpretar el contenido.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "write", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "specialistId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecialistPatch" } } } }, "responses": { "200": { "description": "Registro actualizado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Specialist" } } } }, "400": { "description": "Rechazo: invalid_json, duplicate_key, json_syntax, json_depth, json_type, numeric_value_loss, numeric_overflow, conflicting_alias, invalid_request, server_owned_field, invalid_query, invalid_path.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_json": { "summary": "El cuerpo no es JSON válido.", "value": { "error": { "code": "invalid_json", "message": "El cuerpo no es JSON válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_key": { "summary": "El cuerpo repite una clave JSON.", "value": { "error": { "code": "duplicate_key", "message": "El cuerpo repite una clave JSON." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "json_syntax": { "summary": "El JSON tiene un error de sintaxis.", "value": { "error": { "code": "json_syntax", "message": "El JSON tiene un error de sintaxis." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, resource_archived, duplicate_resource.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "resource_archived": { "summary": "El recurso está archivado.", "value": { "error": { "code": "resource_archived", "message": "El recurso está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: request_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "request_too_large": { "summary": "El cuerpo supera el tamaño permitido.", "value": { "error": { "code": "request_too_large", "message": "El cuerpo supera el tamaño permitido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "415": { "description": "Rechazo: unsupported_media_type.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported_media_type": { "summary": "El tipo de contenido no es compatible con esta operación.", "value": { "error": { "code": "unsupported_media_type", "message": "El tipo de contenido no es compatible con esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } }, "delete": { "operationId": "specialists.archive", "tags": [ "Profesionales" ], "summary": "Archivar un profesional", "description": "Borrado lógico. El registro se conserva para auditoría y se puede reactivar. Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. PAT: requiere el permiso write y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "write", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "specialistId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Registro archivado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Specialist" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/specialists/{specialistId}/restore": { "post": { "operationId": "specialists.restore", "tags": [ "Profesionales" ], "summary": "Reactivar un profesional", "description": "Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. PAT: requiere el permiso write y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "write", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "specialistId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Registro reactivado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Specialist" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, duplicate_resource.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_resource": { "summary": "Ya existe un recurso con la misma identificación.", "value": { "error": { "code": "duplicate_resource", "message": "Ya existe un recurso con la misma identificación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/services": { "get": { "operationId": "services.list", "tags": [ "Servicios" ], "summary": "Listar servicios guardados", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "q", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Incluir registros archivados." }, "required": false, "description": "Incluir registros archivados.", "name": "includeArchived", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Tamaño máximo de página. Predeterminado: 100; máximo: 500.", "example": 100 }, "required": false, "description": "Tamaño máximo de página. Predeterminado: 100; máximo: 500.", "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000, "description": "Registros que se omiten. Predeterminado: 0. Para avanzar use offset + items.length.", "example": 0 }, "required": false, "description": "Registros que se omiten. Predeterminado: 0. Para avanzar use offset + items.length.", "name": "offset", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 7 }, "required": false, "name": "category", "in": "query" } ], "responses": { "200": { "description": "Página de registros activos (o archivados si se solicita).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceList" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } }, "post": { "operationId": "services.create", "tags": [ "Servicios" ], "summary": "Crear un servicio guardado", "description": "Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. PAT: requiere el permiso write y acceso al espacio de la ruta, cuando exista. Límite del cuerpo HTTP: 1000000 bytes, antes de interpretar el contenido.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "write", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceInput" } } } }, "responses": { "201": { "description": "Registro creado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Service" } } } }, "400": { "description": "Rechazo: invalid_json, duplicate_key, json_syntax, json_depth, json_type, numeric_value_loss, numeric_overflow, conflicting_alias, invalid_request, server_owned_field, invalid_query, invalid_path, invalid_service_category, invalid_medication_code, invalid_input_provenance, invalid_rips_input.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_json": { "summary": "El cuerpo no es JSON válido.", "value": { "error": { "code": "invalid_json", "message": "El cuerpo no es JSON válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_key": { "summary": "El cuerpo repite una clave JSON.", "value": { "error": { "code": "duplicate_key", "message": "El cuerpo repite una clave JSON." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "json_syntax": { "summary": "El JSON tiene un error de sintaxis.", "value": { "error": { "code": "json_syntax", "message": "El JSON tiene un error de sintaxis." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, duplicate_resource.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_resource": { "summary": "Ya existe un recurso con la misma identificación.", "value": { "error": { "code": "duplicate_resource", "message": "Ya existe un recurso con la misma identificación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: request_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "request_too_large": { "summary": "El cuerpo supera el tamaño permitido.", "value": { "error": { "code": "request_too_large", "message": "El cuerpo supera el tamaño permitido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "415": { "description": "Rechazo: unsupported_media_type.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported_media_type": { "summary": "El tipo de contenido no es compatible con esta operación.", "value": { "error": { "code": "unsupported_media_type", "message": "El tipo de contenido no es compatible con esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/services/{serviceId}": { "get": { "operationId": "services.get", "tags": [ "Servicios" ], "summary": "Consultar un servicio guardado", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "serviceId", "in": "path" } ], "responses": { "200": { "description": "Registro.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Service" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } }, "patch": { "operationId": "services.update", "tags": [ "Servicios" ], "summary": "Actualizar un servicio guardado", "description": "Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. PAT: requiere el permiso write y acceso al espacio de la ruta, cuando exista. Límite del cuerpo HTTP: 1000000 bytes, antes de interpretar el contenido.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "write", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "serviceId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServicePatch" } } } }, "responses": { "200": { "description": "Registro actualizado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Service" } } } }, "400": { "description": "Rechazo: invalid_json, duplicate_key, json_syntax, json_depth, json_type, numeric_value_loss, numeric_overflow, conflicting_alias, invalid_request, server_owned_field, invalid_query, invalid_path, invalid_service_category, invalid_medication_code, invalid_input_provenance, invalid_rips_input.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_json": { "summary": "El cuerpo no es JSON válido.", "value": { "error": { "code": "invalid_json", "message": "El cuerpo no es JSON válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_key": { "summary": "El cuerpo repite una clave JSON.", "value": { "error": { "code": "duplicate_key", "message": "El cuerpo repite una clave JSON." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "json_syntax": { "summary": "El JSON tiene un error de sintaxis.", "value": { "error": { "code": "json_syntax", "message": "El JSON tiene un error de sintaxis." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, resource_archived, duplicate_resource.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "resource_archived": { "summary": "El recurso está archivado.", "value": { "error": { "code": "resource_archived", "message": "El recurso está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: request_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "request_too_large": { "summary": "El cuerpo supera el tamaño permitido.", "value": { "error": { "code": "request_too_large", "message": "El cuerpo supera el tamaño permitido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "415": { "description": "Rechazo: unsupported_media_type.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported_media_type": { "summary": "El tipo de contenido no es compatible con esta operación.", "value": { "error": { "code": "unsupported_media_type", "message": "El tipo de contenido no es compatible con esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } }, "delete": { "operationId": "services.archive", "tags": [ "Servicios" ], "summary": "Archivar un servicio guardado", "description": "Borrado lógico. El registro se conserva para auditoría y se puede reactivar. Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. PAT: requiere el permiso write y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "write", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "serviceId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Registro archivado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Service" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/services/{serviceId}/restore": { "post": { "operationId": "services.restore", "tags": [ "Servicios" ], "summary": "Reactivar un servicio guardado", "description": "Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. PAT: requiere el permiso write y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "write", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "serviceId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Registro reactivado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Service" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, duplicate_resource.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_resource": { "summary": "Ya existe un recurso con la misma identificación.", "value": { "error": { "code": "duplicate_resource", "message": "Ya existe un recurso con la misma identificación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/clients": { "get": { "operationId": "clients.list", "tags": [ "Pagadores" ], "summary": "Listar pagadores", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "q", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Incluir registros archivados." }, "required": false, "description": "Incluir registros archivados.", "name": "includeArchived", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Tamaño máximo de página. Predeterminado: 100; máximo: 500.", "example": 100 }, "required": false, "description": "Tamaño máximo de página. Predeterminado: 100; máximo: 500.", "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000, "description": "Registros que se omiten. Predeterminado: 0. Para avanzar use offset + items.length.", "example": 0 }, "required": false, "description": "Registros que se omiten. Predeterminado: 0. Para avanzar use offset + items.length.", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Página de registros activos (o archivados si se solicita).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientList" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } }, "post": { "operationId": "clients.create", "tags": [ "Pagadores" ], "summary": "Crear un pagador", "description": "Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. PAT: requiere el permiso write y acceso al espacio de la ruta, cuando exista. Límite del cuerpo HTTP: 1000000 bytes, antes de interpretar el contenido.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "write", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientInput" } } } }, "responses": { "201": { "description": "Registro creado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Client" } } } }, "400": { "description": "Rechazo: invalid_json, duplicate_key, json_syntax, json_depth, json_type, numeric_value_loss, numeric_overflow, conflicting_alias, invalid_request, server_owned_field, invalid_query, invalid_path.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_json": { "summary": "El cuerpo no es JSON válido.", "value": { "error": { "code": "invalid_json", "message": "El cuerpo no es JSON válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_key": { "summary": "El cuerpo repite una clave JSON.", "value": { "error": { "code": "duplicate_key", "message": "El cuerpo repite una clave JSON." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "json_syntax": { "summary": "El JSON tiene un error de sintaxis.", "value": { "error": { "code": "json_syntax", "message": "El JSON tiene un error de sintaxis." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, duplicate_resource.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_resource": { "summary": "Ya existe un recurso con la misma identificación.", "value": { "error": { "code": "duplicate_resource", "message": "Ya existe un recurso con la misma identificación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: request_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "request_too_large": { "summary": "El cuerpo supera el tamaño permitido.", "value": { "error": { "code": "request_too_large", "message": "El cuerpo supera el tamaño permitido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "415": { "description": "Rechazo: unsupported_media_type.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported_media_type": { "summary": "El tipo de contenido no es compatible con esta operación.", "value": { "error": { "code": "unsupported_media_type", "message": "El tipo de contenido no es compatible con esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/clients/{clientId}": { "get": { "operationId": "clients.get", "tags": [ "Pagadores" ], "summary": "Consultar un pagador", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "clientId", "in": "path" } ], "responses": { "200": { "description": "Registro.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Client" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } }, "patch": { "operationId": "clients.update", "tags": [ "Pagadores" ], "summary": "Actualizar un pagador", "description": "Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. PAT: requiere el permiso write y acceso al espacio de la ruta, cuando exista. Límite del cuerpo HTTP: 1000000 bytes, antes de interpretar el contenido.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "write", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "clientId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientPatch" } } } }, "responses": { "200": { "description": "Registro actualizado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Client" } } } }, "400": { "description": "Rechazo: invalid_json, duplicate_key, json_syntax, json_depth, json_type, numeric_value_loss, numeric_overflow, conflicting_alias, invalid_request, server_owned_field, invalid_query, invalid_path.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_json": { "summary": "El cuerpo no es JSON válido.", "value": { "error": { "code": "invalid_json", "message": "El cuerpo no es JSON válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_key": { "summary": "El cuerpo repite una clave JSON.", "value": { "error": { "code": "duplicate_key", "message": "El cuerpo repite una clave JSON." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "json_syntax": { "summary": "El JSON tiene un error de sintaxis.", "value": { "error": { "code": "json_syntax", "message": "El JSON tiene un error de sintaxis." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, resource_archived, duplicate_resource.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "resource_archived": { "summary": "El recurso está archivado.", "value": { "error": { "code": "resource_archived", "message": "El recurso está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: request_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "request_too_large": { "summary": "El cuerpo supera el tamaño permitido.", "value": { "error": { "code": "request_too_large", "message": "El cuerpo supera el tamaño permitido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "415": { "description": "Rechazo: unsupported_media_type.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported_media_type": { "summary": "El tipo de contenido no es compatible con esta operación.", "value": { "error": { "code": "unsupported_media_type", "message": "El tipo de contenido no es compatible con esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } }, "delete": { "operationId": "clients.archive", "tags": [ "Pagadores" ], "summary": "Archivar un pagador", "description": "Borrado lógico. El registro se conserva para auditoría y se puede reactivar. Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. PAT: requiere el permiso write y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "write", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "clientId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Registro archivado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Client" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/clients/{clientId}/restore": { "post": { "operationId": "clients.restore", "tags": [ "Pagadores" ], "summary": "Reactivar un pagador", "description": "Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. PAT: requiere el permiso write y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "write", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "clientId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Registro reactivado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Client" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, duplicate_resource.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_resource": { "summary": "Ya existe un recurso con la misma identificación.", "value": { "error": { "code": "duplicate_resource", "message": "Ya existe un recurso con la misma identificación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/invoice-resolutions": { "get": { "operationId": "invoiceResolutions.list", "tags": [ "Resoluciones" ], "summary": "Listar resoluciones de facturación", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "q", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Incluir registros archivados." }, "required": false, "description": "Incluir registros archivados.", "name": "includeArchived", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Tamaño máximo de página. Predeterminado: 100; máximo: 500.", "example": 100 }, "required": false, "description": "Tamaño máximo de página. Predeterminado: 100; máximo: 500.", "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000, "description": "Registros que se omiten. Predeterminado: 0. Para avanzar use offset + items.length.", "example": 0 }, "required": false, "description": "Registros que se omiten. Predeterminado: 0. Para avanzar use offset + items.length.", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Página de registros activos (o archivados si se solicita).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResolutionList" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/invoice-resolutions/{resolutionId}": { "get": { "operationId": "invoiceResolutions.get", "tags": [ "Resoluciones" ], "summary": "Consultar una resolución de facturación", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "resolutionId", "in": "path" } ], "responses": { "200": { "description": "Registro.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resolution" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/credit-note-resolutions": { "get": { "operationId": "creditNoteResolutions.list", "tags": [ "Resoluciones" ], "summary": "Listar resoluciones de notas crédito", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "q", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Incluir registros archivados." }, "required": false, "description": "Incluir registros archivados.", "name": "includeArchived", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Tamaño máximo de página. Predeterminado: 100; máximo: 500.", "example": 100 }, "required": false, "description": "Tamaño máximo de página. Predeterminado: 100; máximo: 500.", "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000, "description": "Registros que se omiten. Predeterminado: 0. Para avanzar use offset + items.length.", "example": 0 }, "required": false, "description": "Registros que se omiten. Predeterminado: 0. Para avanzar use offset + items.length.", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Página de registros activos (o archivados si se solicita).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteResolutionList" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/patients/templates/{format}": { "get": { "operationId": "patients.downloadTemplate", "tags": [ "Pacientes" ], "summary": "Descargar la plantilla de pacientes", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "enum": [ "csv", "xlsx" ] }, "required": true, "name": "format", "in": "path" } ], "responses": { "200": { "description": "Plantilla.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/patients/xlsx-conversions": { "post": { "operationId": "patients.convertXlsx", "tags": [ "Pacientes" ], "summary": "Convertir un XLSX de pacientes a CSV", "description": "Convierte el archivo para revisión en el portal. No guarda pacientes; la importación usa la operación de creación. Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista. Límite del cuerpo HTTP: 5000000 bytes, antes de interpretar el contenido.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/XlsxUpload" } } } }, "responses": { "200": { "description": "CSV convertido.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_xlsx_file, invalid_request, invalid_json, duplicate_key, json_syntax, json_depth, json_type, numeric_value_loss, numeric_overflow, conflicting_alias, server_owned_field.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_xlsx_file": { "summary": "El archivo XLSX no es válido.", "value": { "error": { "code": "invalid_xlsx_file", "message": "El archivo XLSX no es válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: request_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "request_too_large": { "summary": "El cuerpo supera el tamaño permitido.", "value": { "error": { "code": "request_too_large", "message": "El cuerpo supera el tamaño permitido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "415": { "description": "Rechazo: unsupported_media_type.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported_media_type": { "summary": "El tipo de contenido no es compatible con esta operación.", "value": { "error": { "code": "unsupported_media_type", "message": "El tipo de contenido no es compatible con esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/rips-packages/context": { "get": { "operationId": "ripsPackages.getContext", "tags": [ "Paquetes RIPS" ], "summary": "Contexto verificado para preparar RIPS", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Contexto del espacio.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RipsContext" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/health-invoices/context": { "get": { "operationId": "healthInvoices.getContext", "tags": [ "Facturas de salud" ], "summary": "Contexto para emitir una factura", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Pagadores, sedes, resoluciones y estado del proveedor sin secretos.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthInvoiceContext" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/credit-note-resolutions/{resolutionId}": { "get": { "operationId": "creditNoteResolutions.get", "tags": [ "Resoluciones" ], "summary": "Consultar una resolución de notas crédito", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "resolutionId", "in": "path" } ], "responses": { "200": { "description": "Registro.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resolution" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/debit-note-resolutions": { "get": { "operationId": "debitNoteResolutions.list", "tags": [ "Resoluciones" ], "summary": "Listar resoluciones de notas débito", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "q", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Incluir registros archivados." }, "required": false, "description": "Incluir registros archivados.", "name": "includeArchived", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Tamaño máximo de página. Predeterminado: 100; máximo: 500.", "example": 100 }, "required": false, "description": "Tamaño máximo de página. Predeterminado: 100; máximo: 500.", "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000, "description": "Registros que se omiten. Predeterminado: 0. Para avanzar use offset + items.length.", "example": 0 }, "required": false, "description": "Registros que se omiten. Predeterminado: 0. Para avanzar use offset + items.length.", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Página de registros activos (o archivados si se solicita).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitNoteResolutionList" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/debit-note-resolutions/{resolutionId}": { "get": { "operationId": "debitNoteResolutions.get", "tags": [ "Resoluciones" ], "summary": "Consultar una resolución de notas débito", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "resolutionId", "in": "path" } ], "responses": { "200": { "description": "Registro.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resolution" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/rips-packages": { "get": { "operationId": "ripsPackages.list", "tags": [ "Paquetes RIPS" ], "summary": "Listar paquetes RIPS", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/RipsPackageKind" }, "required": false, "description": "Uno de los once tipos de paquete FEV RIPS fijados en el contrato nativo.", "name": "kind", "in": "query" }, { "schema": { "$ref": "#/components/schemas/RipsPackageStatus" }, "required": false, "description": "Draft: editable. Dispatching: intento registrado, en curso. Accepted: recibo verificado. Rejected: rechazo terminal; se corrige con una revisión nueva. Unknown: resultado incierto; solo se resuelve conciliando con evidencia.", "name": "status", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": false, "description": "Identificador opaco.", "name": "sourceInvoiceId", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": false, "description": "Identificador opaco.", "name": "sourceCreditNoteId", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": false, "description": "Identificador opaco.", "name": "sourceDebitNoteId", "in": "query" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "q", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Incluir registros archivados." }, "required": false, "description": "Incluir registros archivados.", "name": "includeArchived", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Tamaño máximo de página. Predeterminado: 100; máximo: 500.", "example": 100 }, "required": false, "description": "Tamaño máximo de página. Predeterminado: 100; máximo: 500.", "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000, "description": "Registros que se omiten. Predeterminado: 0. Para avanzar use offset + items.length.", "example": 0 }, "required": false, "description": "Registros que se omiten. Predeterminado: 0. Para avanzar use offset + items.length.", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Paquetes del espacio sin cuerpos grandes.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RipsPackageList" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } }, "post": { "operationId": "ripsPackages.create", "tags": [ "Paquetes RIPS" ], "summary": "Guardar un borrador RIPS", "description": "Guarda la revisión 1 con su original exacto y procedencia. No llama al Ministerio ni autoriza el envío. Un objeto tiene campos tipados opcionales; para importar JSON que necesita corrección use rips como texto exacto.\n\nGuardar permite un borrador incompleto. Esta tabla indica lo exigido **para validar y enviar**; `attachedDocument` siempre es una referencia a PahFacturar, nunca XML enviado por el cliente.\n| kind | rips | attachedDocument | Referencia aceptada y números |\n| --- | --- | --- | --- |\n| rips_sin_factura | objeto | null | Sin referencia; numFactura=null, tipoNota=RS, numNota propio obligatorio. |\n| fev_rips | objeto | invoice | numFactura igual al documento; tipoNota y numNota vacíos/null. No usar para cápita. |\n| nc_parcial | objeto | credit-note | Factura RIPS aceptada; numFactura=factura original, numNota=nota y tipoNota=NC. Control de saldo. |\n| nc_total | null | credit-note | Factura RIPS aceptada; anulación total con control de saldo/total. Números derivados del XML. |\n| nd | objeto | debit-note | Factura RIPS aceptada; numFactura=factura original, numNota=nota, tipoNota=ND. La nota se emite por POST /debit-notes con RIPS adicionales explícitos. |\n| nota_ajuste | objeto | null | Factura RIPS aceptada; numFactura=factura original, numNota propio, tipoNota=NA. |\n| capita_inicial | null | invoice | Sin referencia anterior; XML con modalidad 03 y contrato o póliza. Números derivados del XML. |\n| capita_periodo | objeto | invoice | Cápita inicial/período aceptado; numFactura=factura anterior, XML=factura nueva (distinta), tipoNota/numNota vacíos; valores de servicios en cero. |\n| capita_final | objeto | null | Cápita inicial/período aceptado; numFactura=factura anterior, tipoNota/numNota vacíos; valores de servicios en cero. |\n| nc_acuerdo_voluntades | null | credit-note | Factura RIPS aceptada; números y referencia derivados del XML. |\n| nc_capita | null | credit-note | Factura RIPS aceptada; números y referencia derivados del XML. No se infiere un control de saldo adicional por el nombre. |\nPara referencias, el servidor busca el recibo aceptado en el mismo espacio, destino y ambiente, por número/NIT y CUFE cuando corresponde. `sourcePackageId` es opcional; si se envía, debe identificar un paquete activo aceptado y coincidir con numFactura. No sustituye estas comprobaciones. Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. PAT: requiere el permiso write y acceso al espacio de la ruta, cuando exista. Límite del cuerpo HTTP: 26000000 bytes, antes de interpretar el contenido.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "write", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRipsPackageInput" }, "examples": { "rips_sin_factura": { "summary": "rips_sin_factura", "description": "Ejemplo sintético con estructura completa. Sustituya identificaciones, códigos, números y referencias por datos válidos del espacio. Los documentos deben estar aceptados en PahFacturar; las referencias deben tener un recibo RIPS aceptado. No prueba aceptación del Ministerio.", "value": { "kind": "rips_sin_factura", "origin": "upload", "ripsSourceProfile": "native-d558206", "rips": { "numDocumentoIdObligado": "900123456", "numFactura": null, "tipoNota": "RS", "numNota": "RS-DEMO-001", "usuarios": [ { "tipoDocumentoIdentificacion": "CC", "numDocumentoIdentificacion": "1000000002", "tipoUsuario": "01", "fechaNacimiento": "1990-01-01", "codSexo": "F", "codPaisResidencia": "170", "codPaisOrigen": "170", "codMunicipioResidencia": "11001", "codZonaTerritorialResidencia": "01", "incapacidad": "NO", "consecutivo": 1, "servicios": { "consultas": [ { "codPrestador": "110010000101", "fechaInicioAtencion": "2026-09-01 10:00", "numAutorizacion": null, "codConsulta": "890201", "modalidadGrupoServicioTecSal": "01", "grupoServicios": "01", "codServicio": 325, "finalidadTecnologiaSalud": "44", "causaMotivoAtencion": "38", "codDiagnosticoPrincipal": "Z000", "codDiagnosticoRelacionado1": null, "codDiagnosticoRelacionado2": null, "codDiagnosticoRelacionado3": null, "tipoDiagnosticoPrincipal": "01", "tipoDocumentoIdentificacion": "CC", "numDocumentoIdentificacion": "1000000001", "vrServicio": 100000, "conceptoRecaudo": "05", "valorPagoModerador": 0, "numFEVPagoModerador": null, "consecutivo": 1 } ] } } ] }, "attachedDocument": null } }, "fev_rips": { "summary": "fev_rips", "description": "Ejemplo sintético con estructura completa. Sustituya identificaciones, códigos, números y referencias por datos válidos del espacio. Los documentos deben estar aceptados en PahFacturar; las referencias deben tener un recibo RIPS aceptado. No prueba aceptación del Ministerio.", "value": { "kind": "fev_rips", "origin": "upload", "ripsSourceProfile": "native-d558206", "rips": { "numDocumentoIdObligado": "900123456", "numFactura": "SETP990000001", "tipoNota": null, "numNota": null, "usuarios": [ { "tipoDocumentoIdentificacion": "CC", "numDocumentoIdentificacion": "1000000002", "tipoUsuario": "01", "fechaNacimiento": "1990-01-01", "codSexo": "F", "codPaisResidencia": "170", "codPaisOrigen": "170", "codMunicipioResidencia": "11001", "codZonaTerritorialResidencia": "01", "incapacidad": "NO", "consecutivo": 1, "servicios": { "consultas": [ { "codPrestador": "110010000101", "fechaInicioAtencion": "2026-09-01 10:00", "numAutorizacion": null, "codConsulta": "890201", "modalidadGrupoServicioTecSal": "01", "grupoServicios": "01", "codServicio": 325, "finalidadTecnologiaSalud": "44", "causaMotivoAtencion": "38", "codDiagnosticoPrincipal": "Z000", "codDiagnosticoRelacionado1": null, "codDiagnosticoRelacionado2": null, "codDiagnosticoRelacionado3": null, "tipoDiagnosticoPrincipal": "01", "tipoDocumentoIdentificacion": "CC", "numDocumentoIdentificacion": "1000000001", "vrServicio": 100000, "conceptoRecaudo": "05", "valorPagoModerador": 0, "numFEVPagoModerador": null, "consecutivo": 1 } ] } } ] }, "attachedDocument": { "documentKind": "invoice", "number": "SETP990000001" } } }, "nc_parcial": { "summary": "nc_parcial", "description": "Ejemplo sintético con estructura completa. Sustituya identificaciones, códigos, números y referencias por datos válidos del espacio. Los documentos deben estar aceptados en PahFacturar; las referencias deben tener un recibo RIPS aceptado. No prueba aceptación del Ministerio.", "value": { "kind": "nc_parcial", "origin": "upload", "ripsSourceProfile": "native-d558206", "rips": { "numDocumentoIdObligado": "900123456", "numFactura": "SETP990000001", "tipoNota": "NC", "numNota": "NC-DEMO-001", "usuarios": [ { "tipoDocumentoIdentificacion": "CC", "numDocumentoIdentificacion": "1000000002", "tipoUsuario": "01", "fechaNacimiento": "1990-01-01", "codSexo": "F", "codPaisResidencia": "170", "codPaisOrigen": "170", "codMunicipioResidencia": "11001", "codZonaTerritorialResidencia": "01", "incapacidad": "NO", "consecutivo": 1, "servicios": { "consultas": [ { "codPrestador": "110010000101", "fechaInicioAtencion": "2026-09-01 10:00", "numAutorizacion": null, "codConsulta": "890201", "modalidadGrupoServicioTecSal": "01", "grupoServicios": "01", "codServicio": 325, "finalidadTecnologiaSalud": "44", "causaMotivoAtencion": "38", "codDiagnosticoPrincipal": "Z000", "codDiagnosticoRelacionado1": null, "codDiagnosticoRelacionado2": null, "codDiagnosticoRelacionado3": null, "tipoDiagnosticoPrincipal": "01", "tipoDocumentoIdentificacion": "CC", "numDocumentoIdentificacion": "1000000001", "vrServicio": 100000, "conceptoRecaudo": "05", "valorPagoModerador": 0, "numFEVPagoModerador": null, "consecutivo": 1 } ] } } ] }, "attachedDocument": { "documentKind": "credit-note", "number": "NC-DEMO-001" }, "sourcePackageId": "pkg-factura-aceptada" } }, "nc_total": { "summary": "nc_total", "description": "Ejemplo sintético con estructura completa. Sustituya identificaciones, códigos, números y referencias por datos válidos del espacio. Los documentos deben estar aceptados en PahFacturar; las referencias deben tener un recibo RIPS aceptado. No prueba aceptación del Ministerio.", "value": { "kind": "nc_total", "origin": "upload", "ripsSourceProfile": "native-d558206", "rips": null, "attachedDocument": { "documentKind": "credit-note", "number": "NC-DEMO-002" }, "sourcePackageId": "pkg-factura-aceptada" } }, "nd": { "summary": "nd", "description": "Ejemplo sintético con estructura completa. Sustituya identificaciones, códigos, números y referencias por datos válidos del espacio. Los documentos deben estar aceptados en PahFacturar; las referencias deben tener un recibo RIPS aceptado. No prueba aceptación del Ministerio.", "value": { "kind": "nd", "origin": "upload", "ripsSourceProfile": "native-d558206", "rips": { "numDocumentoIdObligado": "900123456", "numFactura": "SETP990000001", "tipoNota": "ND", "numNota": "ND-DEMO-001", "usuarios": [ { "tipoDocumentoIdentificacion": "CC", "numDocumentoIdentificacion": "1000000002", "tipoUsuario": "01", "fechaNacimiento": "1990-01-01", "codSexo": "F", "codPaisResidencia": "170", "codPaisOrigen": "170", "codMunicipioResidencia": "11001", "codZonaTerritorialResidencia": "01", "incapacidad": "NO", "consecutivo": 1, "servicios": { "consultas": [ { "codPrestador": "110010000101", "fechaInicioAtencion": "2026-09-01 10:00", "numAutorizacion": null, "codConsulta": "890201", "modalidadGrupoServicioTecSal": "01", "grupoServicios": "01", "codServicio": 325, "finalidadTecnologiaSalud": "44", "causaMotivoAtencion": "38", "codDiagnosticoPrincipal": "Z000", "codDiagnosticoRelacionado1": null, "codDiagnosticoRelacionado2": null, "codDiagnosticoRelacionado3": null, "tipoDiagnosticoPrincipal": "01", "tipoDocumentoIdentificacion": "CC", "numDocumentoIdentificacion": "1000000001", "vrServicio": 100000, "conceptoRecaudo": "05", "valorPagoModerador": 0, "numFEVPagoModerador": null, "consecutivo": 1 } ] } } ] }, "attachedDocument": { "documentKind": "debit-note", "number": "ND-DEMO-001" }, "sourcePackageId": "pkg-factura-aceptada" } }, "nota_ajuste": { "summary": "nota_ajuste", "description": "Ejemplo sintético con estructura completa. Sustituya identificaciones, códigos, números y referencias por datos válidos del espacio. Los documentos deben estar aceptados en PahFacturar; las referencias deben tener un recibo RIPS aceptado. No prueba aceptación del Ministerio.", "value": { "kind": "nota_ajuste", "origin": "upload", "ripsSourceProfile": "native-d558206", "rips": { "numDocumentoIdObligado": "900123456", "numFactura": "SETP990000001", "tipoNota": "NA", "numNota": "NA-DEMO-001", "usuarios": [ { "tipoDocumentoIdentificacion": "CC", "numDocumentoIdentificacion": "1000000002", "tipoUsuario": "01", "fechaNacimiento": "1990-01-01", "codSexo": "F", "codPaisResidencia": "170", "codPaisOrigen": "170", "codMunicipioResidencia": "11001", "codZonaTerritorialResidencia": "01", "incapacidad": "NO", "consecutivo": 1, "servicios": { "consultas": [ { "codPrestador": "110010000101", "fechaInicioAtencion": "2026-09-01 10:00", "numAutorizacion": null, "codConsulta": "890201", "modalidadGrupoServicioTecSal": "01", "grupoServicios": "01", "codServicio": 325, "finalidadTecnologiaSalud": "44", "causaMotivoAtencion": "38", "codDiagnosticoPrincipal": "Z000", "codDiagnosticoRelacionado1": null, "codDiagnosticoRelacionado2": null, "codDiagnosticoRelacionado3": null, "tipoDiagnosticoPrincipal": "01", "tipoDocumentoIdentificacion": "CC", "numDocumentoIdentificacion": "1000000001", "vrServicio": 100000, "conceptoRecaudo": "05", "valorPagoModerador": 0, "numFEVPagoModerador": null, "consecutivo": 1 } ] } } ] }, "attachedDocument": null, "sourcePackageId": "pkg-factura-aceptada" } }, "capita_inicial": { "summary": "capita_inicial", "description": "Ejemplo sintético con estructura completa. Sustituya identificaciones, códigos, números y referencias por datos válidos del espacio. Los documentos deben estar aceptados en PahFacturar; las referencias deben tener un recibo RIPS aceptado. No prueba aceptación del Ministerio.", "value": { "kind": "capita_inicial", "origin": "upload", "ripsSourceProfile": "native-d558206", "rips": null, "attachedDocument": { "documentKind": "invoice", "number": "CAP-DEMO-001" } } }, "capita_periodo": { "summary": "capita_periodo", "description": "Ejemplo sintético con estructura completa. Sustituya identificaciones, códigos, números y referencias por datos válidos del espacio. Los documentos deben estar aceptados en PahFacturar; las referencias deben tener un recibo RIPS aceptado. No prueba aceptación del Ministerio.", "value": { "kind": "capita_periodo", "origin": "upload", "ripsSourceProfile": "native-d558206", "rips": { "numDocumentoIdObligado": "900123456", "numFactura": "CAP-DEMO-001", "tipoNota": null, "numNota": null, "usuarios": [ { "tipoDocumentoIdentificacion": "CC", "numDocumentoIdentificacion": "1000000002", "tipoUsuario": "01", "fechaNacimiento": "1990-01-01", "codSexo": "F", "codPaisResidencia": "170", "codPaisOrigen": "170", "codMunicipioResidencia": "11001", "codZonaTerritorialResidencia": "01", "incapacidad": "NO", "consecutivo": 1, "servicios": { "consultas": [ { "codPrestador": "110010000101", "fechaInicioAtencion": "2026-09-01 10:00", "numAutorizacion": null, "codConsulta": "890201", "modalidadGrupoServicioTecSal": "01", "grupoServicios": "01", "codServicio": 325, "finalidadTecnologiaSalud": "44", "causaMotivoAtencion": "38", "codDiagnosticoPrincipal": "Z000", "codDiagnosticoRelacionado1": null, "codDiagnosticoRelacionado2": null, "codDiagnosticoRelacionado3": null, "tipoDiagnosticoPrincipal": "01", "tipoDocumentoIdentificacion": "CC", "numDocumentoIdentificacion": "1000000001", "vrServicio": 0, "conceptoRecaudo": "05", "valorPagoModerador": 0, "numFEVPagoModerador": null, "consecutivo": 1 } ] } } ] }, "attachedDocument": { "documentKind": "invoice", "number": "CAP-DEMO-002" }, "sourcePackageId": "pkg-capita-aceptada" } }, "capita_final": { "summary": "capita_final", "description": "Ejemplo sintético con estructura completa. Sustituya identificaciones, códigos, números y referencias por datos válidos del espacio. Los documentos deben estar aceptados en PahFacturar; las referencias deben tener un recibo RIPS aceptado. No prueba aceptación del Ministerio.", "value": { "kind": "capita_final", "origin": "upload", "ripsSourceProfile": "native-d558206", "rips": { "numDocumentoIdObligado": "900123456", "numFactura": "CAP-DEMO-001", "tipoNota": null, "numNota": null, "usuarios": [ { "tipoDocumentoIdentificacion": "CC", "numDocumentoIdentificacion": "1000000002", "tipoUsuario": "01", "fechaNacimiento": "1990-01-01", "codSexo": "F", "codPaisResidencia": "170", "codPaisOrigen": "170", "codMunicipioResidencia": "11001", "codZonaTerritorialResidencia": "01", "incapacidad": "NO", "consecutivo": 1, "servicios": { "consultas": [ { "codPrestador": "110010000101", "fechaInicioAtencion": "2026-09-01 10:00", "numAutorizacion": null, "codConsulta": "890201", "modalidadGrupoServicioTecSal": "01", "grupoServicios": "01", "codServicio": 325, "finalidadTecnologiaSalud": "44", "causaMotivoAtencion": "38", "codDiagnosticoPrincipal": "Z000", "codDiagnosticoRelacionado1": null, "codDiagnosticoRelacionado2": null, "codDiagnosticoRelacionado3": null, "tipoDiagnosticoPrincipal": "01", "tipoDocumentoIdentificacion": "CC", "numDocumentoIdentificacion": "1000000001", "vrServicio": 0, "conceptoRecaudo": "05", "valorPagoModerador": 0, "numFEVPagoModerador": null, "consecutivo": 1 } ] } } ] }, "attachedDocument": null, "sourcePackageId": "pkg-capita-aceptada" } }, "nc_acuerdo_voluntades": { "summary": "nc_acuerdo_voluntades", "description": "Ejemplo sintético con estructura completa. Sustituya identificaciones, códigos, números y referencias por datos válidos del espacio. Los documentos deben estar aceptados en PahFacturar; las referencias deben tener un recibo RIPS aceptado. No prueba aceptación del Ministerio.", "value": { "kind": "nc_acuerdo_voluntades", "origin": "upload", "ripsSourceProfile": "native-d558206", "rips": null, "attachedDocument": { "documentKind": "credit-note", "number": "NC-DEMO-003" }, "sourcePackageId": "pkg-factura-aceptada" } }, "nc_capita": { "summary": "nc_capita", "description": "Ejemplo sintético con estructura completa. Sustituya identificaciones, códigos, números y referencias por datos válidos del espacio. Los documentos deben estar aceptados en PahFacturar; las referencias deben tener un recibo RIPS aceptado. No prueba aceptación del Ministerio.", "value": { "kind": "nc_capita", "origin": "upload", "ripsSourceProfile": "native-d558206", "rips": null, "attachedDocument": { "documentKind": "credit-note", "number": "NC-DEMO-004" }, "sourcePackageId": "pkg-capita-aceptada" } } } } } }, "responses": { "201": { "description": "Borrador creado; no se ha enviado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "ETag": { "$ref": "#/components/headers/ResourceRevision" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RipsPackage" }, "example": { "id": "pkg-demo-001", "kind": "rips_sin_factura", "status": "Draft", "revision": 1, "isActive": true, "statusMessage": null, "numFactura": null, "numNota": "RS-DEMO-001", "tipoNota": "RS", "cufeOrCude": null, "attachedDocument": null, "sourceInvoiceId": null, "sourceCreditNoteId": null, "sourceDebitNoteId": null, "sourcePackageId": null, "procesoId": null, "cuv": null, "validation": null, "lastAttempt": null, "createdByUserId": "user-demo-001", "createdAt": "2026-09-01T15:00:00.000Z", "updatedAt": "2026-09-01T15:00:00.000Z", "ripsPayloadJson": "{\"numDocumentoIdObligado\":\"900123456\",\"numFactura\":null,\"tipoNota\":\"RS\",\"numNota\":\"RS-DEMO-001\",\"usuarios\":[{\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000002\",\"tipoUsuario\":\"01\",\"fechaNacimiento\":\"1990-01-01\",\"codSexo\":\"F\",\"codPaisResidencia\":\"170\",\"codPaisOrigen\":\"170\",\"codMunicipioResidencia\":\"11001\",\"codZonaTerritorialResidencia\":\"01\",\"incapacidad\":\"NO\",\"consecutivo\":1,\"servicios\":{\"consultas\":[{\"codPrestador\":\"110010000101\",\"fechaInicioAtencion\":\"2026-09-01 10:00\",\"numAutorizacion\":null,\"codConsulta\":\"890201\",\"modalidadGrupoServicioTecSal\":\"01\",\"grupoServicios\":\"01\",\"codServicio\":325,\"finalidadTecnologiaSalud\":\"44\",\"causaMotivoAtencion\":\"38\",\"codDiagnosticoPrincipal\":\"Z000\",\"codDiagnosticoRelacionado1\":null,\"codDiagnosticoRelacionado2\":null,\"codDiagnosticoRelacionado3\":null,\"tipoDiagnosticoPrincipal\":\"01\",\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000001\",\"vrServicio\":100000,\"conceptoRecaudo\":\"05\",\"valorPagoModerador\":0,\"numFEVPagoModerador\":null,\"consecutivo\":1}]}}]}", "workingPayloadJson": "{\"numDocumentoIdObligado\":\"900123456\",\"numFactura\":null,\"tipoNota\":\"RS\",\"numNota\":\"RS-DEMO-001\",\"usuarios\":[{\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000002\",\"tipoUsuario\":\"01\",\"fechaNacimiento\":\"1990-01-01\",\"codSexo\":\"F\",\"codPaisResidencia\":\"170\",\"codPaisOrigen\":\"170\",\"codMunicipioResidencia\":\"11001\",\"codZonaTerritorialResidencia\":\"01\",\"incapacidad\":\"NO\",\"consecutivo\":1,\"servicios\":{\"consultas\":[{\"codPrestador\":\"110010000101\",\"fechaInicioAtencion\":\"2026-09-01 10:00\",\"numAutorizacion\":null,\"codConsulta\":\"890201\",\"modalidadGrupoServicioTecSal\":\"01\",\"grupoServicios\":\"01\",\"codServicio\":325,\"finalidadTecnologiaSalud\":\"44\",\"causaMotivoAtencion\":\"38\",\"codDiagnosticoPrincipal\":\"Z000\",\"codDiagnosticoRelacionado1\":null,\"codDiagnosticoRelacionado2\":null,\"codDiagnosticoRelacionado3\":null,\"tipoDiagnosticoPrincipal\":\"01\",\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000001\",\"vrServicio\":100000,\"conceptoRecaudo\":\"05\",\"valorPagoModerador\":0,\"numFEVPagoModerador\":null,\"consecutivo\":1}]}}]}", "provenance": { "sourceProfile": "native-d558206", "declaration": "user-declared", "inputFormat": "json", "changeCount": 0, "inputCount": 1 } } } } }, "400": { "description": "Rechazo: invalid_json, duplicate_key, json_syntax, json_depth, json_type, numeric_value_loss, numeric_overflow, conflicting_alias, invalid_request, server_owned_field, invalid_query, invalid_path, invalid_rips_input, invalid_package_kind, invalid_input_provenance, invalid_medication_code.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_json": { "summary": "El cuerpo no es JSON válido.", "value": { "error": { "code": "invalid_json", "message": "El cuerpo no es JSON válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_key": { "summary": "El cuerpo repite una clave JSON.", "value": { "error": { "code": "duplicate_key", "message": "El cuerpo repite una clave JSON." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "json_syntax": { "summary": "El JSON tiene un error de sintaxis.", "value": { "error": { "code": "json_syntax", "message": "El JSON tiene un error de sintaxis." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, invoice_provider_not_configured, invoice_provider_company_mismatch, artifact_context_unverified.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invoice_provider_not_configured": { "summary": "Configure el token, el equipo y la empresa de PahFacturar.", "value": { "error": { "code": "invoice_provider_not_configured", "message": "Configure el token, el equipo y la empresa de PahFacturar." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: request_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "request_too_large": { "summary": "El cuerpo supera el tamaño permitido.", "value": { "error": { "code": "request_too_large", "message": "El cuerpo supera el tamaño permitido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "415": { "description": "Rechazo: unsupported_media_type.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported_media_type": { "summary": "El tipo de contenido no es compatible con esta operación.", "value": { "error": { "code": "unsupported_media_type", "message": "El tipo de contenido no es compatible con esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "422": { "description": "Rechazo: source_package_not_accepted, source_invoice_mismatch, attached_document_kind_mismatch, attached_document_not_found, attached_document_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "source_package_not_accepted": { "summary": "El paquete de origen debe estar aceptado con un recibo verificado.", "value": { "error": { "code": "source_package_not_accepted", "message": "El paquete de origen debe estar aceptado con un recibo verificado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "source_invoice_mismatch": { "summary": "El número de factura no coincide con el paquete de origen.", "value": { "error": { "code": "source_invoice_mismatch", "message": "El número de factura no coincide con el paquete de origen." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "attached_document_kind_mismatch": { "summary": "El documento del sistema de facturación no corresponde al tipo de paquete.", "value": { "error": { "code": "attached_document_kind_mismatch", "message": "El documento del sistema de facturación no corresponde al tipo de paquete." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "502": { "description": "Rechazo: invoice_provider_unavailable, artifact_download_failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invoice_provider_unavailable": { "summary": "PahFacturar no respondió. Intente de nuevo.", "value": { "error": { "code": "invoice_provider_unavailable", "message": "PahFacturar no respondió. Intente de nuevo." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "artifact_download_failed": { "summary": "No fue posible descargar el artefacto del proveedor.", "value": { "error": { "code": "artifact_download_failed", "message": "No fue posible descargar el artefacto del proveedor." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/catalogs/medications/metadata": { "get": { "operationId": "catalog.getMedicationMetadata", "tags": [ "Catálogo de medicamentos" ], "summary": "Versión fijada del catálogo", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Versión y hashes del catálogo.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MedicationCatalogMetadata" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/catalogs/medications/{catalog}": { "get": { "operationId": "catalog.searchMedications", "tags": [ "Catálogo de medicamentos" ], "summary": "Buscar medicamentos", "description": "Devuelve códigos habilitados, ordenados por código. Copie next en after sin modificarlo y conserve q y catalog en todas las páginas; next=null termina la consulta. El nombre es opcional. Solo CUM e IUM están disponibles: otros catálogos clínicos no tienen endpoint en esta versión. Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "enum": [ "CUM", "IUM" ] }, "required": true, "name": "catalog", "in": "path" }, { "schema": { "type": "string", "maxLength": 128, "description": "Fragmento del código o nombre revisado, sin distinguir mayúsculas." }, "required": false, "description": "Fragmento del código o nombre revisado, sin distinguir mayúsculas.", "name": "q", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Tamaño de página. Predeterminado: 50.", "example": 50 }, "required": false, "description": "Tamaño de página. Predeterminado: 50.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 40, "description": "Valor exacto de next de la página anterior; omitir en la primera página." }, "required": false, "description": "Valor exacto de next de la página anterior; omitir en la primera página.", "name": "after", "in": "query" } ], "responses": { "200": { "description": "Página del catálogo fijado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MedicationSearchResult" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_catalog, invalid_catalog_cursor, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_catalog": { "summary": "Use el catálogo CUM o IUM.", "value": { "error": { "code": "invalid_catalog", "message": "Use el catálogo CUM o IUM." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/catalogs/medications/{catalog}/{code}": { "get": { "operationId": "catalog.getMedication", "tags": [ "Catálogo de medicamentos" ], "summary": "Consultar un medicamento", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "enum": [ "CUM", "IUM" ] }, "required": true, "name": "catalog", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 40 }, "required": true, "name": "code", "in": "path" } ], "responses": { "200": { "description": "Código habilitado y presentación disponible.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MedicationDetail" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_catalog, invalid_medication_code, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_catalog": { "summary": "Use el catálogo CUM o IUM.", "value": { "error": { "code": "invalid_catalog", "message": "Use el catálogo CUM o IUM." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/rips-packages/{packageId}": { "get": { "operationId": "ripsPackages.get", "tags": [ "Paquetes RIPS" ], "summary": "Consultar un paquete RIPS", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "packageId", "in": "path" } ], "responses": { "200": { "description": "Paquete con su revisión vigente.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "ETag": { "$ref": "#/components/headers/ResourceRevision" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RipsPackage" }, "example": { "id": "pkg-demo-001", "kind": "rips_sin_factura", "status": "Draft", "revision": 1, "isActive": true, "statusMessage": null, "numFactura": null, "numNota": "RS-DEMO-001", "tipoNota": "RS", "cufeOrCude": null, "attachedDocument": null, "sourceInvoiceId": null, "sourceCreditNoteId": null, "sourceDebitNoteId": null, "sourcePackageId": null, "procesoId": null, "cuv": null, "validation": null, "lastAttempt": null, "createdByUserId": "user-demo-001", "createdAt": "2026-09-01T15:00:00.000Z", "updatedAt": "2026-09-01T15:00:00.000Z", "ripsPayloadJson": "{\"numDocumentoIdObligado\":\"900123456\",\"numFactura\":null,\"tipoNota\":\"RS\",\"numNota\":\"RS-DEMO-001\",\"usuarios\":[{\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000002\",\"tipoUsuario\":\"01\",\"fechaNacimiento\":\"1990-01-01\",\"codSexo\":\"F\",\"codPaisResidencia\":\"170\",\"codPaisOrigen\":\"170\",\"codMunicipioResidencia\":\"11001\",\"codZonaTerritorialResidencia\":\"01\",\"incapacidad\":\"NO\",\"consecutivo\":1,\"servicios\":{\"consultas\":[{\"codPrestador\":\"110010000101\",\"fechaInicioAtencion\":\"2026-09-01 10:00\",\"numAutorizacion\":null,\"codConsulta\":\"890201\",\"modalidadGrupoServicioTecSal\":\"01\",\"grupoServicios\":\"01\",\"codServicio\":325,\"finalidadTecnologiaSalud\":\"44\",\"causaMotivoAtencion\":\"38\",\"codDiagnosticoPrincipal\":\"Z000\",\"codDiagnosticoRelacionado1\":null,\"codDiagnosticoRelacionado2\":null,\"codDiagnosticoRelacionado3\":null,\"tipoDiagnosticoPrincipal\":\"01\",\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000001\",\"vrServicio\":100000,\"conceptoRecaudo\":\"05\",\"valorPagoModerador\":0,\"numFEVPagoModerador\":null,\"consecutivo\":1}]}}]}", "workingPayloadJson": "{\"numDocumentoIdObligado\":\"900123456\",\"numFactura\":null,\"tipoNota\":\"RS\",\"numNota\":\"RS-DEMO-001\",\"usuarios\":[{\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000002\",\"tipoUsuario\":\"01\",\"fechaNacimiento\":\"1990-01-01\",\"codSexo\":\"F\",\"codPaisResidencia\":\"170\",\"codPaisOrigen\":\"170\",\"codMunicipioResidencia\":\"11001\",\"codZonaTerritorialResidencia\":\"01\",\"incapacidad\":\"NO\",\"consecutivo\":1,\"servicios\":{\"consultas\":[{\"codPrestador\":\"110010000101\",\"fechaInicioAtencion\":\"2026-09-01 10:00\",\"numAutorizacion\":null,\"codConsulta\":\"890201\",\"modalidadGrupoServicioTecSal\":\"01\",\"grupoServicios\":\"01\",\"codServicio\":325,\"finalidadTecnologiaSalud\":\"44\",\"causaMotivoAtencion\":\"38\",\"codDiagnosticoPrincipal\":\"Z000\",\"codDiagnosticoRelacionado1\":null,\"codDiagnosticoRelacionado2\":null,\"codDiagnosticoRelacionado3\":null,\"tipoDiagnosticoPrincipal\":\"01\",\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000001\",\"vrServicio\":100000,\"conceptoRecaudo\":\"05\",\"valorPagoModerador\":0,\"numFEVPagoModerador\":null,\"consecutivo\":1}]}}]}", "provenance": { "sourceProfile": "native-d558206", "declaration": "user-declared", "inputFormat": "json", "changeCount": 0, "inputCount": 1 } } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } }, "patch": { "operationId": "ripsPackages.revise", "tags": [ "Paquetes RIPS" ], "summary": "Crear una revisión del paquete", "description": "Requiere If-Match con la revisión vigente. Solo en Draft o Rejected. Un rechazo conserva su intento y exige validar la revisión nueva. Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. Requiere If-Match con la revisión vigente. PAT: requiere el permiso write y acceso al espacio de la ruta, cuando exista. Límite del cuerpo HTTP: 26000000 bytes, antes de interpretar el contenido.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "write", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "packageId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" }, { "schema": { "type": "string", "pattern": "^(?:\"\\d+\"|\\d+)$", "description": "ETag de GET del paquete, por ejemplo \"3\". Debe corresponder a su revisión vigente; un cambio concurrente produce revision_conflict.", "example": "\"3\"" }, "required": true, "description": "ETag de GET del paquete, por ejemplo \"3\". Debe corresponder a su revisión vigente; un cambio concurrente produce revision_conflict.", "name": "if-match", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviseRipsPackageInput" } } } }, "responses": { "200": { "description": "Revisión creada. Use el nuevo ETag en la siguiente edición.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "ETag": { "$ref": "#/components/headers/ResourceRevision" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RipsPackage" }, "example": { "id": "pkg-demo-001", "kind": "rips_sin_factura", "status": "Draft", "revision": 2, "isActive": true, "statusMessage": null, "numFactura": null, "numNota": "RS-DEMO-001", "tipoNota": "RS", "cufeOrCude": null, "attachedDocument": null, "sourceInvoiceId": null, "sourceCreditNoteId": null, "sourceDebitNoteId": null, "sourcePackageId": null, "procesoId": null, "cuv": null, "validation": null, "lastAttempt": null, "createdByUserId": "user-demo-001", "createdAt": "2026-09-01T15:00:00.000Z", "updatedAt": "2026-09-01T15:00:00.000Z", "ripsPayloadJson": "{\"numDocumentoIdObligado\":\"900123456\",\"numFactura\":null,\"tipoNota\":\"RS\",\"numNota\":\"RS-DEMO-001\",\"usuarios\":[{\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000002\",\"tipoUsuario\":\"01\",\"fechaNacimiento\":\"1990-01-01\",\"codSexo\":\"F\",\"codPaisResidencia\":\"170\",\"codPaisOrigen\":\"170\",\"codMunicipioResidencia\":\"11001\",\"codZonaTerritorialResidencia\":\"01\",\"incapacidad\":\"NO\",\"consecutivo\":1,\"servicios\":{\"consultas\":[{\"codPrestador\":\"110010000101\",\"fechaInicioAtencion\":\"2026-09-01 10:00\",\"numAutorizacion\":null,\"codConsulta\":\"890201\",\"modalidadGrupoServicioTecSal\":\"01\",\"grupoServicios\":\"01\",\"codServicio\":325,\"finalidadTecnologiaSalud\":\"44\",\"causaMotivoAtencion\":\"38\",\"codDiagnosticoPrincipal\":\"Z000\",\"codDiagnosticoRelacionado1\":null,\"codDiagnosticoRelacionado2\":null,\"codDiagnosticoRelacionado3\":null,\"tipoDiagnosticoPrincipal\":\"01\",\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000001\",\"vrServicio\":100000,\"conceptoRecaudo\":\"05\",\"valorPagoModerador\":0,\"numFEVPagoModerador\":null,\"consecutivo\":1}]}}]}", "workingPayloadJson": "{\"numDocumentoIdObligado\":\"900123456\",\"numFactura\":null,\"tipoNota\":\"RS\",\"numNota\":\"RS-DEMO-001\",\"usuarios\":[{\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000002\",\"tipoUsuario\":\"01\",\"fechaNacimiento\":\"1990-01-01\",\"codSexo\":\"F\",\"codPaisResidencia\":\"170\",\"codPaisOrigen\":\"170\",\"codMunicipioResidencia\":\"11001\",\"codZonaTerritorialResidencia\":\"01\",\"incapacidad\":\"NO\",\"consecutivo\":1,\"servicios\":{\"consultas\":[{\"codPrestador\":\"110010000101\",\"fechaInicioAtencion\":\"2026-09-01 10:00\",\"numAutorizacion\":null,\"codConsulta\":\"890201\",\"modalidadGrupoServicioTecSal\":\"01\",\"grupoServicios\":\"01\",\"codServicio\":325,\"finalidadTecnologiaSalud\":\"44\",\"causaMotivoAtencion\":\"38\",\"codDiagnosticoPrincipal\":\"Z000\",\"codDiagnosticoRelacionado1\":null,\"codDiagnosticoRelacionado2\":null,\"codDiagnosticoRelacionado3\":null,\"tipoDiagnosticoPrincipal\":\"01\",\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000001\",\"vrServicio\":100000,\"conceptoRecaudo\":\"05\",\"valorPagoModerador\":0,\"numFEVPagoModerador\":null,\"consecutivo\":1}]}}]}", "provenance": { "sourceProfile": "native-d558206", "declaration": "user-declared", "inputFormat": "json", "changeCount": 0, "inputCount": 1 } } } } }, "400": { "description": "Rechazo: invalid_json, duplicate_key, json_syntax, json_depth, json_type, numeric_value_loss, numeric_overflow, conflicting_alias, invalid_request, server_owned_field, invalid_query, invalid_path, invalid_rips_input, invalid_input_provenance, invalid_medication_code.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_json": { "summary": "El cuerpo no es JSON válido.", "value": { "error": { "code": "invalid_json", "message": "El cuerpo no es JSON válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_key": { "summary": "El cuerpo repite una clave JSON.", "value": { "error": { "code": "duplicate_key", "message": "El cuerpo repite una clave JSON." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "json_syntax": { "summary": "El JSON tiene un error de sintaxis.", "value": { "error": { "code": "json_syntax", "message": "El JSON tiene un error de sintaxis." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, resource_archived, revision_conflict, dispatch_in_progress, submission_outcome_unknown, package_already_accepted, invalid_field_profile, invoice_provider_not_configured, invoice_provider_company_mismatch, artifact_context_unverified.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "resource_archived": { "summary": "El recurso está archivado.", "value": { "error": { "code": "resource_archived", "message": "El recurso está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: request_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "request_too_large": { "summary": "El cuerpo supera el tamaño permitido.", "value": { "error": { "code": "request_too_large", "message": "El cuerpo supera el tamaño permitido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "415": { "description": "Rechazo: unsupported_media_type.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported_media_type": { "summary": "El tipo de contenido no es compatible con esta operación.", "value": { "error": { "code": "unsupported_media_type", "message": "El tipo de contenido no es compatible con esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "422": { "description": "Rechazo: source_package_not_accepted, source_invoice_mismatch, attached_document_kind_mismatch, attached_document_not_found, attached_document_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "source_package_not_accepted": { "summary": "El paquete de origen debe estar aceptado con un recibo verificado.", "value": { "error": { "code": "source_package_not_accepted", "message": "El paquete de origen debe estar aceptado con un recibo verificado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "source_invoice_mismatch": { "summary": "El número de factura no coincide con el paquete de origen.", "value": { "error": { "code": "source_invoice_mismatch", "message": "El número de factura no coincide con el paquete de origen." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "attached_document_kind_mismatch": { "summary": "El documento del sistema de facturación no corresponde al tipo de paquete.", "value": { "error": { "code": "attached_document_kind_mismatch", "message": "El documento del sistema de facturación no corresponde al tipo de paquete." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required, revision_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "revision_required": { "summary": "La operación requiere la revisión actual en If-Match.", "value": { "error": { "code": "revision_required", "message": "La operación requiere la revisión actual en If-Match." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "502": { "description": "Rechazo: invoice_provider_unavailable, artifact_download_failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invoice_provider_unavailable": { "summary": "PahFacturar no respondió. Intente de nuevo.", "value": { "error": { "code": "invoice_provider_unavailable", "message": "PahFacturar no respondió. Intente de nuevo." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "artifact_download_failed": { "summary": "No fue posible descargar el artefacto del proveedor.", "value": { "error": { "code": "artifact_download_failed", "message": "No fue posible descargar el artefacto del proveedor." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } }, "delete": { "operationId": "ripsPackages.archive", "tags": [ "Paquetes RIPS" ], "summary": "Archivar un paquete RIPS", "description": "Borrado lógico. Conserva intentos y recibos; no reabre un resultado aceptado. Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. PAT: requiere el permiso write y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "write", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "packageId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Paquete archivado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "ETag": { "$ref": "#/components/headers/ResourceRevision" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RipsPackage" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/rips-packages/{packageId}/restore": { "post": { "operationId": "ripsPackages.restore", "tags": [ "Paquetes RIPS" ], "summary": "Reactivar un paquete RIPS", "description": "Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. PAT: requiere el permiso write y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "write", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "packageId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Paquete reactivado con su estado anterior.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "ETag": { "$ref": "#/components/headers/ResourceRevision" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RipsPackage" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/rips-packages/{packageId}/validations": { "post": { "operationId": "ripsPackages.validate", "tags": [ "Paquetes RIPS" ], "summary": "Validar una revisión", "description": "Evalúa la revisión indicada con las reglas, referencias aceptadas y contexto vigentes, y registra la evidencia. Lee el AttachedDocument vigente del sistema de facturación y registra su digest. Un resultado inválido no altera el paquete. No llama al Ministerio. Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso write y acceso al espacio de la ruta, cuando exista. Límite del cuerpo HTTP: 1000000 bytes, antes de interpretar el contenido.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "write", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "write", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "packageId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionInput" }, "examples": { "revision": { "summary": "Validar/enviar la revisión vigente", "value": { "revision": 1 } } } } } }, "responses": { "200": { "description": "Evidencia registrada (válida o con hallazgos). El ejemplo muestra un borrador sin usuarios; el HTTP 200 no implica validez.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RipsValidationResult" }, "example": { "validation": { "id": "val-demo-001", "revision": 1, "outcome": "invalid", "current": true, "contentDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "attachedDocumentSha256": null, "rulesVersion": "native-d558206", "contextDigest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "referencesDigest": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", "issues": [ { "code": "usuarios_required", "field": "usuarios", "message": "Se requiere al menos un usuario para enviar el paquete." } ], "validatedAt": "2026-09-01T15:01:00.000Z" }, "payload": null, "fieldConditions": null } } } }, "400": { "description": "Rechazo: invalid_json, duplicate_key, json_syntax, json_depth, json_type, numeric_value_loss, numeric_overflow, conflicting_alias, invalid_request, server_owned_field, invalid_query, invalid_path.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_json": { "summary": "El cuerpo no es JSON válido.", "value": { "error": { "code": "invalid_json", "message": "El cuerpo no es JSON válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_key": { "summary": "El cuerpo repite una clave JSON.", "value": { "error": { "code": "duplicate_key", "message": "El cuerpo repite una clave JSON." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "json_syntax": { "summary": "El JSON tiene un error de sintaxis.", "value": { "error": { "code": "json_syntax", "message": "El JSON tiene un error de sintaxis." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: resource_archived, revision_conflict, invoice_provider_not_configured, invoice_provider_company_mismatch, artifact_context_unverified.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "resource_archived": { "summary": "El recurso está archivado.", "value": { "error": { "code": "resource_archived", "message": "El recurso está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "revision_conflict": { "summary": "La revisión cambió. Recargue el recurso antes de continuar.", "value": { "error": { "code": "revision_conflict", "message": "La revisión cambió. Recargue el recurso antes de continuar." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invoice_provider_not_configured": { "summary": "Configure el token, el equipo y la empresa de PahFacturar.", "value": { "error": { "code": "invoice_provider_not_configured", "message": "Configure el token, el equipo y la empresa de PahFacturar." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: request_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "request_too_large": { "summary": "El cuerpo supera el tamaño permitido.", "value": { "error": { "code": "request_too_large", "message": "El cuerpo supera el tamaño permitido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "415": { "description": "Rechazo: unsupported_media_type.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported_media_type": { "summary": "El tipo de contenido no es compatible con esta operación.", "value": { "error": { "code": "unsupported_media_type", "message": "El tipo de contenido no es compatible con esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "422": { "description": "Rechazo: attached_document_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "attached_document_too_large": { "summary": "El AttachedDocument del sistema de facturación supera 16 MiB; el Ministerio no lo recibe.", "value": { "error": { "code": "attached_document_too_large", "message": "El AttachedDocument del sistema de facturación supera 16 MiB; el Ministerio no lo recibe." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "502": { "description": "Rechazo: invoice_provider_unavailable, artifact_download_failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invoice_provider_unavailable": { "summary": "PahFacturar no respondió. Intente de nuevo.", "value": { "error": { "code": "invoice_provider_unavailable", "message": "PahFacturar no respondió. Intente de nuevo." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "artifact_download_failed": { "summary": "No fue posible descargar el artefacto del proveedor.", "value": { "error": { "code": "artifact_download_failed", "message": "No fue posible descargar el artefacto del proveedor." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "503": { "description": "Rechazo: upstream_configuration_invalid.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "upstream_configuration_invalid": { "summary": "La conexión con el servicio externo no está configurada para este entorno.", "value": { "error": { "code": "upstream_configuration_invalid", "message": "La conexión con el servicio externo no está configurada para este entorno." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/rips-packages/{packageId}/dispatches": { "get": { "operationId": "ripsPackages.listDispatches", "tags": [ "Paquetes RIPS" ], "summary": "Consultar los intentos de envío y su evidencia", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "packageId", "in": "path" } ], "responses": { "200": { "description": "Intentos inmutables.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DispatchAttemptList" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } }, "post": { "operationId": "ripsPackages.requestDispatch", "tags": [ "Paquetes RIPS" ], "summary": "Solicitar el envío de una revisión al Ministerio", "description": "Valida de nuevo la revisión exacta con el AttachedDocument vigente del sistema de facturación, verifica permisos, referencias y saldos, registra el intento inmutable con el cuerpo exacto y luego llama al Ministerio. Un resultado incierto bloquea reenvíos automáticos. Requiere una membresía activa en el espacio de la ruta. Requiere Idempotency-Key. PAT: requiere el permiso send y acceso al espacio de la ruta, cuando exista. Límite del cuerpo HTTP: 1000000 bytes, antes de interpretar el contenido.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "external", "x-ripscloud-idempotency": "required", "x-ripscloud-pat-scope": "send", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "packageId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": true, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionInput" }, "examples": { "revision": { "summary": "Validar/enviar la revisión vigente", "value": { "revision": 1 } } } } } }, "responses": { "200": { "description": "Intento con resultado terminal (aceptado o rechazado). El CUV de ejemplo es sintético.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RipsDispatchResult" }, "example": { "attempt": { "id": "attempt-demo-001", "revision": 1, "outcome": "accepted", "environment": 2, "attemptedAt": "2026-09-01T15:02:00.000Z", "completedAt": "2026-09-01T15:02:01.000Z", "procesoId": "123456", "cuv": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "message": "Ejemplo sintético de recibo verificado", "requestDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "validations": [], "reconciliation": null }, "package": { "id": "pkg-demo-001", "kind": "rips_sin_factura", "status": "Accepted", "revision": 1, "isActive": true, "statusMessage": null, "numFactura": null, "numNota": "RS-DEMO-001", "tipoNota": "RS", "cufeOrCude": null, "attachedDocument": null, "sourceInvoiceId": null, "sourceCreditNoteId": null, "sourceDebitNoteId": null, "sourcePackageId": null, "procesoId": "123456", "cuv": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "validation": { "id": "val-demo-001", "revision": 1, "outcome": "valid", "current": true, "contentDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "attachedDocumentSha256": null, "rulesVersion": "native-d558206", "contextDigest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "referencesDigest": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", "validatedAt": "2026-09-01T15:01:00.000Z" }, "lastAttempt": { "id": "attempt-demo-001", "revision": 1, "outcome": "accepted", "environment": 2, "attemptedAt": "2026-09-01T15:02:00.000Z", "completedAt": "2026-09-01T15:02:01.000Z", "procesoId": "123456", "cuv": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "message": "Ejemplo sintético de recibo verificado", "requestDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "validations": [], "reconciliation": null }, "createdByUserId": "user-demo-001", "createdAt": "2026-09-01T15:00:00.000Z", "updatedAt": "2026-09-01T15:00:00.000Z", "ripsPayloadJson": "{\"numDocumentoIdObligado\":\"900123456\",\"numFactura\":null,\"tipoNota\":\"RS\",\"numNota\":\"RS-DEMO-001\",\"usuarios\":[{\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000002\",\"tipoUsuario\":\"01\",\"fechaNacimiento\":\"1990-01-01\",\"codSexo\":\"F\",\"codPaisResidencia\":\"170\",\"codPaisOrigen\":\"170\",\"codMunicipioResidencia\":\"11001\",\"codZonaTerritorialResidencia\":\"01\",\"incapacidad\":\"NO\",\"consecutivo\":1,\"servicios\":{\"consultas\":[{\"codPrestador\":\"110010000101\",\"fechaInicioAtencion\":\"2026-09-01 10:00\",\"numAutorizacion\":null,\"codConsulta\":\"890201\",\"modalidadGrupoServicioTecSal\":\"01\",\"grupoServicios\":\"01\",\"codServicio\":325,\"finalidadTecnologiaSalud\":\"44\",\"causaMotivoAtencion\":\"38\",\"codDiagnosticoPrincipal\":\"Z000\",\"codDiagnosticoRelacionado1\":null,\"codDiagnosticoRelacionado2\":null,\"codDiagnosticoRelacionado3\":null,\"tipoDiagnosticoPrincipal\":\"01\",\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000001\",\"vrServicio\":100000,\"conceptoRecaudo\":\"05\",\"valorPagoModerador\":0,\"numFEVPagoModerador\":null,\"consecutivo\":1}]}}]}", "workingPayloadJson": "{\"numDocumentoIdObligado\":\"900123456\",\"numFactura\":null,\"tipoNota\":\"RS\",\"numNota\":\"RS-DEMO-001\",\"usuarios\":[{\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000002\",\"tipoUsuario\":\"01\",\"fechaNacimiento\":\"1990-01-01\",\"codSexo\":\"F\",\"codPaisResidencia\":\"170\",\"codPaisOrigen\":\"170\",\"codMunicipioResidencia\":\"11001\",\"codZonaTerritorialResidencia\":\"01\",\"incapacidad\":\"NO\",\"consecutivo\":1,\"servicios\":{\"consultas\":[{\"codPrestador\":\"110010000101\",\"fechaInicioAtencion\":\"2026-09-01 10:00\",\"numAutorizacion\":null,\"codConsulta\":\"890201\",\"modalidadGrupoServicioTecSal\":\"01\",\"grupoServicios\":\"01\",\"codServicio\":325,\"finalidadTecnologiaSalud\":\"44\",\"causaMotivoAtencion\":\"38\",\"codDiagnosticoPrincipal\":\"Z000\",\"codDiagnosticoRelacionado1\":null,\"codDiagnosticoRelacionado2\":null,\"codDiagnosticoRelacionado3\":null,\"tipoDiagnosticoPrincipal\":\"01\",\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000001\",\"vrServicio\":100000,\"conceptoRecaudo\":\"05\",\"valorPagoModerador\":0,\"numFEVPagoModerador\":null,\"consecutivo\":1}]}}]}", "provenance": { "sourceProfile": "native-d558206", "declaration": "user-declared", "inputFormat": "json", "changeCount": 0, "inputCount": 1 } }, "replayed": false } } } }, "202": { "description": "Intento registrado con resultado incierto o en curso. Requiere consulta/conciliación; no se reenvía.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RipsDispatchResult" }, "example": { "attempt": { "id": "attempt-demo-001", "revision": 1, "outcome": "unknown", "environment": 2, "attemptedAt": "2026-09-01T15:02:00.000Z", "completedAt": "2026-09-01T15:02:01.000Z", "procesoId": null, "cuv": null, "message": "Resultado incierto. No reenviar.", "requestDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "validations": [], "reconciliation": null }, "package": { "id": "pkg-demo-001", "kind": "rips_sin_factura", "status": "Unknown", "revision": 1, "isActive": true, "statusMessage": null, "numFactura": null, "numNota": "RS-DEMO-001", "tipoNota": "RS", "cufeOrCude": null, "attachedDocument": null, "sourceInvoiceId": null, "sourceCreditNoteId": null, "sourceDebitNoteId": null, "sourcePackageId": null, "procesoId": null, "cuv": null, "validation": { "id": "val-demo-001", "revision": 1, "outcome": "valid", "current": true, "contentDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "attachedDocumentSha256": null, "rulesVersion": "native-d558206", "contextDigest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "referencesDigest": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", "validatedAt": "2026-09-01T15:01:00.000Z" }, "lastAttempt": { "id": "attempt-demo-001", "revision": 1, "outcome": "unknown", "environment": 2, "attemptedAt": "2026-09-01T15:02:00.000Z", "completedAt": "2026-09-01T15:02:01.000Z", "procesoId": null, "cuv": null, "message": "Resultado incierto. No reenviar.", "requestDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "validations": [], "reconciliation": null }, "createdByUserId": "user-demo-001", "createdAt": "2026-09-01T15:00:00.000Z", "updatedAt": "2026-09-01T15:00:00.000Z", "ripsPayloadJson": "{\"numDocumentoIdObligado\":\"900123456\",\"numFactura\":null,\"tipoNota\":\"RS\",\"numNota\":\"RS-DEMO-001\",\"usuarios\":[{\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000002\",\"tipoUsuario\":\"01\",\"fechaNacimiento\":\"1990-01-01\",\"codSexo\":\"F\",\"codPaisResidencia\":\"170\",\"codPaisOrigen\":\"170\",\"codMunicipioResidencia\":\"11001\",\"codZonaTerritorialResidencia\":\"01\",\"incapacidad\":\"NO\",\"consecutivo\":1,\"servicios\":{\"consultas\":[{\"codPrestador\":\"110010000101\",\"fechaInicioAtencion\":\"2026-09-01 10:00\",\"numAutorizacion\":null,\"codConsulta\":\"890201\",\"modalidadGrupoServicioTecSal\":\"01\",\"grupoServicios\":\"01\",\"codServicio\":325,\"finalidadTecnologiaSalud\":\"44\",\"causaMotivoAtencion\":\"38\",\"codDiagnosticoPrincipal\":\"Z000\",\"codDiagnosticoRelacionado1\":null,\"codDiagnosticoRelacionado2\":null,\"codDiagnosticoRelacionado3\":null,\"tipoDiagnosticoPrincipal\":\"01\",\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000001\",\"vrServicio\":100000,\"conceptoRecaudo\":\"05\",\"valorPagoModerador\":0,\"numFEVPagoModerador\":null,\"consecutivo\":1}]}}]}", "workingPayloadJson": "{\"numDocumentoIdObligado\":\"900123456\",\"numFactura\":null,\"tipoNota\":\"RS\",\"numNota\":\"RS-DEMO-001\",\"usuarios\":[{\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000002\",\"tipoUsuario\":\"01\",\"fechaNacimiento\":\"1990-01-01\",\"codSexo\":\"F\",\"codPaisResidencia\":\"170\",\"codPaisOrigen\":\"170\",\"codMunicipioResidencia\":\"11001\",\"codZonaTerritorialResidencia\":\"01\",\"incapacidad\":\"NO\",\"consecutivo\":1,\"servicios\":{\"consultas\":[{\"codPrestador\":\"110010000101\",\"fechaInicioAtencion\":\"2026-09-01 10:00\",\"numAutorizacion\":null,\"codConsulta\":\"890201\",\"modalidadGrupoServicioTecSal\":\"01\",\"grupoServicios\":\"01\",\"codServicio\":325,\"finalidadTecnologiaSalud\":\"44\",\"causaMotivoAtencion\":\"38\",\"codDiagnosticoPrincipal\":\"Z000\",\"codDiagnosticoRelacionado1\":null,\"codDiagnosticoRelacionado2\":null,\"codDiagnosticoRelacionado3\":null,\"tipoDiagnosticoPrincipal\":\"01\",\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000001\",\"vrServicio\":100000,\"conceptoRecaudo\":\"05\",\"valorPagoModerador\":0,\"numFEVPagoModerador\":null,\"consecutivo\":1}]}}]}", "provenance": { "sourceProfile": "native-d558206", "declaration": "user-declared", "inputFormat": "json", "changeCount": 0, "inputCount": 1 } }, "replayed": false } } } }, "400": { "description": "Rechazo: invalid_json, duplicate_key, json_syntax, json_depth, json_type, numeric_value_loss, numeric_overflow, conflicting_alias, invalid_request, server_owned_field, invalid_query, invalid_path.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_json": { "summary": "El cuerpo no es JSON válido.", "value": { "error": { "code": "invalid_json", "message": "El cuerpo no es JSON válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_key": { "summary": "El cuerpo repite una clave JSON.", "value": { "error": { "code": "duplicate_key", "message": "El cuerpo repite una clave JSON." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "json_syntax": { "summary": "El JSON tiene un error de sintaxis.", "value": { "error": { "code": "json_syntax", "message": "El JSON tiene un error de sintaxis." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, resource_archived, revision_conflict, credit_balance_exceeded, dispatch_in_progress, dispatch_conflict, submission_outcome_unknown, package_already_accepted, submission_receipt_missing, sispro_credentials_missing, authorization_changed, invalid_field_profile, invoice_provider_not_configured, invoice_provider_company_mismatch, artifact_context_unverified.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "resource_archived": { "summary": "El recurso está archivado.", "value": { "error": { "code": "resource_archived", "message": "El recurso está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: request_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "request_too_large": { "summary": "El cuerpo supera el tamaño permitido.", "value": { "error": { "code": "request_too_large", "message": "El cuerpo supera el tamaño permitido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "415": { "description": "Rechazo: unsupported_media_type.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported_media_type": { "summary": "El tipo de contenido no es compatible con esta operación.", "value": { "error": { "code": "unsupported_media_type", "message": "El tipo de contenido no es compatible con esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "422": { "description": "Rechazo: package_validation_failed, reference_not_accepted, credit_total_mismatch, attached_document_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "package_validation_failed": { "summary": "La revisión no cumple las reglas de envío.", "value": { "error": { "code": "package_validation_failed", "message": "La revisión no cumple las reglas de envío." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "reference_not_accepted": { "summary": "La referencia no tiene un resultado aceptado y verificado en este espacio.", "value": { "error": { "code": "reference_not_accepted", "message": "La referencia no tiene un resultado aceptado y verificado en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "credit_total_mismatch": { "summary": "Una nota crédito total debe igualar el saldo de la factura.", "value": { "error": { "code": "credit_total_mismatch", "message": "Una nota crédito total debe igualar el saldo de la factura." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "502": { "description": "Rechazo: invoice_provider_unavailable, artifact_download_failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invoice_provider_unavailable": { "summary": "PahFacturar no respondió. Intente de nuevo.", "value": { "error": { "code": "invoice_provider_unavailable", "message": "PahFacturar no respondió. Intente de nuevo." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "artifact_download_failed": { "summary": "No fue posible descargar el artefacto del proveedor.", "value": { "error": { "code": "artifact_download_failed", "message": "No fue posible descargar el artefacto del proveedor." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "503": { "description": "Rechazo: upstream_configuration_invalid.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "upstream_configuration_invalid": { "summary": "La conexión con el servicio externo no está configurada para este entorno.", "value": { "error": { "code": "upstream_configuration_invalid", "message": "La conexión con el servicio externo no está configurada para este entorno." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/rips-packages/{packageId}/reconciliations": { "post": { "operationId": "ripsPackages.reconcile", "tags": [ "Paquetes RIPS" ], "summary": "Conciliar un resultado incierto", "description": "Consulta un CUV que ya conoce el cliente y lo compara con el snapshot inmutable del intento. No descubre CUV por número de factura. Si falta el CUV, conserve Unknown y escale la recuperación; no use una clave nueva para reenviar. Solo evidencia concluyente resuelve el estado; nunca reenvía el paquete. Requiere una membresía activa en el espacio de la ruta. Requiere Idempotency-Key. PAT: requiere el permiso send y acceso al espacio de la ruta, cuando exista. Límite del cuerpo HTTP: 1000000 bytes, antes de interpretar el contenido.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "external", "x-ripscloud-idempotency": "required", "x-ripscloud-pat-scope": "send", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "packageId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": true, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconcileDispatchInput" }, "examples": { "knownCuv": { "summary": "Conciliar con un CUV conocido", "value": { "attemptId": "attempt-demo-001", "evidence": { "cuv": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } } } } } }, "responses": { "200": { "description": "Intento conciliado como aceptado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RipsDispatchResult" }, "example": { "attempt": { "id": "attempt-demo-001", "revision": 1, "outcome": "accepted", "environment": 2, "attemptedAt": "2026-09-01T15:02:00.000Z", "completedAt": "2026-09-01T15:02:01.000Z", "procesoId": "123456", "cuv": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "message": "Ejemplo sintético de recibo verificado", "requestDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "validations": [], "reconciliation": { "evidenceCuv": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "outcome": "accepted", "reconciledAt": "2026-09-01T15:05:00.000Z" } }, "package": { "id": "pkg-demo-001", "kind": "rips_sin_factura", "status": "Accepted", "revision": 1, "isActive": true, "statusMessage": null, "numFactura": null, "numNota": "RS-DEMO-001", "tipoNota": "RS", "cufeOrCude": null, "attachedDocument": null, "sourceInvoiceId": null, "sourceCreditNoteId": null, "sourceDebitNoteId": null, "sourcePackageId": null, "procesoId": "123456", "cuv": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "validation": { "id": "val-demo-001", "revision": 1, "outcome": "valid", "current": true, "contentDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "attachedDocumentSha256": null, "rulesVersion": "native-d558206", "contextDigest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "referencesDigest": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", "validatedAt": "2026-09-01T15:01:00.000Z" }, "lastAttempt": { "id": "attempt-demo-001", "revision": 1, "outcome": "accepted", "environment": 2, "attemptedAt": "2026-09-01T15:02:00.000Z", "completedAt": "2026-09-01T15:02:01.000Z", "procesoId": "123456", "cuv": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "message": "Ejemplo sintético de recibo verificado", "requestDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "validations": [], "reconciliation": { "evidenceCuv": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "outcome": "accepted", "reconciledAt": "2026-09-01T15:05:00.000Z" } }, "createdByUserId": "user-demo-001", "createdAt": "2026-09-01T15:00:00.000Z", "updatedAt": "2026-09-01T15:00:00.000Z", "ripsPayloadJson": "{\"numDocumentoIdObligado\":\"900123456\",\"numFactura\":null,\"tipoNota\":\"RS\",\"numNota\":\"RS-DEMO-001\",\"usuarios\":[{\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000002\",\"tipoUsuario\":\"01\",\"fechaNacimiento\":\"1990-01-01\",\"codSexo\":\"F\",\"codPaisResidencia\":\"170\",\"codPaisOrigen\":\"170\",\"codMunicipioResidencia\":\"11001\",\"codZonaTerritorialResidencia\":\"01\",\"incapacidad\":\"NO\",\"consecutivo\":1,\"servicios\":{\"consultas\":[{\"codPrestador\":\"110010000101\",\"fechaInicioAtencion\":\"2026-09-01 10:00\",\"numAutorizacion\":null,\"codConsulta\":\"890201\",\"modalidadGrupoServicioTecSal\":\"01\",\"grupoServicios\":\"01\",\"codServicio\":325,\"finalidadTecnologiaSalud\":\"44\",\"causaMotivoAtencion\":\"38\",\"codDiagnosticoPrincipal\":\"Z000\",\"codDiagnosticoRelacionado1\":null,\"codDiagnosticoRelacionado2\":null,\"codDiagnosticoRelacionado3\":null,\"tipoDiagnosticoPrincipal\":\"01\",\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000001\",\"vrServicio\":100000,\"conceptoRecaudo\":\"05\",\"valorPagoModerador\":0,\"numFEVPagoModerador\":null,\"consecutivo\":1}]}}]}", "workingPayloadJson": "{\"numDocumentoIdObligado\":\"900123456\",\"numFactura\":null,\"tipoNota\":\"RS\",\"numNota\":\"RS-DEMO-001\",\"usuarios\":[{\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000002\",\"tipoUsuario\":\"01\",\"fechaNacimiento\":\"1990-01-01\",\"codSexo\":\"F\",\"codPaisResidencia\":\"170\",\"codPaisOrigen\":\"170\",\"codMunicipioResidencia\":\"11001\",\"codZonaTerritorialResidencia\":\"01\",\"incapacidad\":\"NO\",\"consecutivo\":1,\"servicios\":{\"consultas\":[{\"codPrestador\":\"110010000101\",\"fechaInicioAtencion\":\"2026-09-01 10:00\",\"numAutorizacion\":null,\"codConsulta\":\"890201\",\"modalidadGrupoServicioTecSal\":\"01\",\"grupoServicios\":\"01\",\"codServicio\":325,\"finalidadTecnologiaSalud\":\"44\",\"causaMotivoAtencion\":\"38\",\"codDiagnosticoPrincipal\":\"Z000\",\"codDiagnosticoRelacionado1\":null,\"codDiagnosticoRelacionado2\":null,\"codDiagnosticoRelacionado3\":null,\"tipoDiagnosticoPrincipal\":\"01\",\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000001\",\"vrServicio\":100000,\"conceptoRecaudo\":\"05\",\"valorPagoModerador\":0,\"numFEVPagoModerador\":null,\"consecutivo\":1}]}}]}", "provenance": { "sourceProfile": "native-d558206", "declaration": "user-declared", "inputFormat": "json", "changeCount": 0, "inputCount": 1 } }, "replayed": false } } } }, "400": { "description": "Rechazo: invalid_json, duplicate_key, json_syntax, json_depth, json_type, numeric_value_loss, numeric_overflow, conflicting_alias, invalid_request, server_owned_field, invalid_query, invalid_path.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_json": { "summary": "El cuerpo no es JSON válido.", "value": { "error": { "code": "invalid_json", "message": "El cuerpo no es JSON válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_key": { "summary": "El cuerpo repite una clave JSON.", "value": { "error": { "code": "duplicate_key", "message": "El cuerpo repite una clave JSON." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "json_syntax": { "summary": "El JSON tiene un error de sintaxis.", "value": { "error": { "code": "json_syntax", "message": "El JSON tiene un error de sintaxis." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, reconciliation_not_applicable, sispro_credentials_missing, authorization_changed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "reconciliation_not_applicable": { "summary": "Solo un resultado incierto se puede conciliar.", "value": { "error": { "code": "reconciliation_not_applicable", "message": "Solo un resultado incierto se puede conciliar." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: request_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "request_too_large": { "summary": "El cuerpo supera el tamaño permitido.", "value": { "error": { "code": "request_too_large", "message": "El cuerpo supera el tamaño permitido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "415": { "description": "Rechazo: unsupported_media_type.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported_media_type": { "summary": "El tipo de contenido no es compatible con esta operación.", "value": { "error": { "code": "unsupported_media_type", "message": "El tipo de contenido no es compatible con esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "422": { "description": "Rechazo: reconciliation_inconclusive.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "reconciliation_inconclusive": { "summary": "La evidencia no resuelve el resultado. El estado sigue incierto.", "value": { "error": { "code": "reconciliation_inconclusive", "message": "La evidencia no resuelve el resultado. El estado sigue incierto." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "503": { "description": "Rechazo: upstream_configuration_invalid.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "upstream_configuration_invalid": { "summary": "La conexión con el servicio externo no está configurada para este entorno.", "value": { "error": { "code": "upstream_configuration_invalid", "message": "La conexión con el servicio externo no está configurada para este entorno." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/health-invoices": { "get": { "operationId": "healthInvoices.list", "tags": [ "Facturas de salud" ], "summary": "Listar facturas de salud", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "description": "Página inicial 1 (valor predeterminado).", "example": 1 }, "required": false, "description": "Página inicial 1 (valor predeterminado).", "name": "page", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Registros por página: 100 por defecto, máximo 500.", "example": 100 }, "required": false, "description": "Registros por página: 100 por defecto, máximo 500.", "name": "pageSize", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "required": false, "name": "sortDirection", "in": "query" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "clientName", "in": "query" }, { "schema": { "type": "string", "maxLength": 40 }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "maxLength": 40, "description": "Fecha/hora ISO 8601 inclusiva; enviar un valor UTC válido.", "example": "2026-09-01T00:00:00.000Z" }, "required": false, "description": "Fecha/hora ISO 8601 inclusiva; enviar un valor UTC válido.", "name": "createdFrom", "in": "query" }, { "schema": { "type": "string", "maxLength": 40, "description": "Fecha/hora ISO 8601 inclusiva; enviar un valor UTC válido.", "example": "2026-09-30T23:59:59.999Z" }, "required": false, "description": "Fecha/hora ISO 8601 inclusiva; enviar un valor UTC válido.", "name": "createdTo", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "includeArchived", "in": "query" }, { "schema": { "type": "string", "enum": [ "invoiceNumber", "clientName", "status", "createdAt", "updatedAt", "totalAmount" ] }, "required": false, "name": "sortBy", "in": "query" }, { "schema": { "type": "string", "maxLength": 60 }, "required": false, "name": "invoiceNumber", "in": "query" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "submittedBy", "in": "query" }, { "schema": { "type": [ "number", "null" ] }, "required": false, "name": "totalMin", "in": "query" }, { "schema": { "type": [ "number", "null" ] }, "required": false, "name": "totalMax", "in": "query" } ], "responses": { "200": { "description": "Página de facturas.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthInvoicePage" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } }, "post": { "operationId": "healthInvoices.emit", "tags": [ "Facturas de salud" ], "summary": "Emitir una factura de salud por PahFacturar", "description": "Valida el contenido antes de reservar número. Registra la intención antes de crear el documento en el proveedor. Un resultado incierto bloquea otra emisión. Requiere una membresía activa en el espacio de la ruta. Requiere Idempotency-Key. PAT: requiere el permiso send y acceso al espacio de la ruta, cuando exista. Límite del cuerpo HTTP: 26000000 bytes, antes de interpretar el contenido.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "external", "x-ripscloud-idempotency": "required", "x-ripscloud-pat-scope": "send", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": true, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmitHealthInvoiceInput" }, "examples": { "healthInvoice": { "summary": "Factura con RIPS de trabajo", "description": "Datos sintéticos. Use los identificadores de GET /health-invoices/context y /credit-note-context, la configuración y el saldo reales. Los ejemplos no autorizan una emisión ni prueban aceptación DIAN.", "value": { "clientId": "payer-demo-001", "invoiceResolutionId": "resolution-demo-001", "invoicePayload": { "invoice_lines": [ { "description": "Consulta de medicina general (ejemplo sintético)", "code": "890201", "invoiced_quantity": "1", "price_amount": "100000.00", "line_extension_amount": "100000.00" } ], "legal_monetary_totals": { "line_extension_amount": "100000.00", "tax_exclusive_amount": "100000.00", "tax_inclusive_amount": "100000.00", "payable_amount": "100000.00" }, "payment_form": { "payment_form_id": 1, "payment_method_id": 10 }, "health_fields": { "invoice_period_start_date": "2026-09-01", "invoice_period_end_date": "2026-09-30", "health_type_operation_id": "SS-CUFE", "users_info": [ { "provider_code": "110010000101", "health_coverage_id": "01", "health_contracting_payment_method_id": "04", "contract_number": "CONTRATO-DEMO" } ] } }, "rips": { "numDocumentoIdObligado": "900123456", "numFactura": null, "tipoNota": null, "numNota": null, "usuarios": [ { "tipoDocumentoIdentificacion": "CC", "numDocumentoIdentificacion": "1000000002", "tipoUsuario": "01", "fechaNacimiento": "1990-01-01", "codSexo": "F", "codPaisResidencia": "170", "codPaisOrigen": "170", "codMunicipioResidencia": "11001", "codZonaTerritorialResidencia": "01", "incapacidad": "NO", "consecutivo": 1, "servicios": { "consultas": [ { "codPrestador": "110010000101", "fechaInicioAtencion": "2026-09-01 10:00", "numAutorizacion": null, "codConsulta": "890201", "modalidadGrupoServicioTecSal": "01", "grupoServicios": "01", "codServicio": 325, "finalidadTecnologiaSalud": "44", "causaMotivoAtencion": "38", "codDiagnosticoPrincipal": "Z000", "codDiagnosticoRelacionado1": null, "codDiagnosticoRelacionado2": null, "codDiagnosticoRelacionado3": null, "tipoDiagnosticoPrincipal": "01", "tipoDocumentoIdentificacion": "CC", "numDocumentoIdentificacion": "1000000001", "vrServicio": 100000, "conceptoRecaudo": "05", "valorPagoModerador": 0, "numFEVPagoModerador": null, "consecutivo": 1 } ] } } ] } } } } } } }, "responses": { "201": { "description": "Documento aceptado o con rechazo terminal registrado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthInvoice" } } } }, "202": { "description": "Emisión registrada con resultado incierto o en curso.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthInvoice" } } } }, "400": { "description": "Rechazo: invalid_json, duplicate_key, json_syntax, json_depth, json_type, numeric_value_loss, numeric_overflow, conflicting_alias, invalid_request, server_owned_field, invalid_query, invalid_path, invalid_rips_input, invalid_medication_code.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_json": { "summary": "El cuerpo no es JSON válido.", "value": { "error": { "code": "invalid_json", "message": "El cuerpo no es JSON válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_key": { "summary": "El cuerpo repite una clave JSON.", "value": { "error": { "code": "duplicate_key", "message": "El cuerpo repite una clave JSON." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "json_syntax": { "summary": "El JSON tiene un error de sintaxis.", "value": { "error": { "code": "json_syntax", "message": "El JSON tiene un error de sintaxis." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, invoice_provider_not_configured, invoice_provider_company_mismatch, resolution_unavailable, provider_dispatch_in_progress, provider_outcome_unknown, health_document_not_emittable, authorization_changed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invoice_provider_not_configured": { "summary": "Configure el token, el equipo y la empresa de PahFacturar.", "value": { "error": { "code": "invoice_provider_not_configured", "message": "Configure el token, el equipo y la empresa de PahFacturar." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: request_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "request_too_large": { "summary": "El cuerpo supera el tamaño permitido.", "value": { "error": { "code": "request_too_large", "message": "El cuerpo supera el tamaño permitido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "415": { "description": "Rechazo: unsupported_media_type.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported_media_type": { "summary": "El tipo de contenido no es compatible con esta operación.", "value": { "error": { "code": "unsupported_media_type", "message": "El tipo de contenido no es compatible con esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "422": { "description": "Rechazo: health_document_invalid.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "health_document_invalid": { "summary": "El contenido del documento de salud no cumple las reglas de emisión.", "value": { "error": { "code": "health_document_invalid", "message": "El contenido del documento de salud no cumple las reglas de emisión." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "502": { "description": "Rechazo: invoice_provider_unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invoice_provider_unavailable": { "summary": "PahFacturar no respondió. Intente de nuevo.", "value": { "error": { "code": "invoice_provider_unavailable", "message": "PahFacturar no respondió. Intente de nuevo." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "503": { "description": "Rechazo: upstream_configuration_invalid.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "upstream_configuration_invalid": { "summary": "La conexión con el servicio externo no está configurada para este entorno.", "value": { "error": { "code": "upstream_configuration_invalid", "message": "La conexión con el servicio externo no está configurada para este entorno." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/health-invoices/{invoiceId}": { "get": { "operationId": "healthInvoices.get", "tags": [ "Facturas de salud" ], "summary": "Consultar una factura de salud", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "invoiceId", "in": "path" } ], "responses": { "200": { "description": "Factura con su historial.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthInvoice" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/health-invoices/{invoiceId}/emissions": { "post": { "operationId": "healthInvoices.retryEmission", "tags": [ "Facturas de salud" ], "summary": "Reintentar la emisión", "description": "Solo para Pending o Failed sin CUFE, o para completar una emisión aceptada por el proveedor. Nunca crea otro documento sobre un resultado incierto. Requiere una membresía activa en el espacio de la ruta. Requiere Idempotency-Key. PAT: requiere el permiso send y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "external", "x-ripscloud-idempotency": "required", "x-ripscloud-pat-scope": "send", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "invoiceId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": true, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Resultado terminal registrado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthInvoice" } } } }, "202": { "description": "Resultado incierto o en curso.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthInvoice" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, invoice_provider_not_configured, invoice_provider_company_mismatch, resolution_unavailable, provider_dispatch_in_progress, provider_outcome_unknown, health_document_not_emittable, authorization_changed, resource_archived.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invoice_provider_not_configured": { "summary": "Configure el token, el equipo y la empresa de PahFacturar.", "value": { "error": { "code": "invoice_provider_not_configured", "message": "Configure el token, el equipo y la empresa de PahFacturar." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "422": { "description": "Rechazo: health_document_invalid.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "health_document_invalid": { "summary": "El contenido del documento de salud no cumple las reglas de emisión.", "value": { "error": { "code": "health_document_invalid", "message": "El contenido del documento de salud no cumple las reglas de emisión." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "502": { "description": "Rechazo: invoice_provider_unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invoice_provider_unavailable": { "summary": "PahFacturar no respondió. Intente de nuevo.", "value": { "error": { "code": "invoice_provider_unavailable", "message": "PahFacturar no respondió. Intente de nuevo." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "503": { "description": "Rechazo: upstream_configuration_invalid.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "upstream_configuration_invalid": { "summary": "La conexión con el servicio externo no está configurada para este entorno.", "value": { "error": { "code": "upstream_configuration_invalid", "message": "La conexión con el servicio externo no está configurada para este entorno." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/health-invoices/{invoiceId}/reconciliations": { "post": { "operationId": "healthInvoices.reconcile", "tags": [ "Facturas de salud" ], "summary": "Conciliar una emisión incierta", "description": "Verifica el UUID conocido de PahFacturar contra la intención registrada (empresa, tipo, número y contenido). No recupera un UUID perdido ni busca por número. Sin UUID, conserve Unknown y solicite recuperación. Solo evidencia concluyente resuelve el estado; no crea documentos. Requiere una membresía activa en el espacio de la ruta. Requiere Idempotency-Key. PAT: requiere el permiso send y acceso al espacio de la ruta, cuando exista. Límite del cuerpo HTTP: 1000000 bytes, antes de interpretar el contenido.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "external", "x-ripscloud-idempotency": "required", "x-ripscloud-pat-scope": "send", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "invoiceId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": true, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconcileHealthDocumentInput" }, "examples": { "knownProviderId": { "summary": "Conciliar con el UUID ya conocido del proveedor", "value": { "providerDocumentId": "11111111-1111-4111-8111-111111111111" } } } } } }, "responses": { "200": { "description": "Emisión conciliada.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthInvoice" } } } }, "400": { "description": "Rechazo: invalid_json, duplicate_key, json_syntax, json_depth, json_type, numeric_value_loss, numeric_overflow, conflicting_alias, invalid_request, server_owned_field, invalid_query, invalid_path.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_json": { "summary": "El cuerpo no es JSON válido.", "value": { "error": { "code": "invalid_json", "message": "El cuerpo no es JSON válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_key": { "summary": "El cuerpo repite una clave JSON.", "value": { "error": { "code": "duplicate_key", "message": "El cuerpo repite una clave JSON." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "json_syntax": { "summary": "El JSON tiene un error de sintaxis.", "value": { "error": { "code": "json_syntax", "message": "El JSON tiene un error de sintaxis." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, reconciliation_not_applicable, invoice_provider_not_configured, authorization_changed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "reconciliation_not_applicable": { "summary": "Solo un resultado incierto se puede conciliar.", "value": { "error": { "code": "reconciliation_not_applicable", "message": "Solo un resultado incierto se puede conciliar." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: request_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "request_too_large": { "summary": "El cuerpo supera el tamaño permitido.", "value": { "error": { "code": "request_too_large", "message": "El cuerpo supera el tamaño permitido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "415": { "description": "Rechazo: unsupported_media_type.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported_media_type": { "summary": "El tipo de contenido no es compatible con esta operación.", "value": { "error": { "code": "unsupported_media_type", "message": "El tipo de contenido no es compatible con esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "422": { "description": "Rechazo: reconciliation_inconclusive.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "reconciliation_inconclusive": { "summary": "La evidencia no resuelve el resultado. El estado sigue incierto.", "value": { "error": { "code": "reconciliation_inconclusive", "message": "La evidencia no resuelve el resultado. El estado sigue incierto." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "502": { "description": "Rechazo: invoice_provider_unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invoice_provider_unavailable": { "summary": "PahFacturar no respondió. Intente de nuevo.", "value": { "error": { "code": "invoice_provider_unavailable", "message": "PahFacturar no respondió. Intente de nuevo." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/health-invoices/{invoiceId}/artifacts/{artifact}": { "get": { "operationId": "healthInvoices.downloadArtifact", "tags": [ "Facturas de salud" ], "summary": "Descargar PDF o XML", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso send y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "external", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "send", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "invoiceId", "in": "path" }, { "schema": { "type": "string", "enum": [ "pdf", "xml", "attached" ] }, "required": true, "name": "artifact", "in": "path" } ], "responses": { "200": { "description": "Artefacto del documento aceptado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found, document_not_available.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "document_not_available": { "summary": "El documento solicitado no está disponible.", "value": { "error": { "code": "document_not_available", "message": "El documento solicitado no está disponible." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: authorization_changed, artifact_context_unverified, invoice_provider_not_configured.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "authorization_changed": { "summary": "Los permisos cambiaron durante la operación. No se realizó ningún efecto externo.", "value": { "error": { "code": "authorization_changed", "message": "Los permisos cambiaron durante la operación. No se realizó ningún efecto externo." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "artifact_context_unverified": { "summary": "El artefacto no corresponde al documento aceptado.", "value": { "error": { "code": "artifact_context_unverified", "message": "El artefacto no corresponde al documento aceptado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invoice_provider_not_configured": { "summary": "Configure el token, el equipo y la empresa de PahFacturar.", "value": { "error": { "code": "invoice_provider_not_configured", "message": "Configure el token, el equipo y la empresa de PahFacturar." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "502": { "description": "Rechazo: artifact_download_failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "artifact_download_failed": { "summary": "No fue posible descargar el artefacto del proveedor.", "value": { "error": { "code": "artifact_download_failed", "message": "No fue posible descargar el artefacto del proveedor." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/health-invoices/{invoiceId}/export": { "get": { "operationId": "healthInvoices.export", "tags": [ "Facturas de salud" ], "summary": "Exportar la factura y su RIPS en JSON", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "invoiceId", "in": "path" } ], "responses": { "200": { "description": "Paquete JSON.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/health-invoices/{invoiceId}/email": { "post": { "operationId": "healthInvoices.sendEmail", "tags": [ "Facturas de salud" ], "summary": "Enviar la factura por correo", "description": "El correo se reclama de forma atómica antes del envío. La misma clave y contenido devuelve el resultado confirmado. Si SMTP falla, demora o se pierde la respuesta, email_outcome_unknown bloquea el reenvío automático con esa clave. Verifique la entrega antes de usar una clave nueva para evitar duplicados. Requiere una membresía activa en el espacio de la ruta. Requiere Idempotency-Key. PAT: requiere el permiso send y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "external", "x-ripscloud-idempotency": "required", "x-ripscloud-pat-scope": "send", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "invoiceId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": true, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Correo enviado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailResult" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found, document_not_available.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "document_not_available": { "summary": "El documento solicitado no está disponible.", "value": { "error": { "code": "document_not_available", "message": "El documento solicitado no está disponible." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: authorization_changed, idempotency_key_reused, idempotency_in_progress, email_disabled, email_outcome_unknown, artifact_context_unverified.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "authorization_changed": { "summary": "Los permisos cambiaron durante la operación. No se realizó ningún efecto externo.", "value": { "error": { "code": "authorization_changed", "message": "Los permisos cambiaron durante la operación. No se realizó ningún efecto externo." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: email_attachment_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "email_attachment_too_large": { "summary": "El adjunto supera el límite de correo.", "value": { "error": { "code": "email_attachment_too_large", "message": "El adjunto supera el límite de correo." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "422": { "description": "Rechazo: recipient_email_missing.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "recipient_email_missing": { "summary": "El cliente no tiene correo registrado.", "value": { "error": { "code": "recipient_email_missing", "message": "El cliente no tiene correo registrado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "502": { "description": "Rechazo: artifact_download_failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "artifact_download_failed": { "summary": "No fue posible descargar el artefacto del proveedor.", "value": { "error": { "code": "artifact_download_failed", "message": "No fue posible descargar el artefacto del proveedor." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "503": { "description": "Rechazo: email_not_configured.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "email_not_configured": { "summary": "El correo saliente no está configurado.", "value": { "error": { "code": "email_not_configured", "message": "El correo saliente no está configurado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/health-invoices/{invoiceId}/rips-package": { "post": { "operationId": "healthInvoices.prepareRipsPackage", "tags": [ "Facturas de salud" ], "summary": "Preparar el RIPS fev_rips de la factura", "description": "Usa la factura aceptada como fuente: número, CUFE y XML adjunto del proveedor. El paquete referencia la factura en el sistema de facturación y no guarda el XML. Devuelve el borrador vinculado existente o crea uno. No envía al Ministerio. Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. PAT: requiere el permiso send y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "external", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "send", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "invoiceId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Paquete vinculado existente.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "ETag": { "$ref": "#/components/headers/ResourceRevision" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RipsPackage" } } } }, "201": { "description": "Paquete creado desde la factura.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "ETag": { "$ref": "#/components/headers/ResourceRevision" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RipsPackage" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found, document_not_available.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "document_not_available": { "summary": "El documento solicitado no está disponible.", "value": { "error": { "code": "document_not_available", "message": "El documento solicitado no está disponible." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: authorization_changed, idempotency_key_reused, idempotency_in_progress, artifact_context_unverified.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "authorization_changed": { "summary": "Los permisos cambiaron durante la operación. No se realizó ningún efecto externo.", "value": { "error": { "code": "authorization_changed", "message": "Los permisos cambiaron durante la operación. No se realizó ningún efecto externo." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "422": { "description": "Rechazo: source_invoice_not_accepted, source_rips_missing.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "source_invoice_not_accepted": { "summary": "La factura de origen no tiene CUFE aceptado.", "value": { "error": { "code": "source_invoice_not_accepted", "message": "La factura de origen no tiene CUFE aceptado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "source_rips_missing": { "summary": "La factura de origen no tiene RIPS aceptado o guardado.", "value": { "error": { "code": "source_rips_missing", "message": "La factura de origen no tiene RIPS aceptado o guardado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "502": { "description": "Rechazo: artifact_download_failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "artifact_download_failed": { "summary": "No fue posible descargar el artefacto del proveedor.", "value": { "error": { "code": "artifact_download_failed", "message": "No fue posible descargar el artefacto del proveedor." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/credit-notes": { "get": { "operationId": "creditNotes.list", "tags": [ "Notas crédito" ], "summary": "Listar notas crédito de salud", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "description": "Página inicial 1 (valor predeterminado).", "example": 1 }, "required": false, "description": "Página inicial 1 (valor predeterminado).", "name": "page", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Registros por página: 100 por defecto, máximo 500.", "example": 100 }, "required": false, "description": "Registros por página: 100 por defecto, máximo 500.", "name": "pageSize", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "required": false, "name": "sortDirection", "in": "query" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "clientName", "in": "query" }, { "schema": { "type": "string", "maxLength": 40 }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "maxLength": 40, "description": "Fecha/hora ISO 8601 inclusiva; enviar un valor UTC válido.", "example": "2026-09-01T00:00:00.000Z" }, "required": false, "description": "Fecha/hora ISO 8601 inclusiva; enviar un valor UTC válido.", "name": "createdFrom", "in": "query" }, { "schema": { "type": "string", "maxLength": 40, "description": "Fecha/hora ISO 8601 inclusiva; enviar un valor UTC válido.", "example": "2026-09-30T23:59:59.999Z" }, "required": false, "description": "Fecha/hora ISO 8601 inclusiva; enviar un valor UTC válido.", "name": "createdTo", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "includeArchived", "in": "query" }, { "schema": { "type": "string", "enum": [ "creditNoteNumber", "originalInvoiceNumber", "clientName", "status", "createdAt", "updatedAt", "totalAmount" ] }, "required": false, "name": "sortBy", "in": "query" }, { "schema": { "type": "string", "maxLength": 60 }, "required": false, "name": "creditNoteNumber", "in": "query" }, { "schema": { "type": "string", "maxLength": 60 }, "required": false, "name": "originalInvoiceNumber", "in": "query" } ], "responses": { "200": { "description": "Página de notas.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNotePage" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } }, "post": { "operationId": "creditNotes.emit", "tags": [ "Notas crédito" ], "summary": "Emitir una nota crédito de salud por PahFacturar", "description": "Deriva cliente, referencia y campos de salud de la factura aceptada; verifica el saldo dentro de la transacción que serializa las notas de esa factura. Requiere una membresía activa en el espacio de la ruta. Requiere Idempotency-Key. PAT: requiere el permiso send y acceso al espacio de la ruta, cuando exista. Límite del cuerpo HTTP: 1000000 bytes, antes de interpretar el contenido.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "external", "x-ripscloud-idempotency": "required", "x-ripscloud-pat-scope": "send", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": true, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmitCreditNoteInput" }, "examples": { "partial": { "summary": "Nota parcial con selección de servicio", "description": "Datos sintéticos. Use los identificadores de GET /health-invoices/context y /credit-note-context, la configuración y el saldo reales. Los ejemplos no autorizan una emisión ni prueban aceptación DIAN.", "value": { "invoiceId": "invoice-demo-001", "creditNoteResolutionId": "credit-resolution-demo-001", "discrepancyResponseCode": 1, "discrepancyResponseDescription": "Devolución de servicio (ejemplo sintético)", "selectedItems": [ { "patientConsecutivo": 1, "includeAllServices": false, "selectedServices": [ { "serviceCategory": "consultas", "serviceConsecutivo": 1 } ] } ], "creditNotePayload": { "credit_note_lines": [ { "description": "Consulta de medicina general (ejemplo sintético)", "code": "890201", "invoiced_quantity": "1", "price_amount": "100000.00", "line_extension_amount": "100000.00" } ], "legal_monetary_totals": { "line_extension_amount": "100000.00", "tax_exclusive_amount": "100000.00", "tax_inclusive_amount": "100000.00", "payable_amount": "100000.00" } } } }, "total": { "summary": "Nota de anulación total", "description": "Datos sintéticos. Use los identificadores de GET /health-invoices/context y /credit-note-context, la configuración y el saldo reales. Los ejemplos no autorizan una emisión ni prueban aceptación DIAN.", "value": { "invoiceId": "invoice-demo-001", "creditNoteResolutionId": "credit-resolution-demo-001", "discrepancyResponseCode": 2, "discrepancyResponseDescription": "Anulación total (ejemplo sintético)", "creditNotePayload": { "credit_note_lines": [ { "description": "Consulta de medicina general (ejemplo sintético)", "code": "890201", "invoiced_quantity": "1", "price_amount": "100000.00", "line_extension_amount": "100000.00" } ], "legal_monetary_totals": { "line_extension_amount": "100000.00", "tax_exclusive_amount": "100000.00", "tax_inclusive_amount": "100000.00", "payable_amount": "100000.00" } } } } } } } }, "responses": { "201": { "description": "Documento aceptado o con rechazo terminal registrado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" } } } }, "202": { "description": "Emisión registrada con resultado incierto o en curso.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" } } } }, "400": { "description": "Rechazo: invalid_json, duplicate_key, json_syntax, json_depth, json_type, numeric_value_loss, numeric_overflow, conflicting_alias, invalid_request, server_owned_field, invalid_query, invalid_path.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_json": { "summary": "El cuerpo no es JSON válido.", "value": { "error": { "code": "invalid_json", "message": "El cuerpo no es JSON válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_key": { "summary": "El cuerpo repite una clave JSON.", "value": { "error": { "code": "duplicate_key", "message": "El cuerpo repite una clave JSON." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "json_syntax": { "summary": "El JSON tiene un error de sintaxis.", "value": { "error": { "code": "json_syntax", "message": "El JSON tiene un error de sintaxis." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, invoice_provider_not_configured, invoice_provider_company_mismatch, resolution_unavailable, provider_dispatch_in_progress, provider_outcome_unknown, health_document_not_emittable, authorization_changed, credit_balance_exceeded.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invoice_provider_not_configured": { "summary": "Configure el token, el equipo y la empresa de PahFacturar.", "value": { "error": { "code": "invoice_provider_not_configured", "message": "Configure el token, el equipo y la empresa de PahFacturar." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: request_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "request_too_large": { "summary": "El cuerpo supera el tamaño permitido.", "value": { "error": { "code": "request_too_large", "message": "El cuerpo supera el tamaño permitido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "415": { "description": "Rechazo: unsupported_media_type.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported_media_type": { "summary": "El tipo de contenido no es compatible con esta operación.", "value": { "error": { "code": "unsupported_media_type", "message": "El tipo de contenido no es compatible con esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "422": { "description": "Rechazo: health_document_invalid, source_invoice_not_accepted, source_customer_missing, source_rips_missing, credit_note_selection_invalid, credit_total_mismatch.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "health_document_invalid": { "summary": "El contenido del documento de salud no cumple las reglas de emisión.", "value": { "error": { "code": "health_document_invalid", "message": "El contenido del documento de salud no cumple las reglas de emisión." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "source_invoice_not_accepted": { "summary": "La factura de origen no tiene CUFE aceptado.", "value": { "error": { "code": "source_invoice_not_accepted", "message": "La factura de origen no tiene CUFE aceptado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "source_customer_missing": { "summary": "La factura de origen no identifica al cliente.", "value": { "error": { "code": "source_customer_missing", "message": "La factura de origen no identifica al cliente." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "502": { "description": "Rechazo: invoice_provider_unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invoice_provider_unavailable": { "summary": "PahFacturar no respondió. Intente de nuevo.", "value": { "error": { "code": "invoice_provider_unavailable", "message": "PahFacturar no respondió. Intente de nuevo." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "503": { "description": "Rechazo: upstream_configuration_invalid.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "upstream_configuration_invalid": { "summary": "La conexión con el servicio externo no está configurada para este entorno.", "value": { "error": { "code": "upstream_configuration_invalid", "message": "La conexión con el servicio externo no está configurada para este entorno." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/health-invoices/{invoiceId}/credit-note-context": { "get": { "operationId": "creditNotes.getContext", "tags": [ "Notas crédito" ], "summary": "Contexto para emitir una nota crédito", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "invoiceId", "in": "path" } ], "responses": { "200": { "description": "Factura, saldo, pacientes y resoluciones vigentes.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteContext" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/credit-notes/{creditNoteId}": { "get": { "operationId": "creditNotes.get", "tags": [ "Notas crédito" ], "summary": "Consultar una nota crédito", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "creditNoteId", "in": "path" } ], "responses": { "200": { "description": "Nota con su historial.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/credit-notes/{creditNoteId}/emissions": { "post": { "operationId": "creditNotes.retryEmission", "tags": [ "Notas crédito" ], "summary": "Reintentar la emisión de la nota", "description": "Requiere una membresía activa en el espacio de la ruta. Requiere Idempotency-Key. PAT: requiere el permiso send y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "external", "x-ripscloud-idempotency": "required", "x-ripscloud-pat-scope": "send", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "creditNoteId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": true, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Resultado terminal registrado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" } } } }, "202": { "description": "Resultado incierto o en curso.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, invoice_provider_not_configured, invoice_provider_company_mismatch, resolution_unavailable, provider_dispatch_in_progress, provider_outcome_unknown, health_document_not_emittable, authorization_changed, resource_archived, credit_balance_exceeded.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invoice_provider_not_configured": { "summary": "Configure el token, el equipo y la empresa de PahFacturar.", "value": { "error": { "code": "invoice_provider_not_configured", "message": "Configure el token, el equipo y la empresa de PahFacturar." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "422": { "description": "Rechazo: health_document_invalid.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "health_document_invalid": { "summary": "El contenido del documento de salud no cumple las reglas de emisión.", "value": { "error": { "code": "health_document_invalid", "message": "El contenido del documento de salud no cumple las reglas de emisión." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "502": { "description": "Rechazo: invoice_provider_unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invoice_provider_unavailable": { "summary": "PahFacturar no respondió. Intente de nuevo.", "value": { "error": { "code": "invoice_provider_unavailable", "message": "PahFacturar no respondió. Intente de nuevo." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "503": { "description": "Rechazo: upstream_configuration_invalid.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "upstream_configuration_invalid": { "summary": "La conexión con el servicio externo no está configurada para este entorno.", "value": { "error": { "code": "upstream_configuration_invalid", "message": "La conexión con el servicio externo no está configurada para este entorno." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/credit-notes/{creditNoteId}/reconciliations": { "post": { "operationId": "creditNotes.reconcile", "tags": [ "Notas crédito" ], "summary": "Conciliar una emisión incierta", "description": "Requiere una membresía activa en el espacio de la ruta. Requiere Idempotency-Key. PAT: requiere el permiso send y acceso al espacio de la ruta, cuando exista. Límite del cuerpo HTTP: 1000000 bytes, antes de interpretar el contenido.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "external", "x-ripscloud-idempotency": "required", "x-ripscloud-pat-scope": "send", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "creditNoteId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": true, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconcileHealthDocumentInput" }, "examples": { "knownProviderId": { "summary": "Conciliar con el UUID ya conocido del proveedor", "value": { "providerDocumentId": "11111111-1111-4111-8111-111111111111" } } } } } }, "responses": { "200": { "description": "Emisión conciliada.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" } } } }, "400": { "description": "Rechazo: invalid_json, duplicate_key, json_syntax, json_depth, json_type, numeric_value_loss, numeric_overflow, conflicting_alias, invalid_request, server_owned_field, invalid_query, invalid_path.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_json": { "summary": "El cuerpo no es JSON válido.", "value": { "error": { "code": "invalid_json", "message": "El cuerpo no es JSON válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_key": { "summary": "El cuerpo repite una clave JSON.", "value": { "error": { "code": "duplicate_key", "message": "El cuerpo repite una clave JSON." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "json_syntax": { "summary": "El JSON tiene un error de sintaxis.", "value": { "error": { "code": "json_syntax", "message": "El JSON tiene un error de sintaxis." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, reconciliation_not_applicable, invoice_provider_not_configured, authorization_changed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "reconciliation_not_applicable": { "summary": "Solo un resultado incierto se puede conciliar.", "value": { "error": { "code": "reconciliation_not_applicable", "message": "Solo un resultado incierto se puede conciliar." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: request_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "request_too_large": { "summary": "El cuerpo supera el tamaño permitido.", "value": { "error": { "code": "request_too_large", "message": "El cuerpo supera el tamaño permitido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "415": { "description": "Rechazo: unsupported_media_type.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported_media_type": { "summary": "El tipo de contenido no es compatible con esta operación.", "value": { "error": { "code": "unsupported_media_type", "message": "El tipo de contenido no es compatible con esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "422": { "description": "Rechazo: reconciliation_inconclusive.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "reconciliation_inconclusive": { "summary": "La evidencia no resuelve el resultado. El estado sigue incierto.", "value": { "error": { "code": "reconciliation_inconclusive", "message": "La evidencia no resuelve el resultado. El estado sigue incierto." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "502": { "description": "Rechazo: invoice_provider_unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invoice_provider_unavailable": { "summary": "PahFacturar no respondió. Intente de nuevo.", "value": { "error": { "code": "invoice_provider_unavailable", "message": "PahFacturar no respondió. Intente de nuevo." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/credit-notes/{creditNoteId}/artifacts/{artifact}": { "get": { "operationId": "creditNotes.downloadArtifact", "tags": [ "Notas crédito" ], "summary": "Descargar el XML o PDF de la nota", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso send y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "external", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "send", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "creditNoteId", "in": "path" }, { "schema": { "type": "string", "enum": [ "pdf", "xml", "attached" ] }, "required": true, "name": "artifact", "in": "path" } ], "responses": { "200": { "description": "Artefacto de la nota aceptada.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found, document_not_available.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "document_not_available": { "summary": "El documento solicitado no está disponible.", "value": { "error": { "code": "document_not_available", "message": "El documento solicitado no está disponible." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: authorization_changed, artifact_context_unverified, invoice_provider_not_configured.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "authorization_changed": { "summary": "Los permisos cambiaron durante la operación. No se realizó ningún efecto externo.", "value": { "error": { "code": "authorization_changed", "message": "Los permisos cambiaron durante la operación. No se realizó ningún efecto externo." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "artifact_context_unverified": { "summary": "El artefacto no corresponde al documento aceptado.", "value": { "error": { "code": "artifact_context_unverified", "message": "El artefacto no corresponde al documento aceptado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invoice_provider_not_configured": { "summary": "Configure el token, el equipo y la empresa de PahFacturar.", "value": { "error": { "code": "invoice_provider_not_configured", "message": "Configure el token, el equipo y la empresa de PahFacturar." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "502": { "description": "Rechazo: artifact_download_failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "artifact_download_failed": { "summary": "No fue posible descargar el artefacto del proveedor.", "value": { "error": { "code": "artifact_download_failed", "message": "No fue posible descargar el artefacto del proveedor." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/credit-notes/{creditNoteId}/email": { "post": { "operationId": "creditNotes.sendEmail", "tags": [ "Notas crédito" ], "summary": "Enviar la nota por correo", "description": "El correo se reclama de forma atómica antes del envío. La misma clave y contenido devuelve el resultado confirmado. Si SMTP falla, demora o se pierde la respuesta, email_outcome_unknown bloquea el reenvío automático con esa clave. Verifique la entrega antes de usar una clave nueva para evitar duplicados. Requiere una membresía activa en el espacio de la ruta. Requiere Idempotency-Key. PAT: requiere el permiso send y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "external", "x-ripscloud-idempotency": "required", "x-ripscloud-pat-scope": "send", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "creditNoteId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": true, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Correo enviado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailResult" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found, document_not_available.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "document_not_available": { "summary": "El documento solicitado no está disponible.", "value": { "error": { "code": "document_not_available", "message": "El documento solicitado no está disponible." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: authorization_changed, idempotency_key_reused, idempotency_in_progress, email_disabled, email_outcome_unknown, artifact_context_unverified.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "authorization_changed": { "summary": "Los permisos cambiaron durante la operación. No se realizó ningún efecto externo.", "value": { "error": { "code": "authorization_changed", "message": "Los permisos cambiaron durante la operación. No se realizó ningún efecto externo." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: email_attachment_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "email_attachment_too_large": { "summary": "El adjunto supera el límite de correo.", "value": { "error": { "code": "email_attachment_too_large", "message": "El adjunto supera el límite de correo." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "422": { "description": "Rechazo: recipient_email_missing.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "recipient_email_missing": { "summary": "El cliente no tiene correo registrado.", "value": { "error": { "code": "recipient_email_missing", "message": "El cliente no tiene correo registrado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "502": { "description": "Rechazo: artifact_download_failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "artifact_download_failed": { "summary": "No fue posible descargar el artefacto del proveedor.", "value": { "error": { "code": "artifact_download_failed", "message": "No fue posible descargar el artefacto del proveedor." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "503": { "description": "Rechazo: email_not_configured.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "email_not_configured": { "summary": "El correo saliente no está configurado.", "value": { "error": { "code": "email_not_configured", "message": "El correo saliente no está configurado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/credit-notes/{creditNoteId}/rips-package": { "post": { "operationId": "creditNotes.prepareRipsPackage", "tags": [ "Notas crédito" ], "summary": "Preparar el RIPS de la nota crédito", "description": "Usa la nota aceptada como fuente (nc_parcial o nc_total). El paquete referencia la nota en el sistema de facturación y no guarda el XML. Devuelve el borrador vinculado o crea uno. No envía al Ministerio. Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. PAT: requiere el permiso send y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "external", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "send", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "creditNoteId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Paquete vinculado existente.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "ETag": { "$ref": "#/components/headers/ResourceRevision" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RipsPackage" } } } }, "201": { "description": "Paquete creado desde la nota.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "ETag": { "$ref": "#/components/headers/ResourceRevision" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RipsPackage" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found, document_not_available.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "document_not_available": { "summary": "El documento solicitado no está disponible.", "value": { "error": { "code": "document_not_available", "message": "El documento solicitado no está disponible." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: authorization_changed, idempotency_key_reused, idempotency_in_progress, artifact_context_unverified.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "authorization_changed": { "summary": "Los permisos cambiaron durante la operación. No se realizó ningún efecto externo.", "value": { "error": { "code": "authorization_changed", "message": "Los permisos cambiaron durante la operación. No se realizó ningún efecto externo." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "422": { "description": "Rechazo: source_invoice_not_accepted, source_rips_missing.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "source_invoice_not_accepted": { "summary": "La factura de origen no tiene CUFE aceptado.", "value": { "error": { "code": "source_invoice_not_accepted", "message": "La factura de origen no tiene CUFE aceptado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "source_rips_missing": { "summary": "La factura de origen no tiene RIPS aceptado o guardado.", "value": { "error": { "code": "source_rips_missing", "message": "La factura de origen no tiene RIPS aceptado o guardado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "502": { "description": "Rechazo: artifact_download_failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "artifact_download_failed": { "summary": "No fue posible descargar el artefacto del proveedor.", "value": { "error": { "code": "artifact_download_failed", "message": "No fue posible descargar el artefacto del proveedor." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/debit-notes": { "get": { "operationId": "debitNotes.list", "tags": [ "Notas débito" ], "summary": "Listar notas débito de salud", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "description": "Página inicial 1 (valor predeterminado).", "example": 1 }, "required": false, "description": "Página inicial 1 (valor predeterminado).", "name": "page", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Registros por página: 100 por defecto, máximo 500.", "example": 100 }, "required": false, "description": "Registros por página: 100 por defecto, máximo 500.", "name": "pageSize", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "required": false, "name": "sortDirection", "in": "query" }, { "schema": { "type": "string", "maxLength": 128 }, "required": false, "name": "clientName", "in": "query" }, { "schema": { "type": "string", "maxLength": 40 }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "maxLength": 40, "description": "Fecha/hora ISO 8601 inclusiva; enviar un valor UTC válido.", "example": "2026-09-01T00:00:00.000Z" }, "required": false, "description": "Fecha/hora ISO 8601 inclusiva; enviar un valor UTC válido.", "name": "createdFrom", "in": "query" }, { "schema": { "type": "string", "maxLength": 40, "description": "Fecha/hora ISO 8601 inclusiva; enviar un valor UTC válido.", "example": "2026-09-30T23:59:59.999Z" }, "required": false, "description": "Fecha/hora ISO 8601 inclusiva; enviar un valor UTC válido.", "name": "createdTo", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "includeArchived", "in": "query" }, { "schema": { "type": "string", "enum": [ "debitNoteNumber", "originalInvoiceNumber", "clientName", "status", "createdAt", "updatedAt", "totalAmount" ] }, "required": false, "name": "sortBy", "in": "query" }, { "schema": { "type": "string", "maxLength": 60 }, "required": false, "name": "debitNoteNumber", "in": "query" }, { "schema": { "type": "string", "maxLength": 60 }, "required": false, "name": "originalInvoiceNumber", "in": "query" } ], "responses": { "200": { "description": "Página de notas.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitNotePage" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } }, "post": { "operationId": "debitNotes.emit", "tags": [ "Notas débito" ], "summary": "Emitir una nota débito de salud por PahFacturar", "description": "Deriva cliente, referencia y campos de salud de la factura aceptada. Exige RIPS adicional explícito, pacientes de la factura y total positivo igual a los servicios adicionales. No aplica un límite de saldo de crédito. Registra la intención antes del efecto y bloquea duplicados o un resultado incierto. Requiere una membresía activa en el espacio de la ruta. Requiere Idempotency-Key. PAT: requiere el permiso send y acceso al espacio de la ruta, cuando exista. Límite del cuerpo HTTP: 26000000 bytes, antes de interpretar el contenido.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "external", "x-ripscloud-idempotency": "required", "x-ripscloud-pat-scope": "send", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": true, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmitDebitNoteInput" }, "examples": { "supplementalServices": { "summary": "Nota débito con servicios adicionales", "description": "Datos sintéticos. Use la factura y la resolución devueltas por debit-note-context; capture los servicios adicionales. El ejemplo no acredita autorización ni aceptación DIAN.", "value": { "invoiceId": "invoice-demo-001", "debitNoteResolutionId": "debit-resolution-demo-001", "discrepancyResponseCode": 3, "discrepancyResponseDescription": "Servicio adicional del mismo paciente (ejemplo sintético)", "debitNotePayload": { "debit_note_lines": [ { "description": "Consulta adicional de ejemplo", "code": "890201", "invoiced_quantity": "1", "price_amount": "100000.00", "line_extension_amount": "100000.00" } ], "legal_monetary_totals": { "line_extension_amount": "100000.00", "tax_exclusive_amount": "100000.00", "tax_inclusive_amount": "100000.00", "payable_amount": "100000.00" } }, "rips": { "numDocumentoIdObligado": "900123456", "numFactura": "SETP990000001", "tipoNota": "ND", "numNota": null, "usuarios": [ { "tipoDocumentoIdentificacion": "CC", "numDocumentoIdentificacion": "1000000002", "tipoUsuario": "01", "fechaNacimiento": "1990-01-01", "codSexo": "F", "codPaisResidencia": "170", "codPaisOrigen": "170", "codMunicipioResidencia": "11001", "codZonaTerritorialResidencia": "01", "incapacidad": "NO", "consecutivo": 1, "servicios": { "consultas": [ { "codPrestador": "110010000101", "fechaInicioAtencion": "2026-09-02 10:00", "numAutorizacion": null, "codConsulta": "890201", "modalidadGrupoServicioTecSal": "01", "grupoServicios": "01", "codServicio": 325, "finalidadTecnologiaSalud": "44", "causaMotivoAtencion": "38", "codDiagnosticoPrincipal": "Z000", "codDiagnosticoRelacionado1": null, "codDiagnosticoRelacionado2": null, "codDiagnosticoRelacionado3": null, "tipoDiagnosticoPrincipal": "01", "tipoDocumentoIdentificacion": "CC", "numDocumentoIdentificacion": "1000000001", "vrServicio": 100000, "conceptoRecaudo": "05", "valorPagoModerador": 0, "numFEVPagoModerador": null, "consecutivo": 1 } ] } } ] } } } } } } }, "responses": { "201": { "description": "Documento aceptado o con rechazo terminal registrado. El CUDE del ejemplo es sintético.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitNote" }, "example": { "id": "debit-note-demo-001", "invoiceId": "invoice-demo-001", "originalInvoiceNumber": "SETP990000001", "clientId": "payer-demo-001", "clientName": "Entidad pagadora de ejemplo", "totalAmount": 100000, "status": "Accepted", "statusMessage": "Ejemplo sintético de nota aceptada", "assignedDebitNoteNumber": "ND990000001", "cude": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "discrepancyResponseCode": 3, "discrepancyResponseDescription": "Servicio adicional del mismo paciente (ejemplo sintético)", "ripsPackageKind": "nd", "isActive": true, "createdAt": "2026-09-02T15:00:00.000Z", "updatedAt": "2026-09-02T15:00:01.000Z", "originalInvoiceCufe": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "dianStatusCode": "00", "dianStatusDescription": "Procesado correctamente (ejemplo)", "submittedByUserId": "user-demo-001", "debitNotePayloadJson": "{\"debit_note_lines\":[{\"description\":\"Consulta adicional de ejemplo\",\"code\":\"890201\",\"invoiced_quantity\":\"1\",\"price_amount\":\"100000.00\",\"line_extension_amount\":\"100000.00\"}],\"legal_monetary_totals\":{\"line_extension_amount\":\"100000.00\",\"tax_exclusive_amount\":\"100000.00\",\"tax_inclusive_amount\":\"100000.00\",\"payable_amount\":\"100000.00\"}}", "workingRipsJson": "{\"numDocumentoIdObligado\":\"900123456\",\"numFactura\":\"SETP990000001\",\"tipoNota\":\"ND\",\"numNota\":\"ND990000001\",\"usuarios\":[{\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000002\",\"tipoUsuario\":\"01\",\"fechaNacimiento\":\"1990-01-01\",\"codSexo\":\"F\",\"codPaisResidencia\":\"170\",\"codPaisOrigen\":\"170\",\"codMunicipioResidencia\":\"11001\",\"codZonaTerritorialResidencia\":\"01\",\"incapacidad\":\"NO\",\"consecutivo\":1,\"servicios\":{\"consultas\":[{\"codPrestador\":\"110010000101\",\"fechaInicioAtencion\":\"2026-09-02 10:00\",\"numAutorizacion\":null,\"codConsulta\":\"890201\",\"modalidadGrupoServicioTecSal\":\"01\",\"grupoServicios\":\"01\",\"codServicio\":325,\"finalidadTecnologiaSalud\":\"44\",\"causaMotivoAtencion\":\"38\",\"codDiagnosticoPrincipal\":\"Z000\",\"codDiagnosticoRelacionado1\":null,\"codDiagnosticoRelacionado2\":null,\"codDiagnosticoRelacionado3\":null,\"tipoDiagnosticoPrincipal\":\"01\",\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000001\",\"vrServicio\":100000,\"conceptoRecaudo\":\"05\",\"valorPagoModerador\":0,\"numFEVPagoModerador\":null,\"consecutivo\":1}]}}]}", "dispatchHistory": [ { "attemptedAt": "2026-09-02T15:00:00.000Z", "succeeded": true, "errorMessage": null, "requestPayload": "{\"debit_note_lines\":[{\"description\":\"Consulta adicional de ejemplo\",\"code\":\"890201\",\"invoiced_quantity\":\"1\",\"price_amount\":\"100000.00\",\"line_extension_amount\":\"100000.00\"}],\"legal_monetary_totals\":{\"line_extension_amount\":\"100000.00\",\"tax_exclusive_amount\":\"100000.00\",\"tax_inclusive_amount\":\"100000.00\",\"payable_amount\":\"100000.00\"}}", "responsePayload": "{\"status\":\"accepted\",\"cude\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}", "source": "pahfacturar" } ], "ripsPackages": [], "documentAvailability": [ { "documentType": "attached", "isSupported": true, "canDownload": true }, { "documentType": "pdf", "isSupported": false, "canDownload": false } ] } } } }, "202": { "description": "Emisión registrada con resultado incierto o en curso.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitNote" }, "example": { "id": "debit-note-demo-001", "invoiceId": "invoice-demo-001", "originalInvoiceNumber": "SETP990000001", "clientId": "payer-demo-001", "clientName": "Entidad pagadora de ejemplo", "totalAmount": 100000, "status": "Unknown", "statusMessage": "No se conoce el resultado de DIAN", "assignedDebitNoteNumber": "ND990000001", "cude": null, "discrepancyResponseCode": 3, "discrepancyResponseDescription": "Servicio adicional del mismo paciente (ejemplo sintético)", "ripsPackageKind": "nd", "isActive": true, "createdAt": "2026-09-02T15:00:00.000Z", "updatedAt": "2026-09-02T15:00:01.000Z", "originalInvoiceCufe": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "dianStatusCode": null, "dianStatusDescription": null, "submittedByUserId": "user-demo-001", "debitNotePayloadJson": "{\"debit_note_lines\":[{\"description\":\"Consulta adicional de ejemplo\",\"code\":\"890201\",\"invoiced_quantity\":\"1\",\"price_amount\":\"100000.00\",\"line_extension_amount\":\"100000.00\"}],\"legal_monetary_totals\":{\"line_extension_amount\":\"100000.00\",\"tax_exclusive_amount\":\"100000.00\",\"tax_inclusive_amount\":\"100000.00\",\"payable_amount\":\"100000.00\"}}", "workingRipsJson": "{\"numDocumentoIdObligado\":\"900123456\",\"numFactura\":\"SETP990000001\",\"tipoNota\":\"ND\",\"numNota\":\"ND990000001\",\"usuarios\":[{\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000002\",\"tipoUsuario\":\"01\",\"fechaNacimiento\":\"1990-01-01\",\"codSexo\":\"F\",\"codPaisResidencia\":\"170\",\"codPaisOrigen\":\"170\",\"codMunicipioResidencia\":\"11001\",\"codZonaTerritorialResidencia\":\"01\",\"incapacidad\":\"NO\",\"consecutivo\":1,\"servicios\":{\"consultas\":[{\"codPrestador\":\"110010000101\",\"fechaInicioAtencion\":\"2026-09-02 10:00\",\"numAutorizacion\":null,\"codConsulta\":\"890201\",\"modalidadGrupoServicioTecSal\":\"01\",\"grupoServicios\":\"01\",\"codServicio\":325,\"finalidadTecnologiaSalud\":\"44\",\"causaMotivoAtencion\":\"38\",\"codDiagnosticoPrincipal\":\"Z000\",\"codDiagnosticoRelacionado1\":null,\"codDiagnosticoRelacionado2\":null,\"codDiagnosticoRelacionado3\":null,\"tipoDiagnosticoPrincipal\":\"01\",\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000001\",\"vrServicio\":100000,\"conceptoRecaudo\":\"05\",\"valorPagoModerador\":0,\"numFEVPagoModerador\":null,\"consecutivo\":1}]}}]}", "dispatchHistory": [ { "attemptedAt": "2026-09-02T15:00:00.000Z", "succeeded": true, "errorMessage": null, "requestPayload": "{\"debit_note_lines\":[{\"description\":\"Consulta adicional de ejemplo\",\"code\":\"890201\",\"invoiced_quantity\":\"1\",\"price_amount\":\"100000.00\",\"line_extension_amount\":\"100000.00\"}],\"legal_monetary_totals\":{\"line_extension_amount\":\"100000.00\",\"tax_exclusive_amount\":\"100000.00\",\"tax_inclusive_amount\":\"100000.00\",\"payable_amount\":\"100000.00\"}}", "responsePayload": "{\"status\":\"accepted\",\"cude\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}", "source": "pahfacturar" } ], "ripsPackages": [], "documentAvailability": [] } } } }, "400": { "description": "Rechazo: invalid_json, duplicate_key, json_syntax, json_depth, json_type, numeric_value_loss, numeric_overflow, conflicting_alias, invalid_request, server_owned_field, invalid_query, invalid_path.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_json": { "summary": "El cuerpo no es JSON válido.", "value": { "error": { "code": "invalid_json", "message": "El cuerpo no es JSON válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_key": { "summary": "El cuerpo repite una clave JSON.", "value": { "error": { "code": "duplicate_key", "message": "El cuerpo repite una clave JSON." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "json_syntax": { "summary": "El JSON tiene un error de sintaxis.", "value": { "error": { "code": "json_syntax", "message": "El JSON tiene un error de sintaxis." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, invoice_provider_not_configured, invoice_provider_company_mismatch, resolution_unavailable, provider_dispatch_in_progress, provider_outcome_unknown, health_document_not_emittable, authorization_changed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invoice_provider_not_configured": { "summary": "Configure el token, el equipo y la empresa de PahFacturar.", "value": { "error": { "code": "invoice_provider_not_configured", "message": "Configure el token, el equipo y la empresa de PahFacturar." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: request_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "request_too_large": { "summary": "El cuerpo supera el tamaño permitido.", "value": { "error": { "code": "request_too_large", "message": "El cuerpo supera el tamaño permitido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "415": { "description": "Rechazo: unsupported_media_type.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported_media_type": { "summary": "El tipo de contenido no es compatible con esta operación.", "value": { "error": { "code": "unsupported_media_type", "message": "El tipo de contenido no es compatible con esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "422": { "description": "Rechazo: health_document_invalid, source_invoice_not_accepted, source_customer_missing, source_rips_missing, debit_note_rips_required, debit_note_rips_invalid, debit_note_patient_mismatch.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "health_document_invalid": { "summary": "El contenido del documento de salud no cumple las reglas de emisión.", "value": { "error": { "code": "health_document_invalid", "message": "El contenido del documento de salud no cumple las reglas de emisión." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "source_invoice_not_accepted": { "summary": "La factura de origen no tiene CUFE aceptado.", "value": { "error": { "code": "source_invoice_not_accepted", "message": "La factura de origen no tiene CUFE aceptado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "source_customer_missing": { "summary": "La factura de origen no identifica al cliente.", "value": { "error": { "code": "source_customer_missing", "message": "La factura de origen no identifica al cliente." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "502": { "description": "Rechazo: invoice_provider_unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invoice_provider_unavailable": { "summary": "PahFacturar no respondió. Intente de nuevo.", "value": { "error": { "code": "invoice_provider_unavailable", "message": "PahFacturar no respondió. Intente de nuevo." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "503": { "description": "Rechazo: upstream_configuration_invalid.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "upstream_configuration_invalid": { "summary": "La conexión con el servicio externo no está configurada para este entorno.", "value": { "error": { "code": "upstream_configuration_invalid", "message": "La conexión con el servicio externo no está configurada para este entorno." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/health-invoices/{invoiceId}/debit-note-context": { "get": { "operationId": "debitNotes.getContext", "tags": [ "Notas débito" ], "summary": "Contexto para emitir una nota débito", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "invoiceId", "in": "path" } ], "responses": { "200": { "description": "Factura, pacientes de referencia y resoluciones vigentes, sin saldo de crédito.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitNoteContext" }, "example": { "invoice": { "id": "invoice-demo-001", "invoiceNumber": "SETP990000001", "cufe": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "issueDate": "2026-09-01T15:00:00.000Z", "totalAmount": 100000, "clientName": "Entidad pagadora de ejemplo", "clientId": "payer-demo-001", "locationId": null }, "patients": [ { "consecutivo": 1, "tipoDocumentoIdentificacion": "CC", "numDocumentoIdentificacion": "1000000002", "patientName": "Paciente de ejemplo", "totalAmount": 100000, "services": [ { "category": "consultas", "consecutivo": 1, "description": "Consulta original de referencia", "amount": 100000, "serviceDate": "2026-09-01 10:00" } ] } ], "rips": { "numDocumentoIdObligado": "900123456", "numFactura": "SETP990000001", "tipoNota": "ND", "numNota": null, "usuarios": [ { "tipoDocumentoIdentificacion": "CC", "numDocumentoIdentificacion": "1000000002", "tipoUsuario": "01", "fechaNacimiento": "1990-01-01", "codSexo": "F", "codPaisResidencia": "170", "codPaisOrigen": "170", "codMunicipioResidencia": "11001", "codZonaTerritorialResidencia": "01", "incapacidad": "NO", "consecutivo": 1, "servicios": { "consultas": [], "procedimientos": [], "urgencias": [], "hospitalizacion": [], "recienNacidos": [], "medicamentos": [], "otrosServicios": [] } } ] }, "availableResolutions": [ { "id": "debit-resolution-demo-001", "resolutionNumber": "18760000001", "prefix": "ND", "nextNumber": 990000001, "fromNumber": 990000001, "toNumber": 990010000, "validFrom": "2026-01-01", "validTo": "2027-12-31", "environment": 2, "hasTechnicalKey": true, "isActive": true, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } ], "canCreateDebitNote": true, "validationMessage": null } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/debit-notes/{debitNoteId}": { "get": { "operationId": "debitNotes.get", "tags": [ "Notas débito" ], "summary": "Consultar una nota débito", "description": "Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso read y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "read", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "read", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "debitNoteId", "in": "path" } ], "responses": { "200": { "description": "Nota con su historial.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitNote" }, "example": { "id": "debit-note-demo-001", "invoiceId": "invoice-demo-001", "originalInvoiceNumber": "SETP990000001", "clientId": "payer-demo-001", "clientName": "Entidad pagadora de ejemplo", "totalAmount": 100000, "status": "Accepted", "statusMessage": "Ejemplo sintético de nota aceptada", "assignedDebitNoteNumber": "ND990000001", "cude": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "discrepancyResponseCode": 3, "discrepancyResponseDescription": "Servicio adicional del mismo paciente (ejemplo sintético)", "ripsPackageKind": "nd", "isActive": true, "createdAt": "2026-09-02T15:00:00.000Z", "updatedAt": "2026-09-02T15:00:01.000Z", "originalInvoiceCufe": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "dianStatusCode": "00", "dianStatusDescription": "Procesado correctamente (ejemplo)", "submittedByUserId": "user-demo-001", "debitNotePayloadJson": "{\"debit_note_lines\":[{\"description\":\"Consulta adicional de ejemplo\",\"code\":\"890201\",\"invoiced_quantity\":\"1\",\"price_amount\":\"100000.00\",\"line_extension_amount\":\"100000.00\"}],\"legal_monetary_totals\":{\"line_extension_amount\":\"100000.00\",\"tax_exclusive_amount\":\"100000.00\",\"tax_inclusive_amount\":\"100000.00\",\"payable_amount\":\"100000.00\"}}", "workingRipsJson": "{\"numDocumentoIdObligado\":\"900123456\",\"numFactura\":\"SETP990000001\",\"tipoNota\":\"ND\",\"numNota\":\"ND990000001\",\"usuarios\":[{\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000002\",\"tipoUsuario\":\"01\",\"fechaNacimiento\":\"1990-01-01\",\"codSexo\":\"F\",\"codPaisResidencia\":\"170\",\"codPaisOrigen\":\"170\",\"codMunicipioResidencia\":\"11001\",\"codZonaTerritorialResidencia\":\"01\",\"incapacidad\":\"NO\",\"consecutivo\":1,\"servicios\":{\"consultas\":[{\"codPrestador\":\"110010000101\",\"fechaInicioAtencion\":\"2026-09-02 10:00\",\"numAutorizacion\":null,\"codConsulta\":\"890201\",\"modalidadGrupoServicioTecSal\":\"01\",\"grupoServicios\":\"01\",\"codServicio\":325,\"finalidadTecnologiaSalud\":\"44\",\"causaMotivoAtencion\":\"38\",\"codDiagnosticoPrincipal\":\"Z000\",\"codDiagnosticoRelacionado1\":null,\"codDiagnosticoRelacionado2\":null,\"codDiagnosticoRelacionado3\":null,\"tipoDiagnosticoPrincipal\":\"01\",\"tipoDocumentoIdentificacion\":\"CC\",\"numDocumentoIdentificacion\":\"1000000001\",\"vrServicio\":100000,\"conceptoRecaudo\":\"05\",\"valorPagoModerador\":0,\"numFEVPagoModerador\":null,\"consecutivo\":1}]}}]}", "dispatchHistory": [ { "attemptedAt": "2026-09-02T15:00:00.000Z", "succeeded": true, "errorMessage": null, "requestPayload": "{\"debit_note_lines\":[{\"description\":\"Consulta adicional de ejemplo\",\"code\":\"890201\",\"invoiced_quantity\":\"1\",\"price_amount\":\"100000.00\",\"line_extension_amount\":\"100000.00\"}],\"legal_monetary_totals\":{\"line_extension_amount\":\"100000.00\",\"tax_exclusive_amount\":\"100000.00\",\"tax_inclusive_amount\":\"100000.00\",\"payable_amount\":\"100000.00\"}}", "responsePayload": "{\"status\":\"accepted\",\"cude\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}", "source": "pahfacturar" } ], "ripsPackages": [], "documentAvailability": [ { "documentType": "attached", "isSupported": true, "canDownload": true }, { "documentType": "pdf", "isSupported": false, "canDownload": false } ] } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/debit-notes/{debitNoteId}/emissions": { "post": { "operationId": "debitNotes.retryEmission", "tags": [ "Notas débito" ], "summary": "Reintentar la emisión de la nota", "description": "Solo para un resultado que permite reintento; un resultado Unknown requiere conciliación. Conserva los servicios adicionales y la referencia originales. No copia servicios de la factura. Requiere una membresía activa en el espacio de la ruta. Requiere Idempotency-Key. PAT: requiere el permiso send y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "external", "x-ripscloud-idempotency": "required", "x-ripscloud-pat-scope": "send", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "debitNoteId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": true, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Resultado terminal registrado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitNote" } } } }, "202": { "description": "Resultado incierto o en curso.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitNote" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, invoice_provider_not_configured, invoice_provider_company_mismatch, resolution_unavailable, provider_dispatch_in_progress, provider_outcome_unknown, health_document_not_emittable, authorization_changed, resource_archived.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invoice_provider_not_configured": { "summary": "Configure el token, el equipo y la empresa de PahFacturar.", "value": { "error": { "code": "invoice_provider_not_configured", "message": "Configure el token, el equipo y la empresa de PahFacturar." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "422": { "description": "Rechazo: health_document_invalid, debit_note_rips_required, debit_note_rips_invalid, debit_note_patient_mismatch.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "health_document_invalid": { "summary": "El contenido del documento de salud no cumple las reglas de emisión.", "value": { "error": { "code": "health_document_invalid", "message": "El contenido del documento de salud no cumple las reglas de emisión." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "debit_note_rips_required": { "summary": "La nota débito requiere los RIPS de los servicios adicionales.", "value": { "error": { "code": "debit_note_rips_required", "message": "La nota débito requiere los RIPS de los servicios adicionales." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "debit_note_rips_invalid": { "summary": "Los RIPS adicionales no cumplen las reglas de la nota débito.", "value": { "error": { "code": "debit_note_rips_invalid", "message": "Los RIPS adicionales no cumplen las reglas de la nota débito." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "502": { "description": "Rechazo: invoice_provider_unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invoice_provider_unavailable": { "summary": "PahFacturar no respondió. Intente de nuevo.", "value": { "error": { "code": "invoice_provider_unavailable", "message": "PahFacturar no respondió. Intente de nuevo." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "503": { "description": "Rechazo: upstream_configuration_invalid.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "upstream_configuration_invalid": { "summary": "La conexión con el servicio externo no está configurada para este entorno.", "value": { "error": { "code": "upstream_configuration_invalid", "message": "La conexión con el servicio externo no está configurada para este entorno." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/debit-notes/{debitNoteId}/reconciliations": { "post": { "operationId": "debitNotes.reconcile", "tags": [ "Notas débito" ], "summary": "Conciliar una emisión incierta", "description": "Comprueba un UUID conocido de PahFacturar contra la intención guardada. No busca un UUID perdido ni emite otra nota. Si no conoce el UUID, conserve Unknown y solicite recuperación. Requiere una membresía activa en el espacio de la ruta. Requiere Idempotency-Key. PAT: requiere el permiso send y acceso al espacio de la ruta, cuando exista. Límite del cuerpo HTTP: 1000000 bytes, antes de interpretar el contenido.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "external", "x-ripscloud-idempotency": "required", "x-ripscloud-pat-scope": "send", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "debitNoteId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": true, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconcileHealthDocumentInput" }, "examples": { "knownProviderId": { "summary": "Conciliar con el UUID ya conocido del proveedor", "value": { "providerDocumentId": "11111111-1111-4111-8111-111111111111" } } } } } }, "responses": { "200": { "description": "Emisión conciliada.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitNote" } } } }, "400": { "description": "Rechazo: invalid_json, duplicate_key, json_syntax, json_depth, json_type, numeric_value_loss, numeric_overflow, conflicting_alias, invalid_request, server_owned_field, invalid_query, invalid_path.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_json": { "summary": "El cuerpo no es JSON válido.", "value": { "error": { "code": "invalid_json", "message": "El cuerpo no es JSON válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "duplicate_key": { "summary": "El cuerpo repite una clave JSON.", "value": { "error": { "code": "duplicate_key", "message": "El cuerpo repite una clave JSON." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "json_syntax": { "summary": "El JSON tiene un error de sintaxis.", "value": { "error": { "code": "json_syntax", "message": "El JSON tiene un error de sintaxis." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: idempotency_key_reused, idempotency_in_progress, reconciliation_not_applicable, invoice_provider_not_configured, authorization_changed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "reconciliation_not_applicable": { "summary": "Solo un resultado incierto se puede conciliar.", "value": { "error": { "code": "reconciliation_not_applicable", "message": "Solo un resultado incierto se puede conciliar." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: request_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "request_too_large": { "summary": "El cuerpo supera el tamaño permitido.", "value": { "error": { "code": "request_too_large", "message": "El cuerpo supera el tamaño permitido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "415": { "description": "Rechazo: unsupported_media_type.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported_media_type": { "summary": "El tipo de contenido no es compatible con esta operación.", "value": { "error": { "code": "unsupported_media_type", "message": "El tipo de contenido no es compatible con esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "422": { "description": "Rechazo: reconciliation_inconclusive.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "reconciliation_inconclusive": { "summary": "La evidencia no resuelve el resultado. El estado sigue incierto.", "value": { "error": { "code": "reconciliation_inconclusive", "message": "La evidencia no resuelve el resultado. El estado sigue incierto." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "502": { "description": "Rechazo: invoice_provider_unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invoice_provider_unavailable": { "summary": "PahFacturar no respondió. Intente de nuevo.", "value": { "error": { "code": "invoice_provider_unavailable", "message": "PahFacturar no respondió. Intente de nuevo." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/debit-notes/{debitNoteId}/artifacts/{artifact}": { "get": { "operationId": "debitNotes.downloadArtifact", "tags": [ "Notas débito" ], "summary": "Descargar XML firmado o AttachedDocument de la nota", "description": "Use xml o attached. PahFacturar no publica un PDF independiente para notas; artifact=pdf devuelve document_not_available. Requiere permiso PAT send por el acceso al proveedor. Requiere una membresía activa en el espacio de la ruta. PAT: requiere el permiso send y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "external", "x-ripscloud-idempotency": "none", "x-ripscloud-pat-scope": "send", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "debitNoteId", "in": "path" }, { "schema": { "type": "string", "enum": [ "pdf", "xml", "attached" ] }, "required": true, "name": "artifact", "in": "path" } ], "responses": { "200": { "description": "Artefacto de la nota aceptada.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found, document_not_available.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "document_not_available": { "summary": "El documento solicitado no está disponible.", "value": { "error": { "code": "document_not_available", "message": "El documento solicitado no está disponible." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: authorization_changed, artifact_context_unverified, invoice_provider_not_configured.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "authorization_changed": { "summary": "Los permisos cambiaron durante la operación. No se realizó ningún efecto externo.", "value": { "error": { "code": "authorization_changed", "message": "Los permisos cambiaron durante la operación. No se realizó ningún efecto externo." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "artifact_context_unverified": { "summary": "El artefacto no corresponde al documento aceptado.", "value": { "error": { "code": "artifact_context_unverified", "message": "El artefacto no corresponde al documento aceptado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invoice_provider_not_configured": { "summary": "Configure el token, el equipo y la empresa de PahFacturar.", "value": { "error": { "code": "invoice_provider_not_configured", "message": "Configure el token, el equipo y la empresa de PahFacturar." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "502": { "description": "Rechazo: artifact_download_failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "artifact_download_failed": { "summary": "No fue posible descargar el artefacto del proveedor.", "value": { "error": { "code": "artifact_download_failed", "message": "No fue posible descargar el artefacto del proveedor." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/debit-notes/{debitNoteId}/email": { "post": { "operationId": "debitNotes.sendEmail", "tags": [ "Notas débito" ], "summary": "Enviar la nota por correo", "description": "El correo se reclama de forma atómica antes del envío. La misma clave y contenido devuelve el resultado confirmado. Si SMTP falla, demora o se pierde la respuesta, email_outcome_unknown bloquea el reenvío automático con esa clave. Verifique la entrega antes de usar una clave nueva para evitar duplicados. Requiere una membresía activa en el espacio de la ruta. Requiere Idempotency-Key. PAT: requiere el permiso send y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "external", "x-ripscloud-idempotency": "required", "x-ripscloud-pat-scope": "send", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "debitNoteId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": true, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Correo enviado.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailResult" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found, document_not_available.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "document_not_available": { "summary": "El documento solicitado no está disponible.", "value": { "error": { "code": "document_not_available", "message": "El documento solicitado no está disponible." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: authorization_changed, idempotency_key_reused, idempotency_in_progress, email_disabled, email_outcome_unknown, artifact_context_unverified.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "authorization_changed": { "summary": "Los permisos cambiaron durante la operación. No se realizó ningún efecto externo.", "value": { "error": { "code": "authorization_changed", "message": "Los permisos cambiaron durante la operación. No se realizó ningún efecto externo." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "413": { "description": "Rechazo: email_attachment_too_large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "email_attachment_too_large": { "summary": "El adjunto supera el límite de correo.", "value": { "error": { "code": "email_attachment_too_large", "message": "El adjunto supera el límite de correo." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "422": { "description": "Rechazo: recipient_email_missing.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "recipient_email_missing": { "summary": "El cliente no tiene correo registrado.", "value": { "error": { "code": "recipient_email_missing", "message": "El cliente no tiene correo registrado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "502": { "description": "Rechazo: artifact_download_failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "artifact_download_failed": { "summary": "No fue posible descargar el artefacto del proveedor.", "value": { "error": { "code": "artifact_download_failed", "message": "No fue posible descargar el artefacto del proveedor." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "503": { "description": "Rechazo: email_not_configured.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "email_not_configured": { "summary": "El correo saliente no está configurado.", "value": { "error": { "code": "email_not_configured", "message": "El correo saliente no está configurado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } }, "/api/v1/workspaces/{workspaceId}/debit-notes/{debitNoteId}/rips-package": { "post": { "operationId": "debitNotes.prepareRipsPackage", "tags": [ "Notas débito" ], "summary": "Preparar el RIPS de la nota débito", "description": "Usa la nota débito aceptada y el RIPS adicional guardado para crear un paquete nd. El servidor fija numFactura de la factura original, tipoNota=ND y numNota de la nota emitida. El paquete referencia la nota en el sistema de facturación y no guarda el XML. Devuelve el borrador vinculado o crea uno. No envía al Ministerio. Requiere una membresía activa en el espacio de la ruta. Acepta Idempotency-Key. PAT: requiere el permiso send y acceso al espacio de la ruta, cuando exista.", "security": [ { "BearerAuth": [] } ], "x-ripscloud-auth": "member", "x-ripscloud-effect": "external", "x-ripscloud-idempotency": "optional", "x-ripscloud-pat-scope": "send", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Identificador opaco." }, "required": true, "description": "Identificador opaco.", "name": "debitNoteId", "in": "path" }, { "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "example": "01J9Z5V4V8M2Q7K3B6N1X0P4R2" }, "required": false, "description": "Clave única por intención. Se comprueba en el ámbito de la operación y espacio, y el digest incluye actor, parámetros y cuerpo. Reintente con la misma clave y el mismo contenido; con rawBody conserve los bytes exactos. Contenido distinto produce idempotency_key_reused. No reutilice claves entre intenciones ni suponga que caducan.", "name": "idempotency-key", "in": "header" } ], "responses": { "200": { "description": "Paquete vinculado existente.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "ETag": { "$ref": "#/components/headers/ResourceRevision" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RipsPackage" } } } }, "201": { "description": "Paquete creado desde la nota.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "ETag": { "$ref": "#/components/headers/ResourceRevision" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RipsPackage" } } } }, "400": { "description": "Rechazo: invalid_query, invalid_path, invalid_request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_query": { "summary": "Los parámetros de consulta no cumplen el contrato.", "value": { "error": { "code": "invalid_query", "message": "Los parámetros de consulta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_path": { "summary": "Los parámetros de la ruta no cumplen el contrato.", "value": { "error": { "code": "invalid_path", "message": "Los parámetros de la ruta no cumplen el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "invalid_request": { "summary": "La solicitud no cumple el contrato.", "value": { "error": { "code": "invalid_request", "message": "La solicitud no cumple el contrato." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "description": "Rechazo: unauthenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "summary": "Inicie sesión con un token de usuario válido.", "value": { "error": { "code": "unauthenticated", "message": "Inicie sesión con un token de usuario válido." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "403": { "description": "Rechazo: account_disabled, phone_identity_retired, personal_access_token_scope_required, personal_access_token_workspace_forbidden, personal_access_token_not_allowed, workspace_membership_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "account_disabled": { "summary": "La cuenta está deshabilitada.", "value": { "error": { "code": "account_disabled", "message": "La cuenta está deshabilitada." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "phone_identity_retired": { "summary": "El celular de acceso cambió. Inicie sesión con el celular vigente.", "value": { "error": { "code": "phone_identity_retired", "message": "El celular de acceso cambió. Inicie sesión con el celular vigente." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "personal_access_token_scope_required": { "summary": "El token personal no tiene el permiso requerido por esta operación.", "value": { "error": { "code": "personal_access_token_scope_required", "message": "El token personal no tiene el permiso requerido por esta operación." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "404": { "description": "Rechazo: workspace_not_found, not_found, document_not_available.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "workspace_not_found": { "summary": "El espacio no existe o está archivado.", "value": { "error": { "code": "workspace_not_found", "message": "El espacio no existe o está archivado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "not_found": { "summary": "El recurso no existe en este espacio.", "value": { "error": { "code": "not_found", "message": "El recurso no existe en este espacio." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "document_not_available": { "summary": "El documento solicitado no está disponible.", "value": { "error": { "code": "document_not_available", "message": "El documento solicitado no está disponible." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "409": { "description": "Rechazo: authorization_changed, idempotency_key_reused, idempotency_in_progress, artifact_context_unverified.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "authorization_changed": { "summary": "Los permisos cambiaron durante la operación. No se realizó ningún efecto externo.", "value": { "error": { "code": "authorization_changed", "message": "Los permisos cambiaron durante la operación. No se realizó ningún efecto externo." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_key_reused": { "summary": "La clave de idempotencia ya se usó con otro contenido.", "value": { "error": { "code": "idempotency_key_reused", "message": "La clave de idempotencia ya se usó con otro contenido." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_in_progress": { "summary": "Una solicitud con la misma clave está en curso.", "value": { "error": { "code": "idempotency_in_progress", "message": "Una solicitud con la misma clave está en curso." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "422": { "description": "Rechazo: source_invoice_not_accepted, source_rips_missing.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "source_invoice_not_accepted": { "summary": "La factura de origen no tiene CUFE aceptado.", "value": { "error": { "code": "source_invoice_not_accepted", "message": "La factura de origen no tiene CUFE aceptado." }, "requestId": "11111111-1111-4111-8111-111111111111" } }, "source_rips_missing": { "summary": "La factura de origen no tiene RIPS aceptado o guardado.", "value": { "error": { "code": "source_rips_missing", "message": "La factura de origen no tiene RIPS aceptado o guardado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "428": { "description": "Rechazo: idempotency_key_required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_required": { "summary": "La operación requiere el encabezado Idempotency-Key.", "value": { "error": { "code": "idempotency_key_required", "message": "La operación requiere el encabezado Idempotency-Key." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "500": { "description": "Rechazo: internal_error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal_error": { "summary": "Error interno. Use el identificador de solicitud para consultar el resultado.", "value": { "error": { "code": "internal_error", "message": "Error interno. Use el identificador de solicitud para consultar el resultado." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "502": { "description": "Rechazo: artifact_download_failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "X-Correlation-ID": { "$ref": "#/components/headers/CorrelationId" }, "X-Operation-ID": { "$ref": "#/components/headers/OperationId" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "artifact_download_failed": { "summary": "No fue posible descargar el artefacto del proveedor.", "value": { "error": { "code": "artifact_download_failed", "message": "No fue posible descargar el artefacto del proveedor." }, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } } } } } }, "webhooks": {} }