Skip to main content

API Woonivers

Este API tiene implementada la autenticación con cabecera HTTP X-API-Key. Solicite este dato a su contacto técnico de Woonivers.

La integración se realizará en el entorno de sandbox con la base de host https://sandbox.woonivers.com/api/v1/.

Una vez realizadas las pruebas necesarias se podrá cambiar a producción mediante el host https://api.woonivers.com/api/v1/.

Considere los valores de estos parámetros como opciones de configuración de su entorno para facilitar su cambio cuando suba de entorno.

  • X-API-Key
  • Base host del entorno

📋Casos de uso​

Venta (Solicitar emisión DER)​

Un viajero compra en una tienda y solicita el Tax Free sobre esa compra.
Se solicita la emisión del DER para registrar la compra.

Obligatorios

Estas llamadas son obligatorias a la hora de realizar una venta.

PeticiónDescripción
GET /travellerPara comprobar que existe el viajero.
POST /derPara solicitar la emisión del documento electrónico de reembolso.

Opcionales

Estas llamadas son opcionales a la hora de realizar una venta.

PeticiónDescripción
POST /travellerPara crear el viajero si no existe.
PUT /travellerPara actualizar la información del viajero.

Devolución total (Solicitar cancelación DER)​

Un viajero que ha comprado en una tienda quiere hacer una devolución de todos los artículos.
Se solicita la cancelación del DER.

Obligatorios

Estas llamadas son obligatorias a la hora de realizar una devolución total.

PeticiónDescripción
GET /derPara solicitar la búsqueda del documento electrónico de reembolso.
DELETE /derPara solicitar la cancelación del documento electrónico de reembolso.

Devolución parcial (Solicitar cancelación DER y Solicitar emisión DER)​

Un viajero que ha comprado en una tienda quiere hacer una devolución de algunos artículos.
Se solicita la cancelación del DER y se solicita la emisión de un DER nuevo.

Obligatorios

Estas llamadas son obligatorias a la hora de realizar una devolución parcial.

PeticiónDescripción
GET /derPara solicitar la búsqueda del documento electrónico de reembolso.
DELETE /derPara solicitar la cancelación del documento electrónico de reembolso.
POST /derPara solicitar la emisión del documento electrónico de reembolso.

🧳Viajero​

[POST /traveller] Creación de viajero​

POST /traveller

Petición

Obligatorios

CampoDescripciónFormatoEjemplo
countryPaís del comercio en formato ISO 3166-1 A-3.ISO 3166-1 A-3ESP
localeIdioma de los mensajes intercambiados vía APIes_ESes_ES
emailDirección de correo electrónico de contacto del viajero para el envío de información exclusivamente del proceso de tax free.Cualquier email válido.john@doe.com
first_nameNombre de pila del viajero tal y como aparece en su documento de identificación.1 a 50 caracteres alfanuméricos con espacio en blanco.John
last_nameApellidos del viajero tal y como aparece en su documento de identificación.1 a 50 caracteres alfanuméricos con espacio en blanco.Doe
phoneNúmero de teléfono del viajero con el fin de contactar con el para gestiones relacionadas con el tax free.5-20 dígitos
phone_prefixPrefijo del número de teléfono del viajero con el fin de contactar con el para gestiones relacionadas con el tax free.1 a 3 caracteres alfanuméricos con espacio en blanco.34
birth_dateFecha de nacimiento del viajero.Formato ISO 8601 (YYYY-MM-DD)1990-01-25
document_typeTipo de documento del viajero.PASSPORT_ID_TYPE o NATIONAL_ID_TYPEPASSPORT_ID_TYPE
document_idNúmero de documento del viajero.Alfanuméricos sin espacios.123456789
document_countryPaís del documento del viajero.ISO 3166-1 A-3ESP
notesInformación adicional del viajero.Alfanuméricos con espacio en blanco hasta.
residence_countryPaís de residencia del viajero.ISO 3166-1 A-3ESP
zip_codeCódigo postal del viajero.Alfanuméricos sin espacios.28001
cityCiudad del viajero.Alfanuméricos con espacios en blanco.Madrid
addressDirección del viajero.Alfanuméricos con espacios en blanco.Calle de la Princesa, 1

Opcionales

Ninguno es opcional.

Respuestas

Código de respuestaDescripción
201Viajero creado correctamente
400Petición no válida. Se devolverá el error explícito
401No autorizado.

Respuesta

