=============== LIBRARY RULES =============== From library maintainers: - Distingue flujos: iframe/widget vs OAuth. No inventes pasos; usa la guía correcta. - No reintentes errores de credenciales. Reintenta solo casos temporales (p.ej. mantenimiento). - Si el rango de fechas es grande, anticipa 2FA/OTP y mayor latencia; ajusta expectativas. ### GET /entities/ example with curl and jq Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/entities.md Fetches the entity catalog with show_only_tested=1 and extracts code, name, and color fields using jq. Uses --fail and --show-error to surface HTTP errors. ```bash curl --fail --show-error "https://api.wealthreader.com/entities/?show_only_tested=1" \ | jq '.[] | {code, name, color}' ``` -------------------------------- ### Example 2 — full response with filters and token recovery Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/wr-conf-widget.md Full response example with wait_full_response=true, date_from, product_types filter, and token recovery. Redirects to a success page on flow completion. Includes the iframe and loader script. ```html ``` -------------------------------- ### Example 2 — register an OAuth domain with error checking (curl) Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/domains.md Registers an OAuth domain using curl and checks the response with jq. The example omits url_callback and tokenize. Exits with code 1 if registration fails. ```bash RESP=$(curl --silent --show-error --location "https://api.wealthreader.com/domains/" \ --header "Content-Type: application/x-www-form-urlencoded" \ --data-urlencode 'method=add' \ --data-urlencode 'api_key=12345678' \ --data-urlencode 'domain=https://www.example.com/oauth/success.php' \ --data-urlencode 'access_type=oauth') echo "$RESP" | jq -e '.success == true' \ || { echo "domain registration failed: $RESP" >&2; exit 1; } ``` -------------------------------- ### curl example for /warning-codes/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/error-codes.md Fetches warning codes in Spanish and outputs code and description for each entry. ```bash curl --fail --show-error "https://api.wealthreader.com/warning-codes/?lang=es" \ | jq '.[] | {code, description}' ``` -------------------------------- ### curl example for POST /user/revoke/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/user.md Example curl command to unregister a user from all services. Uses --fail and --show-error to surface HTTP errors. The commented line shows the expected response. ```bash curl --fail --show-error --location "https://api.wealthreader.com/user/revoke/" \ --header "Content-Type: application/x-www-form-urlencoded" \ --data-urlencode "api_key=A1B2C3D4" \ --data-urlencode "user_id=12345678A" \ --data-urlencode "service=all" # {"success": true, "message": "User unregistered successfully"} ``` -------------------------------- ### Example 1 — basic registration (curl) Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/user.md Curl command to register a user with easy-transfer service. Uses --fail and --show-error to surface HTTP errors. ```bash curl --fail --show-error --location "https://api.wealthreader.com/user/register/" \ --header "Content-Type: application/x-www-form-urlencoded" \ --data-urlencode "api_key=A1B2C3D4" \ --data-urlencode "user_id=12345678A" \ --data-urlencode "email=sai_banker@singularbank.com" \ --data-urlencode "service=easy-transfer" ``` -------------------------------- ### Example response for /error-codes/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/error-codes.md Verbatim sample response from the spec, showing the structure of a warning-error-codes element. ```json [{"code":2,"description":"Incorrect call","possible_reasons":"Some of the required parameters have not been sent or have been sent in an incorrect format","how_to_proceed":"The text received in \"message\" will detail the reason for the error. For example, \"The parameter \\\"api_key\\\" is mandatory\"."}] ``` -------------------------------- ### 200 OK response example Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/iban-ownership.md Example successful response with result code 1 and message 'The IBAN belongs to the indicated holder'. The statistics object contains session and execution time metadata. ```json { "success": true, "result": { "code": 1, "message": "The IBAN belongs to the indicated holder" }, "statistics": { "SESSION": null, "execution_time": 0.958 } } ``` -------------------------------- ### Example 2 — verification with error handling (Python) Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/iban-ownership.md Python example using requests to verify IBAN ownership. Handles non-200 responses by printing the session ID and raising an error. Checks result code and exits if the IBAN does not belong to the holder. ```python import requests r = requests.post("https://api.wealthreader.com/verify/iban-ownership/", data={ "api_key": "12345678", "iban": "ES4914651234561234567890", "document_type": "CIF", "document_number": "B12345678", "holder_name": "ACME SL", }) if r.status_code != 200: body = r.json() print("SESSION (save for support):", body["statistics"]["SESSION"]) raise SystemExit(f"verification request failed: {body['error']['code']} {body['error']['message']}") result = r.json()["result"] print(result["code"], result["message"]) if result["code"] != 1: # holder mismatch — drive onboarding accordingly raise SystemExit("IBAN does not belong to the indicated holder") ``` -------------------------------- ### POST /tokens/reasign/ — curl example Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/tokens.md Example curl command to reassign a token. Uses --fail and --show-error to surface HTTP errors. The response is shown in the comment. ```bash curl --fail --show-error --location "https://api.wealthreader.com/tokens/reasign/" \ --header "Content-Type: application/x-www-form-urlencoded" \ --data-urlencode "api_key_source=12345678" \ --data-urlencode "api_key_target=87654321" \ --data-urlencode "token=FRJ0mHlaqZwLzu" # {"success": true, "message": "Token successfully reassigned."} ``` -------------------------------- ### Example 1 — basic embed Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/wr-conf-widget.md Basic embed of the Wealth Reader widget with a minimal wr_conf (wait_full_response=false) and a message listener that logs when the flow completes. Includes the iframe and loader script. ```html ``` -------------------------------- ### GET /entities/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/entities.md Retrieves the catalog of supported entities. Use this to obtain entity codes for use in other endpoints. ```APIDOC ## [GET] /entities/ ### Description Retrieves the catalog of supported entities. Use this to obtain entity codes for use in other endpoints. ### Method GET ### Endpoint https://api.wealthreader.com/entities/ ### Parameters #### Query Parameters - **show_only_tested** (integer, enum 0/1) - Optional - Default: 0 - Whether to show only tested entities. In production, always use 1. ### Response #### Success Response (200) - **code** (string) - Entity code - **name** (string) - Entity name - **logo** (string) - Logo URL - **color** (string) - Color code - **inputs** (object) - Required input fields: document_type, user, password (each with required and name) - **statistics** (object) - Statistics data #### Response Example ```json [ { "code": "caixabank", "name": "CaixaBank", "logo": "https://...", "color": "#...", "inputs": { "document_type": {"required": true, "name": "Document type"}, "user": {"required": true, "name": "User"}, "password": {"required": true, "name": "Password"} }, "statistics": {} } ] ``` ### Error Handling - **400**: Error - Response body contains an `error` object ``` -------------------------------- ### Example 2 — registration with error handling (Python) Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/user.md Python script using requests to register a user. Checks for 401 status (invalid API key) and non-success response, raising SystemExit with the server message. ```python import requests r = requests.post("https://api.wealthreader.com/user/register/", data={ "api_key": "A1B2C3D4", "user_id": "12345678A", "email": "sai_banker@singularbank.com", "service": "easy-transfer", }) if r.status_code == 401: raise SystemExit("invalid api_key — check credentials, do not retry") body = r.json() if not body.get("success"): raise SystemExit(f"registration failed: {body.get('message')}") ``` -------------------------------- ### curl example for /error-codes/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/error-codes.md Fetches error codes in English and filters for codes between 2000 and 2999, outputting code, description, and how_to_proceed. ```bash curl --fail --show-error "https://api.wealthreader.com/error-codes/?lang=en" \ | jq '.[] | select(.code >= 2000 and .code < 3000) | {code, description, how_to_proceed}' ``` -------------------------------- ### POST /batch/fetch/connection-result/ - Example curl Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/batch.md Calls the connection-result endpoint and pipes the response through jq to extract account balances. ```bash curl --fail --show-error --location "https://api.wealthreader.com/batch/fetch/connection-result/" \ --header "Content-Type: application/json" \ --data '{"api_key": "12345678", "batch_id": "batch_20250120_a1b2c3d4", "credential_id": "cred_001"}' \ | jq '.payload.accounts[0].balances' ``` -------------------------------- ### GET /entities/ signature Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/entities.md Shows the HTTP GET request format for the entity catalog endpoint. The show_only_tested parameter is optional and defaults to 0; in production, always use 1. ```http GET https://api.wealthreader.com/entities/?show_only_tested= ``` -------------------------------- ### Example 1 — register a widget domain (curl) Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/domains.md Registers a widget domain using curl. The domain must not be an IP address and must not include 'localhost'. Uses access_type=widget and tokenize=1. ```bash API_KEY='12345678' DOMAIN='http://desarrollo.cliente.es' # no IP, no "localhost" URL_CALLBACK='https://desarrollo.cliente.es/hooks/wealthreader' ACCESS_TYPE='widget' curl --location "https://api.wealthreader.com/domains/" \ --header "Content-Type: application/x-www-form-urlencoded" \ --data-urlencode "method=add" \ --data-urlencode "tokenize=1" \ --data-urlencode "api_key=${API_KEY}" \ --data-urlencode "domain=${DOMAIN}" \ --data-urlencode "url_callback=${URL_CALLBACK}" \ --data-urlencode "access_type=${ACCESS_TYPE}" ``` -------------------------------- ### Example 1 — paginated listing (basic) using curl and jq Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/tokens.md Curl command to list tokens for a given api_key, paginated, and pipe to jq to extract token, entity_code, and latest_code fields. ```bash curl --fail --show-error --location "https://api.wealthreader.com/tokens/" \ --header "Content-Type: application/x-www-form-urlencoded" \ --data-urlencode "api_key=12345678" \ --data-urlencode "page=1" \ | jq '.[] | {token, entity_code, latest_code}' ``` -------------------------------- ### cURL Example for /user/check/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/user.md Uses curl to call the endpoint and extract the easy-transfer link with jq. Requires api_key and user_id. Fails on HTTP errors due to --fail. ```bash curl --fail --show-error --location "https://api.wealthreader.com/user/check/" \ --header "Content-Type: application/x-www-form-urlencoded" \ --data-urlencode "api_key=A1B2C3D4" \ --data-urlencode "user_id=12345678A" \ | jq -r '.links["easy-transfer"]' ``` -------------------------------- ### GET /warning-codes/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/configuration.md Retrieves warning codes. The `lang` query parameter specifies the language of the warning messages, with a default of `es`. ```APIDOC ## [GET] /warning-codes/ ### Description Retrieves warning codes. The `lang` query parameter specifies the language of the warning messages, with a default of `es`. ### Method GET ### Endpoint /warning-codes/ ### Parameters #### Query Parameters - **lang** (string) - Optional - Default: `"es"`. Language for warning messages. Enum: `es`, `en`. ### Request Example ``` GET /warning-codes/?lang=es ``` ### Response #### Success Response (200) - **warning_codes** (array) - List of warning codes. #### Response Example ```json { "warning_codes": [] } ``` ``` -------------------------------- ### GET /warning-codes/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/endpoints.md Retrieves a list of warning codes. No authentication required. ```APIDOC ## GET /warning-codes/ ### Description Retrieves a list of warning codes. No authentication required. ### Method GET ### Endpoint /warning-codes/ ### Parameters None ### Response #### Success Response (200) - Success response body. #### Error Statuses - 400 - Bad request ``` -------------------------------- ### Callback GET with nonce and code Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/oauth.md The auth server redirects to the callback with a GET request containing nonce and code parameters after user authorization. The nonce must match the generated value and the code is used for token exchange. ```http https://example.com/oauth/success.php ?nonce=7065556651485978744d7669633373686c44427532556d71506170425178724d584738693548365444 &code=1234567890abcdef1234567890abcdef1234567890a ``` -------------------------------- ### GET /entities/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/configuration.md Retrieves a list of entities. The `show_only_tested` query parameter controls whether only tested entities are returned; in production it is always set to `1`. ```APIDOC ## [GET] /entities/ ### Description Retrieves a list of entities. The `show_only_tested` query parameter controls whether only tested entities are returned; in production it is always set to `1`. ### Method GET ### Endpoint /entities/ ### Parameters #### Query Parameters - **show_only_tested** (integer) - Optional - Default: `0`. Set to `1` to return only tested entities. In production, this is always `1`. ### Request Example ``` GET /entities/?show_only_tested=0 ``` ### Response #### Success Response (200) - **entities** (array) - List of entities. #### Response Example ```json { "entities": [] } ``` ``` -------------------------------- ### Basic refresh with curl Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/entities.md Basic refresh example for the POST /entities/ endpoint using curl. Uses mock token MOCKDATA to return anonymized sample data. Includes api_key, code, token, product_types, date_from, and only_balances parameters. ```bash API_KEY='12345678' CODE='caixabank' TOKEN='MOCKDATA' # mock user: returns anonymized sample data curl --fail --show-error --location "https://api.wealthreader.com/entities/" \ --header "Content-Type: application/x-www-form-urlencoded" \ --data-urlencode "api_key=${API_KEY}" \ --data-urlencode "code=${CODE}" \ --data-urlencode "token=${TOKEN}" \ --data-urlencode "product_types=accounts,portfolios" \ --data-urlencode "date_from=2024-01-01" \ --data-urlencode "only_balances=false" ``` -------------------------------- ### Full backend exchange with verification in Python Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/oauth.md Complete Python example for the OAuth flow: generates nonce, state, and code_verifier, then exchanges the code for an access token. Uses requests library and SHA-256 for the challenge. ```python import hashlib, secrets, requests # 1. Generate challenge values nonce = secrets.token_hex(41) # hex state = secrets.token_hex(41) code_verifier = secrets.token_hex(41) # hex -> SHA-256 for challenge challenge_code = hashlib.sha256(code_verifier.encode()).hexdigest() # 2. Redirect the user to https://oauth.wealthreader.com/oauth2/?... (as above) # ... user authorizes; callback GET arrives with ?nonce=...&code=... # 3. Exchange the code resp = requests.post("https://oauth.wealthreader.com/token/", data={ "grant_type": "authorization_code", "redirect_uri": "https://example.com/oauth/success.php", "code": "1234567890abcdef1234567890abcdef1234567890a", "code_verifier": code_verifier, }) resp.raise_for_status() # response contains the bank's data + access token; persist the token ``` -------------------------------- ### Example 1 — basic verification (curl) Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/iban-ownership.md Basic curl command to verify IBAN ownership. Uses --fail and --show-error to surface HTTP errors. ```bash curl --fail --show-error --location "https://api.wealthreader.com/verify/iban-ownership/" \ --header "Content-Type: application/x-www-form-urlencoded" \ --data-urlencode "api_key=12345678" \ --data-urlencode "iban=ES4914651234561234567890" \ --data-urlencode "document_type=NIF" \ --data-urlencode "document_number=12345678Z" \ --data-urlencode "holder_name=LUIS GARCIA BAQUERO" ``` -------------------------------- ### POST /batch/fetch/statistics/ - Example curl Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/batch.md Calls the statistics endpoint and pipes the response through jq to extract status and connection counts. ```bash curl --fail --show-error --location "https://api.wealthreader.com/batch/fetch/statistics/" \ --header "Content-Type: application/json" \ --data '{"api_key": "12345678", "batch_id": "batch_20250120_a1b2c3d4"}' \ | jq '{status, ok: .statistics.successful_connections, failed: .statistics.failed_connections}' ``` -------------------------------- ### POST /batch/load/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/endpoints.md Starts asynchronous multi-connection processing. Returns a 202 with batch ID and estimated completion time, and notifies the provided URL on completion. ```APIDOC ## POST /batch/load/ ### Description Initiates asynchronous multi-connection processing. ### Method POST ### Endpoint /batch/load/ ### Parameters #### Request Body - **connections** (array) - Required - List of connections to process. - **notification_url** (string) - Optional - URL to notify on completion. ### Response #### Success Response (202) Returns an object with `batch_id`, `total_connections`, and `estimated_completion_time`. ``` -------------------------------- ### GET /warning-codes/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/error-codes.md Retrieves the catalog of warning codes. Use this endpoint to interpret the `statistics.warnings[].code` field returned by other API calls. ```APIDOC ## [GET] /warning-codes/ ### Description Retrieves the catalog of warning codes. Use this endpoint to interpret the `statistics.warnings[].code` field returned by other API calls. ### Method GET ### Endpoint https://api.wealthreader.com/warning-codes/ ### Parameters #### Query Parameters - **lang** (string, enum `es`, `en`) - Optional - Response language. Default: `"es"`. ### Request Example ``` GET https://api.wealthreader.com/warning-codes/?lang=es ``` ### Response #### Success Response (200) - **code** (integer) - Warning code - **description** (string) - Warning description - **possible_reasons** (string) - Possible causes of the warning - **how_to_proceed** (string) - How to act when this warning code is obtained #### Response Example ```json [{"code":2,"description":"Incorrect call","possible_reasons":"Some of the required parameters have not been sent or have been sent in an incorrect format","how_to_proceed":"The text received in \"message\" will detail the reason for the error. For example, \"The parameter \\\"api_key\\\" is mandatory\"."}] ``` ### Error Handling | Status | Condition | Body | |---|---|---| | 400 | Error | array of `error` | ``` -------------------------------- ### GET /error-codes/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/configuration.md Retrieves error codes. The `lang` query parameter specifies the language of the error messages, with a default of `es`. ```APIDOC ## [GET] /error-codes/ ### Description Retrieves error codes. The `lang` query parameter specifies the language of the error messages, with a default of `es`. ### Method GET ### Endpoint /error-codes/ ### Parameters #### Query Parameters - **lang** (string) - Optional - Default: `"es"`. Language for error messages. Enum: `es`, `en`. ### Request Example ``` GET /error-codes/?lang=es ``` ### Response #### Success Response (200) - **error_codes** (array) - List of error codes. #### Response Example ```json { "error_codes": [] } ``` ``` -------------------------------- ### GET /error-codes/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/error-codes.md Retrieves the catalog of error codes. Use this endpoint to interpret the `error-detail.code` field returned by other API calls. ```APIDOC ## [GET] /error-codes/ ### Description Retrieves the catalog of error codes. Use this endpoint to interpret the `error-detail.code` field returned by other API calls. ### Method GET ### Endpoint https://api.wealthreader.com/error-codes/ ### Parameters #### Query Parameters - **lang** (string, enum `es`, `en`) - Optional - Response language. Default: `"es"`. ### Request Example ``` GET https://api.wealthreader.com/error-codes/?lang=en ``` ### Response #### Success Response (200) - **code** (integer) - Error code - **description** (string) - Error description - **possible_reasons** (string) - Possible causes of the error - **how_to_proceed** (string) - How to act when this error code is obtained #### Response Example ```json [{"code":2,"description":"Incorrect call","possible_reasons":"Some of the required parameters have not been sent or have been sent in an incorrect format","how_to_proceed":"The text received in \"message\" will detail the reason for the error. For example, \"The parameter \\\"api_key\\\" is mandatory\"."}] ``` ### Error Handling | Status | Condition | Body | |---|---|---| | 400 | Error | array of `error` | ``` -------------------------------- ### GET /entities/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/endpoints.md Retrieves the catalog of supported entities with fields needed to render the login form. Use the `show_only_tested` query parameter to filter to tested entities in production. ```APIDOC ## GET /entities/ ### Description Returns the supported-entity catalog with fields needed to render the login form. ### Method GET ### Endpoint /entities/ ### Parameters #### Query Parameters - **show_only_tested** (integer) - Optional - Set to 1 to show only tested entities (default 0; production should use 1). ### Response #### Success Response (200) Returns an array of `entities` objects. ``` -------------------------------- ### Token exchange with curl Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/oauth.md Example curl command for the token exchange. Sends a POST request with form-urlencoded data including grant_type, redirect_uri, code, and code_verifier. ```bash curl --location --request POST 'https://oauth.wealthreader.com/token/' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=authorization_code' \ --data-urlencode 'redirect_uri=https://example.com/oauth/success.php' \ --data-urlencode 'code=1234567890abcdef1234567890abcdef1234567890a' \ --data-urlencode 'code_verifier=6e37325953774b514b4f6a553374484d67423656524a4e31584c64327030384b4b4a7452666f506d6b' ``` -------------------------------- ### Check User Response JSON Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/user.md Example JSON response for a successful check. Contains success flag, registration status, user ID, and single-use access links per aggregation service. ```json { "success": true, "registered": true, "user_id": "12345", "links": { "easy-transfer": "https://singularbank.wealthreader.com/...", "integra": "https://www.acumulas.com/register?..." } } ``` -------------------------------- ### GET /entities/category-types/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/configuration.md Retrieves entity category types. The `lang` query parameter specifies the language of the category type names, with a default of `es`. ```APIDOC ## [GET] /entities/category-types/ ### Description Retrieves entity category types. The `lang` query parameter specifies the language of the category type names, with a default of `es`. ### Method GET ### Endpoint /entities/category-types/ ### Parameters #### Query Parameters - **lang** (string) - Optional - Default: `"es"`. Language for category type names. Enum: `es`, `en`. ### Request Example ``` GET /entities/category-types/?lang=es ``` ### Response #### Success Response (200) - **category_types** (array) - List of category types. #### Response Example ```json { "category_types": [] } ``` ``` -------------------------------- ### Submit a mixed token/credential batch (curl) Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/batch.md Example curl command to submit a batch with two connections: one using a token, the other using user/password. The response is a 202 with batch_id, total_connections, and estimated_completion_time. ```bash curl --fail --show-error --location "https://api.wealthreader.com/batch/load/" \ --header "Content-Type: application/json" \ --data '{ "api_key": "12345678", "notification_url": "https://example.com/webhook/batch-complete", "connections": [ {"credential_id": "cred_001", "code": "santander", "token": "FRJ0mHlaqZwLzu", "only_balances": true}, {"credential_id": "cred_002", "code": "caixabank", "user": "user1", "password": "pass1", "product_types": "accounts,loans"} ] }' # 202 {"success": true, "batch_id": "batch_20250120_a1b2c3d4", "total_connections": 2, "estimated_completion_time": "2025-01-20T10:45:00Z"} ``` -------------------------------- ### GET https://oauth.wealthreader.com/oauth2/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/endpoints.md Redirect endpoint for initiating OAuth authorization. Users are redirected to this URL with the specified query parameters to start the OAuth flow. ```APIDOC ## [GET] https://oauth.wealthreader.com/oauth2/ ### Description Redirect endpoint for initiating OAuth authorization. Users are redirected to this URL with the specified query parameters to start the OAuth flow. ### Method GET ### Endpoint https://oauth.wealthreader.com/oauth2/ ### Parameters #### Query Parameters - **challenge_code** (string) - Required - The PKCE challenge code. - **code_challenge_method** (string) - Required - The PKCE challenge method (e.g., S256). - **redirect_uri** (string) - Required - The URI to redirect to after authorization. - **response_type** (string) - Required - The response type (e.g., code). - **state** (string) - Required - A state parameter for CSRF protection. - **nonce** (string) - Required - A nonce parameter. - **wr_conf** (string) - Required - WealthReader configuration identifier. ### Response #### Success Response (302) Redirects to the specified redirect_uri with authorization code and state. #### Response Example (Redirect response) ``` -------------------------------- ### warning-error-codes Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/types.md Defines the structure of each element in the responses of `GET /error-codes/` and `GET /warning-codes/`. It contains four required fields: code, description, possible_reasons, and how_to_proceed. ```APIDOC ## warning-error-codes ### Description Element of GET `/error-codes/` and `/warning-codes/`. ### Fields - **code** (integer) - Required - Error or warning code - **description** (string) - Required - Description of the code - **possible_reasons** (string) - Required - Possible reasons for the code - **how_to_proceed** (string) - Required - How to proceed ### Example ```json {"type": "array", "items": {"type": "object", "required": ["code","description","possible_reasons","how_to_proceed"], "properties": { "code": {"type": "integer"}, "description": {"type": "string"}, "possible_reasons": {"type": "string"}, "how_to_proceed": {"type": "string"}}}} ``` ``` -------------------------------- ### POST /entities/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/entities.md Creates a new entity session by providing credentials and optional product schema. Returns account and card data, including PDFs if requested. ```APIDOC ## [POST] /entities/ ### Description Creates a new entity session by providing credentials and optional product schema. Returns account and card data, including PDFs if requested. ### Method POST ### Endpoint https://api.wealthreader.com/entities/ ### Parameters #### Request Body - **api_key** (string) - Required - API key for authentication - **code** (string) - Required - Entity code (e.g., "caixabank") - **token** (string) - Required - Session token - **required_products_schema** (string) - Optional - JSON string specifying per-product options (only_balances, add_pdf_from_uuids, date_from) - **add_pdf_from_uuids** (string) - Optional - UUID(s) of documents to include as PDFs ### Request Example ```json { "api_key": "12345678", "code": "caixabank", "token": "FRJ0mHlaqZwLzu", "required_products_schema": "{\"ACCOUNTS\":{\"0ae4d722b1c82feeafb4b36b2893230444071335\":{\"only_balances\":false,\"add_pdf_from_uuids\":[\"90763109952d4f2ebece8dceca8254078c5384a0\"],\"date_from\":\"2024-04-03\"}},\"CARDS\":{\"957e6f63546f3fecacce80192b6f7436496dc057\":{}}}", "add_pdf_from_uuids": "90763109952d4f2ebece8dceca8254078c5384a0" } ``` ### Response #### Success Response (200) - **payload** (object) - Contains accounts and cards data - **accounts** (array) - List of accounts with transactions - **transactions** (array) - List of transactions, each with optional pdf_file (Base64) #### Response Example ```json { "payload": { "accounts": [ { "transactions": [ { "pdf_file": "" } ] } ] } } ``` ### Error Handling - **Non-200 status**: Response is an array with an error envelope - **error.code** (integer) - Error code; 2000-2999 indicates login errors (do not retry), others are temporary (retry with backoff) - **error.message** (string) - Error description - **statistics.SESSION** (string) - Session identifier for support ``` -------------------------------- ### POST /tokens/revoke/ — curl example Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/tokens.md Example curl command to revoke a token. Uses --fail and --show-error to surface HTTP errors. The response is shown in the comment. ```bash curl --fail --show-error --location "https://api.wealthreader.com/tokens/revoke/" \ --header "Content-Type: application/x-www-form-urlencoded" \ --data-urlencode "api_key=12345678" \ --data-urlencode "token=FRJ0mHlaqZwLzu" # {"success": true, "message": "Token successfully revoked."} ``` -------------------------------- ### POST /user/register/ signature (register-user-request) Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/user.md Exact request body for registering a user. Requires api_key (8 alphanumeric characters), user_id, email, and service (integra or easy-transfer). Content-Type must be application/x-www-form-urlencoded. ```http POST https://api.wealthreader.com/user/register/ Content-Type: application/x-www-form-urlencoded api_key= # Authentication key, 8 alphanumeric characters (example: A1B2C3D4) user_id= # User identification document (example: 12345678A) email= # User email, used according to service type (format: email) service= # Service associated with the user: integra | easy-transfer ``` -------------------------------- ### GET your callback — authorization response Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/oauth.md After the user authorizes, the auth server redirects the client to your callback with a GET containing nonce and code. This callback is used to receive the authorization code for the token exchange. ```APIDOC ## [GET] your callback ### Description After the user authorizes, the auth server redirects the client to your callback with a GET containing `nonce` and `code`. ### Method GET ### Endpoint `https://example.com/oauth/success.php` ### Parameters #### Query Parameters - **nonce** (string hex) - Required - Must match the `nonce` you generated (verify it) - **code** (string) - Required - Authorization code for the token exchange ### Request Example ``` https://example.com/oauth/success.php ?nonce=7065556651485978744d7669633373686c44427532556d71506170425178724d584738693548365444 &code=1234567890abcdef1234567890abcdef1234567890a ``` ``` -------------------------------- ### POST /tokens/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/configuration.md Creates a token. The `page` parameter in the request body specifies the page number for pagination, with a default of `1`. ```APIDOC ## [POST] /tokens/ ### Description Creates a token. The `page` parameter in the request body specifies the page number for pagination, with a default of `1`. ### Method POST ### Endpoint /tokens/ ### Parameters #### Request Body - **page** (integer) - Optional - Default: `1`. Page number for pagination. ### Request Example ```json { "page": 1 } ``` ### Response #### Success Response (200) - **token** (string) - The generated token. #### Response Example ```json { "token": "string" } ``` ``` -------------------------------- ### GET /entities/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/endpoints.md Retrieves a list of entities. No authentication required. ```APIDOC ## GET /entities/ ### Description Retrieves a list of entities. No authentication required. ### Method GET ### Endpoint /entities/ ### Parameters None ### Response #### Success Response (200) - Success response body. #### Error Statuses - 400 - Bad request ``` -------------------------------- ### POST /entities/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/configuration.md Creates a new entity. The request body can include the `only_balances` parameter to control whether only balance information is returned. The `product_types` parameter is omitted, so the entity default of `ALL` is used. ```APIDOC ## [POST] /entities/ ### Description Creates a new entity. The request body can include the `only_balances` parameter to control whether only balance information is returned. The `product_types` parameter is omitted, so the entity default of `ALL` is used. ### Method POST ### Endpoint /entities/ ### Parameters #### Request Body - **only_balances** (boolean) - Optional - Default: `false`. If `true`, only balance information is returned. ### Request Example ```json { "only_balances": false } ``` ### Response #### Success Response (200) - **entity** (object) - The created entity. #### Response Example ```json { "entity": {} } ``` ``` -------------------------------- ### GET /error-codes/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/endpoints.md Retrieves a list of error codes. No authentication required. ```APIDOC ## GET /error-codes/ ### Description Retrieves a list of error codes. No authentication required. ### Method GET ### Endpoint /error-codes/ ### Parameters None ### Response #### Success Response (200) - Success response body. #### Error Statuses - 400 - Bad request ``` -------------------------------- ### POST /domains/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/configuration.md Adds a domain. The `tokenize` parameter in the request body controls whether tokenization is enabled, with a default of `1` (enabled). ```APIDOC ## [POST] /domains/ ### Description Adds a domain. The `tokenize` parameter in the request body controls whether tokenization is enabled, with a default of `1` (enabled). ### Method POST ### Endpoint /domains/ ### Parameters #### Request Body - **tokenize** (integer) - Optional - Default: `1`. Set to `1` to enable tokenization, `0` to disable. ### Request Example ```json { "tokenize": 1 } ``` ### Response #### Success Response (200) - **domain** (object) - The created domain. #### Response Example ```json { "domain": {} } ``` ``` -------------------------------- ### GET /entities/category-types/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/endpoints.md Retrieves category types for entities. No authentication required. ```APIDOC ## GET /entities/category-types/ ### Description Retrieves category types for entities. No authentication required. ### Method GET ### Endpoint /entities/category-types/ ### Parameters None ### Response #### Success Response (200) - Success response body. #### Error Statuses - 400 - Bad request ``` -------------------------------- ### GET /warning-codes/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/endpoints.md Retrieves the warning-code catalog with the same response shape as `/error-codes/`. Supports language selection. ```APIDOC ## GET /warning-codes/ ### Description Returns the warning-code catalog. ### Method GET ### Endpoint /warning-codes/ ### Parameters #### Query Parameters - **lang** (string) - Optional - Language for the catalog. ### Response #### Success Response (200) Returns an array of warning-code objects with fields: `code`, `description`, `possible_reasons`, `how_to_proceed`. ``` -------------------------------- ### GET /entities/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/errors.md Retrieves a list of entities. Returns a 400 error on invalid request. ```APIDOC ## [GET] /entities/ ### Description Retrieves a list of entities. Returns a 400 error on invalid request. ### Method GET ### Endpoint /entities/ ### Response #### Success Response (200) - No details provided in source. #### Error Response (400) - **error** - Invalid request. ``` -------------------------------- ### Advanced per-product schema with PDFs and error handling (Python) Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/entities.md Posts to /entities/ with a per-product schema selecting specific accounts/cards by UUID, enabling only_balances, add_pdf_from_uuids, and date_from options. Handles login errors (codes 2000-2999) by not retrying and prints a session ID for support. Requires a valid API key, entity code, and token. ```python import requests # required_products_schema selects specific accounts/cards (by uuid) with # per-product options: only_balances, add_pdf_from_uuids, date_from schema = json.dumps({ "ACCOUNTS": { "0ae4d722b1c82feeafb4b36b2893230444071335": { "only_balances": False, "add_pdf_from_uuids": ["90763109952d4f2ebece8dceca8254078c5384a0"], "date_from": "2024-04-03", } }, "CARDS": {"957e6f63546f3fecacce80192b6f7436496dc057": {}} }) r = requests.post("https://api.wealthreader.com/entities/", data={ "api_key": "12345678", "code": "caixabank", "token": "FRJ0mHlaqZwLzu", "required_products_schema": schema, "add_pdf_from_uuids": "90763109952d4f2ebece8dceca8254078c5384a0", }) if r.status_code != 200: body = r.json()[0] # error envelope (array) code = body["error"]["code"] print("SESSION (save for support):", body["statistics"]["SESSION"]) if 2000 <= code < 3000: # login family: do NOT retry raise SystemExit(f"login error: {body['error']['message']}") raise SystemExit(f"temporary error {code}, retry with backoff") data = r.json()[0]["payload"] print(data["accounts"][0]["transactions"][0]["pdf_file"]) # Base64 PDF ``` -------------------------------- ### GET /entities/category-types/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/endpoints.md Retrieves the transaction category catalog. Supports language selection via the `lang` query parameter. ```APIDOC ## GET /entities/category-types/ ### Description Returns the transaction category catalog. ### Method GET ### Endpoint /entities/category-types/ ### Parameters #### Query Parameters - **lang** (string) - Optional - Language for the catalog: `es` (default) or `en`. ### Response #### Success Response (200) Returns an array of `category-types` objects. ``` -------------------------------- ### register-user-response (200 OK) Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/api-reference/user.md Successful response body for POST /user/register/. Returns success flag and message. ```json { "success": true, "message": "User registered successfully" } ``` -------------------------------- ### GET /entities/ Source: https://github.com/santiagomqv/wealthreader-agent-docs/blob/main/_autodocs/README.md Retrieves a list of entities associated with the authenticated user. This endpoint returns basic information about each entity. ```APIDOC ## [GET] /entities/ ### Description Retrieves a list of entities associated with the authenticated user. ### Method GET ### Endpoint /entities/ ### Parameters #### Query Parameters - `api_key` (string) - Required - API key for authentication. - `token` (string) - Required - Token obtained from authentication. ### Request Example GET /entities/?api_key=your_api_key&token=your_token ### Response #### Success Response (200) - `entities` (array) - List of entity objects. #### Response Example { "entities": [ { "id": "12345", "name": "John Doe" } ] } ```