Documentación de la API para gestionar NIFs

# Funcionamiento básico Aquí encontrarás la documentación técnica de nuestra API para la gestión general de tus NIFs en nuestro sistema.

NIFs

Se pueden crear NIFs en el entorno de test, que se comunican con el entorno de test de la administración.

`GET` /nifs

Listar NIFs

Este endpoint devuelve una lista de todos los NIFs.

Responses

Status	Description
`200`	Lista de NIFs
`400`	Parámetros de consulta inválidos
`401`	No autorizado — API key inválida o ausente.
`500`	Error interno del servidor.

`POST` /nifs

Añadir NIFs

Mediante este endpoint se añaden nuevos NIFs.

Responses

Status	Description
`200`	NIF
`400`	Datos de entrada inválidos
`401`	No autorizado — API key inválida o ausente.
`409`	NIF ya existe
`500`	Error interno del servidor.

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

Información de NIF

Este endpoint devuelve la información de un NIF concreto.

Responses

Status	Description
`200`	NIF
`401`	No autorizado — API key inválida o ausente.
`404`	NIF no encontrado
`500`	Error interno del servidor.

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

Modificar NIF

Este endpoint permite modificar la información de un NIF concreto.

Request body

Field	Type	Required	Description
`nombre`	string	no	Nombre y apellidos o razón social del NIF.
`direccion`	string	no	Dirección del NIF.
`cp`	string	no	Código postal del NIF.
`poblacion`	string	no	Población del NIF.
`provincia`	string	no	Provincia del NIF.
`webhooks`	array	no	Lista de identificadores de los webhooks a los que estará vinculado el NIF.
`label`	string	no	Etiqueta asociada al NIF.

Responses

Status	Description
`200`	NIF
`400`	Datos de entrada inválidos
`401`	No autorizado — API key inválida o ausente.
`404`	NIF no encontrado
`500`	Error interno del servidor.

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

Desactivar NIF

Este endpoint permite desactivar un NIF.

Responses

Status	Description
`200`	OK
`401`	No autorizado — API key inválida o ausente.
`403`	NIF ya está inactivo
`404`	NIF no encontrado
`500`	Error interno del servidor.

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

Eliminar NIF

Este endpoint permite eliminar permanentemente un NIF.

Responses

Status	Description
`200`	OK
`401`	No autorizado — API key inválida o ausente.
`404`	NIF no encontrado
`500`	Error interno del servidor.

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

Activar NIF

Este endpoint permite activar un NIF que ha sido desactivado previamente.

Responses

Status	Description
`200`	OK
`401`	No autorizado — API key inválida o ausente.
`403`	NIF ya está activo
`404`	NIF no encontrado
`500`	Error interno del servidor.

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

API key de NIF

Este endpoint devuelve la API key de un NIF concreto y en un entorno concreto.

Responses

Status	Description
`200`	API key
`401`	No autorizado — API key inválida o ausente.
`404`	NIF no encontrado
`500`	Error interno del servidor.

Validación

Existen muchas circunstancias en las que resulta útil validar que un NIF es correcto y está registrado en la administración, tanto para empresas (CIF) como ciudadanos nacionales (DNI) y residentes extranjeros (NIE).

`POST` /nifs/validar

Validar NIF en la AEAT

Este endpoint permite validar que un NIF de una persona física o jurídica está identificado en la agencia tributaria.

Request body

Field	Type	Required	Description
`nif`	string	yes	NIF de la persona física o jurídica sobre la que se quiere efectuar la consulta de verificación.
`nombre`	string	no	Apellidos y nombre de la persona física o razón social de la persona jurídica sobre la que se quiere efectuar la consulta de verificación.

Responses

Status	Description
`200`	Respuesta de la AEAT
`400`	Datos de entrada inválidos
`401`	No autorizado — API key inválida o ausente.
`500`	Error interno del servidor o servicio de la AEAT no disponible

`POST` /nifs/validar_lotes

Validar NIFs en lote

Este endpoint permite validar hasta 20000 NIFs en una única llamada, comprobando si cada NIF de una persona física o jurídica existe.

Responses

Status	Description
`200`	Respuesta de la AEAT
`400`	Datos de entrada inválidos
`401`	No autorizado — API key inválida o ausente.
`500`	Error interno del servidor o servicio de la AEAT no disponible

`POST` /nifs/validar/vies

Validar IVA en VIES

Este endpoint permite validar que un número de IVA intracomunitario se encuentra en el censo VIES.

Request body

Field	Type	Required	Description
`codigo_pais`	string	yes	Código de país al que pertenece el IVA.
`iva`	string	yes	Número de IVA intracomunitario.

Responses

Status	Description
`200`	Respuesta del censo VIES
`400`	Datos de entrada inválidos
`401`	No autorizado — API key inválida o ausente.
`500`	Error interno del servidor.

Modelo de representación

Para generar y enviar facturas al entorno de producción de la AEAT usando la nuestra API, es necesario rellenar un modelo de otorgamiento de representación y el NIF emisor de las facturas debe firmalo digitalmente.

`POST` /representacion/generar/{nif}

Generar PDF de representación

Este endpoint permite descargar el documento PDF de otorgamiento de representación para un NIF de Verifactu.

Request body

