DEHU

Conecta tus aplicaciones con funciones DEHU.

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/dehu

Errores

Los errores recibidos en la API del DEHU o errores de validación.

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 del DEHU o errores de validación.
- dehu: Errores relacionados con el DEHU.
- regimen: Errores de validación.
maintenance (booleano) : Cuando el DEHU 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": {
    "dehu": [
      "Página no operativa, inténtelo de nuevo más tarde. StatusCode: 500"
    ]
  },
  "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.

Cabecera	Tipo	Cuándo se envía	Qué indica
`X-Ratelimit-Limit`	entero	Siempre	Peticiones permitidas por minuto.
`X-Ratelimit-Remaining`	entero	Siempre	Peticiones que te quedan en la ventana actual.
`X-Ratelimit-Reset`	timestamp UNIX	Siempre	Instante en que la ventana se renueva y `X-Ratelimit-Remaining` vuelve a su máximo.
`Retry-After`	segundos	Solo en `429`	Segundos que debes esperar antes de reintentar.

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

⚠️

Espera los segundos que indique Retry-After antes de reintentar. Reintentar antes de tiempo no adelanta el desbloqueo: consume más cupo y alarga la espera.

Obtener estadísticas

GET /notification-stats

{}

Respuesta

{
  "success": true,
  "message": "OK",
  "data": {
    "totalNotReadCommunications": "29",
    "totalPendingNotifications": "78",
    "newDeviceForPushNotify": "0",
    "userHasUnverifiedEmail": "0",
    "userHasNotContact": "0"
  }
}

Buscar estado de notificación

Parámetros (filtros)

id (número entero) : campo "identifier" de la notificación.

GET /notification-finder

{
  "id": "N259998999"
}

Respuesta

{
  "success": true,
  "message": "OK",
  "status": 200,
  "data": [
    {
      "type": "notifications/pending",
      "emitterSourceEntity": "Ministerio de Inclusión, Seguridad Social y Migraciones",
      "sentReference": "446dee88a09c99995754f4d68dc7weq3ea3c909873991",
      "state": "PENDIENTE"
    }
  ]
}

Notificaciones Pendientes

Parámetros

page (número entero) : Número de página actual, por defecto es 1.
limit (número entero) : Registros por petición, opcional; por defecto y como límite 50 registros.
titularNif (caracteres) : NIF del titular, opcional.
startDate: Fecha de inicio en formato Y-m-d, opcional.
endDate: Fecha de fin en formato Y-m-d, opcional.

GET /notifications-pending

{
  "page": 1,
  "startDate": "2025-01-01",
  "endDate": "2025-01-02"
}

Respuesta

sentReference: Identificador de la notificación.

Respuesta

{
  "success": true,
  "message": "OK",
  "data": {
    "count": 50,
    "total": 51,
    "limit": 50,
    "page": 1,
    "items": [
      {
        "emitterEntity": "Tesoreria General de la Seguridad Social",
        "emitterSourceEntity": "Ministerio de Inclusión, Seguridad Social y Migraciones",
        "nifTitular": "B19994999",
        "sentReference": "446dee88a09c99995754f4d68dc7weq3ea3c909873991",
        "identifier": "N259998999",
        "concept": "REGIMENES SEG. SOCIAL OBLIGADOS A RED / 2101V0999999990999 / PROVIDENCIA DE APREMIO",
        "description": null,
        "postalDelivery": false,
        "availabilityDate": "2025-10-05T00:03:49+02:00",
        "expirationDate": "2025-10-16T23:59:59+02:00",
        "finalDate": null,
        "bondType": "DESTINATARIO",
        "notificationPriority": "NORMAL",
        "unsynchronizedAppearance": null,
        "assuranceLevel": "low"
      }
    ]
  }
}

Notificaciones Realizadas

Parámetros

page (número entero) : Número de página actual, por defecto es 1.
limit (número entero) : Registros por petición, opcional; por defecto y como límite 50 registros.
titularNif (caracteres) : NIF del titular, opcional.
startDate: Fecha de inicio en formato Y-m-d, opcional.
endDate: Fecha de fin en formato Y-m-d, opcional.

GET /notifications-done

{
  "page": 1,
  "startDate": "2025-01-01",
  "endDate": "2025-01-02"
}

Respuesta

sentReference: Identificador de la notificación.

Respuesta

{
  "success": true,
  "message": "OK",
  "data": {
    "count": 50,
    "total": 51,
    "limit": 50,
    "page": 1,
    "items": [
      {
        "emitterEntity": "Tesoreria General de la Seguridad Social",
        "emitterSourceEntity": "Ministerio de Inclusión, Seguridad Social y Migraciones",
        "vinculoReceptor": "TITULAR",
        "nifTitular": "B21999999",
        "sentReference": "446dee88a09c99995754f4d68dc7weq3ea3c909873991",
        "state": "ACEPTADA",
        "identifier": "N259993999",
        "concept": "REGIMENES SEG. SOCIAL OBLIGADOS A RED / 2190A4525099999999 / RESOLUCION ALTAS/BAJAS (RED)",
        "postalDelivery": false,
        "availabilityDate": "2025-10-10T01:28:53+02:00",
        "expirationDate": "2025-10-21T23:59:59+02:00",
        "finalDate": "2025-10-10T08:26:02+02:00",
        "bondType": "DESTINATARIO",
        "hasAnnexes": false,
        "notificationPriority": "NORMAL",
        "assuranceLevel": "low"
      }
    ]
  }
}

