Navarre Tax Office

Connect your applications to the tax certificates issued by the Hacienda Foral de Navarra (Navarre regional tax office).

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

Errors

Errors returned by the Navarre Tax Office, 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 the Navarre Tax Office or validation errors.
  • navarra: Errors related to the Navarre Tax Office.
  • nif, representation, type: Validation errors.
• maintenance (boolean) : Set when the Navarre Tax Office is under maintenance.
• retryable optional (boolean) : true on 503 responses where we could not communicate with the authority; retry after Retry-After. It is absent on 424 and on the unknown-outcome 503 of a write.

Status codes

Response

Navarre Tax Office error (424):

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

Validation error (422):

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

Rate 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

GET /report-corriente — Certificate of being up to date with tax obligations at the Hacienda Foral de Navarra. Returns the PDF issued by the tax office and, when it can be read, whether its result is positive or negative.

Parameters

• representation optional (boolean) : true (default) to request the certificate on behalf of the given nif; false to request it in the holder’s own name (the holder of the digital certificate).
• nif (string) : NIF/CIF of the represented person or company, 9 characters at most. Mandatory when requesting on behalf of someone; if omitted, the CIF of the authenticated user’s company is used. Ignored with representation=false.
• type optional (string) : Certificate to request. Possible values:
  • EstarAlCorriente: Being up to date with tax obligations. Default value.
  • DeudasPorNif: Certificate of debts for the NIF.
  • EstarAlCorrienteContratistas: Being up to date with tax obligations for contractors and subcontractors.

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

Response parameters

• data.result (string) : Result of the certificate: positive (up to date), negative (not up to date) or null if it could not be determined from the PDF.
• data.file (object) : The certificate as a PDF.
  • contentType (string) : application/pdf.
  • name (string) : File name.
  • content (string) : The PDF as base64.

Response

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