Credentials and security
This guide describes sk_test_ and sk_live_ tokens. The public demonstration uses sk_demo_, expires after 24 hours and has its own limits and temporary storage.
Use the token
SERTEC PESAGE support provides your integration token. Include it in every /api/v1 request:
Code
Use HTTPS, with TLS 1.2 or later, and send the token only in this header. Tokens are opaque: do not decode them or generate a JWT. sk_test_ selects development and sk_live_ production, with the same routes and separate documents.
Code
Authorized IP addresses
If a token has an authorized IP list, requests must originate from one of those public outbound IP addresses. A valid token from an unauthorized IP receives 403. An empty list permits any IP. IP restrictions supplement protection of tokens and authorized servers.
The API cannot register IP addresses. Sending X-Forwarded-For does not authorize an address. Contact support before an outbound address changes.
Protect credentials
- Store tokens in a secrets manager or protected server configuration.
- Call from your server; do not expose tokens in web pages, browser JavaScript or applications distributed to third parties.
- Keep tokens out of URLs, repositories, logs, screenshots and support tickets.
- Use a separate credential for each integration.
- If a token may have leaked, ask support to revoke it and issue a new one.
The QR URL contains a separate secret. Use the returned link unchanged and do not publish or log it. QR access uses that secret, without Bearer or API IP restrictions.
Limits and retries
Each token allows 60 requests per minute. QR downloads allow 30 requests per minute for the same IP and document. On 429, wait the seconds in Retry-After.
Request bodies are limited to 128 KiB. Send JSON with Content-Type: application/json; another format returns 415, malformed JSON returns 400.
References identify versions and are unique within the organization and environment. Repeating a creation with the same reference and data returns the original document for 24 hours. Without a reference, each creation issues a new document. Corrections require all data again and, if provided, a new reference. The original and its QR remain unchanged.
Bearer retrieval and downloads are limited to documents issued by that credential in the last 24 hours. QR access continues during PDF retention, after this window and after token rotation or revocation. Deleted documents cannot be downloaded. Logical deletion is only allowed within 2 hours, before handing over or using the document; the first successful QR access also blocks deletion with 409 DOCUMENT_ALREADY_ACCESSED. QR access alone does not prove that transport has taken place.
The deployment must run Laravel's scheduler. The hourly documents:prune-recent-keys task removes expired recent-access keys; the API enforces 24 hours even before cleanup runs.
Portal account and recovery
A recovery code belongs to a portal account; it is not an API token and is not sent in the Bearer header. Registration, including additional administrator accounts, requires configuring the first passkey, printing or downloading the code, and re-entering it before the account is created. DeCA does not display the saved code again.
If a passkey fails, a modal offers recovery-code entry. Login still requires the correct password; the code replaces the passkey and opens the same encrypted archive keys. Operations requiring the current password still require it. Canceling returns to the previous form without executing the operation.
A code can confirm any operation that requests a passkey, including its own regeneration and passkey deletion. If a passkey is used to delete another passkey, it must be different from the one being deleted; every user always retains at least one. In Security, the previous code remains active until the new code is printed or downloaded and correctly re-entered; it and its pending confirmations are then invalidated.
Keep the code outside the system, in a private place separate from your password. Do not include it in API calls, logs or support messages. Losing the credentials that can open the keys may prevent archive recovery.
Retention and private copies
PDFs are retained for one year and encrypted structured data for four years, from issue or the transport date if later. Bearer access remains limited to 24 hours. The QR link provides account-free PDF access during PDF retention; token rotation or revocation alone does not disable it. Once the PDF is removed, the old QR no longer permits its download.
While data is retained, an authorized person can unlock the portal archive and generate a private copy of the PDF. The copy is newly generated: it does not recover the deleted original file's bytes, is not saved as a new permanent PDF and does not reactivate an expired QR link. The issue language and logo are preserved when included in the original data.
Encryption does not mean the server never handles keys: recovery-code verification and private-copy generation use transient key material. Neither the plain-text code nor the data key supplied for regeneration is persisted.
Hostinger backups are retained for 7 days. Manual copies of the project in ZIP and the database in SQL can also be made: keep them outside public access, protected and with restricted access. The private temporary-key store for the last 24 hours is separate from the project and database and must stay outside those ZIP and SQL copies. After restoration, run pruning according to retention periods and invalidate sessions and temporary access before reopening the service. Backups do not grant unlimited retention.
Transport data and scope
For domestic road goods transport in Spain, Order FOM/2861/2012 requires the contractual shipper's name, tax ID and address; the actual carrier's name and tax ID; loading and unloading locations; the nature and weight of goods, or an alternative measurement if weight is difficult to determine; the transport date, vehicle and trailer registrations, and any required special circulation authorization.
origin.place and destination.place may identify a site by name or address. Together with city and country they must identify the real location clearly; optional street and postal_code provide precision. A full consignee identity is not mandatory under this order. carrier.address is optional; if supplied, all Address fields are required. Supply an actual transport date, accurate goods details and a trailer when present.
Operators must ensure retention and availability for at least one year, including access by other transport parties. PDF generation does not itself establish certification for eFTI or replace international CMR, ADR, waste transfer or animal by-product documents. An electronic signature is not generally required for this administrative control document; separate contractual uses may require an appropriate electronic signature.
Troubleshoot access
| Response | Check |
|---|---|
401 | Missing, incorrect or revoked token. Check the header and contact support for replacement. |
403 | Check the outbound public IP and request authorization. It can also mean the operation is not permitted. |
When contacting support, provide the request time, outbound public IP, method, path and error code. Never send the token or secret QR link.
Electronic requirements: Resolution of 5 June 2026. Electronic PDFs are limited to 5 MB, include creation and modification metadata and provide direct HTTPS access. Using the API does not replace the parties' operational duties.
The eight languages translate PDF headings and labels, not names, addresses, remarks or other data submitted by the integration. Printed text supports font-compatible Latin, Greek and Cyrillic characters; emoji, CJK and right-to-left scripts return 422 UNSUPPORTED_CHARACTERS for the affected field. metadata preserves arbitrary Unicode and is not printed.
Document URLs use the public HTTPS URL configured by the service operator. An invalid configuration returns 503 SERVICE_UNAVAILABLE; a failed issue does not persist a partial document.
Special Spanish K, L and M tax IDs are validated by format; DNI, NIE and entity NIF retain check-character validation. Validating an identifier does not establish existence or tax registration.