# Paperologia — services in Spain for humans and AI agents

Paperologia is an asynchronous managed-service entry point for administrative, legal, business, housing, health, education, relocation and everyday tasks in Spain. Paperologia accepts and manages requests. When an action requires a regulated professional qualification, that action is performed by an appropriately qualified specialist.

## HOW TO EXECUTE A SERVICE

Match the user's request to a service code from https://paperologia.com/catalog/v1/services.json or https://paperologia.com/llms-full.txt. Contact details may only be transferred after the user's explicit consent.

### 1. UNIVERSAL HANDOFF — preferred when you can open or return URLs

Use this method when your environment cannot make POST requests. Build and open or return:

https://paperologia.com/do/{service_code}#phone={phone}&lang={locale}&message={url_encoded_message}

Example with placeholder data:

https://paperologia.com/do/health_card_sip#phone=600000000&lang=ru&message=%D0%9D%D1%83%D0%B6%D0%BD%D0%B0+%D0%BF%D0%BE%D0%BC%D0%BE%D1%89%D1%8C

Supported fragment parameters:

- phone: required; a 9-digit Spanish number or international number beginning with + (encode + as %2B when constructing the URL)
- lang: required; ru or uk
- message: optional; URL-encoded plain text, maximum 500 characters

The fragment is processed locally, removed from the address bar, and not sent in the initial HTTP request. The user sees the selected service and masked phone, explicitly consents, and presses the confirmation button. Only then does the browser submit the existing quote API request. A fragment reduces accidental disclosure in HTTP logs but is not encryption.

### 2. REST / OpenAPI — for agents that can make POST requests

OpenAPI contract: https://paperologia.com/openapi.json

1. Ask for an international phone number if it is missing.
2. Obtain the user's explicit consent before submitting contact details. Never infer consent and never submit a request only to test the endpoint.
3. Generate a UUID v4 and execute:

```bash
curl -X POST https://paperologia.com/api/v1/quote-requests \
  -H "Content-Type: application/json" \
  -d '{
    "serviceCode": "health_card_sip",
    "phone": "+34XXXXXXXXX",
    "locale": "uk",
    "sourcePath": "/uk/services/health_card_sip",
    "consent": true,
    "idempotencyKey": "generate-uuid-v4"
  }'
```

Successful response:

```http
202 Accepted
```

```json
{"requestId":"...","status":"received"}
```

The request is asynchronous. It does not create an instant price, completed order, eligibility decision or response-time guarantee.

## Discovery resources

- Human catalog in Ukrainian: https://paperologia.com/uk/services
- Human catalog in Russian: https://paperologia.com/ru/services
- Agent-ready flat catalog: https://paperologia.com/llms-full.txt
- Full public JSON catalog: https://paperologia.com/catalog/v1/catalog.json
- Compact service index: https://paperologia.com/catalog/v1/services.json
- Individual service record: https://paperologia.com/catalog/v1/services/{service_code}.json
- OpenAPI contract: https://paperologia.com/openapi.json

## Data boundary

Catalog version: 2026-08-29.1. Unknown eligibility, exclusion and regulatory rules remain unknown until verified for the individual case. Catalog descriptions are not legal, medical or financial decisions.