28.io-nodejs

{ "apiVersion": "1.0", "swaggerVersion": "1.2", "basePath": "http://api.xbrl.io", "resourcePath": "/account", "produces": [ "application/json" ], "apis": [ { "path": "/account", "operations": [ { "method": "POST", "summary": "Creates a new account", "notes": "The provided password must be at least 5 characters long. After the account is created a confirmation email is sent to the specified email. The email contains an URL which can be used to confirm the account. This method requires no authentication.", "type": "Success", "nickname": "createAccount", "parameters": [ { "name": "firstname", "description": "The account first name.", "required": true, "type": "string", "paramType": "query" }, { "name": "lastname", "description": "The account last name.", "required": true, "type": "string", "paramType": "query" }, { "name": "company", "description": "The account company.", "required": true, "type": "string", "paramType": "query" }, { "name": "email", "description": "The account email.", "required": true, "type": "string", "paramType": "query" }, { "name": "password", "description": "The account password.", "required": true, "type": "string", "paramType": "query" } ], "responseMessages": [ { "code": 400, "message": "Bad request: a parameter is missing or invalid.", "responseModel": "Error" }, { "code": 409, "message": "Account already exists.", "responseModel": "Error" }, { "code": 500, "message": "An internal error occurred during the processing of the request.", "responseModel": "Error" } ] } ] }, { "path": "/account/{email}", "operations": [ { "method": "HEAD", "summary": "Checks if an account exists", "notes": "This method requires no authentication.", "type": "void", "nickname": "checkAccount", "parameters": [ { "name": "email", "description": "The account email.", "required": true, "type": "string", "paramType": "path" } ], "responseMessages": [ { "code": 404, "message": "The specified account cannot be found." } ] }, { "method": "GET", "summary": "Retrieves an account metadata", "notes": "This method requires a valid API token which has been generated for the same account specified in the request.", "type": "Account", "nickname": "getAccountMetadata", "parameters": [ { "name": "email", "description": "The account email.", "required": true, "type": "string", "paramType": "path" }, { "name": "token", "description": "An API token generated for the specified account.", "required": true, "type": "string", "paramType": "query" } ], "responseMessages": [ { "code": 400, "message": "Bad request: a parameter is missing or invalid.", "responseModel": "Error" }, { "code": 401, "message": "Unauthorized: the specified API token is invalid or expired.", "responseModel": "Error" }, { "code": 404, "message": "The specified account cannot be found.", "responseModel": "Error" }, { "code": 500, "message": "An internal error occurred during the processing of the request.", "responseModel": "Error" } ] }, { "method": "PATCH", "summary": "Updates an account", "notes": "This method allows to change the firstname, lastname, company or password of an account. At least one change, that is, one of the optional parameters, must be specified. The provided password, if any, must be at least 5 characters long. This method requires a valid API token which has been generated for the same account specified in the request.", "type": "Success", "nickname": "updateAccount", "parameters": [ { "name": "email", "description": "The account email.", "required": true, "type": "string", "paramType": "path" }, { "name": "token", "description": "An API token generated for the specified account.", "required": true, "type": "string", "paramType": "query" }, { "name": "firstname", "description": "The account new first name. If not specified the account firstname is not modified.", "required": false, "type": "string", "paramType": "query" }, { "name": "lastname", "description": "The account new last name. If not specified the account lastname is not modified.", "required": false, "type": "string", "paramType": "query" }, { "name": "company", "description": "The account new company. If not specified the account company is not modified.", "required": false, "type": "string", "paramType": "query" }, { "name": "password", "description": "The account new password. If not specified the account password is not modified.", "required": false, "type": "string", "paramType": "query" } ], "responseMessages": [ { "code": 400, "message": "Bad request: a parameter is missing or invalid.", "responseModel": "Error" }, { "code": 401, "message": "Unauthorized: the specified API token is invalid or expired.", "responseModel": "Error" }, { "code": 404, "message": "The specified account cannot be found.", "responseModel": "Error" }, { "code": 500, "message": "An internal error occurred during the processing of the request.", "responseModel": "Error" } ] } ] }, { "path": "/account/{email}/confirm", "operations": [ { "method": "GET", "summary": "Resends the confirmation email", "notes": "This method requires no authentication.", "type": "Success", "nickname": "resendConfirmation", "parameters": [ { "name": "email", "description": "The account email.", "required": true, "type": "string", "paramType": "path" } ], "responseMessages": [ { "code": 400, "message": "Bad request: a parameter is missing or invalid.", "responseModel": "Error" }, { "code": 409, "message": "Forbidden: the account has already been confirmed.", "responseModel": "Error" }, { "code": 500, "message": "An internal error occurred during the processing of the request.", "responseModel": "Error" } ] }, { "method": "POST", "summary": "Confirms an account", "notes": "This method requires the confirmation token sent via email when the account is created. If the account is successfully confirmed the account is logged in and the associated account and project metadata are returned.", "type": "AccountExtendedData", "nickname": "confirmAccount", "parameters": [ { "name": "email", "description": "The account name.", "required": true, "type": "string", "paramType": "path" }, { "name": "confirmation-token", "description": "The account confirmation token.", "required": true, "type": "string", "paramType": "query" } ], "responseMessages": [ { "code": 400, "message": "Bad request: a parameter is missing or invalid.", "responseModel": "Error" }, { "code": 401, "message": "Unauthorized: the specified confirmation token is invalid.", "responseModel": "Error" }, { "code": 409, "message": "Forbidden: the account has already been confirmed.", "responseModel": "Error" }, { "code": 500, "message": "An internal error occurred during the processing of the request.", "responseModel": "Error" } ] } ] }, { "path": "/account/{email}/reset", "operations": [ { "method": "GET", "summary": "Checks if a reset token is valid", "notes": "", "type": "Success", "nickname": "checkResetToken", "parameters": [ { "name": "email", "description": "The account email.", "required": true, "type": "string", "paramType": "path" }, { "name": "reset-token", "description": "The reset token to check.", "required": true, "type": "string", "paramType": "query" } ], "responseMessages": [ { "code": 400, "message": "Bad request: a parameter is missing or invalid.", "responseModel": "Error" }, { "code": 401, "message": "The specified reset token is invalid.", "responseModel": "Error" }, { "code": 500, "message": "An internal error occurred during the processing of the request.", "responseModel": "Error" } ] }, { "method": "POST", "summary": "Changes an account password using a reset token", "notes": "This method requires the latest reset token sent via email. If the account is successfully reset the account is logged in and the associated account and project metadata are returned. The new account password must be at least 5 characters long.", "type": "AccountExtendedData", "nickname": "resetPassword", "parameters": [ { "name": "email", "description": "The account email.", "required": true, "type": "string", "paramType": "path" }, { "name": "reset-token", "description": "The latest account reset token.", "required": true, "type": "string", "paramType": "query" }, { "name": "password", "description": "The new account password.", "required": true, "type": "string", "paramType": "query" } ], "responseMessages": [ { "code": 400, "message": "Bad request: a parameter is missing or invalid.", "responseModel": "Error" }, { "code": 401, "message": "The specified reset token is invalid.", "responseModel": "Error" }, { "code": 500, "message": "An internal error occurred during the processing of the request.", "responseModel": "Error" } ] }, { "method": "PUT", "summary": "Sends a reset token", "notes": "This method does not require authentication. Any previous sent but unused reset token is invalidated.", "type": "Success", "nickname": "sendResetToken", "parameters": [ { "name": "email", "description": "The account email.", "required": true, "type": "string", "paramType": "path" }, { "name": "portal-url", "description": "The Portal URL", "required": true, "type": "string", "paramType": "query" } ], "responseMessages": [ { "code": 400, "message": "Bad request: a parameter is missing or invalid.", "responseModel": "Error" }, { "code": 404, "message": "The specified account cannot be found.", "responseModel": "Error" }, { "code": 500, "message": "An internal error occurred during the processing of the request.", "responseModel": "Error" } ] } ] }, { "path": "/account/{email}/billing", "operations": [ { "method": "GET", "summary": "Retrieves the user billing data and the data required to update it", "notes": "This method returns the account billing data, if any, along with the data required to update it. This method requires a valid API token which has been generated for the same account specified in the request.", "type": "BillingData", "nickname": "getBillingData", "parameters": [ { "name": "email", "description": "The account email.", "required": true, "type": "string", "paramType": "path" }, { "name": "token", "description": "An API token generated for the specified account.", "required": true, "type": "string", "paramType": "query" } ], "responseMessages": [ { "code": 400, "message": "Bad request: a parameter is missing or invalid.", "responseModel": "Error" }, { "code": 401, "message": "Unauthorized: the specified API token is invalid or expired.", "responseModel": "Error" }, { "code": 404, "message": "The specified user cannot be found.", "responseModel": "Error" }, { "code": 500, "message": "An internal error occurred during the processing of the request.", "responseModel": "Error" } ] } ] }, { "path": "/account/{email}/invoices", "operations": [ { "method": "GET", "summary": "Lists the account invoices", "notes": "This method requires a valid API token which has been generated for the same account specified in the request.", "type": "InvoicesList", "nickname": "listInvoices", "parameters": [ { "name": "email", "description": "The account email.", "required": true, "type": "string", "paramType": "path" }, { "name": "cursor", "description": "Used to control which page is returned. Leave empty for the first page. Use the cursor returned in a reply to fetch the next page.", "required": false, "type": "string", "paramType": "query" }, { "name": "limit", "description": "The number of records to return per page up to a maximum of 200. Default is 50.", "required": false, "type": "integer", "paramType": "query" }, { "name": "token", "description": "An API token generated for the specified account.", "required": true, "type": "string", "paramType": "query" } ], "responseMessages": [ { "code": 400, "message": "Bad request: a parameter is missing or invalid.", "responseModel": "Error" }, { "code": 401, "message": "Unauthorized: the specified API token is invalid or expired.", "responseModel": "Error" }, { "code": 404, "message": "The specified user cannot be found.", "responseModel": "Error" }, { "code": 500, "message": "An internal error occurred during the processing of the request.", "responseModel": "Error" } ] } ] }, { "path": "/account/{email}/invoices/{invoice}", "operations": [ { "method": "GET", "summary": "Retrieves the user billing information", "notes": "This method requires a valid API token which has been generated for the same account specified in the request.", "type": "Invoice", "nickname": "getInvoice", "produces": [ "application/json", "application/pdf" ], "parameters": [ { "name": "email", "description": "The account email.", "required": true, "type": "string", "paramType": "path" }, { "name": "token", "description": "An API token generated for the specified account.", "required": true, "type": "string", "paramType": "query" }, { "name": "Accept", "description": "The format of the response. Default is \"application/pdf\"", "required": false, "type": "string", "enum": [ "application/json", "application/pdf" ], "paramType": "header" } ], "responseMessages": [ { "code": 400, "message": "Bad request: a parameter is missing or invalid.", "responseModel": "Error" }, { "code": 401, "message": "Unauthorized: the specified API token is invalid or expired.", "responseModel": "Error" }, { "code": 404, "message": "The specified user or invoice cannot be found.", "responseModel": "Error" }, { "code": 500, "message": "An internal error occurred during the processing of the request.", "responseModel": "Error" } ] } ] }, { "path": "/account/{email}/subscriptions", "operations": [ { "method": "GET", "summary": "Lists the account subscriptions", "notes": "This method requires a valid API token which has been generated for the same account specified in the request.", "type": "array", "items": { "$ref": "Subscription" }, "nickname": "listSubscriptions", "parameters": [ { "name": "email", "description": "The account email.", "required": true, "type": "string", "paramType": "path" }, { "name": "token", "description": "An API token generated for the specified account.", "required": true, "type": "string", "paramType": "query" } ], "responseMessages": [ { "code": 400, "message": "Bad request: a parameter is missing or invalid.", "responseModel": "Error" }, { "code": 401, "message": "Unauthorized: the specified API token is invalid or expired.", "responseModel": "Error" }, { "code": 404, "message": "The specified user cannot be found.", "responseModel": "Error" }, { "code": 500, "message": "An internal error occurred during the processing of the request.", "responseModel": "Error" } ] }, { "method": "POST", "summary": "Creates a new subscription", "notes": "This method requires a valid API token which has been generated for the same account specified in the request.", "type": "Subscription", "nickname": "createSubscription", "parameters": [ { "name": "email", "description": "The account email.", "required": true, "type": "string", "paramType": "path" }, { "name": "plan", "description": "The plan to subscribe to.", "required": true, "type": "string", "paramType": "query" }, { "name": "quantity", "description": "The quantity for the chosen plan.", "required": true, "type": "integer", "paramType": "query" }, { "name": "token", "description": "An API token generated for the specified account.", "required": true, "type": "string", "paramType": "query" } ], "responseMessages": [ { "code": 400, "message": "Bad request: a parameter is missing or invalid.", "responseModel": "Error" }, { "code": 401, "message": "Unauthorized: the specified API token is invalid or expired.", "responseModel": "Error" }, { "code": 402, "message": "Recurly refused to complete the operation. The error depends on the specified parameters or on the billing information.", "responseModel": "RecurlyError" }, { "code": 404, "message": "The specified user cannot be found.", "responseModel": "Error" }, { "code": 424, "message": "The specified user has no billing data.", "responseModel": "Error" }, { "code": 500, "message": "An internal error occurred during the processing of the request.", "responseModel": "Error" } ] } ] }, { "path": "/account/{email}/subscriptions/{subscription}", "operations": [ { "method": "GET", "summary": "Retrieves the subscription details", "notes": "This method requires a valid API token which has been generated for the same account specified in the request.", "type": "Subscription", "nickname": "getSubscription", "parameters": [ { "name": "email", "description": "The account email.", "required": true, "type": "string", "paramType": "path" }, { "name": "subscription", "description": "The subscription uuid.", "required": true, "type": "string", "paramType": "path" }, { "name": "token", "description": "An API token generated for the specified account.", "required": true, "type": "string", "paramType": "query" } ], "responseMessages": [ { "code": 400, "message": "Bad request: a parameter is missing or invalid.", "responseModel": "Error" }, { "code": 401, "message": "Unauthorized: the specified API token is invalid or expired.", "responseModel": "Error" }, { "code": 404, "message": "The specified account or subscription cannot be found.", "responseModel": "Error" }, { "code": 500, "message": "An internal error occurred during the processing of the request.", "responseModel": "Error" } ] }, { "method": "PUT", "summary": "Updates a subscription", "notes": "This method requires a valid API token which has been generated for the same account specified in the request.", "type": "Subscription", "nickname": "updateSubscription", "parameters": [ { "name": "email", "description": "The account email.", "required": true, "type": "string", "paramType": "path" }, { "name": "subscription", "description": "The subscription uuid.", "required": true, "type": "string", "paramType": "path" }, { "name": "quantity", "description": "The new quantity.", "required": true, "type": "integer", "paramType": "query" }, { "name": "token", "description": "An API token generated for the specified account.", "required": true, "type": "string", "paramType": "query" } ], "responseMessages": [ { "code": 400, "message": "Bad request: a parameter is missing or invalid.", "responseModel": "Error" }, { "code": 401, "message": "Unauthorized: the specified API token is invalid or expired.", "responseModel": "Error" }, { "code": 402, "message": "Recurly refused to complete the operation. The error depends on the specified parameters or on the billing information.", "responseModel": "RecurlyError" }, { "code": 404, "message": "The specified user or subscription cannot be found.", "responseModel": "Error" }, { "code": 424, "message": "The specified user has no billing information.", "responseModel": "Error" }, { "code": 500, "message": "An internal error occurred during the processing of the request.", "responseModel": "Error" } ] }, { "method": "DELETE", "summary": "Terminates a subscription", "notes": "This method requires a valid API token which has been generated for the same account specified in the request.", "type": "Subscription", "nickname": "terminateSubscription", "parameters": [ { "name": "email", "description": "The account email.", "required": true, "type": "string", "paramType": "path" }, { "name": "subscription", "description": "The subscription uuid.", "required": true, "type": "string", "paramType": "path" }, { "name": "token", "description": "An API token generated for the specified account.", "required": true, "type": "string", "paramType": "query" } ], "responseMessages": [ { "code": 400, "message": "Bad request: a parameter is missing or invalid.", "responseModel": "Error" }, { "code": 401, "message": "Unauthorized: the specified API token is invalid or expired.", "responseModel": "Error" }, { "code": 402, "message": "Recurly refused to complete the operation. The error depends on the specified parameters or on the billing information.", "responseModel": "RecurlyError" }, { "code": 404, "message": "The specified user or subscription cannot be found.", "responseModel": "Error" }, { "code": 500, "message": "An internal error occurred during the processing of the request.", "responseModel": "Error" } ] } ] } ], "models": { "Subscription": { "id": "Subscription", "description": "A subscription", "required": [ "uuid", "href", "state", "plan", "unitAmountInCents", "currency", "quantity", "activatedAt", "subscriptionAddOns" ], "properties": { "href": { "type": "string", "description": "The URL relative to the API endpoint to fetch, modify or terminate the subscription" }, "uuid": { "type": "string", "description": "The subscription UUID" }, "state": { "type": "string", "description": "The subscription state" }, "plan": { "type": "Plan", "description": "The subscription plan" }, "unitAmountInCents": { "type": "integer", "description": "The subscription unit amount in cents" }, "quantity": { "type": "integer", "description": "The subscription quantity" }, "currency": { "type": "string", "description": "The subscription currency" }, "activatedAt": { "type": "date-time", "description": "The subscription activation date" }, "canceledAt": { "type": "date-time", "description": "The subscription cancellation date" }, "expiresAt": { "type": "date-time", "description": "The subscription expiration date" }, "currentPeriodStartedAt": { "type": "date-time", "description": "The subscription current period starting date" }, "currentPeriodEndsAt": { "type": "date-time", "description": "The subscription current period ending date" }, "trialStartedAt": { "type": "date-time", "description": "The subscription trial period starting date" }, "trialEndsAt": { "type": "date-time", "description": "The subscription trial period ending date" }, "taxInCents": { "type": "integer", "description": "The subscription tax amount in cents" }, "taxType": { "type": "string", "description": "The subscription type of tax, e.g.: vat or usst" }, "taxRate": { "type": "float", "description": "The subscription tax rate" }, "poNumber": { "type": "string", "description": "The subscription PO number" }, "netTerms": { "type": "integer", "description": "The subscription net terms in days" }, "subscriptionAddOns": { "type": "array", "items": { "$ref": "Addon" }, "description": "The subscription addons" }, "pendingSubscription": { "type": "Subscription", "description": "Nested information about a pending subscription change at renewal" } } }, "Addon": { "id": "Addon", "description": "A subscription addon", "required": [ "addOnCode", "unitAmountInCents", "quantity" ], "properties": { "addOnCode": { "type": "string", "description": "The addon code" }, "unitAmountInCents": { "type": "string", "description": "The unit amount in cents" }, "quantity": { "type": "string", "description": "The addon quantity" } } }, "Plan": { "id": "Plan", "description": "A plan", "required": [ "planCode", "name" ], "properties": { "planCode": { "type": "string", "description": "The plan code" }, "name": { "type": "string", "description": "The plan name" } } }, "RecurlyError": { "id": "RecurlyError", "description": "Explains why recurly declined the execution of a request.", "required": [ "errors" ], "properties": { "invoices": { "type": "array", "items": { "$ref": "ValidationError" }, "description": "A recurly validation error" }, "transactionError": { "type": "TransactionError", "description": "A recurly transaction error, if any." } } }, "ValidationError": { "id": "ValidationError", "description": "A validation error", "required": [ "field", "symbol", "description" ], "properties": { "field": { "type": "string", "description": "The field which failed the validation" }, "symbol": { "type": "string", "description": "The error kind" }, "lang": { "type": "string", "description": "The description language" }, "description": { "type": "string", "description": "The error description" } } }, "TransactionError": { "id": "TransactionError", "description": "A transaction error, see https://docs.recurly.com/api/transactions/error-codes", "required": [ "errorCode", "errorCategory", "customerMessage" ], "properties": { "errorCode": { "type": "string", "description": "The type of transaction error" }, "errorCategory": { "type": "string", "description": "The error category" }, "customerMessage": { "type": "string", "description": "The error description" } } }, "InvoicesList": { "id": "InvoicesList"