{"openapi":"3.0.0","info":{"title":"Senvia Integration API","version":"1.5.5","description":"Server-to-server OTP integration. Both x-api-key and x-project-id are required."},"servers":[{"url":"https://senvia-api.eleazargamez.dev"}],"paths":{"/otp/send":{"post":{"description":"Defaults to 8 mixed letters and digits. Numeric format uses 6 digits. The current account plan controls cumulative credits shared across companies, allowed channels, language and branding; sandbox has its own bounded allowance. Verification does not consume an extra request. Requires Mongo replica set transactions. WhatsApp is unavailable until a provider is implemented.","operationId":"OtpController_sendOtp","parameters":[{"name":"x-project-id","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-api-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"x-project-id","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateOtpDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OtpAcceptedDto"}}}}},"security":[{"api-key":[],"project-id":[]}],"summary":"Queue a code; accepted does not mean delivered","tags":["OTP"]}},"/otp/verify":{"post":{"description":"Pass challengeId from send. Legacy recordId accepts the external reference or returned challenge ID. Expired codes are rejected even before Mongo TTL cleanup.","operationId":"OtpController_verifyOtp","parameters":[{"name":"x-project-id","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-api-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"x-project-id","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyOtpDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OtpVerificationDto"}}}}},"security":[{"api-key":[],"project-id":[]}],"summary":"Consume a code once; five attempts maximum","tags":["OTP"]}},"/otp/records":{"get":{"description":"Lists persistent usage events with bounded pagination, channel, verification and creation-date filters. Expired or consumed challenge deletion does not remove these events.","operationId":"OtpController_getOtpRecords","parameters":[{"name":"x-project-id","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-api-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"x-project-id","required":true,"in":"header","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"default":1,"allOf":[{"$ref":"#/components/schemas/Object"}]}},{"name":"limit","required":false,"in":"query","schema":{"default":10,"allOf":[{"$ref":"#/components/schemas/Object"}]}},{"name":"channel","required":false,"in":"query","description":"Optional channel filter: email or whatsapp.","schema":{"$ref":"#/components/schemas/OtpChannel"}},{"name":"verified","required":false,"in":"query","schema":{"type":"boolean"}},{"name":"dateFrom","required":false,"in":"query","schema":{"type":"string"}},{"name":"dateTo","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"api-key":[],"project-id":[]}],"summary":"Usage metadata without secrets or email content","tags":["OTP"]}},"/otp/stats":{"get":{"description":"Aggregates issued and verified usage events for this project in the optional date range.","operationId":"OtpController_getOtpStats","parameters":[{"name":"x-project-id","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-api-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"x-project-id","required":true,"in":"header","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"default":1,"allOf":[{"$ref":"#/components/schemas/Object"}]}},{"name":"limit","required":false,"in":"query","schema":{"default":10,"allOf":[{"$ref":"#/components/schemas/Object"}]}},{"name":"channel","required":false,"in":"query","description":"Optional channel filter: email or whatsapp.","schema":{"$ref":"#/components/schemas/OtpChannel"}},{"name":"verified","required":false,"in":"query","schema":{"type":"boolean"}},{"name":"dateFrom","required":false,"in":"query","schema":{"type":"string"}},{"name":"dateTo","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OtpStatsDto"}}}}},"security":[{"api-key":[],"project-id":[]}],"summary":"Persistent usage statistics","tags":["OTP"]}},"/otp/token-info":{"get":{"description":"Returns the credit balance, reserved usage and unlimited-credit flag for the authenticated project.","operationId":"OtpController_getTokenInfo","parameters":[{"name":"x-project-id","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-api-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"x-project-id","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenInfoDto"}}}}},"security":[{"api-key":[],"project-id":[]}],"summary":"Project credits and usage","tags":["OTP"]}}},"components":{"schemas":{"GenerateOtpDto":{"type":"object","properties":{"language":{"type":"string","enum":["es","en"],"description":"Must be allowed by the company plan; defaults to its configured language."},"target":{"type":"string"},"channel":{"description":"One channel per request: email or whatsapp. WhatsApp returns 503 while disabled or its transport is not implemented.","example":"email","allOf":[{"$ref":"#/components/schemas/OtpChannel"}]},"recordId":{"type":"string"},"countryCode":{"type":"string"},"format":{"default":"alphanumeric","example":"alphanumeric","description":"Code format: alphanumeric produces 8 uppercase letters and digits; numeric produces 6 digits.","allOf":[{"$ref":"#/components/schemas/CodeFormat"}]}},"required":["target","channel"]},"OtpChannel":{"type":"string","enum":["email","whatsapp"],"description":"One channel per request: email or whatsapp. WhatsApp returns 503 while disabled or its transport is not implemented."},"CodeFormat":{"type":"string","enum":["numeric","alphanumeric"],"description":"Code format: alphanumeric produces 8 uppercase letters and digits; numeric produces 6 digits."},"OtpAcceptedDto":{"type":"object","properties":{"message":{"type":"string","example":"OTP accepted for delivery"},"expiresIn":{"type":"number","example":300,"description":"Challenge lifetime in seconds from acceptance, including queue delay"},"expiresAt":{"format":"date-time","type":"string"},"recordId":{"type":"string","example":"507f1f77bcf86cd799439011","description":"Legacy alias of challengeId"},"challengeId":{"type":"string","example":"507f1f77bcf86cd799439011"}},"required":["message","expiresIn","expiresAt","recordId","challengeId"]},"VerifyOtpDto":{"type":"object","properties":{"target":{"type":"string"},"code":{"type":"string"},"recordId":{"type":"string","description":"Legacy external reference; prefer challengeId"},"challengeId":{"type":"string"}},"required":["target","code"]},"OtpVerificationDto":{"type":"object","properties":{"valid":{"type":"boolean","example":true},"reason":{"type":"string","example":"Invalid or expired code"},"challengeId":{"type":"string","example":"507f1f77bcf86cd799439011"},"recordId":{"type":"string","example":"507f1f77bcf86cd799439011"},"verifiedAt":{"format":"date-time","type":"string"}},"required":["valid"]},"Object":{"type":"object","properties":{}},"OtpStatsDto":{"type":"object","properties":{"total":{"type":"number","example":15},"verified":{"type":"number","example":10},"unverified":{"type":"number","example":5},"verificationRate":{"oneOf":[{"type":"string","example":"66.67"},{"type":"number","example":0}],"description":"Percentage; zero is numeric when no usage exists"},"byChannel":{"type":"object","additionalProperties":{"type":"number"},"example":{"email":15}}},"required":["total","verified","unverified","verificationRate","byChannel"]},"TokenInfoDto":{"type":"object","properties":{"tokens":{"type":"number","example":100},"tokensUsed":{"type":"number","example":15},"remainingTokens":{"type":"number","example":85},"hasUnlimitedTokens":{"type":"boolean","example":false}},"required":["tokens","tokensUsed","remainingTokens","hasUnlimitedTokens"]}},"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key"},"project-id":{"type":"apiKey","in":"header","name":"x-project-id"}}}}