AEAT

Connect your applications to Tax Agency services.

HTTP header parameters

• Authorization (string): API authorisation. Example: Bearer {token}
• X-Cert-Secret (string) : Secret key associated with the client certificate.

Base URL

https://api.saltra.es/api/v4/aeat

Errors

Errors returned by the Social Security API, or validation errors.

Response parameters

• success (boolean) : Returns "true" when everything is correct, and "false" when there are errors.
• message (string) : The response message.
• errors (array) : Errors captured by the API, either from AEAT or validation errors.
  • aeat: Errors related to AEAT.
  • regimen: Validation errors.
• maintenance (boolean) : Set when AEAT is under maintenance.

Response

{
  "success": false,
  "message": "Página no operativa, inténtelo de nuevo más tarde. StatusCode: 500",
  "status": 500,
  "data": [],
  "errors": {
    "aeat": [
      "Página no operativa, inténtelo de nuevo más tarde. StatusCode: 500"
    ],
    "regimen": ["El campo regimen es obligatorio."]
  },
  "maintenance": true
}

Limits

Authenticated requests are limited to 80 per minute for reads (GET) and 120 per minute for writes (POST). The limit is counted per certificate (if X-Cert-Secret is sent) or, failing that, per authenticated user, and per route. Unauthenticated requests are limited to 60 per minute per IP. The heavy-integration endpoints —GET /employee-situations and GET /ta-info-for-nss from Social Security, and GET /contrata/data from SEPE— share a lower combined quota of 30 requests per minute per certificate (or user): using one reduces the quota of the other two.

Saltra reports your quota status in the headers of every response, so you can pace your calls before running out.

Example of a successful response:

HTTP/1.1 200 OK
X-Ratelimit-Limit: 80
X-Ratelimit-Remaining: 45
X-Ratelimit-Reset: 1786012860

X-Ratelimit-Reset is an absolute instant, not a countdown: it stays the same across every response in the same window and only moves forward when the quota renews. Combined with X-Ratelimit-Remaining, it is what lets you space out requests as you approach the limit instead of stopping dead.

Once the limit is exceeded, the API responds 429 Too Many Requests and adds Retry-After:

HTTP/1.1 429 Too Many Requests
X-Ratelimit-Limit: 80
X-Ratelimit-Remaining: 0
X-Ratelimit-Reset: 1786012860
Retry-After: 37

The body follows the usual error format:

{
  "success": false,
  "status": 429,
  "message": "Too Many Requests"
}

Certificate of being up to date with tax obligations

Parameters

• type (string) : Certificate type. Possible values:
  • C1: Being up to date with tax obligations in order to contract with the public sector.
  • T1: Being up to date with tax obligations in order to obtain transport authorisations.
  • B1: Being up to date with tax obligations in order to obtain public subsidies.
  • E1: Being up to date with tax obligations in order to obtain work/residence permits for foreign nationals.
  • G1: Being up to date with tax obligations. Generic (for a purpose other than the four above).

{
  "type": "C1"
}

Response

{
  "success": true,
  "message": "OK",
  "data": {
    "file": {
      "contentType": "application/pdf",
      "name": "document.pdf",
      "content": "base64"
    }
  }
}

Obtain an AEAT certificate for Economic Activities Tax (IAE)

Parameters

• period (integer) : Period.

{
  "period": "2022"
}

Response

{
  "success": true,
  "message": "OK",
  "data": {
    "file": {
      "contentType": "application/pdf",
      "name": "document.pdf",
      "content": "base64"
    }
  }
}

Obtain a certificate for contractors and subcontractors

Parameters

• nif_entidad (string) : NIF of the entity.
• entidad (string) : Optional. Surname and first name / registered name of the entity.
• startDate (date) : Optional. Date, format YYYY-MM-DD.

{
  "nif_entidad": "B999999"
}

Response

{
  "success": true,
  "message": "OK",
  "data": {
    "file": {
      "contentType": "application/pdf",
      "name": "document.pdf",
      "content": "base64"
    }
  }
}