AEAT

Conecta tus aplicaciones con funciones de la hacienda.

Parámetros en la cabecera HTTP

• Authorization (caracteres): Autorización de la API. Ejemplo: Bearer {token}
• X-Cert-Secret (caracteres) : Clave secreta asociada al certificado del cliente.

URL base

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

Errores

Los errores recibidos en la API de Seguridad Social o errores de validación.

Parámetros de respuesta

• success (booleano) : La respuesta “true” cuando todo esta correcto, y “false” cuando hay errores.
• message (caracteres) : El mensaje de la respuesta.
• errors (arreglo) : Los errores capturados en la API, ya sea de AEAT o errores de validación.
  • aeat: Errores relacionados con AEAT.
  • regimen: Errores de validación.
• maintenance (booleano) : Cuando AEAT se encuentra en mantenimiento.
• retryable opcional (booleano) : true en los 503 en los que no hemos podido comunicarnos con el organismo; reintenta después de Retry-After. No aparece en el 424 ni en el 503 de resultado desconocido de una escritura.

Respuesta

{
  "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
}

Códigos de estado

Cuando el fallo está en el organismo (TGSS/Sistema RED, SEPE, DEHU, AEAT, Hacienda de Navarra) o en el sistema conectado, el código HTTP dice si merece la pena reintentar. El cuerpo es siempre el formato de error habitual (success, message, status, data, errors): léelo en cualquier código, el motivo está en message.

Los errores de validación de Saltra siguen siendo 422 (no reintentes hasta corregir los datos).

Ejemplo de 503 reintentable:

HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Retry-After: 60
X-Saltra-Error: organism-unavailable

{
  "success": false,
  "message": "Error de conexión de SALTRA con el (SISTEMA RED).",
  "status": 503,
  "data": [],
  "errors": {
    "tgss": ["Error de conexión de SALTRA con el (SISTEMA RED)."]
  },
  "maintenance": false,
  "retryable": true,
  "retry_after": 60
}

Límites de consultas

Las peticiones autenticadas están limitadas a 80 por minuto en las consultas (GET) y 120 por minuto en las escrituras (POST). El límite se cuenta por certificado (si se envía X-Cert-Secret) o, en su defecto, por usuario autenticado, y por ruta. Las peticiones no autenticadas se limitan a 60 por minuto por IP. Los endpoints de integración pesada —GET /employee-situations y GET /ta-info-for-nss de Seguridad Social, y GET /contrata/data del SEPE— comparten un cupo combinado más bajo, de 30 peticiones por minuto por certificado (o usuario): consumir uno reduce el cupo de los otros dos.

Saltra publica el estado de tu cupo en las cabeceras de todas las respuestas, para que puedas regular el ritmo de tus llamadas antes de agotarlo.

Ejemplo de respuesta correcta:

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

X-Ratelimit-Reset es un instante absoluto, no una cuenta atrás: se mantiene igual en todas las respuestas de la misma ventana y solo avanza cuando el cupo se renueva. Combinado con X-Ratelimit-Remaining es lo que te permite espaciar las peticiones cuando te acercas al límite, en vez de detenerte en seco.

Al superar el límite, la API responde 429 Too Many Requests y añade Retry-After:

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

El cuerpo sigue el formato de error habitual:

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

Certificado de hallarse al corriente

Parámetros

• type (caracteres) : Tipo de certificado. Posibles valores:
  • C1: Encontrarse al corriente de las obligaciones tributarias para contratar con el sector público.
  • T1: Encontrarse al corriente de las obligaciones tributarias para obtener autorizaciones de transporte.
  • B1: Encontrarse al corriente de las obligaciones tributarias para obtener subvenciones públicas.
  • E1: Encontrarse al corriente de las obligaciones tributarias para obtener autorizaciones de trabajo/residencia por extranjeros.
  • G1: Encontrarse al corriente de las obligaciones tributarias. Genérico (finalidad distinta de las 4 anteriores).

{
  "type": "C1"
}

Respuesta

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

Obtener certificado de AEAT de Impuestos de Actividades Económicas(IAE)

Parámetros

• period (número entero) : Periodo.

{
  "period": "2022"
}

Respuesta

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

Obtener certificado de Contratistas y subcontratistas

Parámetros

• nif_entidad (caracteres) : NIF de la Entidad.
• entidad opcional (caracteres) : Apellidos y nombre / Razón social de la entidad.
• startDate opcional (date) : Fecha, formato YYYY-MM-DD.

{
  "nif_entidad": "B999999"
}

Respuesta

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