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.

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
}

Limitaciones

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 (caracteres) : Opcional. Apellidos y nombre / Razón social de la entidad.
• startDate (date) : Opcional. Fecha, formato YYYY-MM-DD.

{
  "nif_entidad": "B999999"
}

Respuesta

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