NIFs Management API Documentation

# Basic operation Here you will find the technical documentation of our API for general management of your NIFs in our system.

NIFs

NIFs can be created in the test environment, which communicates with the administration's test environment.

`GET` /nifs

List NIFs

This endpoint returns a list of all NIFs.

Responses

Status	Description
`200`	NIF list
`400`	Invalid query parameters
`401`	Unauthorized — invalid or missing API key.
`500`	Internal server error.

`POST` /nifs

Add NIFs

This endpoint adds new NIFs.

Responses

Status	Description
`200`	NIF
`400`	Invalid input data
`401`	Unauthorized — invalid or missing API key.
`409`	NIF already exists
`500`	Internal server error.

`GET` /nifs/{entorno}/{nif}

NIF Information

This endpoint returns the information of a specific NIF.

Responses

Status	Description
`200`	NIF
`401`	Unauthorized — invalid or missing API key.
`404`	NIF not found
`500`	Internal server error.

`PUT` /nifs/{entorno}/{nif}

Modify NIF

This endpoint allows modifying the information of a specific NIF.

Request body

Field	Type	Required	Description
`nombre`	string	no	Full name or company name of the NIF.
`direccion`	string	no	NIF address.
`cp`	string	no	NIF postal code.
`poblacion`	string	no	NIF city.
`provincia`	string	no	NIF province.
`webhooks`	array	no	List of webhook identifiers to which the NIF will be linked.
`label`	string	no	Label associated with the NIF.

Responses

Status	Description
`200`	NIF
`400`	Invalid input data
`401`	Unauthorized — invalid or missing API key.
`404`	NIF not found
`500`	Internal server error.

`DELETE` /nifs/{entorno}/{nif}

Deactivate NIF

This endpoint allows deactivating a NIF.

Responses

Status	Description
`200`	OK
`401`	Unauthorized — invalid or missing API key.
`403`	NIF is already inactive
`404`	NIF not found
`500`	Internal server error.

`DELETE` /nifs/{entorno}/{nif}/permanent

Delete NIF

This endpoint allows permanently deleting a NIF.

Responses

Status	Description
`200`	OK
`401`	Unauthorized — invalid or missing API key.
`404`	NIF not found
`500`	Internal server error.

`PUT` /nifs/activate/{entorno}/{nif}

Activate NIF

This endpoint allows activating a NIF that has been previously deactivated.

Responses

Status	Description
`200`	OK
`401`	Unauthorized — invalid or missing API key.
`403`	NIF is already active
`404`	NIF not found
`500`	Internal server error.

`GET` /nifs/keys/{entorno}/{nif}

NIF API Key

This endpoint returns the API key for a specific NIF in a specific environment.

Responses

Status	Description
`200`	API key
`401`	Unauthorized — invalid or missing API key.
`404`	NIF not found
`500`	Internal server error.

Validation

There are many circumstances where it is useful to validate that a NIF is correct and registered with the administration, for both companies (CIF) and national citizens (DNI) and foreign residents (NIE).

`POST` /nifs/validar

Validate NIF at the AEAT

This endpoint validates whether a NIF of an individual or legal entity is identified at the tax agency.

Request body

Field	Type	Required	Description
`nif`	string	yes	NIF of the individual or legal entity to be verified.
`nombre`	string	no	Last name and first name of the individual or company name of the legal entity for which the verification query is to be made.

Responses

Status	Description
`200`	AEAT response
`400`	Invalid input data
`401`	Unauthorized — invalid or missing API key.
`500`	Internal server error or AEAT service unavailable

`POST` /nifs/validar_lotes

Batch Validate NIFs

This endpoint allows validating up to 20,000 NIFs in a single call, checking whether each NIF of an individual or legal entity exists.

Responses

Status	Description
`200`	AEAT response
`400`	Invalid input data
`401`	Unauthorized — invalid or missing API key.
`500`	Internal server error or AEAT service unavailable

`POST` /nifs/validar/vies

Validate VAT in VIES

This endpoint allows validating that an intra-community VAT number is registered in the VIES census.

Request body

Field	Type	Required	Description
`codigo_pais`	string	yes	Country code to which the VAT number belongs.
`iva`	string	yes	Intra-community VAT number.

Responses

Status	Description
`200`	VIES census response
`400`	Invalid input data
`401`	Unauthorized — invalid or missing API key.
`500`	Internal server error.

Representation

<div style="margin-bottom: 16px; padding: 12px 16px; background-color: #FFF7ED; border-left: 4px solid #FF6C37; border-radius: 4px;"> Important: The representation model described in this section only applies to Verifactu.

