{"openapi":"3.0.0","info":{"title":"IDDrive API","version":"1.0.0","description":"IDDrive is a comprehensive driver and vehicle licensing platform integrating OTP authentication, KYC verification via Kyciris, subscription management, and company vehicle management. Provides endpoints for driver identity verification, company license management, vehicle documentation, and subscription lifecycle management.","contact":{"name":"IDDrive Team","email":"support@iddrive.ao"},"license":{"name":"Proprietary","url":"https://iddrive.ao/license"}},"servers":[{"url":"/api","description":"API Server"}],"security":[{"apiKeyAuth":[]}],"components":{"schemas":{"Error":{"type":"object","description":"Standard API error response","properties":{"error":{"type":"string","description":"Error message","example":"Invalid data"},"issues":{"type":"array","description":"Validation error details","items":{"type":"object","properties":{"message":{"type":"string"},"path":{"type":"array","items":{"type":"string"}}}}}},"required":["error"]},"SendOTPRequest":{"type":"object","required":["phoneNumber"],"description":"Send OTP via SMS request","properties":{"phoneNumber":{"type":"string","minLength":9,"maxLength":15,"example":"244923456789","pattern":"^\\d+$","description":"Phone number (9-15 digits, international or local format)"}}},"SendOTPResponse":{"type":"object","description":"OTP sent successfully response","properties":{"message":{"type":"string","example":"OTP sent successfully","description":"Success message"},"debug_code":{"type":"string","example":"123456","description":"Código OTP enviado (somente retornado em modo desenvolvimento)"}},"required":["message"]},"VerifyOTPRequest":{"type":"object","required":["phoneNumber","code"],"description":"Verify OTP via SMS request","properties":{"phoneNumber":{"type":"string","minLength":9,"maxLength":15,"example":"244923456789","pattern":"^\\d+$","description":"Phone number that received OTP"},"code":{"type":"string","minLength":6,"maxLength":6,"example":"123456","pattern":"^\\d{6}$","description":"6-digit OTP code"}}},"VerifyOTPResponse":{"type":"object","properties":{"message":{"type":"string","example":"OTP verified successfully","description":"Success message"},"verified":{"type":"boolean","example":true,"description":"OTP verification status"},"driver":{"type":"object","description":"Driver data (created or updated)","properties":{"id":{"type":"string","example":"clx1234567890abcdef1234","description":"Driver unique ID (CUID)"},"phone":{"type":"string","example":"244923456789","description":"Driver phone number"}},"required":["id","phone"]},"license":{"type":"object","description":"Driver license info","properties":{"number":{"type":"string","example":"AO0001","description":"License number"},"status":{"type":"string","enum":["APPROVED","REJECTED","PENDING"],"example":"PENDING","description":"License status (approved after Kyciris verification)"}},"required":["number","status"]}},"required":["message","verified","driver","license"]},"Document":{"type":"object","description":"Driver identity document","properties":{"id":{"type":"string","description":"Document unique ID"},"type":{"type":"string","enum":["DRIVING_LICENSE","IDENTITY_CARD"],"description":"Document type"},"number":{"type":"string","description":"Document number or ID"},"status":{"type":"string","enum":["APPROVED","REJECTED","PENDING"],"example":"PENDING","description":"Document verification status"},"issuedAt":{"type":"string","format":"date-time","nullable":true,"description":"Document issue date"},"expiresAt":{"type":"string","format":"date-time","nullable":true,"description":"Document expiration date"},"rejectionType":{"type":"string","nullable":true,"enum":["FACE_MISMATCH","DOCUMENT_EXPIRED","INVALID_DOCUMENT_QUALITY","ACCOUNT_SUSPENDED","DUPLICATE_SUBMISSION","INVALID_DOCUMENT","DOCUMENT_NOT_READABLE","SELFIE_NOT_MATCHING"],"example":"FACE_MISMATCH","description":"Rejection type code (only present if status is REJECTED). Possible values: FACE_MISMATCH (face does not match document), DOCUMENT_EXPIRED (document has expired), INVALID_DOCUMENT_QUALITY (document image quality is insufficient), ACCOUNT_SUSPENDED (account suspended), DUPLICATE_SUBMISSION (duplicate submission detected), INVALID_DOCUMENT (invalid or fake document), DOCUMENT_NOT_READABLE (document text cannot be read), SELFIE_NOT_MATCHING (selfie does not match requirements)"},"rejectionReason":{"type":"string","nullable":true,"example":"The face in the selfie does not match the document face. The facial features do not correspond.","description":"Detailed rejection reason message (only present if status is REJECTED). Provides human-readable explanation of why the document was rejected."}},"required":["id","type","number","status"]},"Subscription":{"type":"object","description":"Driver subscription plan information","nullable":true,"properties":{"id":{"type":"string","description":"Subscription unique ID"},"plan":{"type":"string","description":"Subscription plan name"},"status":{"type":"string","enum":["ACTIVE","INACTIVE","CANCELLED","EXPIRED"],"description":"Subscription status"},"startDate":{"type":"string","format":"date-time","description":"Subscription start date"},"renewalDate":{"type":"string","format":"date-time","nullable":true,"description":"Subscription renewal date"}}},"GetLicenseResponse":{"type":"object","description":"Complete driver license information response","properties":{"id":{"type":"string","description":"License unique ID"},"number":{"type":"string","example":"AO0001","description":"License number"},"status":{"type":"string","enum":["APPROVED","REJECTED","PENDING"],"example":"APPROVED","description":"Current license status"},"type":{"type":"string","description":"License type (INDIVIDUAL or COMPANY)"},"rejectionType":{"type":"string","nullable":true,"enum":["LICENSE_NOT_FOUND","LICENSE_INACTIVE","INVALID_LICENSE_TYPE","NO_DRIVER_ASSOCIATED","DRIVER_NOT_FOUND","DRIVING_LICENSE_MISSING","DRIVING_LICENSE_NOT_APPROVED","IDENTITY_CARD_MISSING","IDENTITY_CARD_NOT_APPROVED","NO_SUBSCRIPTION","SUBSCRIPTION_INACTIVE","SUBSCRIPTION_EXPIRED"],"example":"DRIVING_LICENSE_NOT_APPROVED","description":"Rejection type code (only present if status is REJECTED). See LicenseRejectionType for detailed descriptions."},"rejectionReason":{"type":"string","nullable":true,"example":"Driver's DRIVING_LICENSE status is PENDING, expected APPROVED","description":"Detailed rejection reason message (only present if status is REJECTED)"},"subscription":{"$ref":"#/components/schemas/Subscription"},"driver":{"type":"object","description":"Driver data with Kyciris identity info","properties":{"id":{"type":"string","description":"Driver unique ID"},"avatar":{"type":"string","nullable":true,"format":"uri","description":"Driver avatar URL from Kyciris document face"},"fullName":{"type":"string","nullable":true,"description":"Full name from Kyciris identity"},"address":{"type":"string","nullable":true,"description":"Address from Kyciris identity"},"gender":{"type":"string","nullable":true,"description":"Gender from Kyciris identity"},"documents":{"type":"array","description":"Driver identity documents list","items":{"$ref":"#/components/schemas/Document"}}},"required":["id","documents"]}},"required":["id","number","status","type","driver"]},"GetCompanyLicenseResponse":{"type":"object","description":"Company license information response","properties":{"number":{"type":"string","example":"AO0001","description":"License number"},"status":{"type":"string","enum":["APPROVED","REJECTED","PENDING"],"example":"APPROVED","description":"Current license status"},"type":{"type":"string","description":"License type (COMPANY)"},"rejectionType":{"type":"string","nullable":true,"enum":["LICENSE_NOT_FOUND","LICENSE_INACTIVE","INVALID_LICENSE_TYPE","NO_DRIVER_ASSOCIATED","DRIVER_NOT_FOUND","DRIVING_LICENSE_MISSING","DRIVING_LICENSE_NOT_APPROVED","IDENTITY_CARD_MISSING","IDENTITY_CARD_NOT_APPROVED","NO_SUBSCRIPTION","SUBSCRIPTION_INACTIVE","SUBSCRIPTION_EXPIRED"],"example":"NO_SUBSCRIPTION","description":"Rejection type code (only present if status is REJECTED). See LicenseRejectionType for detailed descriptions."},"rejectionReason":{"type":"string","nullable":true,"example":"License does not have an associated subscription","description":"Detailed rejection reason message (only present if status is REJECTED)"},"company":{"type":"object","description":"Company information","properties":{"nif":{"type":"string","description":"Company Tax Identification Number"},"name":{"type":"string","description":"Company name"},"email":{"type":"string","format":"email","description":"Company email"}},"required":["nif","name","email"]}},"required":["number","status","type","company"]},"KycirysVerificationRequest":{"type":"object","required":["driverId"],"properties":{"driverId":{"type":"string","example":"clx1234567890abcdef1234567","description":"Driver ID (CUID)"}}},"KycirysVerificationResponse":{"type":"object","description":"Kyciris KYC verification links and status","properties":{"license":{"type":"object","description":"Driver license info","properties":{"number":{"type":"string","description":"License number"},"status":{"type":"string","enum":["APPROVED","REJECTED","PENDING"],"example":"PENDING","description":"Current license status"}},"required":["number","status"]},"pending":{"type":"array","description":"KYC verification URLs for expired or pending documents","items":{"type":"string","format":"uri","example":"https://kyc.kyciris.io/verify/token123?documentType=DRIVING_LICENSE&..."}}},"required":["license","pending"]},"SendEmailOTPRequest":{"type":"object","required":["email"],"description":"Send OTP via email request","properties":{"email":{"type":"string","format":"email","example":"empresa@example.com","description":"Company email address"}}},"SendEmailOTPResponse":{"type":"object","description":"OTP sent to email successfully response","properties":{"message":{"type":"string","example":"OTP sent successfully to email","description":"Success message"},"debug_code":{"type":"string","example":"123456","description":"Código OTP enviado (somente retornado em modo desenvolvimento)"}},"required":["message"]},"VerifyEmailOTPRequest":{"type":"object","required":["email","code"],"description":"Verify OTP via email request","properties":{"email":{"type":"string","format":"email","example":"empresa@example.com","description":"Email that received OTP"},"code":{"type":"string","minLength":6,"maxLength":6,"example":"123456","pattern":"^\\d{6}$","description":"6-digit OTP code"}}},"VerifyEmailOTPResponse":{"type":"object","description":"Email verified successfully response","properties":{"message":{"type":"string","example":"Email verified successfully","description":"Success message"},"email":{"type":"string","format":"email","example":"empresa@example.com","description":"Verified email address"}},"required":["message","email"]},"VerifyCompanyNIFRequest":{"type":"object","required":["nif"],"description":"Get company by NIF request","properties":{"nif":{"type":"string","example":"123456789","pattern":"^\\d{8,9}$","description":"Tax Identification Number (NIF) unformatted"}}},"VerifyCompanyNIFResponse":{"type":"object","description":"Company data with corporate license info","properties":{"id":{"type":"string","description":"Company unique ID"},"nif":{"type":"string","description":"Tax Identification Number"},"email":{"type":"string","format":"email","description":"Verified company email"},"name":{"type":"string","description":"Registered company name"},"license":{"type":"object","description":"Corporate license info","properties":{"id":{"type":"string","description":"Corporate license ID"},"number":{"type":"string","description":"License number"},"status":{"type":"string","enum":["APPROVED","REJECTED","PENDING"],"example":"ACTIVE","description":"Corporate license status"},"subscription":{"$ref":"#/components/schemas/Subscription"}},"required":["id","number","status"]}},"required":["id","nif","email","name","license"]},"KycirysWebhookRequest":{"type":"object","description":"Kyciris KYC verification webhook payload","required":["verificationId","status","faceMatchScore","timestamp","verification"],"properties":{"verificationId":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000","description":"Kyciris verification unique ID"},"externalId":{"type":"string","nullable":true,"example":"clx1234567890abcdef1234","description":"External driver ID (required for webhook processing)"},"status":{"type":"string","enum":["APPROVED","REJECTED","PENDING"],"example":"APPROVED","description":"Overall verification status"},"faceMatchScore":{"type":"number","minimum":0,"maximum":1,"example":0.98,"description":"Face match score (0-1, where 1 is perfect match)"},"timestamp":{"type":"string","format":"date-time","example":"2026-02-16T14:50:00.000Z","description":"Verification timestamp"},"verification":{"type":"object","description":"Complete verification details","required":["id","status","documentType","country","faceMatchScore","ocrData","selfiePath","documentFrontPath","documentBackPath","documentFacePath","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000","description":"Verification unique ID"},"status":{"type":"string","enum":["APPROVED","REJECTED","PENDING"],"example":"APPROVED"},"externalId":{"type":"string","nullable":true,"example":"clx1234567890abcdef1234"},"documentType":{"type":"string","enum":["DRIVING_LICENSE","IDENTITY_CARD"],"example":"DRIVING_LICENSE","description":"Verified document type"},"country":{"type":"string","example":"AO","description":"Country code (ISO 3166-1 alpha-2)"},"faceMatchScore":{"type":"number","minimum":0,"maximum":1,"example":0.98},"ocrData":{"type":"object","description":"OCR extracted document data","properties":{"idNumber":{"type":"string","example":"123456789","description":"Extracted identity number"},"issueDate":{"type":"string","example":"15/02/2020","description":"Issue date (DD/MM/YYYY format)"},"expiryDate":{"type":"string","example":"15/02/2030","description":"Expiry date (DD/MM/YYYY format)"}},"required":["idNumber","issueDate","expiryDate"]},"selfiePath":{"type":"string","format":"uri","example":"https://cdn-kyciris.com/selfies/abc123.jpg","description":"Captured selfie image URL"},"documentFrontPath":{"type":"string","format":"uri","example":"https://cdn-kyciris.com/docs/doc_front_abc123.jpg","description":"Document front image URL"},"documentBackPath":{"type":"string","format":"uri","example":"https://cdn-kyciris.com/docs/doc_back_abc123.jpg","description":"Document back image URL"},"documentFacePath":{"type":"string","format":"uri","example":"https://cdn-kyciris.com/docs/doc_face_abc123.jpg","description":"Detected face image URL"},"rejectionType":{"type":"string","nullable":true,"enum":["FACE_MISMATCH","DOCUMENT_EXPIRED","INVALID_DOCUMENT_QUALITY","ACCOUNT_SUSPENDED","DUPLICATE_SUBMISSION","INVALID_DOCUMENT","DOCUMENT_NOT_READABLE","SELFIE_NOT_MATCHING"],"example":"FACE_MISMATCH","description":"Rejection type code (only present if status is REJECTED)"},"rejectionReason":{"type":"string","nullable":true,"example":"The face in the selfie does not match the document face. The facial features do not correspond.","description":"Detailed rejection reason message (only present if status is REJECTED)"},"createdAt":{"type":"string","format":"date-time","example":"2026-02-16T14:40:00.000Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-02-16T14:50:00.000Z"}}}}},"KycirysWebhookResponse":{"type":"object","description":"Webhook processed successfully response","properties":{"message":{"type":"string","example":"Webhook processed successfully","description":"Success message"},"driverId":{"type":"string","example":"clx1234567890abcdef1234","description":"Driver ID whose verification was processed"},"status":{"type":"string","example":"APPROVED","enum":["APPROVED","REJECTED","PENDING"],"description":"Driver license status after webhook processing"}},"required":["message","driverId","status"]},"CreateSubscriptionRequest":{"type":"object","required":["licenseId"],"description":"Create subscription request","properties":{"licenseId":{"type":"string","example":"clx1234567890abcdef1234","description":"License ID (CUID)"},"plan":{"type":"string","enum":["BASIC","PREMIUM","ENTERPRISE"],"default":"BASIC","example":"BASIC","description":"Subscription plan"},"price":{"type":"number","example":99.99,"description":"Subscription price (optional)"}}},"SubscriptionResponse":{"type":"object","description":"Subscription data","properties":{"id":{"type":"string","example":"clx1234567890abcdef1234","description":"Subscription unique ID"},"licenseId":{"type":"string","example":"clx1234567890abcdef1234","description":"Associated license ID"},"plan":{"type":"string","enum":["BASIC","PREMIUM","ENTERPRISE"],"example":"BASIC","description":"Current subscription plan"},"status":{"type":"string","enum":["ACTIVE","INACTIVE"],"example":"INACTIVE","description":"Subscription status"},"startDate":{"type":"string","format":"date-time","example":"2026-02-25T10:00:00.000Z","description":"Subscription start date"},"renewalDate":{"type":"string","format":"date-time","example":"2026-03-25T10:00:00.000Z","description":"Next renewal date"},"cancelledAt":{"type":"string","format":"date-time","nullable":true,"example":null,"description":"Cancellation date (null if active)"},"price":{"type":"number","nullable":true,"example":99.99,"description":"Subscription price"},"createdAt":{"type":"string","format":"date-time","example":"2026-02-25T10:00:00.000Z","description":"Creation date"},"updatedAt":{"type":"string","format":"date-time","example":"2026-02-25T10:00:00.000Z","description":"Last update date"}},"required":["id","licenseId","plan","status","startDate","renewalDate","createdAt","updatedAt"]},"UpdateSubscriptionPlanRequest":{"type":"object","required":["plan"],"description":"Update subscription plan request","properties":{"plan":{"type":"string","enum":["BASIC","PREMIUM","ENTERPRISE"],"example":"PREMIUM","description":"New subscription plan"}}},"ActivateSubscriptionRequest":{"type":"object","required":["subscriptionId"],"description":"Activate subscription request","properties":{"subscriptionId":{"type":"string","example":"clx1234567890abcdef1234","description":"Subscription ID to activate"}}},"RenewSubscriptionRequest":{"type":"object","required":["subscriptionId"],"description":"Renew subscription request","properties":{"subscriptionId":{"type":"string","example":"clx1234567890abcdef1234","description":"Subscription ID to renew"}}},"CancelSubscriptionRequest":{"type":"object","required":["subscriptionId"],"description":"Cancel subscription request","properties":{"subscriptionId":{"type":"string","example":"clx1234567890abcdef1234","description":"Subscription ID to cancel"}}},"CarPhoto":{"type":"object","description":"Car photo","properties":{"id":{"type":"string","example":"clx1234567890abcdef1234","description":"Photo ID"},"url":{"type":"string","example":"/uploads/photos/1704067200000-0.jpg","description":"Photo URL"},"createdAt":{"type":"string","format":"date-time","description":"Photo creation date"}}},"Car":{"type":"object","description":"Company car information","properties":{"id":{"type":"string","example":"clx1234567890abcdef1234","description":"Car ID"},"plate":{"type":"string","nullable":true,"example":"AA-00-AA","description":"Car license plate"},"brand":{"type":"string","nullable":true,"example":"Toyota","description":"Car brand"},"model":{"type":"string","nullable":true,"example":"Corolla","description":"Car model"},"year":{"type":"integer","nullable":true,"example":2022,"description":"Car year"},"color":{"type":"string","nullable":true,"example":"Black","description":"Car color"},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED"],"example":"PENDING","description":"Car status"},"fuelType":{"type":"string","enum":["GASOLINE","DIESEL","ELECTRIC","HYBRID","OTHER"],"example":"GASOLINE","description":"Car fuel type"},"seats":{"type":"integer","example":5,"description":"Number of seats in the car"},"companyId":{"type":"string","example":"clx1234567890abcdef1234","description":"Company ID"},"company":{"type":"object","nullable":true,"description":"Company data when included","properties":{"id":{"type":"string","example":"clx1234567890abcdef1234","description":"Company ID"},"nif":{"type":"string","example":"123456789","description":"Company Tax Identification Number"},"email":{"type":"string","format":"email","example":"company@example.com","description":"Company email"},"name":{"type":"string","example":"My Company","description":"Company name"}}},"documents":{"type":"array","description":"Uploaded car documents","items":{"$ref":"#/components/schemas/CarDocument"}},"createdAt":{"type":"string","format":"date-time","description":"Car creation date"},"updatedAt":{"type":"string","format":"date-time","description":"Car last update date"}}},"CreateCarRequest":{"type":"object","required":["companyId","plate"],"description":"Create car request","properties":{"companyId":{"type":"string","example":"clx1234567890abcdef1234","description":"Company ID"},"plate":{"type":"string","example":"AA-00-AA","description":"Car license plate (will be converted to uppercase)"}}},"CreateCarDocumentRequest":{"type":"object","required":["carId","type"],"description":"Create car document request (multipart/form-data)","properties":{"carId":{"type":"string","example":"clx1234567890abcdef1234","description":"Car ID"},"type":{"type":"string","enum":["REGISTRATION_CERTIFICATE","TITLE","PHOTO"],"description":"Car document type"},"image":{"type":"string","format":"binary","description":"Car document image file"}}},"CarDocument":{"type":"object","description":"Car document information","properties":{"id":{"type":"string","example":"clx1234567890abcdef1234","description":"Document ID"},"carId":{"type":"string","example":"clx1234567890abcdef1234","description":"Associated car ID"},"type":{"type":"string","enum":["REGISTRATION_CERTIFICATE","TITLE","PHOTO"],"example":"TITLE","description":"Document type"},"image":{"type":"string","example":"car-documents/clx1234567890abcdef1234/1704067200000-title.jpg","description":"Document image URL/path in storage"},"externalId":{"type":"string","nullable":true,"example":"ocr-123456","description":"External ID from OCR service (if applicable)"},"status":{"type":"string","enum":["APPROVED","REJECTED","PENDING"],"example":"PENDING","description":"Document verification status"},"ocr":{"type":"object","nullable":true,"description":"OCR extracted data from document"},"createdAt":{"type":"string","format":"date-time","description":"Document creation date"},"updatedAt":{"type":"string","format":"date-time","description":"Document last update date"}},"required":["id","carId","type","image"]},"CreateCompanyLicenseRequest":{"type":"object","required":["nif"],"description":"Create company license request","properties":{"nif":{"type":"string","example":"123456789","pattern":"^\\d{8,9}$","description":"Company Tax Identification Number"},"name":{"type":"string","example":"My Company","description":"Company name (required for new company creation)"}}},"OcrExtractedField":{"type":"object","description":"OCR extracted field from document","properties":{"line_number":{"type":"integer","example":17,"description":"Line number in the OCR result"},"text":{"type":"string","example":"Cor","description":"Extracted text from document"},"type":{"type":"string","example":"text","description":"Field type (text, numeric_sequence, unknown, etc)"},"value":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"nullable":true,"description":"Parsed value (optional, depends on field type)"}}},"OcrResult":{"type":"object","description":"OCR result with extracted fields from document","required":["front"],"properties":{"front":{"type":"object","description":"Front side OCR result","properties":{"rawText":{"type":"string","description":"Raw OCR text from document front"},"extractedFields":{"type":"array","description":"Structured extracted fields","items":{"$ref":"#/components/schemas/OcrExtractedField"}}}},"back":{"type":"object","nullable":true,"description":"Back side OCR result (optional)","properties":{"rawText":{"type":"string","description":"Raw OCR text from document back"},"extractedFields":{"type":"array","description":"Structured extracted fields","items":{"$ref":"#/components/schemas/OcrExtractedField"}}}}}},"CarOcrWebhookRequest":{"type":"object","description":"Kyciris OCR car document webhook payload","required":["externalId","documentType","country","ocrResult"],"properties":{"ocrId":{"type":"string","format":"uuid","example":"9e2a3de2-efb9-42f4-819a-7de32fdfd301","description":"OCR processing unique ID from Kyciris"},"externalId":{"type":"string","example":"user-123","description":"External car ID (required for webhook processing)"},"documentType":{"type":"string","example":"CAR_TITLE","description":"Type of car document processed (CAR_TITLE, etc)"},"country":{"type":"string","example":"AO","description":"Country code (ISO 3166-1 alpha-2)"},"ocrResult":{"$ref":"#/components/schemas/OcrResult"},"documentFaceUrl":{"type":"string","nullable":true,"description":"URL of extracted document face/front"},"completedAt":{"type":"string","format":"date-time","example":"2026-04-13T16:28:45.445Z","description":"OCR processing completion timestamp"}}},"CarOcrWebhookResponse":{"type":"object","description":"Car OCR webhook processed successfully response","properties":{"message":{"type":"string","example":"Webhook processado com sucesso","description":"Success message"},"car":{"$ref":"#/components/schemas/Car","description":"Updated car with OCR extracted data"}},"required":["message"]},"LicenseRejectionType":{"type":"string","enum":["LICENSE_NOT_FOUND","LICENSE_INACTIVE","INVALID_LICENSE_TYPE","NO_DRIVER_ASSOCIATED","DRIVER_NOT_FOUND","DRIVING_LICENSE_MISSING","DRIVING_LICENSE_NOT_APPROVED","IDENTITY_CARD_MISSING","IDENTITY_CARD_NOT_APPROVED","NO_SUBSCRIPTION","SUBSCRIPTION_INACTIVE","SUBSCRIPTION_EXPIRED"],"description":"License validation rejection types"},"LicenseRejectionTypeDetails":{"type":"object","description":"Detailed description of all license rejection types","properties":{"LICENSE_NOT_FOUND":{"type":"string","example":"License not found","description":"The license does not exist in the system"},"LICENSE_INACTIVE":{"type":"string","example":"License status is REJECTED, expected ACTIVE","description":"The license exists but is not in ACTIVE status (must be ACTIVE for validation)"},"INVALID_LICENSE_TYPE":{"type":"string","example":"License type is COMPANY, expected DRIVER","description":"License type is not DRIVER (only driver licenses can be validated)"},"NO_DRIVER_ASSOCIATED":{"type":"string","example":"License is not associated with a driver","description":"The license does not have a driver ID associated"},"DRIVER_NOT_FOUND":{"type":"string","example":"Associated driver not found","description":"The driver referenced by the license does not exist"},"DRIVING_LICENSE_MISSING":{"type":"string","example":"Driver does not have a DRIVING_LICENSE document","description":"The driver must have a DRIVING_LICENSE document for license validation"},"DRIVING_LICENSE_NOT_APPROVED":{"type":"string","example":"Driver's DRIVING_LICENSE status is PENDING, expected APPROVED","description":"The driver's DRIVING_LICENSE document must be APPROVED by Kyciris"},"IDENTITY_CARD_MISSING":{"type":"string","example":"Driver does not have an IDENTITY_CARD document","description":"The driver must have an IDENTITY_CARD document for license validation"},"IDENTITY_CARD_NOT_APPROVED":{"type":"string","example":"Driver's IDENTITY_CARD status is PENDING, expected APPROVED","description":"The driver's IDENTITY_CARD document must be APPROVED by Kyciris"},"NO_SUBSCRIPTION":{"type":"string","example":"License does not have an associated subscription","description":"The license must have a subscription for validation"},"SUBSCRIPTION_INACTIVE":{"type":"string","example":"Subscription status is INACTIVE, expected ACTIVE","description":"The subscription must be in ACTIVE status"},"SUBSCRIPTION_EXPIRED":{"type":"string","example":"Subscription expired on 2026-03-25T10:00:00.000Z","description":"The subscription's renewal date has passed (subscription is expired)"}}},"LicenseValidationError":{"type":"object","description":"License validation error with rejection details","properties":{"rejectionType":{"$ref":"#/components/schemas/LicenseRejectionType"},"rejectionReason":{"type":"string","example":"License status is REJECTED, expected ACTIVE","description":"Human-readable reason for validation failure"}},"required":["rejectionType","rejectionReason"]},"LicenseValidationDetails":{"type":"object","description":"Detailed validation status for each validation step","properties":{"licenseExists":{"type":"boolean","example":true,"description":"License exists in the system"},"licenseActive":{"type":"boolean","example":true,"description":"License is in ACTIVE status"},"driverExists":{"type":"boolean","example":true,"description":"Driver associated with license exists"},"drivingLicenseApproved":{"type":"boolean","example":true,"description":"Driver's DRIVING_LICENSE document is APPROVED"},"identityCardApproved":{"type":"boolean","example":true,"description":"Driver's IDENTITY_CARD document is APPROVED"},"subscriptionActive":{"type":"boolean","example":true,"description":"Subscription is in ACTIVE status"},"subscriptionNotExpired":{"type":"boolean","example":true,"description":"Subscription renewal date has not passed"}},"required":["licenseExists","licenseActive","driverExists","drivingLicenseApproved","identityCardApproved","subscriptionActive","subscriptionNotExpired"]},"LicenseValidationResult":{"type":"object","description":"Complete license validation result with all validation errors and details","properties":{"isValid":{"type":"boolean","example":true,"description":"Whether the license is valid (no errors)"},"errors":{"type":"array","description":"Array of validation errors (empty if valid)","items":{"$ref":"#/components/schemas/LicenseValidationError"}},"details":{"$ref":"#/components/schemas/LicenseValidationDetails"}},"required":["isValid","errors","details"]}},"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API Key for secure authentication. Required for sensitive data endpoints. Contact support@iddrive.ao for access."}}},"tags":[{"name":"Authentication","description":"OTP-based authentication for drivers and companies"},{"name":"License","description":"Driver and company license management and validation"},{"name":"Company","description":"Company registration and management"},{"name":"Car","description":"Company vehicle management and documentation"},{"name":"Kyciris","description":"KYC verification webhooks and integration endpoints"},{"name":"Subscription","description":"Subscription lifecycle management (create, activate, renew, cancel)"}],"paths":{"/auth/otp/send":{"post":{"tags":["Authentication"],"summary":"Send OTP via SMS or Email","description":"Send 6-digit OTP code via SMS (for driver authentication) or email (for company verification). OTP expires in 10 minutes. Use phoneNumber for driver registration or email for company registration.","operationId":"sendOTP","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/SendOTPRequest"},{"$ref":"#/components/schemas/SendEmailOTPRequest"}]},"examples":{"Driver Phone OTP":{"value":{"phoneNumber":"244923456789"}},"Company Email OTP":{"value":{"email":"empresa@example.com"}}}}}},"responses":{"200":{"description":"OTP sent successfully via SMS or email","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/SendOTPResponse"},{"$ref":"#/components/schemas/SendEmailOTPResponse"}]}}}},"400":{"description":"Invalid data - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable Entity - neither phoneNumber nor email provided"},"500":{"description":"Internal server error - SMS/email service unavailable"}}}},"/auth/otp/verify":{"post":{"tags":["Authentication"],"summary":"Verify OTP and register/authenticate user","operationId":"verifyOTP","description":"Verify OTP code sent via SMS or email. On success, creates or updates driver/company record with their phone/email.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/VerifyOTPRequest"},{"$ref":"#/components/schemas/VerifyEmailOTPRequest"}]},"examples":{"Driver OTP Verification":{"value":{"phoneNumber":"244923456789","code":"123456"}},"Company Email Verification":{"value":{"email":"empresa@example.com","code":"123456"}}}}}},"responses":{"200":{"description":"OTP verified successfully. Driver/Company registered and license created.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/VerifyOTPResponse"},{"$ref":"#/components/schemas/VerifyEmailOTPResponse"}]}}}},"400":{"description":"Expired or invalid OTP code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"OTP not found for provided phone number or email"},"422":{"description":"Unprocessable Entity - neither phoneNumber nor email provided"},"500":{"description":"Error creating Kyciris identity or driver"}}}},"/license":{"get":{"tags":["License"],"summary":"Get driver or company license information","operationId":"getLicense","description":"Retrieve complete license information for a driver or company. Can search by license number (e.g., AO0001, AO2026/E1) or by driver phone number. Returns full license details including subscription status, driver/company info, and documents.","parameters":[{"name":"number","in":"query","required":true,"schema":{"type":"string","example":"AO0001"},"description":"License number (e.g., AO0001, AO2026/E1) or driver phone number"}],"responses":{"200":{"description":"License information retrieved successfully - returns driver or company license","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/GetLicenseResponse"},{"$ref":"#/components/schemas/GetCompanyLicenseResponse"}]}}}},"400":{"description":"Invalid license number format or missing required parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - invalid or missing API Key"},"404":{"description":"Driver or license not found"},"500":{"description":"Internal server error retrieving license or Kyciris data"}}}},"/company":{"get":{"tags":["Company"],"summary":"Get or create company license","operationId":"getCompanyLicense","description":"Retrieve existing company license by NIF or create a new company with license if it doesn't exist. Requires verified email OTP for new company creation. Name parameter is required when creating new company.","parameters":[{"name":"nif","in":"query","required":true,"schema":{"type":"string","example":"123456789","pattern":"^\\d{8,9}$"},"description":"Company Tax Identification Number (8-9 digits)"},{"name":"name","in":"query","required":false,"schema":{"type":"string","example":"Company Name"},"description":"Company name (required only for creating new company)"}],"responses":{"200":{"description":"Company data and corporate license retrieved or created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyCompanyNIFResponse"}}}},"400":{"description":"Invalid data - email not verified, invalid NIF format, or missing name for new company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - invalid or missing API Key"},"409":{"description":"Conflict - NIF already registered with different email"},"500":{"description":"Internal server error - database or subscription error"}}}},"/kyciris/verification":{"get":{"tags":["Kyciris"],"summary":"Generate Kyciris KYC verification links","operationId":"getKycirysVerificationLinks","description":"Generate KYC verification URLs for a driver with expired or pending document verification. These links are used to redirect the driver to Kyciris for document submission (identity card, driver's license).","parameters":[{"name":"driverId","in":"query","required":true,"schema":{"type":"string","example":"clx1234567890abcdef1234"},"description":"Driver unique ID (CUID)"}],"responses":{"200":{"description":"KYC verification links generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KycirysVerificationResponse"}}}},"400":{"description":"Invalid driver ID format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - invalid or missing API Key"},"404":{"description":"Driver not found"},"500":{"description":"Internal server error generating verification token or Kyciris error"}}}},"/kyciris/webhook":{"post":{"tags":["Kyciris"],"summary":"Process Kyciris KYC document verification webhook","operationId":"handleKycirysWebhook","description":"Webhook endpoint for receiving KYC verification results from Kyciris. Updates driver documents and license status based on verification results (APPROVED/REJECTED/PENDING). Requires externalId field to match driver.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KycirysWebhookRequest"}}}},"security":[],"responses":{"200":{"description":"Webhook processed successfully. Driver license and document status updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KycirysWebhookResponse"}}}},"400":{"description":"Invalid data or missing externalId","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"externalId é obrigatório"}}}}}},"404":{"description":"Driver not found for provided externalId","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Driver não encontrado"}}}}}},"422":{"description":"Unprocessable Entity - validation error in webhook payload"},"500":{"description":"Internal server error - database or Kyciris API error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Unknown error processing webhook"}}}}}}}}},"/kyciris/webhook/car":{"post":{"tags":["Kyciris"],"summary":"Process Kyciris OCR car document webhook","description":"Webhook endpoint for Kyciris OCR processing. Extracts car data (brand, model, color, plate) from car title documents and updates car record with OCR results.","operationId":"handleKycirysCarOcrWebhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CarOcrWebhookRequest"},"examples":{"Car OCR Result":{"value":{"ocrId":"9e2a3de2-efb9-42f4-819a-7de32fdfd301","externalId":"user-123","documentType":"CAR_TITLE","country":"AO","ocrResult":{"front":{"rawText":"REPUBLICA DE ANGOLA...","extractedFields":[{"line_number":14,"text":"Marca do veiculo","type":"text"},{"line_number":16,"text":"SUZUKI","type":"text"},{"line_number":20,"text":"Modelo do veiculo","type":"text"},{"line_number":22,"text":"ALTO","type":"text"},{"line_number":17,"text":"Cor","type":"text"},{"line_number":19,"text":"CINZENTA","type":"text"},{"line_number":32,"text":"Matricula do veiculo","type":"text"},{"line_number":34,"text":"LDA-69-68-AE","type":"text"}]}},"completedAt":"2026-04-13T16:28:45.445Z"}}}}}},"security":[],"responses":{"200":{"description":"Car OCR webhook processed successfully. Car record updated with extracted data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CarOcrWebhookResponse"}}}},"400":{"description":"Invalid request data or unsupported document type (expected CAR_TITLE)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Tipo de documento não suportado"}}}}}},"404":{"description":"Car not found with provided externalId","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Carro não encontrado com o externalId fornecido"}}}}}},"500":{"description":"Internal server error - database or OCR processing error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Erro desconhecido ao processar webhook"}}}}}}}}},"/subscription":{"post":{"tags":["Subscription"],"summary":"Create subscription","description":"Create a new subscription for a license. Subscription starts in INACTIVE state and must be activated separately. Default plan is BASIC.","operationId":"createSubscription","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubscriptionRequest"}}}},"responses":{"201":{"description":"Subscription created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionResponse"}}}},"400":{"description":"Invalid data - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - invalid or missing API Key"},"500":{"description":"Internal server error creating subscription"}}}},"/subscription/{id}":{"get":{"tags":["Subscription"],"summary":"Get subscription by ID","description":"Retrieve subscription details including license information and subscription status.","operationId":"getSubscription","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"clx1234567890abcdef1234"},"description":"Subscription ID (CUID)"}],"responses":{"200":{"description":"Subscription retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionResponse"}}}},"400":{"description":"Invalid subscription ID format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - invalid or missing API Key"},"404":{"description":"Subscription not found"},"500":{"description":"Internal server error retrieving subscription"}}},"put":{"tags":["Subscription"],"summary":"Update subscription plan","description":"Change the subscription plan (BASIC, PREMIUM, ENTERPRISE) for an existing subscription.","operationId":"updateSubscriptionPlan","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"clx1234567890abcdef1234"},"description":"Subscription ID (CUID)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubscriptionPlanRequest"}}}},"responses":{"200":{"description":"Subscription plan updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionResponse"}}}},"400":{"description":"Invalid data - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - invalid or missing API Key"},"404":{"description":"Subscription not found"},"500":{"description":"Internal server error updating subscription plan"}}}},"/subscription/by-license":{"get":{"tags":["Subscription"],"summary":"Get subscription by license ID","description":"Retrieve subscription information by providing a license ID. Useful for checking subscription status for a specific license.","operationId":"getSubscriptionByLicense","parameters":[{"name":"licenseId","in":"query","required":true,"schema":{"type":"string","example":"clx1234567890abcdef1234"},"description":"License ID (CUID)"}],"responses":{"200":{"description":"Subscription retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionResponse"}}}},"400":{"description":"Missing required licenseId parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - invalid or missing API Key"},"404":{"description":"Subscription not found for provided license"},"500":{"description":"Internal server error retrieving subscription"}}}},"/subscription/activate":{"post":{"tags":["Subscription"],"summary":"Activate subscription","description":"Activate a subscription, setting its status to ACTIVE and initializing renewal dates. An active subscription is required for license validation.","operationId":"activateSubscription","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivateSubscriptionRequest"}}}},"responses":{"200":{"description":"Subscription activated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionResponse"}}}},"400":{"description":"Invalid data - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - invalid or missing API Key"},"500":{"description":"Internal server error activating subscription"}}}},"/subscription/renew":{"post":{"tags":["Subscription"],"summary":"Renew subscription","description":"Renew an active subscription, extending the renewal date by one month. Cannot renew cancelled subscriptions.","operationId":"renewSubscription","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenewSubscriptionRequest"}}}},"responses":{"200":{"description":"Subscription renewed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionResponse"}}}},"400":{"description":"Invalid data - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - invalid or missing API Key"},"500":{"description":"Internal server error renewing subscription"}}}},"/subscription/cancel":{"post":{"tags":["Subscription"],"summary":"Cancel subscription","description":"Cancel an active subscription and set the associated license status to PENDING.","operationId":"cancelSubscription","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelSubscriptionRequest"}}}},"responses":{"200":{"description":"Subscription cancelled successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionResponse"}}}},"400":{"description":"Invalid data - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - invalid or missing API Key"},"500":{"description":"Internal server error cancelling subscription"}}}},"/company/license":{"get":{"tags":["Company"],"summary":"Verify company license","operationId":"verifyCompanyLicense","description":"Get or create company license by NIF. Returns company data with license information.","parameters":[{"name":"nif","in":"query","required":true,"schema":{"type":"string","example":"123456789"},"description":"Company Tax Identification Number"},{"name":"name","in":"query","required":false,"schema":{"type":"string","example":"My Company"},"description":"Company name (required only for creating new company)"}],"responses":{"200":{"description":"Company license data retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyCompanyNIFResponse"}}}},"400":{"description":"Invalid data - email not verified or invalid NIF format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - invalid or missing API Key"},"409":{"description":"Conflict - NIF already registered with different email"},"500":{"description":"Internal server error - database or subscription error"}}}},"/company/car":{"post":{"tags":["Car"],"summary":"Create company car","description":"Create a new vehicle record for a company. Prepares the vehicle for document upload and OCR processing. Use POST /company/car/document to add vehicle documents.","operationId":"createCar","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCarRequest"},"examples":{"Create Car":{"value":{"companyId":"clx1234567890abcdef1234","plate":"AA-00-AA"}}}}}},"responses":{"201":{"description":"Car created successfully - ready for document upload (status: PENDING by default)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Car"},"examples":{"Car Created":{"value":{"id":"clx1234567890abcdef1234","plate":"AA-00-AA","brand":null,"model":null,"year":null,"color":null,"status":"PENDING","companyId":"clx1234567890abcdef1234","documents":[],"createdAt":"2026-04-21T11:00:00.000Z","updatedAt":"2026-04-21T11:00:00.000Z"}}}}}},"400":{"description":"Invalid data - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - invalid or missing API Key"},"404":{"description":"Company not found"},"500":{"description":"Internal server error creating car"}}},"get":{"tags":["Car"],"summary":"List company cars","description":"Retrieve all vehicles registered for a specific company, including documents and metadata.","operationId":"listCars","parameters":[{"name":"companyId","in":"query","required":true,"schema":{"type":"string","example":"clx1234567890abcdef1234"},"description":"Company ID"}],"responses":{"200":{"description":"Cars list retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Car"}}}}},"400":{"description":"Missing or invalid company ID"},"401":{"description":"Unauthorized - invalid or missing API Key"},"404":{"description":"Company not found"},"500":{"description":"Internal server error retrieving cars"}}}},"/company/car/document":{"post":{"tags":["Car"],"summary":"Create car document","description":"Upload a car document (title, registration certificate, or photo). Non-photo documents are sent for OCR processing.","operationId":"createCarDocument","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/CreateCarDocumentRequest"},"examples":{"Car Title Document":{"value":{"carId":"clx1234567890abcdef1234","type":"TITLE","image":"binary file"}},"Car Photo":{"value":{"carId":"clx1234567890abcdef1234","type":"PHOTO","image":"binary file"}}}}}},"responses":{"201":{"description":"Car document created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CarDocument"}}}},"400":{"description":"Invalid data - validation or OCR processing error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Car not found"},"500":{"description":"Internal server error - file upload or OCR processing error"}}},"get":{"tags":["Car"],"summary":"List car documents","operationId":"listCarDocuments","description":"Get all documents (titles, registrations, photos) for a specific car","parameters":[{"name":"carId","in":"query","required":true,"schema":{"type":"string","example":"clx1234567890abcdef1234"},"description":"Car ID"}],"responses":{"200":{"description":"Car documents retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CarDocument"}}}}},"400":{"description":"Missing or invalid carId parameter"},"404":{"description":"Car not found"},"500":{"description":"Internal server error retrieving documents"}}}},"/company/car/{plate}":{"get":{"tags":["Car"],"summary":"Get car by license plate","description":"Retrieve detailed information for a specific car using its license plate","operationId":"getCarByPlate","parameters":[{"name":"plate","in":"path","required":true,"schema":{"type":"string","example":"AA-00-AA"},"description":"Car license plate"}],"responses":{"200":{"description":"Car retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Car"}}}},"400":{"description":"Missing plate parameter"},"401":{"description":"Unauthorized - invalid or missing API Key"},"404":{"description":"Car not found"},"500":{"description":"Internal server error retrieving car"}}},"put":{"tags":["Car"],"summary":"Update car information","description":"Update car details (brand, model, year, color, status) after OCR processing or manual updates","operationId":"updateCar","parameters":[{"name":"plate","in":"path","required":true,"schema":{"type":"string","example":"AA-00-AA"},"description":"Car license plate"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brand":{"type":"string","description":"Car brand (e.g., Toyota, Honda, Suzuki)"},"model":{"type":"string","description":"Car model (e.g., Corolla, Civic, Alto)"},"year":{"type":"integer","example":2022,"description":"Manufacturing year"},"color":{"type":"string","description":"Car color"},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED"],"description":"Car operational status (PENDING = awaiting OCR processing, APPROVED = fully configured, REJECTED = disabled)"}}},"examples":{"Update car details":{"value":{"brand":"Toyota","model":"Corolla","year":2022,"color":"Black","status":"ACTIVE"}}}}}},"responses":{"200":{"description":"Car updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Car"}}}},"400":{"description":"Invalid data - validation error"},"401":{"description":"Unauthorized - invalid or missing API Key"},"404":{"description":"Car not found"},"500":{"description":"Internal server error updating car"}}},"delete":{"tags":["Car"],"summary":"Delete car","description":"Remove a vehicle record and all associated documents from the system","operationId":"deleteCar","parameters":[{"name":"plate","in":"path","required":true,"schema":{"type":"string","example":"AA-00-AA"},"description":"Car license plate"}],"responses":{"200":{"description":"Car deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Carro deletado com sucesso"}}}}}},"401":{"description":"Unauthorized - invalid or missing API Key"},"404":{"description":"Car not found"},"500":{"description":"Internal server error deleting car"}}}}}}