{"openapi":"3.0.0","info":{"title":"Rantipunku API","description":"Documentación de la API de Rantipunku. Las operaciones con candado requieren Authorization: Bearer <token>.","version":"1.0","contact":{}},"tags":[{"name":"users","description":"Sesión y usuarios"},{"name":"companies","description":"Empresas"},{"name":"invoices","description":"Facturas de proveedores"},{"name":"reports","description":"Reportes"},{"name":"settings","description":"Configuración por empresa"},{"name":"files","description":"Archivos en S3"},{"name":"uploads","description":"Carga de archivos"},{"name":"purchase-orders","description":"Órdenes de compra"}],"servers":[],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Token devuelto por POST /users/login o POST /users/login/google."}},"schemas":{"LoginUserDto":{"type":"object","properties":{"usernameOrEmail":{"type":"string","example":"ana@empresa.com"},"password":{"type":"string","example":"secreto"}},"required":["usernameOrEmail","password"]},"GoogleLoginDto":{"type":"object","properties":{"code":{"type":"string","description":"Código de autorización devuelto por Google"},"redirectUri":{"type":"string","example":"http://localhost:8000/auth/google/return","description":"redirect_uri usado al pedir el código. Debe coincidir con el registrado en Google."}},"required":["code","redirectUri"]},"CreateUserDto":{"type":"object","properties":{"internalId":{"type":"string","description":"Id de la empresa interna"},"name":{"type":"string"},"lastname":{"type":"string"},"documentType":{"type":"string","enum":["DNI","CE","RUC","LC"],"default":"DNI"},"documentNumber":{"type":"string"},"username":{"type":"string"},"email":{"type":"string","example":"ana@empresa.com"},"phone":{"type":"string"},"type":{"type":"string","enum":["provider","internal"]},"companyId":{"type":"string","description":"Id de la empresa del usuario"},"password":{"type":"string","minLength":6},"status":{"type":"string","enum":["active","desactive"],"default":"active"}},"required":["internalId","name","lastname","documentNumber","username","email","phone","type","password"]},"UpdateUserDto":{"type":"object","properties":{"internalId":{"type":"string","description":"Id de la empresa interna"},"name":{"type":"string"},"lastname":{"type":"string"},"documentType":{"type":"string","enum":["DNI","CE","RUC","LC"],"default":"DNI"},"documentNumber":{"type":"string"},"username":{"type":"string"},"email":{"type":"string","example":"ana@empresa.com"},"phone":{"type":"string"},"type":{"type":"string","enum":["provider","internal"]},"companyId":{"type":"string","description":"Id de la empresa del usuario"},"password":{"type":"string","minLength":6},"status":{"type":"string","enum":["active","desactive"],"default":"active"}}},"CreateCompanyDto":{"type":"object","properties":{"internalId":{"type":"string"},"internalIdRaw":{"type":"number"},"types":{"type":"array","items":{"type":"string","enum":["provider","customer","internal"]}},"tradeName":{"type":"string"},"name":{"type":"string"},"ruc":{"type":"string","description":"RUC de la empresa"},"address":{"type":"string"},"phone":{"type":"string"},"contactName":{"type":"string"},"observation":{"type":"string"},"status":{"type":"string","enum":["active","desactive"]}},"required":["types","tradeName","name","ruc"]},"UpdateCompanyDto":{"type":"object","properties":{"internalId":{"type":"string"},"internalIdRaw":{"type":"number"},"types":{"type":"array","items":{"type":"string","enum":["provider","customer","internal"]}},"tradeName":{"type":"string"},"name":{"type":"string"},"ruc":{"type":"string","description":"RUC de la empresa"},"address":{"type":"string"},"phone":{"type":"string"},"contactName":{"type":"string"},"observation":{"type":"string"},"status":{"type":"string","enum":["active","desactive"]}}},"InvoiceFileDto":{"type":"object","properties":{"file_extension":{"type":"string"},"name":{"type":"string"},"public_url":{"type":"string"},"path":{"type":"string"}},"required":["file_extension","name","public_url","path"]},"InvoiceFilesDto":{"type":"object","properties":{"invoice_pdf":{"$ref":"#/components/schemas/InvoiceFileDto"},"invoice_xml":{"$ref":"#/components/schemas/InvoiceFileDto"},"invoice_cdr":{"$ref":"#/components/schemas/InvoiceFileDto"},"evidence_service":{"$ref":"#/components/schemas/InvoiceFileDto"},"purchaseOrder":{"$ref":"#/components/schemas/InvoiceFileDto"},"refund":{"$ref":"#/components/schemas/InvoiceFileDto"},"professionalServices":{"$ref":"#/components/schemas/InvoiceFileDto"}}},"CreateInvoiceDto":{"type":"object","properties":{"internalId":{"type":"string"},"companyId":{"type":"string"},"ruc":{"type":"string","minLength":11,"maxLength":11,"example":"20600980794"},"companyName":{"type":"string"},"documentType":{"type":"string","enum":["invoice","refund","professionalServices","creditNote"]},"purchaseOrder":{"type":"string"},"type":{"type":"string"},"serie":{"type":"string"},"correlative":{"type":"string"},"currency":{"type":"string","example":"PEN"},"amount":{"type":"number"},"issueDate":{"type":"string","format":"date-time"},"accountingDate":{"type":"string","format":"date-time"},"expirationDate":{"type":"string","format":"date-time"},"note":{"type":"string"},"description":{"type":"string"},"files":{"$ref":"#/components/schemas/InvoiceFilesDto"},"status":{"type":"string","enum":["created","processed","rejected"]},"paymentCondition":{"type":"string"},"paidAmount":{"type":"number"},"pendingAmount":{"type":"number"},"paymentMethod":{"type":"string"},"paymentDate":{"type":"string","format":"date-time"},"costCenter":{"type":"string"},"issuer":{"type":"string"},"reportId":{"type":"string"},"providerInternalId":{"type":"string"},"detail":{"type":"object","description":"Detalle completo del XML parseado"},"purchaseOrderDetail":{"type":"object","description":"Detalle completo de la orden de compra"},"refundDetail":{"type":"object"},"professionalServicesDetail":{"type":"object"},"creditNoteDetail":{"type":"object"}},"required":["internalId","companyId","type","serie","correlative","amount","issueDate"]},"UpdateInvoiceDto":{"type":"object","properties":{"internalId":{"type":"string"},"companyId":{"type":"string"},"ruc":{"type":"string","minLength":11,"maxLength":11,"example":"20600980794"},"companyName":{"type":"string"},"documentType":{"type":"string","enum":["invoice","refund","professionalServices","creditNote"]},"purchaseOrder":{"type":"string"},"type":{"type":"string"},"serie":{"type":"string"},"correlative":{"type":"string"},"currency":{"type":"string","example":"PEN"},"amount":{"type":"number"},"issueDate":{"type":"string","format":"date-time"},"accountingDate":{"type":"string","format":"date-time"},"expirationDate":{"type":"string","format":"date-time"},"note":{"type":"string"},"description":{"type":"string"},"files":{"$ref":"#/components/schemas/InvoiceFilesDto"},"status":{"type":"string","enum":["created","processed","rejected"]},"paymentCondition":{"type":"string"},"paidAmount":{"type":"number"},"pendingAmount":{"type":"number"},"paymentMethod":{"type":"string"},"paymentDate":{"type":"string","format":"date-time"},"costCenter":{"type":"string"},"issuer":{"type":"string"},"reportId":{"type":"string"},"providerInternalId":{"type":"string"},"detail":{"type":"object","description":"Detalle completo del XML parseado"},"purchaseOrderDetail":{"type":"object","description":"Detalle completo de la orden de compra"},"refundDetail":{"type":"object"},"professionalServicesDetail":{"type":"object"},"creditNoteDetail":{"type":"object"}}},"CreateSettingDto":{"type":"object","properties":{"internalId":{"type":"string"},"condition":{"type":"string"},"value":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["active","inactive"]}},"required":["internalId","condition","value"]},"UpdateSettingDto":{"type":"object","properties":{"internalId":{"type":"string"},"condition":{"type":"string"},"value":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["active","inactive"]}}},"CreateReportDto":{"type":"object","properties":{"internalId":{"type":"string","description":"Id de la empresa interna"}},"required":["internalId"]}}},"paths":{"/users/login":{"post":{"operationId":"UsersController_login","summary":"Iniciar sesión","description":"Devuelve access_token y el usuario. El token se usa como Bearer en el resto de rutas.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginUserDto"}}}},"responses":{"201":{"description":""}},"tags":["users"]}},"/users/login/google":{"post":{"operationId":"UsersController_loginWithGoogle","summary":"Iniciar sesión con Google","description":"Intercambia el código de autorización de Google por access_token y el usuario.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleLoginDto"}}}},"responses":{"201":{"description":""}},"tags":["users"]}},"/users":{"post":{"operationId":"UsersController_create","summary":"Registrar un usuario","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserDto"}}}},"responses":{"201":{"description":""}},"tags":["users"]},"get":{"operationId":"UsersController_findAll","summary":"Listar usuarios","parameters":[{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"0 devuelve todos los registros","schema":{"minimum":0,"maximum":100,"default":10,"type":"number"}},{"name":"status","required":false,"in":"query","schema":{"enum":["active","desactive"],"type":"string"}},{"name":"type","required":false,"in":"query","schema":{"enum":["provider","internal"],"type":"string"}},{"name":"internalId","required":true,"in":"query","description":"Id de la empresa interna","schema":{"type":"string"}},{"name":"companyId","required":false,"in":"query","schema":{"type":"string"}},{"name":"search","required":false,"in":"query","description":"Busca en nombre, apellido, email y username","schema":{"type":"string"}},{"name":"createdAtFrom","required":false,"in":"query","schema":{"format":"date","type":"string"}},{"name":"createdAtTo","required":false,"in":"query","schema":{"format":"date","type":"string"}}],"responses":{"200":{"description":""}},"tags":["users"],"security":[{"bearer":[]}]}},"/users/{id}":{"get":{"operationId":"UsersController_findOne","summary":"Obtener un usuario","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["users"],"security":[{"bearer":[]}]},"patch":{"operationId":"UsersController_update","summary":"Actualizar un usuario","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserDto"}}}},"responses":{"200":{"description":""}},"tags":["users"],"security":[{"bearer":[]}]},"delete":{"operationId":"UsersController_remove","summary":"Eliminar un usuario","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["users"],"security":[{"bearer":[]}]}},"/companies":{"post":{"operationId":"CompaniesController_create","summary":"Crear una empresa","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCompanyDto"}}}},"responses":{"201":{"description":""}},"tags":["companies"],"security":[{"bearer":[]}]},"get":{"operationId":"CompaniesController_findAll","summary":"Listar empresas","parameters":[{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":0,"maximum":100,"default":10,"type":"number"}},{"name":"internalId","required":false,"in":"query","schema":{"type":"string"}},{"name":"type","required":false,"in":"query","schema":{"type":"array","items":{"type":"string","enum":["provider","customer","internal"]}}},{"name":"name","required":false,"in":"query","schema":{"type":"string"}},{"name":"tradeName","required":false,"in":"query","schema":{"type":"string"}},{"name":"ruc","required":false,"in":"query","schema":{"type":"string"}},{"name":"search","required":false,"in":"query","description":"Busca en name, tradeName y ruc","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"enum":["active","desactive"],"type":"string"}},{"name":"createdAtFrom","required":false,"in":"query","schema":{"format":"date","type":"string"}},{"name":"createdAtTo","required":false,"in":"query","schema":{"format":"date","type":"string"}}],"responses":{"200":{"description":""}},"tags":["companies"],"security":[{"bearer":[]}]}},"/companies/{id}":{"get":{"operationId":"CompaniesController_findOne","summary":"Obtener una empresa","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["companies"],"security":[{"bearer":[]}]},"patch":{"operationId":"CompaniesController_update","summary":"Actualizar una empresa","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCompanyDto"}}}},"responses":{"200":{"description":""}},"tags":["companies"],"security":[{"bearer":[]}]},"delete":{"operationId":"CompaniesController_remove","summary":"Eliminar una empresa","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["companies"],"security":[{"bearer":[]}]}},"/invoices":{"post":{"operationId":"InvoicesController_create","summary":"Registrar una factura","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvoiceDto"}}}},"responses":{"201":{"description":""}},"tags":["invoices"],"security":[{"bearer":[]}]},"get":{"operationId":"InvoicesController_findAll","summary":"Listar facturas","parameters":[{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":0,"maximum":100,"default":10,"type":"number"}},{"name":"internalId","required":true,"in":"query","schema":{"type":"string"}},{"name":"companyId","required":false,"in":"query","schema":{"type":"string"}},{"name":"ruc","required":false,"in":"query","minLength":11,"maxLength":11,"schema":{"type":"array","items":{"type":"string"}}},{"name":"purchaseOrder","required":false,"in":"query","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"enum":["created","processed","rejected"],"type":"string"}},{"name":"withoutReport","required":false,"in":"query","description":"Si es true, solo facturas que no pertenecen a un reporte","schema":{"type":"boolean"}},{"name":"issueDateFrom","required":false,"in":"query","schema":{"format":"date","type":"string"}},{"name":"issueDateTo","required":false,"in":"query","schema":{"format":"date","type":"string"}}],"responses":{"200":{"description":""}},"tags":["invoices"],"security":[{"bearer":[]}]}},"/invoices/{id}":{"get":{"operationId":"InvoicesController_findOne","summary":"Obtener una factura","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["invoices"],"security":[{"bearer":[]}]},"patch":{"operationId":"InvoicesController_update","summary":"Actualizar una factura","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInvoiceDto"}}}},"responses":{"200":{"description":""}},"tags":["invoices"],"security":[{"bearer":[]}]},"delete":{"operationId":"InvoicesController_remove","summary":"Eliminar una factura","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["invoices"],"security":[{"bearer":[]}]}},"/invoices/read-xml":{"post":{"operationId":"InvoicesController_readXml","summary":"Leer una factura desde un XML","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"XML de la factura"}}}}}},"responses":{"201":{"description":""}},"tags":["invoices"],"security":[{"bearer":[]}]}},"/invoices/read-professional-services-document":{"post":{"operationId":"InvoicesController_readProfessionalServicesDocument","summary":"Leer un recibo de honorarios en PDF","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"PDF del recibo"}}}}}},"responses":{"201":{"description":""}},"tags":["invoices"],"security":[{"bearer":[]}]}},"/uploads/presigned":{"get":{"operationId":"UploadsController_getPresigned","summary":"URL firmada de carga","description":"Devuelve uploadUrl, key y publicUrl para subir directo a S3.","parameters":[{"name":"filename","required":true,"in":"query","schema":{"type":"string"}},{"name":"contentType","required":false,"in":"query","schema":{"type":"string"}},{"name":"companyId","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["uploads"],"security":[{"bearer":[]}]}},"/uploads/upload":{"post":{"operationId":"UploadsController_upload","summary":"Subir un archivo","description":"Sube el archivo por la API y devuelve key y publicUrl.","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","companyId"],"properties":{"file":{"type":"string","format":"binary"},"companyId":{"type":"string"}}}}}},"responses":{"201":{"description":""}},"tags":["uploads"],"security":[{"bearer":[]}]}},"/purchase-orders/read-pdf":{"post":{"operationId":"PurchaseOrdersController_readPdf","summary":"Leer una orden de compra en PDF","description":"Devuelve el contenido del PDF parseado en JSON.","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"PDF de la orden de compra"}}}}}},"responses":{"201":{"description":""}},"tags":["purchase-orders"],"security":[{"bearer":[]}]}},"/files/presign":{"get":{"operationId":"FilesController_presignRead","summary":"URL firmada de lectura","description":"Devuelve url y expiresIn para leer o descargar un objeto existente en S3.","parameters":[{"name":"key","required":true,"in":"query","description":"Clave del objeto en S3","schema":{"type":"string"}},{"name":"disposition","required":false,"in":"query","schema":{"enum":["inline","attachment"],"type":"string"}}],"responses":{"200":{"description":""}},"tags":["files"],"security":[{"bearer":[]}]}},"/files/presigned":{"get":{"operationId":"FilesController_getPresigned","summary":"URL firmada de carga","description":"Devuelve uploadUrl, key y publicUrl para subir directo a S3.","parameters":[{"name":"filename","required":true,"in":"query","schema":{"type":"string"}},{"name":"contentType","required":false,"in":"query","schema":{"type":"string"}},{"name":"companyId","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["files"],"security":[{"bearer":[]}]}},"/files/upload":{"post":{"operationId":"FilesController_upload","summary":"Subir un archivo","description":"Sube el archivo por la API y devuelve key y publicUrl.","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","companyId"],"properties":{"file":{"type":"string","format":"binary"},"companyId":{"type":"string"}}}}}},"responses":{"201":{"description":""}},"tags":["files"],"security":[{"bearer":[]}]}},"/settings":{"post":{"operationId":"SettingsController_create","summary":"Crear una configuración","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSettingDto"}}}},"responses":{"201":{"description":""}},"tags":["settings"],"security":[{"bearer":[]}]},"get":{"operationId":"SettingsController_findAll","summary":"Listar configuraciones","parameters":[{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":0,"maximum":100,"default":10,"type":"number"}},{"name":"internalId","required":true,"in":"query","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"enum":["active","inactive"],"type":"string"}}],"responses":{"200":{"description":""}},"tags":["settings"],"security":[{"bearer":[]}]}},"/settings/{id}":{"get":{"operationId":"SettingsController_findOne","summary":"Obtener una configuración","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["settings"],"security":[{"bearer":[]}]},"patch":{"operationId":"SettingsController_update","summary":"Actualizar una configuración","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSettingDto"}}}},"responses":{"200":{"description":""}},"tags":["settings"],"security":[{"bearer":[]}]},"delete":{"operationId":"SettingsController_remove","summary":"Eliminar una configuración","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["settings"],"security":[{"bearer":[]}]}},"/reports":{"post":{"operationId":"ReportsController_create","summary":"Crear un reporte","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateReportDto"}}}},"responses":{"201":{"description":""}},"tags":["reports"],"security":[{"bearer":[]}]},"get":{"operationId":"ReportsController_findAll","summary":"Listar reportes","parameters":[{"name":"internalId","required":true,"in":"query","schema":{"type":"string"}},{"name":"issuer","required":false,"in":"query","schema":{"type":"string"}},{"name":"name","required":false,"in":"query","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":0,"maximum":100,"default":10,"type":"number"}}],"responses":{"200":{"description":""}},"tags":["reports"],"security":[{"bearer":[]}]}},"/reports/{reportId}/export":{"get":{"operationId":"ReportsController_exportCsv","summary":"Exportar un reporte en CSV","parameters":[{"name":"reportId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["reports"],"security":[{"bearer":[]}]}},"/reports/{reportId}":{"get":{"operationId":"ReportsController_findOne","summary":"Obtener un reporte","parameters":[{"name":"reportId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["reports"],"security":[{"bearer":[]}]},"patch":{"operationId":"ReportsController_update","summary":"Regenerar un reporte","parameters":[{"name":"reportId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["reports"],"security":[{"bearer":[]}]},"delete":{"operationId":"ReportsController_remove","summary":"Eliminar un reporte","parameters":[{"name":"reportId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["reports"],"security":[{"bearer":[]}]}}}}