El proceso de tax free se encuentra resumido en el diagrama principal de esta página.

Los pasos identificados con (A) están realacionados con la compra y consideran todos los detalles de financieros del ticket además de la familia de artículos.

Los pasos identificados (B) contiene la recogida de información acerca del viajero y su identificación personal.

En (C) tenemos toda tecnología propia que nos permite conectarnos con la AEAT para enviar los datos del viajero y de su compra para solicitar la autorización de tax free y acreditarlo con el DER (Documento Electrónico de Reembolso).

Integración

Para facilitar la comprensión de la integració, se ha representado un diagrama de flujos de los pasos que se deben realizar para poder realizar la integración.

Resumiendo, existen dos formas de integrar en función de si tiene la pasarela de pagos. En caso de de haber integrado el DeviceHub, se recomienda utilizar la API_2 y tan solo tendrá que integrar las nuevas llamadas específicas.

Pasos con el API_2:

B1. Se realiza una compra y se quiere pagar con tarjeta.
B2. El POS integrado con el API de Sipay envía todo el detalle de la compra.
B3. DeviceHub envía a procesar la operación y se detecta el BIN (ACR - automatic card recognition) como elegible para tax free.
B4. Entrega y comunica su información de pasaporte y contacto.
B5. El POS envía la información del viajero y la referencia de la compra.
B6. DeviceHub integrado con el API de Woonivers envía los datos de viajero y ticket para crear el DER.
B7. Woonivers comnunica a la AEAT la información de viajero y de la compra.
B8. Se envía el DER al viajero.

Si quiere realizar una integración directa con Woonivers, se recomienda utilizar el API_1.

Pasos con el API_1:

A1. Entrega y comunica su información de pasaporte y contacto.
A2. El POS integrado con el API de Woonivers envía información necesaria para crear el DER.
A3. Woonivers comnunica a la AEAT la información de viajero y de la compra.
A4. Se envía el DER al viajero.

API Woonivers (API 1)

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

Viajero

Creación de viajero

POST /traveller

Petición

Obligatorios

Campo	Descripción	Formato	Ejemplo
`country`	País del comercio en formato ISO 3166-1 A-3.	ISO 3166-1 A-3	ESP
`locale`	Idioma de los mensajes intercambiados vía API	es_ES	es_ES
`email`	Direcció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_name`	Nombre 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_name`	Apellidos del viajero tal y como aparece en su documento de identificación.	1 a 50 caracteres alfanuméricos con espacio en blanco.	Doe
`phone`	Nú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_prefix`	Prefijo 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_date`	Fecha de nacimiento del viajero.	Formato ISO 8601 (YYYY-MM-DD)	1990-01-25
`document_type`	Tipo de documento del viajero.	PASSPORT_ID_TYPE o NATIONAL_ID_TYPE	PASSPORT_ID_TYPE
`document_id`	Número de documento del viajero.	Alfanuméricos sin espacios.	123456789
`document_country`	País del documento del viajero.	ISO 3166-1 A-3	ESP
`notes`	Información adicional del viajero.	Alfanuméricos con espacio en blanco hasta.
`residence_country`	País de residencia del viajero.	ISO 3166-1 A-3	ESP
`zip_code`	Código postal del viajero.	Alfanuméricos sin espacios.	28001
`city`	Ciudad del viajero.	Alfanuméricos con espacios en blanco.	Madrid
`address`	Dirección del viajero.	Alfanuméricos con espacios en blanco.	Calle de la Princesa, 1

Opcionales

Ninguno es opcional.

Respuestas

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

Respuesta

Campo	Descripción	Formato	Ejemplo
`id`	Número generado por Woonivers.	Numérico	12345
`request_id`	Identificador único de la llamada API. Se recomienda almacenar para agilizar los procesos de Soporte.	uuid4	4b0a6622-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 respuest 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 respuest 400

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

Ejemplo de respuest 401

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

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 respuesta	Descripción
200	Viajero encontrado correctamente
401	No autorizado.
404	No encontrado.

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.

Se enviarán los mismos de datos que en una creación de viajero.

Petición

DER

API DeviceHub (API 2)

nota

