Hacienda de Navarra

Conecta tus aplicaciones con la emisión de certificados tributarios de la Hacienda Foral de Navarra.

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

Errores

Los errores devueltos por Hacienda de Navarra 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 Hacienda de Navarra o errores de validación.
  • navarra: Errores relacionados con Hacienda de Navarra.
  • nif, representation, type: Errores de validación.
• maintenance (booleano) : Cuando Hacienda de Navarra se encuentra en mantenimiento.

Códigos de estado

Respuesta

Error de Hacienda de Navarra (502):

{
  "success": false,
  "message": "Hacienda de Navarra no ha validado la representación del NIF B31000000.",
  "status": 502,
  "data": [],
  "errors": {
    "navarra": [
      "Hacienda de Navarra no ha validado la representación del NIF B31000000."
    ]
  }
}

Error de validación (422):

{
  "success": false,
  "message": "validation_errors",
  "status": 422,
  "data": [],
  "errors": {
    "nif": ["El campo NIF es obligatorio si se solicita en representación."]
  }
}

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 estar al corriente

GET /report-corriente — Certificado de estar al corriente de las obligaciones tributarias en la Hacienda Foral de Navarra. Se devuelve el PDF emitido por Hacienda y, cuando se puede leer, si su resultado es positivo o negativo.

Parámetros

• representation (booleano) : Opcional. true (valor por defecto) para pedir el certificado en representación del nif indicado; false para pedirlo en nombre propio del titular del certificado digital.
• nif (caracteres) : NIF/CIF de la persona o empresa representada, máximo 9 caracteres. Obligatorio cuando se pide en representación; si no se envía, se usa el CIF de la empresa del usuario autenticado. Se ignora con representation=false.
• type (caracteres) : Opcional. Certificado que se solicita. Posibles valores:
  • EstarAlCorriente: Estar al corriente de las obligaciones tributarias. Valor por defecto.
  • DeudasPorNif: Certificado de deudas del NIF.
  • EstarAlCorrienteContratistas: Estar al corriente de las obligaciones tributarias para contratistas y subcontratistas.

{
  "representation": true,
  "nif": "B31000000",
  "type": "EstarAlCorriente"
}

curl -G "https://api.saltra.es/api/v4/navarra/report-corriente" \
  -H "Authorization: Bearer {token}" \
  -H "X-Cert-Secret: {cert_secret}" \
  -H "Accept: application/json" \
  --data-urlencode "nif=B31000000"

Parámetros de respuesta

• data.result (caracteres) : Resultado del certificado: positive (al corriente), negative (no al corriente) o null si no se ha podido determinar a partir del PDF.
• data.file (objeto) : El certificado en PDF.
  • contentType (caracteres) : application/pdf.
  • name (caracteres) : Nombre del fichero.
  • content (caracteres) : El PDF en base64.

Respuesta

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