`POST` /representacion/firma_remota/{nif}

Start Online Signing

Starts an online signing process for the representation grant document, with identity verification and without needing an electronic certificate.

Request body

Field	Type	Required	Description
`nombre`	string	yes	Required. Signer's given name (the NIF holder).
`apellidos`	string	yes	Required. Signer's surname.
`municipio`	string	yes	Required. Municipality of residence of the invoice issuer.
`calle`	string	yes	Required. Street of residence of the invoice issuer.
`numero`	string	yes	Required. Street number of residence of the invoice issuer.
`email`	string	yes	Required. Signer's email.
`idioma`	string	no	Optional. Language of the signing ceremony and of the notification email the signer receives (<code>es</code> or <code>en</code>).
`notificacion`	object	no	Optional. Personalization of the notification email the signer receives.

Responses

Status	Description
`200`	Online signing process created
`400`	Invalid input data, the NIF is not a DNI/NIE, or a valid representation or an in-progress signing process already exists for the NIF
`401`	Unauthorized — invalid or missing API key.
`402`	Payment required: the account has accumulated unbilled online signatures and the charge with the subscription's payment method failed.
`500`	Internal server error.
`502`	Temporary error while starting the online signing process (signing provider or charge processing).

`POST` /representacion/generar/{nif}

Generate Representation PDF

This endpoint allows downloading the representation grant PDF document for a VeriFactu NIF.

Request body

Field	Type	Required	Description
`tipo_entidad`	object	no	Entity type, individuals or legal entities.
`nombre`	string	no	Required for individuals.
`municipio`	string	no	Required for individuals.
`calle`	string	no	Required for individuals.
`numero`	string	no	Required for individuals.
`nombre_entidad`	string	no	Required for legal entities.
`municipio_entidad`	string	no	Required for legal entities.
`calle_entidad`	string	no	Required for legal entities.
`numero_entidad`	string	no	Required for legal entities.
`nombre_representante`	string	no	Required for legal entities.
`nif_representante`	string	no	Required for legal entities.
`municipio_representante`	string	no	Required for legal entities.
`calle_representante`	string	no	Required for legal entities.
`numero_representante`	string	no	Required for legal entities.

Responses

Status	Description
`200`	Representation grant PDF document
`400`	Invalid input data or a valid representation already exists for the NIF
`401`	Unauthorized — invalid or missing API key.
`500`	Internal server error.

`POST` /representacion/enviar/{nif}

Submit Signed PDF

This endpoint submits the representation grant PDF document for a VeriFactu NIF.

Responses

Status	Description
`200`	PDF submitted successfully
`400`	PDF not submitted correctly
`401`	Unauthorized — invalid or missing API key.
`500`	Internal server error or failure processing the PDF

`PUT` /representacion/cancelar/{nif}

Cancel Signed PDF

This endpoint cancels the representation grant PDF document for a VeriFactu NIF.

Responses

Status	Description
`200`	PDF cancelled successfully
`401`	Unauthorized — invalid or missing API key.
`404`	Representation not found
`500`	Internal server error while processing the cancellation

`GET` /representacion/descargar/{nif}

Download Signed PDF

This endpoint allows downloading the signed representation grant PDF document for a VeriFactu NIF.

Responses

Status	Description
`200`	PDF downloaded successfully
`401`	Unauthorized — invalid or missing API key.
`404`	PDF not found for the given NIF
`500`	Internal server error.

`GET` /representacion/estado/{nif}

Representation Status

This endpoint allows retrieving the representation status for a NIF.

Responses

Status	Description
`200`	Representation status
`401`	Unauthorized — invalid or missing API key.
`500`	Internal server error.

Webhooks

Our platform supports webhooks to receive automatic notifications when a invoicing record is generated.

`GET` /webhooks

List Webhooks

This endpoint returns a list of all configured webhooks.

Responses

Status	Description
`200`	Webhook list
`400`	Invalid query parameters
`401`	Unauthorized — invalid or missing API key.
`500`	Internal server error.

`POST` /webhooks

Add Webhook

This endpoint allows registering a webhook.

Request body

Field	Type	Required	Description
`url`	string	yes	URL that will be called when the webhook fires.
`entorno`	string	yes	Webhook environment. Can be "test" or "prod".
`secret`	object	no	Optional parameter. A secret key shared between our API and the webhook receiver.
`nifs`	object	no	NIF list. When invoicing records are sent for any of these NIFs, the webhook will be triggered with the tax authority's result once obtained.

Responses

