Spain AEAT: Document API token integration with Raul

{
  "cost": {
    "input_tokens": 60,
    "estimated_usd": 0.2175,
    "output_tokens": 2888
  },
  "model": "claude-opus-4-6",
  "status": "success",
  "transport": "anthropic_api",
  "latency_ms": 63300,
  "response_text": "# Spain AEAT API Integration — Documentation\n\n## Project Overview\n\n**Objective:** Integrate with AEAT (Agencia Estatal de Administración Tributaria) APIs for customs/tax document processing.\n\n**Key Contact:** Raul — Barcelona office (holds API token/credentials)\n\n**Status:** Pre-integration — awaiting technical handshake\n\n---\n\n## Action Items\n\n### Immediate (Before Monday Call)\n\n- [ ] **Contact Raul** to confirm he has the production/sandbox API token and can share securely (NOT via email/Slack — use a secrets manager or encrypted channel)\n- [ ] **Schedule Monday call** — send calendar invite to Raul + dev team\n- [ ] **Request from Raul ahead of call:**\n  - API token scope and expiration policy\n  - Which AEAT environment(s) he has access to (sandbox / pre-production / production)\n  - Any existing Postman collections or sample requests\n\n---\n\n## Technical Requirements to Document\n\n### 1. Endpoint URLs\n\n| Environment | Base URL (typical AEAT pattern) | Status |\n|---|---|---|\n| Production | `https://www2.agenciatributaria.gob.es/...` | ❓ Confirm with Raul |\n| Sandbox/Test | `https://www7.aeat.es/...` or pruebas variant | ❓ Confirm with Raul |\n\n**Known AEAT API portals to reference:**\n- AEAT Sede Electrónica: [https://sede.agenciatributaria.gob.es](https://sede.agenciatributaria.gob.es)\n- AEAT technical documentation: [https://www.agenciatributaria.es/AEAT.internet/en_gb/Inicio/La_Agencia_Tributaria/Campanas/Suministro_Inmediato_de_Informacion_en_el_IVA__SII_/Informacion_General/Informacion_tecnica.shtml](https://www.agenciatributaria.es/AEAT.internet/en_gb/Inicio/)\n\n**Ask Raul:**\n- Exact service paths (e.g., `/wlpl/SSII-FACT/ws/...` for SII, or customs-specific endpoints)\n- WSDL locations if SOAP-based\n- REST vs SOAP — which APIs are we consuming?\n\n---\n\n### 2. Authentication Flow\n\nAEAT typically supports these auth methods — **confirm which applies:**\n\n```\n┌─────────────────────────────────────────────┐\n│         AEAT Auth Methods (typical)         │\n├─────────────────────────────────────────────┤\n│                                             │\n│  Option A: Digital Certificate (X.509)      │\n│  ├── FNMT / Spanish CA issued               │\n│  ├── Mutual TLS (client cert + server cert) │\n│  └── Most common for AEAT integrations      │\n│                                             │\n│  Option B: Cl@ve PIN / Cl@ve Permanente     │\n│  ├── User-interactive (not ideal for APIs)  │\n│  └── Typically for portal access only       │\n│                                             │\n│  Option C: API Token (OAuth2 / Bearer)      │\n│  ├── If AEAT has issued a specific token    │\n│  └── ⬅ This seems to be what Raul has      │\n│                                             │\n└─────────────────────────────────────────────┘\n```\n\n**Critical questions for Raul:**\n- Is the \"token\" actually a **digital certificate** (.pfx / .p12) or a literal **API key/bearer token**?\n- If certificate-based: who is the issuing CA? What's the expiry?\n- Token refresh mechanism — is it static or does it expire/rotate?\n- Is there an OAuth2 flow (client_credentials grant)?\n\n**Draft auth implementation (placeholder):**\n\n```python\n# Option A: Certificate-based (most likely for AEAT)\nimport requests\n\nresponse = requests.post(\n    url=AEAT_ENDPOINT,\n    cert=('/path/to/client_cert.pem', '/path/to/client_key.pem'),\n    headers={'Content-Type': 'application/xml'},\n    data=xml_payload\n)\n\n# Option B: Bearer token\nresponse = requests.post(\n    url=AEAT_ENDPOINT,\n    headers={\n        'Authorization': f'Bearer {AEAT_TOKEN}',\n        'Content-Type': 'application/json'\n    },\n    json=payload\n)\n```\n\n---\n\n### 3. TARIC Code Mapping\n\n**What is it:** TARIC (Tarif Intégré Communautaire) — EU's integrated tariff classification system used in customs declarations.\n\n**Structure:**\n```\nTARIC Code: 10 digits\n├── HS Code (Harmonized System):  6 digits  (international)\n├── CN Code (Combined Nomenclature): 8 digits  (EU level)\n└── TARIC subheading:               10 digits (EU-specific measures)\n\nExample: 0901.21.00.00\n         ├─ 0901       = Coffee (HS Chapter 09)\n         ├─ 0901.21    = Roasted, not decaffeinated\n         ├─ 0901.21.00 = CN subdivision\n         └─ 0901.21.00.00 = TARIC-specific\n```\n\n**What we need to build/document:**\n\n| Task | Detail | Owner |\n|---|---|---|\n| Internal product → TARIC mapping table | Map our product catalog SKUs to TARIC codes | Dev team |\n| TARIC lookup API | EU TARIC consultation service or AEAT's own | Research |\n| Validation rules | Ensure codes are valid 10-digit format | Dev team |\n| Update frequency | TARIC codes change — need a refresh strategy | Dev team |\n\n**Useful references:**\n- EU TARIC database: [https://ec.europa.eu/taxation_customs/dds2/taric/](https://ec.europa.eu/taxation_customs/dds2/taric/)\n- AEAT TARIC consultation: [https://www.agenciatributaria.es/AEAT.internet/Inicio/Aduanas-e-Impuestos-Especiales/](https://www.agenciatributaria.es/AEAT.internet/Inicio/Aduanas-e-Impuestos-Especiales/)\n\n**Ask Raul:**\n- Does AEAT's API accept raw TARIC codes or does it require their internal nomenclature coding?\n- Any Spain-specific additional digits beyond the 10-digit TARIC?\n\n---\n\n### 4. DUA Format (Documento Único Administrativo)\n\n**What is it:** The DUA is the Single Administrative Document (SAD) used for customs declarations in the EU. In Spain, AEAT processes DUAs electronically.\n\n**DUA Structure — Key fields to map:**\n\n```\n┌──────────────────────────────────────────────────────────┐\n│                    DUA / SAD Layout                       │\n├────────┬─────────────────────────────────────────────────┤\n│ Box 1  │ Declaration type (IM/EX/CO)                     │\n│ Box 2  │ Consignor/Exporter (EORI number)                │\n│ Box 8  │ Consignee (EORI number)                         │\n│ Box 14 │ Declarant/Representative                        │\n│ Box 22 │ Currency and total invoiced amount               │\n│ Box 31 │ Packages and description of goods               │\n│ Box 33 │ Commodity code (← TARIC code goes here)        │\n│ Box 34 │ Country of origin code                          │\n│ Box 37 │ Procedure code (e.g., 4000 = free circulation)  │\n│ Box 44 │ Additional information / documents produced      │\n│ Box 46 │ Statistical value                               │\n│ Box 47 │ Calculation of taxes (duties, VAT, etc.)        │\n│ Box 54 │ Place, date, signature of declarant             │\n└────────┴─────────────────────────────────────────────────┘\n```\n\n**Electronic DUA via AEAT:**\n- AEAT uses **EDI (EDIFACT)** or **XML** format for electronic DUA submission\n- System: **Despacho Aduanero** (customs clearance) platform\n- Message types: CUSDEC (customs declaration), CUSRES (customs response)\n\n**What we need to confirm with Raul:**\n\n| Question | Why it matters |\n|---|---|\n| XML Schema / XSD for DUA submission? | Need exact field formats and validation rules |\n| Which DUA types? (Import/Export/Transit) | Determines required fields |\n| EORI numbers we'll be using? | Required in multiple DUA boxes |\n| Simplified vs full declaration? | Affects data requirements |\n| Response format from AEAT? | Need to parse acceptance/rejection messages |\n\n---\n\n## Monday Call Agenda\n\n```\nAEAT API Integration — Technical Kickoff\nMonday [DATE TBD] — [TIME TBD] CET (Barcelona time)\n\nAttendees: Raul (Barcelona), Dev team\n\nAgenda:\n─────────────────────────────────────────\n1. [10 min] Token/credentials walkthrough\n   - What exactly does Raul have?\n   - Secure handoff of credentials\n   - Environment access (sandbox?)\n\n2. [15 min] Authentication flow\n   - Certificate vs token clarification\n   - Test a basic authenticated request live\n\n3. [15 min] Endpoint mapping\n   - Which AEAT services do we need?\n   - Walk through available endpoints\n   - SOAP vs REST confirmation\n\n4. [10 min] TARIC code mapping\n   - How are product codes submitted?\n   - Any AEAT-specific quirks?\n\n5. [10 min] DUA format & submission\n   - XML schema review\n   - Declaration types in scope\n   - Response handling\n\n6. [10 min] Next steps & timeline\n   - Sandbox testing plan\n   - Who owns what\n   - Target date for first test submission\n─────────────────────────────────────────\n```\n\n---\n\n## Security Notes\n\n> ⚠️ **CRITICAL: Credential Handling**\n> - Do **NOT** share AEAT tokens/certificates over email, Slack, or any unencrypted channel\n> - Use a secrets manager (Vault, AWS Secrets Manager, 1Password team vault, etc.)\n> - Store certificates with restricted file permissions (`chmod 600`)\n> - Never commit credentials to version control\n> - Document which team members have access\n\n---\n\n## Open Questions Log\n\n| # | Question | Assigned To | Status |\n|---|---|---|---|\n| 1 | Exact nature of \"token\" (cert vs API key vs OAuth) | Raul | ⏳ Pending |\n| 2 | Sandbox environment availability | Raul | ⏳ Pending |\n| 3 | AEAT API version in use (SII v1.1? Customs v?) | Raul | ⏳ Pending |\n| 4 | Our EORI number(s) for testing | Internal | ⏳ Pending |\n| 5 | DUA types in scope (import only? export?) | Product/Business | ⏳ Pending |\n| 6 | XML schema / WSDL files | Raul | ⏳ Pending |\n| 7 | Rate limits / throttling on AEAT APIs | Raul | ⏳ Pending |\n\n---\n\n**Next update:** After Monday call\n**Document owner:** [Your name]\n**Last updated:** [Today's date]"
}