{"openapi":"3.0.0","info":{"title":"360Pay Partner API","version":"1.0.0","description":"API para integraciones de partners (gestiona negocios, clientes, cupones y settlements dentro del scope permitido por la API key). Los partners pueden configurar hooks al crear negocios; la guía de webhooks está disponible en /docs/webhooks.","contact":{"name":"Soporte 360Pay","email":"soporte@360pay.com"}},"externalDocs":{"description":"Centro de documentación 360Pay","url":"/docs"},"servers":[{"url":"https://api.360pay.pe/partners/v1","description":"Produccion"},{"url":"https://sandbox.api.360pay.pe/partners/v1","description":"Sandbox"}],"tags":[{"name":"Businesses","description":"Gestion de negocios del partner."},{"name":"Customers","description":"Gestion de clientes del partner."},{"name":"Coupons","description":"Gestion de cupones del partner."},{"name":"Settlements","description":"Consulta de settlements del partner."}],"x-tagGroups":[{"name":"Partner","tags":["Businesses","Customers","Coupons","Settlements"]}],"components":{"securitySchemes":{"PartnerApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key"},"PartnerApiKeyBearer":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"parameters":{"IdPathParam":{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"ID del recurso."},"BusinessIdPathParam":{"in":"path","name":"businessId","required":true,"schema":{"type":"string"},"description":"ID del negocio autorizado para el partner."},"HookIdPathParam":{"in":"path","name":"hookId","required":true,"schema":{"type":"string"},"description":"ID del webhook del negocio."}},"schemas":{"GenericSuccess":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":{}},"message":{"type":"string"}},"required":["success","data"]},"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"]},"GenericError":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Error message description"},"required_scopes":{"type":"array","items":{"type":"string"}}},"required":["success","error"]},"PartnerCouponCreateInput":{"type":"object","properties":{"business_id":{"type":"string","description":"Negocio destino. Requerido cuando la API key del partner tiene acceso a mas de un negocio."},"contact_id":{"type":"string","description":"Cliente existente del negocio."},"code":{"type":"string","example":"EMP1001","description":"Codigo de cupon del cliente (alias: coupon_code). Requerido si no se envia contact_id."},"coupon_code":{"type":"string","description":"Alias de `code`."},"name":{"type":"string","description":"Nombre del cliente cuando se crea junto al cupon."},"email":{"type":"string"},"phone":{"type":"string"},"document_type":{"type":"string","example":"DNI"},"document_number":{"type":"string"},"amount":{"type":"number","example":150.5},"external_ref":{"type":"string","example":"ORD-9988"},"description":{"type":"string"},"issue_date":{"type":"string","format":"date-time"},"expiry_date":{"type":"string","format":"date-time"},"payment_reference":{"type":"string"}},"required":["amount","external_ref","expiry_date"],"additionalProperties":{}},"PartnerCouponUpdateInput":{"type":"object","properties":{"amount":{"type":"number","example":150.5},"description":{"type":"string"},"issue_date":{"type":"string","format":"date-time"},"expiry_date":{"type":"string","format":"date-time"},"payment_date":{"type":"string","format":"date-time"},"external_ref":{"type":"string","example":"ORD-9988"}},"additionalProperties":{}},"CreateBusinessRequest":{"type":"object","properties":{"business":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Mi Empresa SAC"},"email":{"type":"string","format":"email","example":"ops@miempresa.com"},"payment_prefix":{"type":"string","example":"EMP"}},"additionalProperties":true},"config":{"type":"object","properties":{"source_account":{"type":"string"},"destination_account":{"type":"string"},"destination_bank":{"type":"string"},"commission_fixed_amount":{"type":"number"},"commission_tiers":{"type":"array","items":{"type":"object","properties":{"limit":{"type":"number"},"amount":{"type":"number"}}}},"partner_fee_override":{"type":"object","properties":{"percentage":{"type":"number"},"min_fixed_amount":{"type":"number"}}}},"additionalProperties":true},"hooks":{"description":"Webhooks que se crearán junto con el negocio. Si se envían hooks, la respuesta incluye hook_signing_secrets una sola vez para verificar firmas HMAC. Ver /docs/webhooks.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","example":"PAYMENT_PAID"},"url":{"type":"string","format":"uri"},"headers":{"type":"object","additionalProperties":{"type":"string"}},"include_unmapped_fields":{"type":"boolean"},"payload_mapping":{"type":"object","additionalProperties":{"type":"string"}},"additional_fields":{"type":"object","additionalProperties":{}},"active":{"type":"boolean"}},"required":["type","url"]}}},"required":["business","config"],"additionalProperties":{}},"CreateBusinessResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean","example":true},"business_id":{"type":"string","example":"665a9f9f0f8a4f0012c3d456"},"payment_prefix":{"type":"string","example":"EMP"},"config_id":{"type":"string","example":"665aa0040f8a4f0012c3d457"},"hook_ids":{"type":"array","items":{"type":"string"},"example":["665aa0100f8a4f0012c3d458"]},"hook_signing_secrets":{"type":"array","items":{"type":"object","properties":{"hook_id":{"type":"string","example":"665aa0100f8a4f0012c3d458"},"signing_secret":{"type":"string","example":"whsec_VsLSN43xjcHqk4UoW6Fv5P8v3v8YGxQ2pLkV9fR8y1A"}},"required":["hook_id","signing_secret"]},"description":"Secretos HMAC generados para los hooks creados. Se muestran una sola vez; guárdalos en el backend del partner."}},"required":["success","business_id","payment_prefix","config_id","hook_ids","hook_signing_secrets"]},"message":{"type":"string","example":"Business created and linked to partner successfully"}},"required":["success","data","message"]},"RotateHookSecretResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"_id":{"type":"string","example":"665aa0100f8a4f0012c3d458"},"business_id":{"type":"string","example":"665a9f9f0f8a4f0012c3d456"},"type":{"type":"string","example":"PAYMENT_PAID"},"url":{"type":"string","format":"uri","example":"https://api.partner.com/webhooks/360pay"},"active":{"type":"boolean","example":true},"signing_secret_preview":{"type":"string","example":"whsec_dF7a...Q9p"},"signing_secret":{"type":"string","description":"Nuevo secreto HMAC. Se muestra una sola vez y debe guardarse en el backend del partner.","example":"whsec_dF7abpQ1Lk2N9s4xRxu6Qv6M0h3J6zK5uGfQ9p"}},"required":["_id","business_id","type","url","active","signing_secret_preview","signing_secret"]}},"required":["success","data"]}}},"security":[{"PartnerApiKeyHeader":[]},{"PartnerApiKeyBearer":[]}],"paths":{"/businesses":{"get":{"summary":"Listar negocios del partner","tags":["Businesses"],"responses":{"200":{"description":"Listado obtenido correctamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"}}}},"401":{"description":"API key invalida o ausente."},"403":{"description":"Scope insuficiente (businesses:read)."}}},"post":{"summary":"Crear negocio para el partner","tags":["Businesses"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBusinessRequest"}}}},"responses":{"201":{"description":"Negocio creado y vinculado al partner. Si se enviaron hooks, hook_signing_secrets incluye los secretos HMAC y solo se muestra en esta respuesta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBusinessResponse"},"example":{"success":true,"data":{"success":true,"business_id":"665a9f9f0f8a4f0012c3d456","payment_prefix":"EMP","config_id":"665aa0040f8a4f0012c3d457","hook_ids":["665aa0100f8a4f0012c3d458"],"hook_signing_secrets":[{"hook_id":"665aa0100f8a4f0012c3d458","signing_secret":"whsec_VsLSN43xjcHqk4UoW6Fv5P8v3v8YGxQ2pLkV9fR8y1A"}]},"message":"Business created and linked to partner successfully"}}}},"400":{"description":"Payload invalido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericError"}}}},"401":{"description":"API key invalida o ausente."},"403":{"description":"Scope insuficiente (businesses:write)."}}}},"/businesses/{businessId}/hooks/{hookId}/rotate-secret":{"post":{"summary":"Rotar secreto de webhook de un negocio","description":"Genera un nuevo signing_secret para un webhook de un negocio autorizado para el partner. El secreto completo solo se muestra en esta respuesta.","tags":["Businesses"],"parameters":[{"$ref":"#/components/parameters/BusinessIdPathParam"},{"$ref":"#/components/parameters/HookIdPathParam"}],"responses":{"200":{"description":"Secreto rotado correctamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotateHookSecretResponse"},"example":{"success":true,"data":{"_id":"665aa0100f8a4f0012c3d458","business_id":"665a9f9f0f8a4f0012c3d456","type":"PAYMENT_PAID","url":"https://api.partner.com/webhooks/360pay","active":true,"signing_secret_preview":"whsec_dF7a...Q9p","signing_secret":"whsec_dF7abpQ1Lk2N9s4xRxu6Qv6M0h3J6zK5uGfQ9p"}}}}},"401":{"description":"API key invalida o ausente."},"403":{"description":"Scope insuficiente o negocio no autorizado."},"404":{"description":"Webhook no encontrado para el negocio."}}}},"/customers":{"get":{"summary":"Listar clientes","tags":["Customers"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListSuccess"}}}}}},"post":{"summary":"Crear cliente","tags":["Customers"],"responses":{"201":{"description":"Creado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"}}}}}}},"/customers/search":{"get":{"summary":"Buscar clientes","tags":["Customers"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListSuccess"}}}}}}},"/customers/bulk-upsert":{"post":{"summary":"Bulk upsert de clientes","tags":["Customers"],"responses":{"200":{"description":"Procesado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"}}}}}}},"/customers/bulk-delete":{"post":{"summary":"Bulk delete de clientes","tags":["Customers"],"responses":{"200":{"description":"Procesado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"}}}}}}},"/customers/{id}":{"get":{"summary":"Obtener cliente por ID","tags":["Customers"],"parameters":[{"$ref":"#/components/parameters/IdPathParam"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"}}}}}},"put":{"summary":"Actualizar cliente","tags":["Customers"],"parameters":[{"$ref":"#/components/parameters/IdPathParam"}],"responses":{"200":{"description":"Actualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"}}}}}},"delete":{"summary":"Eliminar cliente","tags":["Customers"],"parameters":[{"$ref":"#/components/parameters/IdPathParam"}],"responses":{"200":{"description":"Eliminado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"}}}}}}},"/customers/{id}/coupons":{"get":{"summary":"Listar cupones de cliente","tags":["Customers"],"parameters":[{"$ref":"#/components/parameters/IdPathParam"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListSuccess"}}}}}}},"/coupons":{"get":{"summary":"Listar cupones","tags":["Coupons"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListSuccess"}}}}}},"post":{"summary":"Crear cupon","tags":["Coupons"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCouponCreateInput"}}}},"responses":{"201":{"description":"Creado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"}}}},"400":{"description":"Payload invalido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericError"}}}}}}},"/coupons/metrics":{"get":{"summary":"Metricas de cupones","tags":["Coupons"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"}}}}}}},"/coupons/import":{"post":{"summary":"Importar cupones","tags":["Coupons"],"responses":{"200":{"description":"Importacion procesada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"}}}}}}},"/coupons/{id}":{"get":{"summary":"Obtener cupon por ID","tags":["Coupons"],"parameters":[{"$ref":"#/components/parameters/IdPathParam"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"}}}}}},"put":{"summary":"Actualizar cupon","tags":["Coupons"],"parameters":[{"$ref":"#/components/parameters/IdPathParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCouponUpdateInput"}}}},"responses":{"200":{"description":"Actualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"}}}},"400":{"description":"Payload invalido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericError"}}}}}}},"/coupons/{id}/annul":{"put":{"summary":"Anular cupon","tags":["Coupons"],"parameters":[{"$ref":"#/components/parameters/IdPathParam"}],"responses":{"200":{"description":"Anulado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"}}}}}}},"/settlements":{"get":{"summary":"Listar settlements","tags":["Settlements"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListSuccess"}}}}}}},"/settlements/{id}":{"get":{"summary":"Obtener settlement por ID","tags":["Settlements"],"parameters":[{"$ref":"#/components/parameters/IdPathParam"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccess"}}}}}}},"/settlements/{id}/coupons":{"get":{"summary":"Cupones de un settlement","tags":["Settlements"],"parameters":[{"$ref":"#/components/parameters/IdPathParam"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericListSuccess"}}}}}}}}}