Status	Description
`200`	Webhook
`400`	Invalid input data
`401`	Unauthorized — invalid or missing API key.
`409`	Webhook already exists with that URL
`500`	Internal server error.

`GET` /webhooks/{webhook_id}

Webhook Information

This endpoint returns the information of a specific webhook.

Responses

Status	Description
`200`	Webhook
`401`	Unauthorized — invalid or missing API key.
`404`	Webhook not found
`500`	Internal server error.

`PUT` /webhooks/{webhook_id}

Modify Webhook

This endpoint allows modifying a specific webhook.

Request body

Field	Type	Required	Description
`url`	string	no	URL that will be called when the webhook fires.
`secret`	string	no	Key to generate the HMAC signature.
`activo`	boolean	no	Indicates whether the webhook will be active or not.
`nifs`	array	no	NIF list. When invoicing records are sent for any of these NIFs, the webhook will be triggered with the tax authority's result once obtained.

Responses

Status	Description
`200`	Webhook
`400`	Invalid input data
`401`	Unauthorized — invalid or missing API key.
`404`	Webhook not found
`409`	Webhook URL conflicts with an existing one
`500`	Internal server error.

`DELETE` /webhooks/{webhook_id}

Delete Webhook

This endpoint allows deleting a specific webhook.

Responses

Status	Description
`200`	OK
`401`	Unauthorized — invalid or missing API key.
`404`	Webhook not found
`500`	Internal server error.

`POST` /webhooks/{webhook_id}/nifs/{nif}

Associate NIF with Webhook

This endpoint allows associating a specific NIF with a specific webhook.

Responses

Status	Description
`200`	OK
`401`	Unauthorized — invalid or missing API key.
`404`	Webhook or NIF not found
`500`	Internal server error.

`DELETE` /webhooks/{webhook_id}/nifs/{nif}

Dissociate NIF from Webhook

This endpoint allows dissociating a specific NIF from a specific webhook.

Responses

Status	Description
`200`	OK
`204`	NIF successfully dissociated from the webhook (no content)
`401`	Unauthorized — invalid or missing API key.
`404`	Webhook or NIF not found
`500`	Internal server error.

NIFs Management API Documentation

NIFs

GET /nifs

Responses

POST /nifs

Responses

GET /nifs/{entorno}/{nif}

Responses

PUT /nifs/{entorno}/{nif}

Request body

Responses

DELETE /nifs/{entorno}/{nif}

Responses

DELETE /nifs/{entorno}/{nif}/permanent

Responses

PUT /nifs/activate/{entorno}/{nif}

Responses

GET /nifs/keys/{entorno}/{nif}

Responses

Validation

POST /nifs/validar

Request body

Responses

POST /nifs/validar_lotes

Responses

POST /nifs/validar/vies

Request body

Responses

Representation

POST /representacion/firma_remota/{nif}

Request body

Responses

POST /representacion/generar/{nif}

Request body

Responses

POST /representacion/enviar/{nif}

Responses

PUT /representacion/cancelar/{nif}

Responses

GET /representacion/descargar/{nif}

Responses

GET /representacion/estado/{nif}

Responses

Webhooks

GET /webhooks

Responses

POST /webhooks

Request body

Responses

GET /webhooks/{webhook_id}

Responses

PUT /webhooks/{webhook_id}

Request body

Responses

DELETE /webhooks/{webhook_id}

Responses

POST /webhooks/{webhook_id}/nifs/{nif}

Responses

DELETE /webhooks/{webhook_id}/nifs/{nif}

Responses

`GET` /nifs

`POST` /nifs

`GET` /nifs/{entorno}/{nif}

`PUT` /nifs/{entorno}/{nif}

`DELETE` /nifs/{entorno}/{nif}

`DELETE` /nifs/{entorno}/{nif}/permanent

`PUT` /nifs/activate/{entorno}/{nif}

`GET` /nifs/keys/{entorno}/{nif}

`POST` /nifs/validar

`POST` /nifs/validar_lotes

`POST` /nifs/validar/vies

`POST` /representacion/firma_remota/{nif}

`POST` /representacion/generar/{nif}

`POST` /representacion/enviar/{nif}

`PUT` /representacion/cancelar/{nif}

`GET` /representacion/descargar/{nif}

`GET` /representacion/estado/{nif}

`GET` /webhooks

`POST` /webhooks

`GET` /webhooks/{webhook_id}

`PUT` /webhooks/{webhook_id}

`DELETE` /webhooks/{webhook_id}

`POST` /webhooks/{webhook_id}/nifs/{nif}

`DELETE` /webhooks/{webhook_id}/nifs/{nif}