Recuerda que estas llamadas API serán peticiones HTTP POST a un la dirección TCP/IP donde está instalado el DeviceHub. Normalmente esta dirección será:

POST http://localhost:17000

Existen llamadas especiales que ofrecen su funcionalidad a través del contenido del propio mensaje XML. Son conocidas como CallSpecificFunction. Tienen los mismos elemementos comunes que todas las llamadas: ClientIdValue, ... pero además todas las de este tipo tienen los siguientes parámetros comunes:

Function
Modifier
Parameter 1
Parameter 2
Parameter 3

A continuación incluimos un ejemplo genérico a modo de prototipo:

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:tem="http://tempuri.org/">
   <soap:Header/>
   <soap:Body>
      <tem:CallSpecificFunctionRequest>
         <tem:Header>
            <tem:ClientId>ClientIdValue</tem:ClientId>
            <tem:StoreId>StoreIdValue</tem:StoreId>
            <tem:PosId>PosValue</tem:PosId>
            <tem:Lang>Idioma</tem:Lang>
            <tem:ExtraData1></tem:ExtraData1>
         </tem:Header>
         <tem:Function>FunctionCode</tem:Function>
         <tem:Modifier>FunctionModifier</tem:Modifier>
         <tem:Parameter1>Parameter1</tem:Parameter1>
         <tem:Parameter2>Parameter1</tem:Parameter2>
         <tem:Parameter3>Parameter3</tem:Parameter3>
      </tem:CallSpecificFunctionRequest>
   </soap:Body>
</soap:Envelope>

Viajero

En este caso, teniendo un importe y un número de ticket, se lanza la transacción de devolución, solicitando la autorización financiera. El código de respuesta refleja si la petición ha sido entregada al servicio device hub. Para obtener el resultado de la transacción, es necesario utilizar la función GetNextMessage.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:tem="http://tempuri.org/">
   <soap:Header/>
   <soap:Body>
      <tem:BeginDevolutionRequest>
         <tem:Header>
            <tem:ClientId>ClientIdValue</tem:ClientId>
            <tem:StoreId>StoreIdValue</tem:StoreId>
            <tem:PosId>PosIdValue</tem:PosId>
            <tem:Lang>Idioma</tem:Lang>
            <tem:ExtraData1></tem:ExtraData1>
         </tem:Header>
         <tem:Amount>Importe</tem:Amount>
         <tem:TicketNumber>TicketNumber</tem:TicketNumber>
      </tem:BeginDevolutionRequest>
   </soap:Body>
</soap:Envelope>

Petición: BeginDevolutionRequest

TIPO	NOMBRE	COMENTARIOS
Header	Header	Datos utilizados durante las siguientes consultas.
String	Amount	Importe de la devolución. Importe de la operación con 10 dígitos numéricos, dónde los dos últimos dígitos representan los céntimos.Ej.: 1€ -> 0000000100; 2,25€-> 0000000225
String	TicketNumber	Número de recibo de la devolución.

Header

TIPO	NOMBRE	COMENTARIOS
String	Clientid	Identificador del comercio.
String	Storeid	Identificador de la tienda.
String	Posid	Identificador del Terminal Punto de Venta.
String	Language	Identificador del idioma: 0 Español 1 English.
String	ExtraData1	No usado.

Nota: El campo Posid no debe superar los 30 caracteres y se recomienda no usar los siguientes símbolos dentro del campo {"/","\"}

Parámetros de Salida

Respuesta: BeginDevolutionResponse

TIPO	NOMBRE	COMENTARIOS
Result	Result	Retorna 0=OK o un código de error y su descripción.

Result

TIPO	NOMBRE	COMENTARIOS
Int	Code	Código de error.
String	Descripción	Descripción del error.

API Woonivers (API 1)​

Viajero​

Creación de viajero​

Obtener datos del viajero​

Actualizar información del viajero​

DER​

API DeviceHub (API 2)​

Viajero​

Petición: BeginDevolutionRequest​

Respuesta: BeginDevolutionResponse​

DER​

API Woonivers (API 1)

Viajero

Creación de viajero

Obtener datos del viajero

Actualizar información del viajero

DER

API DeviceHub (API 2)

Viajero

Petición: BeginDevolutionRequest

Respuesta: BeginDevolutionResponse

DER