Field	Type	Required	Description
`tipo_entidad`	object	no	Tipo de entidad, personas físicas o jurídicas.
`nombre`	string	no	Obligatorio para personas físicas.
`municipio`	string	no	Obligatorio para personas físicas.
`calle`	string	no	Obligatorio para personas físicas.
`numero`	string	no	Obligatorio para personas físicas.
`nombre_entidad`	string	no	Obligatorio para personas jurídicas.
`municipio_entidad`	string	no	Obligatorio para personas jurídicas.
`calle_entidad`	string	no	Obligatorio para personas jurídicas.
`numero_entidad`	string	no	Obligatorio para personas jurídicas.
`nombre_representante`	string	no	Obligatorio para personas jurídicas.
`nif_representante`	string	no	Obligatorio para personas jurídicas.
`municipio_representante`	string	no	Obligatorio para personas jurídicas.
`calle_representante`	string	no	Obligatorio para personas jurídicas.
`numero_representante`	string	no	Obligatorio para personas jurídicas.

Responses

Status	Description
`200`	Documento PDF de otorgamiento de representación
`400`	Datos de entrada inválidos
`401`	No autorizado — API key inválida o ausente.
`500`	Error interno del servidor.

`POST` /representacion/enviar/{nif}

Enviar PDF firmado

Mediante este endpoint se envía el documento PDF de otorgamiento de representación para un NIF de Verifactu.

Responses

Status	Description
`200`	PDF enviado correctamente
`400`	PDF no enviado correctamente
`401`	No autorizado — API key inválida o ausente.
`500`	Error interno del servidor o fallo al procesar el PDF

`PUT` /representacion/cancelar/{nif}

Cancelar PDF firmado

Mediante este endpoint se cancela el documento PDF de otorgamiento de representación para un NIF de Verifactu.

Responses

Status	Description
`200`	PDF cancelado correctamente
`401`	No autorizado — API key inválida o ausente.
`404`	Modelo de representación no encontrado
`500`	Error interno del servidor al procesar la cancelación

`GET` /representacion/descargar/{nif}

Descargar PDF firmado

Mediante este endpoint se puede descargar el documento PDF de otorgamiento de representación para un NIF de Verifactu firmado.

Responses

Status	Description
`200`	PDF descargado correctamente
`401`	No autorizado — API key inválida o ausente.
`404`	PDF no encontrado para el NIF indicado
`500`	Error interno del servidor.

`GET` /representacion/estado/{nif}

Estado de representación

Mediante este endpoint se puede obtener el estado de la representación para un NIF.

Responses

Status	Description
`200`	PDF enviado correctamente
`401`	No autorizado — API key inválida o ausente.
`500`	Error interno del servidor.

Webhooks

Nuestra plataforma permite el uso de webhooks para recibir notificaciones automáticas cuando se genera un registro de facturación.

`GET` /webhooks

Listar webhooks

Este endpoint devuelve una lista de todos los webhooks configurados.

Responses

Status	Description
`200`	Lista de webhooks
`400`	Parámetros de consulta inválidos
`401`	No autorizado — API key inválida o ausente.
`500`	Error interno del servidor.

`POST` /webhooks

Añadir webhook

Mediante este endpoint se puede registrar un webhook.

Request body

Field	Type	Required	Description
`url`	string	yes	URL a la que se hará la llamada cuando se dispare el webhook.
`entorno`	string	yes	Entorno del webhook. Puede ser "test" o "prod".
`secret`	object	no	Parámetro opcional. Una clave secreta que se comparte entre nuestra API y el receptor del webhook.
`nifs`	object	no	Lista de NIFs. Cuando se envíen registros de facturación para cualquiera de estos NIFs, se disparará el webhook con el resultado de hacienda una vez obtenido.

Responses

Status	Description
`200`	Webhook
`400`	Datos de entrada inválidos
`401`	No autorizado — API key inválida o ausente.
`409`	Webhook ya existe con esa URL
`500`	Error interno del servidor.

`GET` /webhooks/{webhook_id}

Información de webhook

Este endpoint devuelve la información de un webhook concreto.

Responses

Status	Description
`200`	Webhook
`401`	No autorizado — API key inválida o ausente.
`404`	Webhook no encontrado
`500`	Error interno del servidor.

`PUT` /webhooks/{webhook_id}

Modificar webhook

Este endpoint permite modificar un webhook concreto.

Request body

Field	Type	Required	Description
`url`	string	no	URL a la que se hará la llamada cuando se dispare el webhook.
`secret`	string	no	Clave para generar la firma HMAC.
`activo`	boolean	no	Indica si el webhook estará activo o no.
`nifs`	array	no	Lista de NIFs. Cuando se envíen registros de facturación para cualquiera de estos NIFs, se disparará el webhook con el resultado de hacienda una vez obtenido.

Responses

Status	Description
`200`	Webhook
`400`	Datos de entrada inválidos
`401`	No autorizado — API key inválida o ausente.
`404`	Webhook no encontrado
`409`	URL de webhook en conflicto con otro existente
`500`	Error interno del servidor.

`DELETE` /webhooks/{webhook_id}

Eliminar webhook

Este endpoint permite eliminar un webhook concreto.

Responses

Status	Description
`200`	OK
`401`	No autorizado — API key inválida o ausente.
`404`	Webhook no encontrado
`500`	Error interno del servidor.

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

Asociar NIF a webhook

Este endpoint permite asociar un NIF concreto a un webhook concreto.

Responses

Status	Description
`200`	OK
`401`	No autorizado — API key inválida o ausente.
`404`	Webhook o NIF no encontrado
`500`	Error interno del servidor.

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

Desasociar NIF a webhook

Este endpoint permite desasociar un NIF concreto a un webhook concreto.

Responses

Status	Description
`200`	OK
`204`	NIF desasociado del webhook correctamente (sin contenido)
`401`	No autorizado — API key inválida o ausente.
`404`	Webhook o NIF no encontrado
`500`	Error interno del servidor.

Documentación de la API para gestionar NIFs

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

Validación

POST /nifs/validar

Request body

Responses

POST /nifs/validar_lotes

Responses

POST /nifs/validar/vies

Request body

Responses

Modelo de representación

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