SIGN ES - How to use the endpoints for the social collaboration agreement?

We provide all the endpoints you need for a compliant solution. SIGN ES API will require all the necessary information to fill out the social collaboration annex, according to the template provided by the authorities in the Resolution of December 18th, 2024.

The Annex 1 is the model of representation between taxpayers and software providers, by which the taxpayer authorizes fiskaly to transmit Verifactu invoicing records to the Spanish Tax Authority. The information required changes depending if the Taxpayer is a COMPANY or an INDIVIDUAL.

Step by step with SIGN ES API

1. Ensure you have provided all the information in the Create taxpayer endpoint:
   • Taxpayer’s legal name (legal_name)
   • Taxpayer’s NIF (tax_number)
   • Taxpayer’s legal address (address). If the address is missing, you can use the Update a taxpayer endpoint to provide it.
2. Use the Generate agreement endpoint to trigger the creation of the document. If any information is missing, you will see this in the response from the API.
   • For INDIVIDUAL taxpayer type, no additional information is needed.
   • For COMPANY taxpayer type, we need the information of the legal representative:
     1. Representative’s name (full_name)
     2. Representative’s NIF (tax_number)
     3. Representative’s address (address)
3. Obtain the filled out PDF for the agreement in the successful response to the Generate agreement endpoint.
4. The taxpayer needs to electronically sign the PDF (e.g. through VALIDe platform online or through the desktop app AutoFirma).
5. Upload the electronically signed agreement through SIGN ES Upload signed agreement endpoint.

If the information of the taxpayer and/or the legal representative is modified, a new agreement must be uploaded.

SIGN ES API will always return the latest valid agreement through the Retrieve agreement endpoint.

What information is fiskaly validating in an uploaded agreement?

When you submit a PDF through the Upload signed agreement endpoint, fiskaly verifies the following:

1. Taxpayer details match
   The agreement must contain the same name and tax number as the Taxpayer submitting it.
2. fiskaly's signature is present
   The PDF must include fiskaly’s electronic signature as provided in the originally generated agreement.
3. Second signature present
   The document must also contain a second electronic signature, associated with the NIF of the individual signing the agreement.

If any of these conditions are not met, the upload will fail and return an error: 

cannot be recognized as a valid agreement

• The uploaded file is not a PDF (e.g. an image, video, etc.), or
• The uploaded file is a PDF, but it's not the one generated by fiskaly.

too few signatures

As we require at least 2 signatures on the agreement, this error appears if:

• The file was uploaded without being signed, or
• The fiskaly e-signature was removed, leaving only your signature.

missing fiskaly seal

• The first signature in the document is not fiskaly's.

signature does not match representative NIF

• The non-fiskaly signature does not match the representative's NIF on the agreement.

cannot parse document

• The document is not a valid PDF file.

signature {n} is invalid

• The n-th signature failed the DSS service validation.