{"openapi":"3.0.0","info":{"title":"360Pay Partner API","version":"1.0.0","description":"API B2B para negocios, clientes, cupones y settlements autorizados por Partner API Key. Todas las fechas de respuesta son ISO-8601; los listados usan data + meta.","contact":{"name":"Soporte 360Pay","email":"soporte@360pay.com"}},"servers":[{"url":"https://api.360pay.pe/partners/v1","description":"Produccion"},{"url":"https://sandbox.api.360pay.pe/partners/v1","description":"Sandbox"}],"externalDocs":{"description":"Guia completa con payloads y respuestas","url":"/docs"},"tags":[{"name":"Businesses","description":"Negocios autorizados y onboarding del partner."},{"name":"Customers","description":"Clientes, busqueda y operaciones bulk."},{"name":"Coupons","description":"Cupones, metricas e importacion JSON/CSV."},{"name":"Settlements","description":"Liquidaciones en modo solo lectura."}],"components":{"securitySchemes":{"PartnerApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key"},"PartnerApiKeyBearer":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"schemas":{"GenericSuccess":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true},"message":{"type":"string"}}},"GenericListSuccess":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"type":"object","example":{"total":1,"page":1,"limit":20,"total_pages":1}}}},"GenericError":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Customer not found"}}},"CouponCreateRequest":{"type":"object","required":["amount","external_ref","expiry_date"],"properties":{"business_id":{"type":"string","example":"67f1f4c5b12e4d0c9a123456","description":"Obligatorio para API keys con varios negocios. Si la API key tiene un solo negocio, el backend lo infiere."},"customer_id":{"type":"string","example":"67f2a7f4b12e4d0c9a987654","description":"Usar si el cliente ya existe. Alternativa a code/coupon_code."},"code":{"type":"string","example":"DEMO0002","description":"Alternativa a customer_id; crea o vincula el cliente."},"coupon_code":{"type":"string","example":"DEMO0002","description":"Alias de code; crea o vincula el cliente."},"name":{"type":"string","example":"Cliente Demo"},"email":{"type":"string","format":"email","example":"cliente@example.com"},"phone":{"type":"string","example":"+51900000000"},"document_type":{"type":"string","example":"DNI"},"document_number":{"type":"string","example":"00000000"},"amount":{"type":"number","format":"double","example":120.5},"description":{"type":"string","example":"Mensualidad abril"},"issue_date":{"type":"string","format":"date-time","example":"2026-04-01T15:20:00.000Z"},"expiry_date":{"type":"string","format":"date","example":"2026-04-30"},"payment_date":{"type":"string","format":"date-time","nullable":true},"external_ref":{"type":"string","example":"ORDER-DEMO-0001","description":"Obligatorio y único por negocio."}},"anyOf":[{"title":"API key multi-negocio: cliente existente","required":["business_id","customer_id"]},{"title":"API key multi-negocio: cliente por code","required":["business_id","code"]},{"title":"API key multi-negocio: cliente por coupon_code","required":["business_id","coupon_code"]},{"title":"API key de un negocio: cliente existente","required":["customer_id"]},{"title":"API key de un negocio: cliente por code","required":["code"]},{"title":"API key de un negocio: cliente por coupon_code","required":["coupon_code"]}]},"Customer":{"type":"object","properties":{"_id":{"type":"string","example":"67f2a7f4b12e4d0c9a987654"},"business_id":{"type":"string","example":"67f1f4c5b12e4d0c9a123456"},"name":{"type":"string","example":"Cliente Demo"},"email":{"type":"string","format":"email","example":"cliente@example.com"},"phone":{"type":"string","example":"+51900000000"},"document_type":{"type":"string","example":"DNI"},"document_number":{"type":"string","example":"00000000"},"dob":{"type":"string","format":"date-time","nullable":true},"coupon_code":{"type":"string","example":"DEMO0001"},"payment_code":{"type":"string","example":"DEMO0001"},"account_status":{"type":"number","example":-120.5},"pending_coupons":{"type":"number","example":1},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"Coupon":{"type":"object","properties":{"_id":{"type":"string","example":"67f3b100b12e4d0c9a222222"},"business_id":{"type":"string","example":"67f1f4c5b12e4d0c9a123456"},"customer_id":{"type":"string","example":"67f2a7f4b12e4d0c9a987654"},"coupon_code":{"type":"string","example":"DEMO0001"},"customer_name":{"type":"string","example":"Cliente Demo"},"external_ref":{"type":"string","example":"ORDER-DEMO-0001"},"payment_reference":{"type":"string","example":"DEMO0001"},"operation_number":{"type":"string","nullable":true,"example":"OP-DEMO-0001"},"bank_tx_id":{"type":"string","nullable":true,"example":"TX-DEMO-0001"},"amount":{"type":"number","example":120.5},"status":{"type":"string","enum":["active","paid","voided"],"example":"paid"},"issue_date":{"type":"string","format":"date-time"},"expiry_date":{"type":"string","format":"date-time"},"payment_date":{"type":"string","format":"date-time","nullable":true},"paid_at":{"type":"string","format":"date-time","nullable":true},"settlement_id":{"type":"string","nullable":true},"settlement_status":{"type":"string","nullable":true},"fee_platform":{"type":"number","nullable":true},"fee_partner":{"type":"number","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Settlement":{"type":"object","properties":{"_id":{"type":"string","example":"67f4c1a2b12e4d0c9a111111"},"business_id":{"type":"string","example":"67f1f4c5b12e4d0c9a123456"},"partner_id":{"type":"string","nullable":true},"source_account":{"type":"string","example":"000-0000000000"},"destination_account":{"type":"string","example":"000-0000000000"},"destination_bank":{"type":"string","example":"BANCO_DEMO"},"coupons_count":{"type":"number","example":1},"total_amount":{"type":"number","example":120.5},"commission_amount":{"type":"number","example":3.62},"partner_fee_amount":{"type":"number","example":1.2},"total_paid":{"type":"number","example":116.88},"status":{"type":"string","enum":["IN_PROCESS","COMPLETED","REJECTED"],"example":"COMPLETED"},"transaction_date":{"type":"string","format":"date-time","nullable":true},"bank_transaction_id":{"type":"string","nullable":true},"batch_id":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"business":{"type":"object","additionalProperties":true}}},"ImportResult":{"type":"object","properties":{"total":{"type":"number","example":2},"success":{"type":"number","example":1},"failed":{"type":"number","example":1},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"number","example":3},"error":{"type":"string","example":"Monto invalido o faltante en la fila 3"},"data":{"type":"object"}}}}}}},"parameters":{"Id":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"67f2a7f4b12e4d0c9a987654"},"BusinessId":{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"example":"67f2a7f4b12e4d0c9a987654"},"HookId":{"name":"hookId","in":"path","required":true,"schema":{"type":"string"},"example":"67f2a7f4b12e4d0c9a987654"}}},"security":[{"PartnerApiKeyHeader":[]},{"PartnerApiKeyBearer":[]}],"paths":{"/businesses":{"get":{"summary":"Listar negocios","tags":["Businesses"],"responses":{"200":{"description":"Negocios autorizados.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"type":"object","example":{"total":1,"page":1,"limit":20,"total_pages":1}}}},"example":{"success":true,"data":[{"_id":"67f1f4c5b12e4d0c9a123456","name":"Comercio Demo SAC","payment_prefix":"DEMO","status":"PENDING_ACTIVATION"}]}}}}}},"post":{"summary":"Crear negocio","tags":["Businesses"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["business","config"],"properties":{"business":{"type":"object"},"config":{"type":"object"},"hooks":{"type":"array"}}},"example":{"business":{"name":"Comercio Demo SAC","payment_prefix":"DEMO"},"config":{"source_account":"000-0000000000","destination_account":"000-0000000000","destination_bank":"BANCO_DEMO"},"hooks":[{"type":"PAYMENT_PAID","url":"https://partner.example.com/hooks/360pay","active":true}]}}}},"responses":{"201":{"description":"Negocio creado; devuelve hook_signing_secrets una sola vez.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true},"message":{"type":"string"}}},"example":{"success":true,"data":{"success":true,"business_id":"67f1f4c5b12e4d0c9a123456","payment_prefix":"DEMO","config_id":"67f1f4c5b12e4d0c9a123457","hook_ids":["67f1f4c5b12e4d0c9a123458"],"hook_signing_secrets":[{"hook_id":"67f1f4c5b12e4d0c9a123458","signing_secret":"whsec_example_only_do_not_use"}]},"message":"Business created and linked to partner successfully"}}}},"400":{"description":"business y config son obligatorios."}}}},"/businesses/{id}":{"patch":{"summary":"Actualizar negocio","description":"No permite modificar status.","tags":["Businesses"],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"email":"admin@example.com"}}}},"responses":{"200":{"description":"Actualizado.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true},"message":{"type":"string"}}},"example":{"success":true,"message":"Negocio actualizado correctamente"}}}},"400":{"description":"status no permitido."},"403":{"description":"Negocio no autorizado."},"404":{"description":"No encontrado."}}}},"/businesses/{businessId}/hooks/{hookId}/rotate-secret":{"post":{"summary":"Rotar secreto HMAC","tags":["Businesses"],"parameters":[{"$ref":"#/components/parameters/BusinessId"},{"$ref":"#/components/parameters/HookId"}],"responses":{"200":{"description":"Devuelve el nuevo secreto una sola vez.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true},"message":{"type":"string"}}},"example":{"success":true,"data":{"_id":"67f1f4c5b12e4d0c9a123458","business_id":"67f1f4c5b12e4d0c9a123456","type":"PAYMENT_PAID","url":"https://partner.example.com/hooks/360pay","active":true,"signing_secret_preview":"whsec_exam..._use","signing_secret":"whsec_example_only_do_not_use"}}}}},"403":{"description":"No autorizado."},"404":{"description":"Hook no encontrado."}}}},"/customers":{"get":{"summary":"Listar clientes","tags":["Customers"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Lista paginada sin eliminados logicamente.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"type":"object","example":{"total":1,"page":1,"limit":20,"total_pages":1}}}},"example":{"success":true,"data":[{"_id":"67f2a7f4b12e4d0c9a987654","business_id":"67f1f4c5b12e4d0c9a123456","name":"Cliente Demo","email":"cliente@example.com","phone":"+51900000000","document_type":"DNI","document_number":"00000000","dob":null,"coupon_code":"DEMO0001","payment_code":"DEMO0001","account_status":-120.5,"pending_coupons":1,"created_at":"2026-04-01T15:20:00.000Z","updated_at":"2026-04-01T15:20:00.000Z"}],"meta":{"total":1,"page":1,"limit":20,"total_pages":1}}}}}}},"post":{"summary":"Crear cliente","tags":["Customers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"},"example":{"business_id":"67f1f4c5b12e4d0c9a123456","name":"Cliente Demo","coupon_code":"DEMO0001","email":"cliente@example.com"}}}},"responses":{"201":{"description":"Creado.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true},"message":{"type":"string"}}},"example":{"success":true,"data":{"_id":"67f2a7f4b12e4d0c9a987654","business_id":"67f1f4c5b12e4d0c9a123456","name":"Cliente Demo","email":"cliente@example.com","phone":"+51900000000","document_type":"DNI","document_number":"00000000","dob":null,"coupon_code":"DEMO0001","payment_code":"DEMO0001","account_status":-120.5,"pending_coupons":1,"created_at":"2026-04-01T15:20:00.000Z","updated_at":"2026-04-01T15:20:00.000Z"},"message":"Customer created successfully"}}}},"400":{"description":"name/coupon_code faltantes o prefijo invalido."}}}},"/customers/search":{"get":{"summary":"Buscar clientes","tags":["Customers"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"example":"demo"},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Busca en nombre, email, telefono, codigo y documento.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"type":"object","example":{"total":1,"page":1,"limit":20,"total_pages":1}}}},"example":{"success":true,"data":[{"_id":"67f2a7f4b12e4d0c9a987654","business_id":"67f1f4c5b12e4d0c9a123456","name":"Cliente Demo","email":"cliente@example.com","phone":"+51900000000","document_type":"DNI","document_number":"00000000","dob":null,"coupon_code":"DEMO0001","payment_code":"DEMO0001","account_status":-120.5,"pending_coupons":1,"created_at":"2026-04-01T15:20:00.000Z","updated_at":"2026-04-01T15:20:00.000Z"}],"meta":{"total":1,"page":1,"limit":20,"total_pages":1}}}}}}}},"/customers/bulk-upsert":{"post":{"summary":"Bulk upsert clientes","tags":["Customers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customers"],"properties":{"business_id":{"type":"string"},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}}},"example":{"business_id":"67f1f4c5b12e4d0c9a123456","customers":[{"name":"Cliente Demo","coupon_code":"DEMO0001"}]}}}},"responses":{"200":{"description":"Resultado por fila con processed, successes, failures y results.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true},"message":{"type":"string"}}},"example":{"success":true,"data":{"processed":1,"successes":1,"failures":0,"results":[{"index":0,"success":true,"action":"created","customer_id":"67f2a7f4b12e4d0c9a987654"}]}}}}}}}},"/customers/bulk-delete":{"post":{"summary":"Bulk delete clientes","tags":["Customers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customers"],"properties":{"customers":{"type":"array","items":{"type":"object","required":["customer_id"]}}}},"example":{"customers":[{"customer_id":"67f2a7f4b12e4d0c9a987654","reason":"Cuenta cerrada"}]}}}},"responses":{"200":{"description":"Eliminacion logica por fila.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true},"message":{"type":"string"}}},"example":{"success":true,"data":{"processed":1,"successes":1,"failures":0,"results":[{"index":0,"success":true,"customer_id":"67f2a7f4b12e4d0c9a987654"}]}}}}}}}},"/customers/{id}":{"get":{"summary":"Obtener cliente","tags":["Customers"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"67f2a7f4b12e4d0c9a987654"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true},"message":{"type":"string"}}},"example":{"success":true,"data":{"_id":"67f2a7f4b12e4d0c9a987654","business_id":"67f1f4c5b12e4d0c9a123456","name":"Cliente Demo","email":"cliente@example.com","phone":"+51900000000","document_type":"DNI","document_number":"00000000","dob":null,"coupon_code":"DEMO0001","payment_code":"DEMO0001","account_status":-120.5,"pending_coupons":1,"created_at":"2026-04-01T15:20:00.000Z","updated_at":"2026-04-01T15:20:00.000Z"}}}}},"404":{"description":"No encontrado."}}},"put":{"summary":"Actualizar cliente","tags":["Customers"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"67f2a7f4b12e4d0c9a987654"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"phone":"+51900000001"}}}},"responses":{"200":{"description":"Actualizado.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true},"message":{"type":"string"}}},"example":{"success":true,"data":{"_id":"67f2a7f4b12e4d0c9a987654","business_id":"67f1f4c5b12e4d0c9a123456","name":"Cliente Demo","email":"cliente@example.com","phone":"+51900000001","document_type":"DNI","document_number":"00000000","dob":null,"coupon_code":"DEMO0001","payment_code":"DEMO0001","account_status":-120.5,"pending_coupons":1,"created_at":"2026-04-01T15:20:00.000Z","updated_at":"2026-04-01T15:20:00.000Z"},"message":"Customer updated successfully"}}}}}},"delete":{"summary":"Eliminar cliente logicamente","tags":["Customers"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"67f2a7f4b12e4d0c9a987654"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Eliminado logicamente.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true},"message":{"type":"string"}}},"example":{"success":true,"message":"Customer deleted successfully"}}}},"404":{"description":"No encontrado."}}}},"/customers/{id}/coupons":{"get":{"summary":"Cupones del cliente","tags":["Customers"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"67f2a7f4b12e4d0c9a987654"},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Cupones paginados.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"type":"object","example":{"total":1,"page":1,"limit":20,"total_pages":1}}}},"example":{"success":true,"data":[{"_id":"67f3b100b12e4d0c9a222222","business_id":"67f1f4c5b12e4d0c9a123456","customer_id":"67f2a7f4b12e4d0c9a987654","coupon_code":"DEMO0001","customer_name":"Cliente Demo","external_ref":"ORDER-DEMO-0001","payment_reference":"DEMO0001","operation_number":null,"bank_tx_id":null,"amount":120.5,"description":"Servicio de ejemplo","status":"active","issue_date":"2026-04-01T15:20:00.000Z","expiry_date":"2026-04-30T23:59:59.000Z","payment_date":null,"paid_at":null,"settlement_id":null,"settlement_status":null,"fee_platform":null,"fee_partner":null,"created_at":"2026-04-01T15:20:00.000Z","updated_at":"2026-04-01T15:20:00.000Z"}],"meta":{"total":1,"page":1,"limit":20,"total_pages":1}}}}},"404":{"description":"Cliente no encontrado."}}}},"/coupons":{"get":{"summary":"Listar cupones","tags":["Coupons"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Incluye datos bancarios y fees cuando existen.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"type":"object","example":{"total":1,"page":1,"limit":20,"total_pages":1}}}},"example":{"success":true,"data":[{"_id":"67f3b100b12e4d0c9a222222","business_id":"67f1f4c5b12e4d0c9a123456","customer_id":"67f2a7f4b12e4d0c9a987654","coupon_code":"DEMO0001","customer_name":"Cliente Demo","external_ref":"ORDER-DEMO-0001","payment_reference":"DEMO0001","operation_number":null,"bank_tx_id":null,"amount":120.5,"description":"Servicio de ejemplo","status":"active","issue_date":"2026-04-01T15:20:00.000Z","expiry_date":"2026-04-30T23:59:59.000Z","payment_date":null,"paid_at":null,"settlement_id":null,"settlement_status":null,"fee_platform":null,"fee_partner":null,"created_at":"2026-04-01T15:20:00.000Z","updated_at":"2026-04-01T15:20:00.000Z"}],"meta":{"total":1,"page":1,"limit":20,"total_pages":1}}}}}}},"post":{"summary":"Crear cupon","tags":["Coupons"],"description":"Requiere amount, external_ref y expiry_date, más customer_id o code/coupon_code. business_id es obligatorio para API keys con varios negocios y se infiere cuando la API key tiene uno solo. Las etiquetas required cambian según la alternativa seleccionada.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CouponCreateRequest"},"examples":{"existingCustomer":{"summary":"API key multi-negocio: cliente existente","value":{"business_id":"67f1f4c5b12e4d0c9a123456","customer_id":"67f2a7f4b12e4d0c9a987654","amount":120.5,"expiry_date":"2026-04-30","external_ref":"ORDER-DEMO-0001"}},"customerByCode":{"summary":"API key multi-negocio: cliente mediante código","value":{"business_id":"67f1f4c5b12e4d0c9a123456","code":"DEMO0002","name":"Cliente Demo Dos","email":"cliente2@example.com","amount":85,"expiry_date":"2026-04-30","external_ref":"ORDER-DEMO-0002"}},"singleBusinessCustomerByCode":{"summary":"API key de un negocio: business_id inferido","value":{"code":"DEMO0003","name":"Cliente Demo Tres","email":"cliente3@example.com","amount":95,"expiry_date":"2026-04-30","external_ref":"ORDER-DEMO-0003"}}}}}},"responses":{"201":{"description":"Creado.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true},"message":{"type":"string"}}},"example":{"success":true,"data":{"_id":"67f3b100b12e4d0c9a222222","business_id":"67f1f4c5b12e4d0c9a123456","customer_id":"67f2a7f4b12e4d0c9a987654","coupon_code":"DEMO0001","customer_name":"Cliente Demo","external_ref":"ORDER-DEMO-0001","payment_reference":"DEMO0001","operation_number":null,"bank_tx_id":null,"amount":120.5,"description":"Servicio de ejemplo","status":"active","issue_date":"2026-04-01T15:20:00.000Z","expiry_date":"2026-04-30T23:59:59.000Z","payment_date":null,"paid_at":null,"settlement_id":null,"settlement_status":null,"fee_platform":null,"fee_partner":null,"created_at":"2026-04-01T15:20:00.000Z","updated_at":"2026-04-01T15:20:00.000Z"},"message":"Coupon created successfully"}}}},"400":{"description":"Faltan amount, external_ref, expiry_date, customer_id/code/coupon_code o business_id para una API key multi-negocio."},"409":{"description":"external_ref duplicado."}}}},"/coupons/metrics":{"get":{"summary":"Metricas de cupones","tags":["Coupons"],"responses":{"200":{"description":"Totales y desglose por status.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true},"message":{"type":"string"}}},"example":{"success":true,"data":{"total_amount":271.5,"total_count":3,"status_breakdown":{"active":{"count":2,"amount":211.5},"paid":{"count":1,"amount":60}}}}}}}}}},"/coupons/import":{"post":{"summary":"Importar cupones JSON o CSV","description":"JSON como array o { coupons: [...] }. CSV multipart con file y business_id. Headers: tipo_documento, cliente_id, documento_identidad, nombre_cliente, email_cliente, telefono_cliente, referencia_externa, monto, descripcion, fecha_expiracion, codigo_cupon.","tags":["Coupons"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"business_id":"67f1f4c5b12e4d0c9a123456","coupons":[{"amount":"120.50","external_ref":"ORDER-DEMO-0001","expiry_date":"2026-04-30","coupon_code":"DEMO0001","nombre_cliente":"Cliente Demo"}]}},"multipart/form-data":{"schema":{"type":"object","required":["file","business_id"],"properties":{"business_id":{"type":"string"},"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"Resultado parcial por lote.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true},"message":{"type":"string"}}},"example":{"success":true,"data":{"total":2,"success":1,"failed":1,"errors":[{"row":3,"error":"Monto invalido o faltante en la fila 3","data":{"monto":""}}]}}}}}}}},"/coupons/{id}":{"get":{"summary":"Obtener cupon","tags":["Coupons"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"67f2a7f4b12e4d0c9a987654"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true},"message":{"type":"string"}}},"example":{"success":true,"data":{"_id":"67f3b100b12e4d0c9a222222","business_id":"67f1f4c5b12e4d0c9a123456","customer_id":"67f2a7f4b12e4d0c9a987654","coupon_code":"DEMO0001","customer_name":"Cliente Demo","external_ref":"ORDER-DEMO-0001","payment_reference":"DEMO0001","operation_number":null,"bank_tx_id":null,"amount":120.5,"description":"Servicio de ejemplo","status":"active","issue_date":"2026-04-01T15:20:00.000Z","expiry_date":"2026-04-30T23:59:59.000Z","payment_date":null,"paid_at":null,"settlement_id":null,"settlement_status":null,"fee_platform":null,"fee_partner":null,"created_at":"2026-04-01T15:20:00.000Z","updated_at":"2026-04-01T15:20:00.000Z"}}}}},"404":{"description":"No encontrado."}}},"put":{"summary":"Actualizar cupon activo","description":"Solo amount, description, issue_date, expiry_date, payment_date y external_ref. No paid, voided ni liquidados.","tags":["Coupons"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"67f2a7f4b12e4d0c9a987654"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"amount":125,"external_ref":"ORDER-DEMO-0001-REV"}}}},"responses":{"200":{"description":"Actualizado.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true},"message":{"type":"string"}}},"example":{"success":true,"data":{"_id":"67f3b100b12e4d0c9a222222","business_id":"67f1f4c5b12e4d0c9a123456","customer_id":"67f2a7f4b12e4d0c9a987654","coupon_code":"DEMO0001","customer_name":"Cliente Demo","external_ref":"ORDER-DEMO-0001-REV","payment_reference":"DEMO0001","operation_number":null,"bank_tx_id":null,"amount":125,"description":"Servicio de ejemplo","status":"active","issue_date":"2026-04-01T15:20:00.000Z","expiry_date":"2026-04-30T23:59:59.000Z","payment_date":null,"paid_at":null,"settlement_id":null,"settlement_status":null,"fee_platform":null,"fee_partner":null,"created_at":"2026-04-01T15:20:00.000Z","updated_at":"2026-04-01T15:20:00.000Z"},"message":"Coupon updated successfully"}}}},"409":{"description":"Cupon no editable o referencia duplicada."}}}},"/coupons/{id}/annul":{"put":{"summary":"Anular cupon","description":"Solo active y no liquidado; cambia status a voided.","tags":["Coupons"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"67f2a7f4b12e4d0c9a987654"}],"responses":{"200":{"description":"Anulado.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":true},"message":{"type":"string"}}},"example":{"success":true,"data":{"_id":"67f3b100b12e4d0c9a222222","status":"voided"},"message":"Coupon annulled successfully"}}}},"409":{"description":"Solo cupones active no liquidados."}}}},"/settlements":{"get":{"summary":"Listar settlements","tags":["Settlements"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Incluye business y meta.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"type":"object","example":{"total":1,"page":1,"limit":20,"total_pages":1}}}},"example":{"success":true,"data":[{"_id":"67f4c1a2b12e4d0c9a111111","business_id":"67f1f4c5b12e4d0c9a123456","partner_id":"67f0a1b2c3d4e5f607182930","source_account":"000-0000000000","destination_account":"000-0000000000","destination_bank":"BANCO_DEMO","coupons_count":1,"total_amount":120.5,"commission_amount":3.62,"partner_fee_amount":1.2,"total_paid":116.88,"status":"COMPLETED","transaction_date":"2026-05-01T15:20:00.000Z","bank_transaction_id":"TX-DEMO-0001","batch_id":"BATCH-DEMO-0001","created_at":"2026-05-01T15:00:00.000Z","business":{"_id":"67f1f4c5b12e4d0c9a123456","name":"Comercio Demo SAC","payment_prefix":"DEMO","status":"PENDING_ACTIVATION"}}],"meta":{"total":1,"page":1,"limit":20,"total_pages":1}}}}}}}},"/settlements/{id}":{"get":{"summary":"Obtener settlement por ID o batch_id","tags":["Settlements"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"67f2a7f4b12e4d0c9a987654"}],"responses":{"200":{"description":"data es un array, incluso para un ID.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"type":"object","example":{"total":1,"page":1,"limit":20,"total_pages":1}}}},"example":{"success":true,"data":[{"_id":"67f4c1a2b12e4d0c9a111111","business_id":"67f1f4c5b12e4d0c9a123456","partner_id":"67f0a1b2c3d4e5f607182930","source_account":"000-0000000000","destination_account":"000-0000000000","destination_bank":"BANCO_DEMO","coupons_count":1,"total_amount":120.5,"commission_amount":3.62,"partner_fee_amount":1.2,"total_paid":116.88,"status":"COMPLETED","transaction_date":"2026-05-01T15:20:00.000Z","bank_transaction_id":"TX-DEMO-0001","batch_id":"BATCH-DEMO-0001","created_at":"2026-05-01T15:00:00.000Z","business":{"_id":"67f1f4c5b12e4d0c9a123456","name":"Comercio Demo SAC","payment_prefix":"DEMO","status":"PENDING_ACTIVATION"}}]}}}},"404":{"description":"No encontrado o no autorizado."}}}},"/settlements/{id}/coupons":{"get":{"summary":"Cupones de settlement","tags":["Settlements"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"67f2a7f4b12e4d0c9a987654"},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Cupones paginados con referencias bancarias cuando existen.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"type":"object","example":{"total":1,"page":1,"limit":20,"total_pages":1}}}},"example":{"success":true,"data":[{"_id":"67f3b100b12e4d0c9a222222","business_id":"67f1f4c5b12e4d0c9a123456","customer_id":"67f2a7f4b12e4d0c9a987654","coupon_code":"DEMO0001","customer_name":"Cliente Demo","external_ref":"ORDER-DEMO-0001","payment_reference":"DEMO0001","operation_number":"OP-DEMO-0001","bank_tx_id":"TX-DEMO-0001","amount":120.5,"description":"Servicio de ejemplo","status":"paid","issue_date":"2026-04-01T15:20:00.000Z","expiry_date":"2026-04-30T23:59:59.000Z","payment_date":null,"paid_at":null,"settlement_id":"67f4c1a2b12e4d0c9a111111","settlement_status":"COMPLETED","fee_platform":null,"fee_partner":null,"created_at":"2026-04-01T15:20:00.000Z","updated_at":"2026-04-01T15:20:00.000Z"}],"meta":{"total":1,"page":1,"limit":20,"total_pages":1}}}}},"404":{"description":"No encontrado o no autorizado."}}}}},"x-tagGroups":[{"name":"Partner","tags":["Businesses","Customers","Coupons","Settlements"]}]}