CampoDescripciónFormatoEjemplo
idNúmero generado por Woonivers.Numérico12345
request_idIdentificador único de la llamada API. Se recomienda almacenar para agilizar los procesos de Soporte.uuid44b0a6622-37dd-4e6a-aba3-804ce8f9818f
Adicionalmente llegarán todos los campos de la creación del viajero

Ejemplo de petición

{
  "country": "ESP",
  "locale": "en",
  "email": "john@doe.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "123456789",
  "phone_prefix": "34",
  "birth_date": "1990-01-25",
  "document_type": "PASSPORT_ID_TYPE",
  "document_id": "123456789",
  "document_country": "ESP",
  "notes": "string",
  "residence_country": "ESP",
  "zip_code": "28001",
  "city": "Madrid",
  "address": "Calle de la Princesa, 1"
}

Ejemplo de respuesta 201

{
  "country": "ESP",
  "locale": "en",
  "email": "john@doe.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "123456789",
  "phone_prefix": "34",
  "birth_date": "1990-01-25",
  "document_type": "PASSPORT_ID_TYPE",
  "document_id": "123456789",
  "document_country": "ESP",
  "notes": "string",
  "residence_country": "ESP",
  "zip_code": "28001",
  "city": "Madrid",
  "address": "Calle de la Princesa, 1",
  "request_id": "string",
  "id": 12345
}

Ejemplo de respuesta 400

{
  "error": {
    "code": "400",
    "message": ["User '{{email}}' already exists."]
  }
}

Ejemplo de respuesta 401

{
  "request_id": "string",
  "error": {
    "code": "401",
    "message": "Unauthorized access, please provide valid credentials"
  }
}

[GET /traveller] Obtener datos del viajero​

GET /traveller?traveller_id={{traveller_id}}

GET /traveller?document_id={{document_id}}

Para obtener los datos del viajero, necesitaremos conocer uno de estos datos:

  • traveller_id: identificador único del viajero interno en Woonivers.
  • document_id: identificador único del documento de identificación del viajero.

Petición

Respuestas

Código de respuestaDescripción
200Viajero encontrado correctamente
401No autorizado.
404No encontrado.

Ejemplo de respuest 200

{
  "country": "ESP",
  "locale": "en",
  "email": "john@doe.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "123456789",
  "phone_prefix": "34",
  "birth_date": "1990-01-25",
  "document_type": "PASSPORT_ID_TYPE",
  "document_id": "123456789",
  "document_country": "ESP",
  "notes": "string",
  "residence_country": "ESP",
  "zip_code": "28001",
  "city": "Madrid",
  "address": "Calle de la Princesa, 1"
}

Ejemplo de respuesta 401

{
  "request_id": "string",
  "error": {
    "code": "401",
    "message": "Unauthorized access, please provide valid credentials"
  }
}

Ejemplo de respuest 404

{
  "request_id": "string",
  "error": {
    "code": "404",
    "message": "Traveller not found"
  }
}

[PUT /traveller] Actualizar información del viajero​

PUT /traveller/<traveller_id>

Para actualizar la información del viajero, necesitaremos conocer uno de estos datos:

  • traveller_id: identificador único del viajero interno en Woonivers.
info

Petición y respuesta

Se enviarán los mismos de datos que en una creación de viajero. Los tipos de respuestas serán los mismos que en la creación de viajero.

🧾DER​

[POST /der] Solicitar emisión DER​

POST /der

Petición

CampoDescripciónFormatoEjemplo
countryPaís del comercio en formato ISO 3166-1 A-3.ISO 3166-1 A-3ESP
localeIdioma de los mensajes intercambiados vía APIes_ESes_ES
orderIdentificador de la factura simplificada. Número de ticket.Alfanuméricos sin espacios.TICKET00001
order_datetimeFecha y hora de la compra.Formato ISO 8601 (YYYY-MM-DDTHH:MM:SS)2025-01-01T00:00:00
currencyMoneda utilizada para el pago.ISO 4217 acrónimoeur
traveller_idIdentificador intenro de Woonivers del viajero. Tendrá que hacer la consulta de obtener viajero antes de esta llamada API.uuid44b0a6622-37dd-4e6a-aba3-804ce8f9818f
products Colección (array) de productos que estarán sujetos al taxfree.[]Ver siguiente bloque de documentación.

Colección (array) de productos que estarán sujetos al taxfree:

CampoDescripciónFormatoEjemplo
amountCantidad de productoNúmero entero1
descriptionDescripción del productoAlfanuméricos con espacio en blancoProducto 1
classificationClasificación del producto, abreviatura oficialEnumALI - Alimentación. # ALT - Alcohol y tabaco. # CUL - Bienes culturales y artesanía. # DEP - Deportes y ocio. # EDM - Electrodomésticos. # HOG - Hogar y decoración. # ELI - Informática y electrónica. # MOD - Moda y accesorios. # PER - Perfumería, cosmética y farmacia. # JOY - Joyería y relojería. # DTO - Descuentos # MAS - Mascotas
tax_rateTasa de impuesto aplicado al productoNúmero decimal7.5
tax_baseBase imponible del productoNúmero entero4000
tax_amountCantidad de impuesto aplicado al productoNúmero entero400
total_taxTotal de impuestos aplicados al productoNúmero entero4400
serial_numberNúmero de serie del producto. Solo es OBLIGATORIO en joyería y electrónica.Alfanuméricos sin espaciosSerial number

Códigos HTTP de respuesta

Código de respuestaDescripción
201DER emitido correctamente
400Petición no válida. Se devolverá el error explícito
401No autorizado.

Ejemplo de respuesta 201

{
  "request_id": "string",
  "metadata": {
    "key_sample1": "value_sample1",
    "key_sample2": "value_sample2"
  },
  "order": "order_id",
  "retailer_id": "B12345678",
  "retailer_name": "Woonivers S.L.",
  "shop_name": "Woonivers Store S.L.",
  "products": [
    {
      "amount": 1,
      "description": "Producto 1",
      "classification": "ALI",
      "tax_rate": 7.5,
      "tax_base": 4000,
      "tax_amount": 400,
      "total_tax": 4400,
      "serial_number": "Serial number",
      "metadata": {
        "key_sample1": "value_sample1",
        "key_sample2": "value_sample2"
      }
    }
  ],
  "name": "aeat",
  "created_at": "2020-01-01T00:00:00Z",
  "aeat_id": "24ES10521265",
  "aeat_ilr": "GETREF0000000000000010720",
  "aeat_csv_der": "NRGQ38U583D7RGUK"
}

Como añadido a los campos que se enviaron en la emisión, la respuesta incluye los siguientes campos:

CampoDescripción
request_idIdentificador único de la llamada API
nameNombre del regulador que genera el DER
created_atFecha de emisión del DER en formato ISO 8601
aeat_idIdentificador de la AEAT
aeat_ilrIdentificador local de referencia
aeat_csv_derCSV declaración electrónica

Ejemplo de respuesta 400

{
  "error": {
    "code": "400",
    "message": {
      "invoice_date": [
        "Traveller ID does not exist."
      ]
    }
  }
}

Ejemplo de respuesta 401

{
  "request_id": "string",
  "error": {
    "code": "401",
    "message": "Unauthorized access, please provide valid credentials"
  }
}

[GET /der] Solicitar búsqueda DER​

GET /der/<order_id>

Se utilizará el parámetro order_id para buscar el orden de compra.

Respuestas

Código de respuestaDescripción
201Viajero creado correctamente
401No autorizado
404No encontrado.

Ejemplo de respuesta 201

El mismo resultado que en la emisión de DER más el traveller_id.

Ejemplo de respuesta 401

{
  "request_id": "string",
  "error": {
    "code": "401",
    "message": "Unauthorized access, please provide valid credentials"
  }
}

Ejemplo de respuesta 404

{
  "request_id": "string",
  "error": {
    "code": "404",
    "message": "DER not found"
  }
}

[DELETE /der] Solicitar cancelación DER​

DELETE /der/delete/<order_id>

Anulación de un DER en el caso que aún no se haya visado. Se utilizará el parámetro order_id para buscar el DER y anularlo.

Respuestas

Código de respuestaDescripción
200DER anulado correctamente
401No autorizado.
404DER no encontrado.

Ejemplo de respuesta 200

{
  "request_id": "request_id",
  "metadata": {
    "key_sample1": "value_sample1",
    "key_sample2": "value_sample2"
  }
}

Ejemplo de respuesta 401

{
  "request_id": "string",
  "error": {
    "code": "401",
    "message": "Unauthorized access, please provide valid credentials"
  }
}

Ejemplo de respuesta 404

{
  "request_id": "string",
  "error": {
    "code": "404",
    "message": "DER not found"
  }
}