Comunicaciones

Parámetros (filtros)

page (número entero) : Número de página actual, por defecto es 1.
limit (número entero) : Registros por petición, opcional; por defecto y como límite 50 registros.
titularNif (caracteres) : NIF del titular, opcional.
startDate: Fecha de inicio en formato Y-m-d, opcional.
endDate: Fecha de fin en formato Y-m-d, opcional.

GET /communications

{
  "page": 1,
  "startDate": "2025-01-01",
  "endDate": "2025-01-02"
}

Respuesta

sentReference: Identificador de la notificación.

Respuesta

{
  "success": true,
  "message": "OK",
  "data": {
    "count": 50,
    "total": 51,
    "limit": 50,
    "page": 1,
    "items": [
      {
        "emitterEntity": "Tesoreria General de la Seguridad Social",
        "emitterSourceEntity": "Ministerio de Inclusión, Seguridad Social y Migraciones",
        "vinculoReceptor": "",
        "nifTitular": "99936799A",
        "sentReference": "446dee88a09c99995754f4d68dc7weq3ea3c909873991",
        "state": "PENDIENTE",
        "identifier": "C59999999",
        "concept": "REGIMENES SEG. SOCIAL OBLIGADOS A RED / 2101D2999942419999 / COMUNICACIÓN CON DESTINO NACIONAL",
        "postalDelivery": false,
        "availabilityDate": "2025-10-09T00:02:48+02:00",
        "finalDate": null,
        "document": [],
        "bondType": "DESTINATARIO",
        "hasAnnexes": false
      }
    ]
  }
}

Obtener detalle de una notificación realizada

Parámetros (filtros)

id (caracteres) : Identificador de la notificación (sentReference).
duplicate (número) : Opcional. obtiene el "content" del document en base64 si lo tiene.
voucher (número) : Opcional. obtiene el "content" del resguardo en base64 si lo tiene.

GET /notification-done

{
  "id": "446dee88a09c99995754f4d68dc7weq3ea3c909873991"
}

Respuesta

{
  "success": true,
  "message": "OK",
  "data": {
    "emitterEntity": "Tesoreria General de la Seguridad Social",
    "emitterSourceEntity": "Ministerio de Inclusión, Seguridad Social y Migraciones",
    "nifReceptor": "99999962X",
    "nameReceptor": "JOSE JUAN PEREZ",
    "receiver": {
      "nif": "99999962X",
      "name": "JOSE JUAN PEREZ",
      "dir3Code": null,
      "direCode": null
    },
    "nifTitular": "B99999999",
    "dir3Code": null,
    "direCode": null,
    "cantAnnexes": 0,
    "sentReference": "446dee88a09c99995754f4d68dc7weq3ea3c909873991",
    "state": "ACEPTADA",
    "identifier": "N999609999",
    "concept": "REGIMENES SEG. SOCIAL OBLIGADOS A RED / 99999999904 / RECLAMACIÓN DE DEUDA",
    "description": null,
    "availabilityDate": "2025-10-01T01:37:22+02:00",
    "expirationDate": "2025-10-12T23:59:59+02:00",
    "finalDate": "2025-10-01T10:29:32+02:00",
    "document": {
      "publicMetadata": null,
      "privateMetadata": null,
      "documentLink": null,
      "name": "SINT_FGDE_999999999.pdf",
      "mimeType": "application/pdf",
      "content": null
    },
    "bondType": "DESTINATARIO",
    "unsuccessfulState": null,
    "hasAnnexes": false,
    "siaCode": "2997999",
    "siaDenomination": "NOTIFICACIONES ELECTRÓNICAS TGSS",
    "voucher": {
      "mimeType": "application/pdf",
      "name": "Resguardo_xxx.pdf",
      "enabled": true,
      "content": null
    }
  }
}

Obtener duplicado de una notificación

Parámetros (filtros)

id (caracteres) : Identificador de la notificación (sentReference).

GET /notification-document

{
  "id": "446dee88a09c99995754f4d68dc7weq3ea3c909873991"
}

Respuesta

{
  "success": true,
  "message": "OK",
  "data": {
    "content": "base64",
    "name": "SINT_FGDE_999999999.pdf",
    "mimeType": "application/pdf",
    "contentType": "application/pdf",
    "privateMetadata": null
  }
}

Obtener resguardo de una notificación

Parámetros (filtros)

id (caracteres) : Identificador de la notificación (sentReference).

GET /notification-voucher

{
  "id": "446dee88a09c99995754f4d68dc7weq3ea3c909873991"
}

Respuesta

{
  "success": true,
  "message": "OK",
  "data": {
    "content": "base64",
    "name": "Resguardo_1xxbbb9x.pdf",
    "mimeType": "application/pdf",
    "contentType": "application/pdf",
    "enabled": true
  }
}