{"openapi":"3.0.0","info":{"title":"360Pay Public API","version":"1.1.0","description":"API publica para gestion de clientes, cupones y liquidaciones de un negocio autenticado con API key. Los endpoints de /tickets permanecen por compatibilidad y estan marcados como deprecados (legacy)."},"servers":[{"url":"https://api.360pay.pe/v1","description":"Produccion"},{"url":"https://sandbox.api.360pay.pe/v1","description":"Sandbox"}],"tags":[{"name":"Customers","description":"Gestion de clientes."},{"name":"Coupons","description":"Gestion de cupones."},{"name":"Settlements","description":"Consulta de liquidaciones."},{"name":"Tickets (Legacy)","description":"Endpoints legacy de tickets. Deprecados; usar customers/coupons/settlements."}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"},"ApiKeyBearer":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"parameters":{"IdPathParam":{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"ID del recurso."},"PageQuery":{"in":"query","name":"page","required":false,"schema":{"type":"integer","minimum":1,"default":1}},"LimitQuery":{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10}}},"schemas":{"GenericError":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message"}},"required":["success","error"],"example":{"success":false,"error":"Cliente no encontrado"}},"GenericSuccess":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":{}},"message":{"type":"string"}},"required":["success","data"],"example":{"success":true,"data":{"_id":"665b1b4f0f8a4f0012c3d600","business_id":"665a9f9f0f8a4f0012c3d456","contact_id":"665b1a3f0f8a4f0012c3d500","coupon_code":"EMP1001-0001","external_ref":"ORD-9988","amount":150.5,"status":"paid","paid_at":"2026-06-10T18:35:10.000Z","bank_tx_id":"BCP","fee_platform":3,"created_at":"2026-06-10T12:00:00.000Z","updated_at":"2026-06-10T18:35:10.000Z"},"message":"Operacion exitosa"}},"GenericListSuccess":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","additionalProperties":{}}},"meta":{"type":"object","properties":{"total":{"type":"number","example":15},"page":{"type":"number","example":1},"limit":{"type":"number","example":10},"total_pages":{"type":"number","example":2}},"required":["total","page","limit","total_pages"]}},"required":["success","data","meta"],"example":{"success":true,"data":[{"_id":"665b1a3f0f8a4f0012c3d500","business_id":"665a9f9f0f8a4f0012c3d456","name":"Juan Perez","email":"juan@example.com","phone":"+51987654321","document_type":"DNI","document_number":"12345678","coupon_code":"EMP1001","pending_coupons":2,"created_at":"2026-06-01T10:00:00.000Z","updated_at":"2026-06-10T09:15:00.000Z"}],"meta":{"total":15,"page":1,"limit":10,"total_pages":2}}},"CustomerInput":{"type":"object","properties":{"name":{"type":"string","example":"Juan Perez"},"email":{"type":"string","example":"juan@example.com"},"phone":{"type":"string","example":"+51987654321"},"document_type":{"type":"string","example":"DNI"},"document_number":{"type":"string","example":"12345678"},"dob":{"type":"string","format":"date-time"},"coupon_code":{"type":"string","example":"EMP1001"}},"required":["name","coupon_code"],"additionalProperties":{}},"CustomerUpdateInput":{"type":"object","properties":{"name":{"type":"string","example":"Juan Perez"},"email":{"type":"string","example":"juan@example.com"},"phone":{"type":"string","example":"+51987654321"},"document_type":{"type":"string","example":"DNI"},"document_number":{"type":"string","example":"12345678"},"dob":{"type":"string","format":"date-time"},"coupon_code":{"type":"string","example":"EMP1001"}},"additionalProperties":{}},"CouponCustomerInput":{"type":"object","properties":{"name":{"type":"string","example":"Juan Perez"},"email":{"type":"string","example":"juan@example.com"},"phone":{"type":"string","example":"+51987654321"},"document_type":{"type":"string","example":"DNI"},"document_number":{"type":"string","example":"12345678"},"dob":{"type":"string","format":"date-time"},"coupon_code":{"type":"string","example":"EMP1001"}},"required":["name","coupon_code"],"additionalProperties":{}},"CouponInput":{"type":"object","properties":{"contact_id":{"type":"string","description":"Cliente existente. Si no se envia, se puede adjuntar `customer` para crear o resolver el cliente en la misma llamada."},"customer":{"allOf":[{"$ref":"#/components/schemas/CouponCustomerInput"}],"description":"Datos del contacto para crear su primer cupon en una sola llamada cuando aun no existe contact_id."},"amount":{"type":"number","example":150.5},"external_ref":{"type":"string","example":"ORD-9988","description":"Referencia externa unica por negocio. Si se omite, se genera una automaticamente."},"description":{"type":"string","example":"Pago de membresia"},"issue_date":{"type":"string","format":"date-time"},"expiry_date":{"type":"string","format":"date-time"},"payment_date":{"type":"string","format":"date-time"}},"required":["amount"],"additionalProperties":{}},"CouponUpdateInput":{"type":"object","properties":{"status":{"type":"string","example":"paid"},"paid_at":{"type":"string","format":"date-time"},"payment_date":{"type":"string","format":"date-time"},"bank_tx_id":{"type":"string","example":"BCP"},"operation_number":{"type":"string","example":"OP-12345"},"external_ref":{"type":"string","example":"ORD-9988"}},"additionalProperties":{}}}},"security":[{"ApiKeyAuth":[]},{"ApiKeyBearer":[]}],"paths":{"/tickets":{"post":{"deprecated":true,"summary":"[Deprecated] Crear ticket","description":"Endpoint legacy. Migrar a POST /coupons para nuevas integraciones.","tags":["Tickets (Legacy)"],"responses":{"201":{"description":"Ticket creado correctamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"},"example":{"success":true,"data":{"ticket_id":"665b1b4f0f8a4f0012c3d600","code":"EMP1001-0001","external_ref":"ORD-9988","status":"active","amount":150.5,"due_date":"2026-06-20T23:59:59.000Z","created_at":"2026-06-12T15:20:30.000Z"}}}}},"401":{"description":"API key invalida o ausente."}}}},"/tickets/search":{"get":{"deprecated":true,"summary":"[Deprecated] Buscar ticket por referencia externa","description":"Endpoint legacy. Migrar a GET /coupons con filtros segun el caso.","tags":["Tickets (Legacy)"],"responses":{"200":{"description":"Ticket encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"},"example":{"success":true,"data":{"ticket_id":"665b1b4f0f8a4f0012c3d600","code":"EMP1001-0001","external_ref":"ORD-9988","status":"paid","amount":150.5,"due_date":"2026-06-20T23:59:59.000Z","paid_at":"2026-06-12T18:35:10.000Z","bank_tx_id":"BCP","created_at":"2026-06-12T15:20:30.000Z","updated_at":"2026-06-12T18:35:10.000Z"}}}}},"404":{"description":"Ticket no encontrado."}}}},"/tickets/{id}":{"get":{"deprecated":true,"summary":"[Deprecated] Obtener ticket por ID","description":"Endpoint legacy. Migrar a GET /coupons/{id}.","tags":["Tickets (Legacy)"],"parameters":[{"$ref":"#/components/parameters/IdPathParam"}],"responses":{"200":{"description":"Ticket encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"},"example":{"success":true,"data":{"ticket_id":"665b1b4f0f8a4f0012c3d600","code":"EMP1001-0001","external_ref":"ORD-9988","status":"paid","amount":150.5,"due_date":"2026-06-20T23:59:59.000Z","paid_at":"2026-06-12T18:35:10.000Z","bank_tx_id":"BCP","created_at":"2026-06-12T15:20:30.000Z","updated_at":"2026-06-12T18:35:10.000Z"}}}}},"404":{"description":"Ticket no encontrado."}}},"delete":{"deprecated":true,"summary":"[Deprecated] Anular ticket","description":"Endpoint legacy. Migrar a PUT /coupons/{id}/annul.","tags":["Tickets (Legacy)"],"parameters":[{"$ref":"#/components/parameters/IdPathParam"}],"responses":{"200":{"description":"Ticket anulado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"},"example":{"success":true,"data":{"code":"EMP1001-0001","external_ref":"ORD-9988","status":"voided","cancelled_at":"2026-06-12T19:10:00.000Z"}}}}},"404":{"description":"Ticket no encontrado."},"409":{"description":"Solo tickets activos pueden anularse."}}}},"/customers":{"get":{"summary":"Listar clientes","tags":["Customers"],"parameters":[{"$ref":"#/components/parameters/PageQuery"},{"$ref":"#/components/parameters/LimitQuery"}],"responses":{"200":{"description":"Listado obtenido correctamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListSuccess"},"example":{"success":true,"data":[{"_id":"665b1a3f0f8a4f0012c3d500","business_id":"665a9f9f0f8a4f0012c3d456","name":"Juan Perez","email":"juan@example.com","phone":"+51987654321","document_type":"DNI","document_number":"12345678","coupon_code":"EMP1001","pending_coupons":2,"created_at":"2026-06-01T10:00:00.000Z","updated_at":"2026-06-10T09:15:00.000Z"}],"meta":{"total":15,"page":1,"limit":10,"total_pages":2}}}}},"401":{"description":"API key invalida o ausente."}}},"post":{"summary":"Crear cliente","tags":["Customers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerInput"}}}},"responses":{"201":{"description":"Cliente creado correctamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"},"example":{"success":true,"data":{"_id":"665b1a3f0f8a4f0012c3d500","business_id":"665a9f9f0f8a4f0012c3d456","name":"Juan Perez","email":"juan@example.com","phone":"+51987654321","document_type":"DNI","document_number":"12345678","coupon_code":"EMP1001","created_at":"2026-06-12T15:20:30.000Z","updated_at":"2026-06-12T15:20:30.000Z"},"message":"Customer created successfully"}}}},"400":{"description":"Payload invalido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericError"}}}},"401":{"description":"API key invalida o ausente."}}}},"/customers/search":{"get":{"summary":"Buscar clientes","tags":["Customers"],"parameters":[{"$ref":"#/components/parameters/PageQuery"},{"in":"query","name":"q","required":false,"schema":{"type":"string"},"description":"Omnisearch por nombre, email, telefono, coupon_code o documento."}],"responses":{"200":{"description":"Resultado de busqueda.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListSuccess"},"example":{"success":true,"data":[{"_id":"665b1a3f0f8a4f0012c3d500","business_id":"665a9f9f0f8a4f0012c3d456","name":"Juan Perez","email":"juan@example.com","phone":"+51987654321","coupon_code":"EMP1001","pending_coupons":2}],"meta":{"total":1,"page":1,"limit":10,"total_pages":1}}}}},"401":{"description":"API key invalida o ausente."}}}},"/customers/{id}":{"get":{"summary":"Obtener cliente por ID","tags":["Customers"],"parameters":[{"$ref":"#/components/parameters/IdPathParam"}],"responses":{"200":{"description":"Cliente encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"},"example":{"success":true,"data":{"_id":"665b1a3f0f8a4f0012c3d500","business_id":"665a9f9f0f8a4f0012c3d456","name":"Juan Perez","email":"juan@example.com","phone":"+51987654321","document_type":"DNI","document_number":"12345678","coupon_code":"EMP1001","pending_coupons":2,"created_at":"2026-06-01T10:00:00.000Z","updated_at":"2026-06-10T09:15:00.000Z"}}}}},"404":{"description":"Cliente no encontrado."}}},"put":{"summary":"Actualizar cliente","tags":["Customers"],"parameters":[{"$ref":"#/components/parameters/IdPathParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerUpdateInput"}}}},"responses":{"200":{"description":"Cliente actualizado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"},"example":{"success":true,"data":{"_id":"665b1a3f0f8a4f0012c3d500","business_id":"665a9f9f0f8a4f0012c3d456","name":"Juan Perez Actualizado","email":"juan@example.com","phone":"+51987654321","coupon_code":"EMP1001","updated_at":"2026-06-12T16:10:00.000Z"},"message":"Customer updated successfully"}}}},"404":{"description":"Cliente no encontrado."}}},"delete":{"summary":"Eliminar cliente","tags":["Customers"],"parameters":[{"$ref":"#/components/parameters/IdPathParam"}],"responses":{"200":{"description":"Cliente eliminado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"},"example":{"success":true,"data":{"deleted_count":1},"message":"Customer deleted successfully"}}}},"404":{"description":"Cliente no encontrado."}}}},"/customers/{id}/coupons":{"get":{"summary":"Listar cupones de cliente","tags":["Customers"],"parameters":[{"$ref":"#/components/parameters/IdPathParam"},{"$ref":"#/components/parameters/PageQuery"},{"$ref":"#/components/parameters/LimitQuery"}],"responses":{"200":{"description":"Listado obtenido correctamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListSuccess"},"example":{"success":true,"data":[{"_id":"665b1b4f0f8a4f0012c3d600","contact_id":"665b1a3f0f8a4f0012c3d500","coupon_code":"EMP1001-0001","external_ref":"ORD-9988","amount":150.5,"status":"paid","paid_at":"2026-06-12T18:35:10.000Z","bank_tx_id":"BCP","fee_platform":3}],"meta":{"total":2,"page":1,"limit":10,"total_pages":1}}}}},"404":{"description":"Cliente no encontrado."}}}},"/coupons":{"get":{"summary":"Listar cupones","tags":["Coupons"],"parameters":[{"$ref":"#/components/parameters/PageQuery"},{"$ref":"#/components/parameters/LimitQuery"}],"responses":{"200":{"description":"Listado obtenido correctamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListSuccess"},"example":{"success":true,"data":[{"_id":"665b1b4f0f8a4f0012c3d600","business_id":"665a9f9f0f8a4f0012c3d456","contact_id":"665b1a3f0f8a4f0012c3d500","coupon_code":"EMP1001-0001","external_ref":"ORD-9988","amount":150.5,"status":"active","created_at":"2026-06-12T15:20:30.000Z"}],"meta":{"total":20,"page":1,"limit":10,"total_pages":2}}}}}}},"post":{"summary":"Crear cupon","tags":["Coupons"],"description":"Acepta un `contact_id` existente o un objeto `customer` para crear o resolver al contacto y emitir su primer cupon en una sola llamada.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CouponInput"},"examples":{"existingCustomer":{"summary":"Crear cupon para cliente existente","value":{"contact_id":"665b1a3f0f8a4f0012c3d500","amount":150.5,"external_ref":"ORD-9988","description":"Pago de membresia"}},"firstCoupon":{"summary":"Crear cliente y primer cupon","value":{"customer":{"name":"Juan Perez","email":"juan@example.com","phone":"+51987654321","document_type":"DNI","document_number":"12345678","coupon_code":"EMP1001"},"amount":150.5,"external_ref":"ORD-9988","description":"Primer pago"}}}}}},"responses":{"201":{"description":"Cupon creado correctamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"},"example":{"success":true,"data":{"_id":"665b1b4f0f8a4f0012c3d600","business_id":"665a9f9f0f8a4f0012c3d456","contact_id":"665b1a3f0f8a4f0012c3d500","coupon_code":"EMP1001-0001","external_ref":"ORD-9988","amount":150.5,"status":"active","issue_date":"2026-06-12T15:20:30.000Z","expiry_date":"2026-06-20T23:59:59.000Z","created_at":"2026-06-12T15:20:30.000Z","updated_at":"2026-06-12T15:20:30.000Z"},"message":"Coupon created successfully"}}}},"400":{"description":"Payload invalido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericError"}}}}}}},"/coupons/{id}":{"get":{"summary":"Obtener cupon por ID","tags":["Coupons"],"parameters":[{"$ref":"#/components/parameters/IdPathParam"}],"responses":{"200":{"description":"Cupon encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"},"example":{"success":true,"data":{"_id":"665b1b4f0f8a4f0012c3d600","business_id":"665a9f9f0f8a4f0012c3d456","contact_id":"665b1a3f0f8a4f0012c3d500","coupon_code":"EMP1001-0001","external_ref":"ORD-9988","amount":150.5,"status":"paid","paid_at":"2026-06-12T18:35:10.000Z","bank_tx_id":"BCP","fee_platform":3,"created_at":"2026-06-12T15:20:30.000Z","updated_at":"2026-06-12T18:35:10.000Z"}}}}},"404":{"description":"Cupon no encontrado."}}},"put":{"summary":"Actualizar cupon","tags":["Coupons"],"parameters":[{"$ref":"#/components/parameters/IdPathParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CouponUpdateInput"}}}},"responses":{"200":{"description":"Cupon actualizado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"},"example":{"success":true,"data":{"_id":"665b1b4f0f8a4f0012c3d600","status":"paid","paid_at":"2026-06-12T18:35:10.000Z","bank_tx_id":"BCP","operation_number":"OP-12345","updated_at":"2026-06-12T18:35:10.000Z"},"message":"Coupon updated successfully"}}}},"404":{"description":"Cupon no encontrado."}}}},"/coupons/{id}/annul":{"put":{"summary":"Anular cupon","tags":["Coupons"],"parameters":[{"$ref":"#/components/parameters/IdPathParam"}],"responses":{"200":{"description":"Cupon anulado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"},"example":{"success":true,"data":{"_id":"665b1b4f0f8a4f0012c3d600","status":"voided","updated_at":"2026-06-12T19:10:00.000Z"},"message":"Coupon annulled successfully"}}}},"404":{"description":"Cupon no encontrado."},"409":{"description":"Solo cupones activos pueden anularse."}}}},"/settlements":{"get":{"summary":"Listar liquidaciones","tags":["Settlements"],"parameters":[{"$ref":"#/components/parameters/PageQuery"},{"$ref":"#/components/parameters/LimitQuery"}],"responses":{"200":{"description":"Listado de liquidaciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListSuccess"},"example":{"success":true,"data":[{"_id":"665c10000f8a4f0012c3d999","business_id":"665a9f9f0f8a4f0012c3d456","settlement_date":"2026-06-12T23:59:59.000Z","status":"completed","coupons_count":30,"gross_amount":4520.75,"fee_platform":90.42,"net_amount":4430.33,"created_at":"2026-06-13T01:00:00.000Z"}],"meta":{"total":1,"page":1,"limit":10,"total_pages":1}}}}}}}},"/settlements/{id}":{"get":{"summary":"Obtener liquidacion por ID","tags":["Settlements"],"parameters":[{"$ref":"#/components/parameters/IdPathParam"}],"responses":{"200":{"description":"Liquidacion encontrada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"},"example":{"success":true,"data":{"_id":"665c10000f8a4f0012c3d999","business_id":"665a9f9f0f8a4f0012c3d456","settlement_date":"2026-06-12T23:59:59.000Z","status":"completed","coupons_count":30,"gross_amount":4520.75,"fee_platform":90.42,"net_amount":4430.33,"created_at":"2026-06-13T01:00:00.000Z","updated_at":"2026-06-13T01:05:00.000Z"}}}}},"404":{"description":"Liquidacion no encontrada."}}}},"/settlements/{id}/coupons":{"get":{"summary":"Listar cupones de una liquidacion","tags":["Settlements"],"parameters":[{"$ref":"#/components/parameters/IdPathParam"},{"$ref":"#/components/parameters/PageQuery"},{"$ref":"#/components/parameters/LimitQuery"}],"responses":{"200":{"description":"Listado de cupones de la liquidacion.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListSuccess"},"example":{"success":true,"data":[{"_id":"665b1b4f0f8a4f0012c3d600","settlement_id":"665c10000f8a4f0012c3d999","coupon_code":"EMP1001-0001","external_ref":"ORD-9988","amount":150.5,"status":"paid","paid_at":"2026-06-12T18:35:10.000Z","bank_tx_id":"BCP","fee_platform":3}],"meta":{"total":30,"page":1,"limit":10,"total_pages":3}}}}},"404":{"description":"Liquidacion no encontrada."}}}}}}