Saltar al contenido principal

Autenticación por token

Este método de autenticación delega la validación de credenciales de usuario al servidor de autorización de Wolters Kluwer. Tu aplicación deberá redireccionar a la página web de Wolters Kluwer que validará el inicio de sesión del usuario, y responderá a tu servidor con el token de acceso.

Registro de la aplicación​

Para poder activar este tipo de autenticación, necesitamos registrar tu aplicación. Por favor, ponte en contacto con nosotros a través del formulario de soporte escogiendo la opción de Quiero registrar mi aplicación para a3factura. Deberás tener habilitada la url de retorno donde tu servidor estará escuchando la petición de autenticación.

Autorización​

Una vez ya tengamos tu aplicación registrada, deberás obtener un token de acceso por cada una de las empresas a las que tenga acceso el usuario. El primer paso es que tu aplicación redirija al usuario a la siguiente url:

https://a3api.wolterskluwer.es/invoicing-login/authorize?name={name}&product={product}&scope=subscription&state={state}&subscription-key={subscription-key}

Los parámetros (en query, sin headers) de la url son:

  • name: Nombre de tu aplicación que te hemos asignado en el paso anterior (case-sensitive).
  • product: puede tomar por valor a3factura o a3innuva dependiendo de a qué aplicación quieras acceder.
  • scope: valor fijo subscription
  • state: es un texto que debe usarse para evitar ataques de falsificación. Informa un valor único para cada llamada (por ejemplo, un GUID) que se devolverá como parámetro en la llamada a tu redirect_uri. Deberás validar que el valor recibido coincide con el que has enviado.
  • subscription-key: es tu clave de suscripción de Conectia.

El servidor de autenticación de WK presentará al usuario la pantalla de login para que introduzca los credenciales que utiliza en a3factura o a3innuva. Una vez validados, se le mostrará la relación de empresas a las que tiene acceso:

LoginWKAIDCA

Cuando el usuario seleccione una de las empresas, se enviará la petición a la url de tu servidor añadiendo en la query el campo Code, que deberás utilizar en el siguiente paso para registrar el token.

Registrar el token​

Una vez ya disponemos del code, necesitaremos obtener un token de registro para la aplicación. Deberás realizar una petición GET al endpoint https://a3api.wolterskluwer.es/invoicing-login/api/tokens/registerToken con los siguientes parámetros en la url:

  • name: Nombre de tu aplicación (case-sensitive)
  • code: valor del code obtenido en el paso anterior.
  • subscription-key: es tu clave de suscripción del developer portal.
GET /invoicing-login/api/tokens/registerToken?name=AppTest&code=fbb1626a-06a7-11ee-aaa2-c4f20151753c&subscription-key=2kxwf5rb7ffb65dd5 HTTP/1.1
Host: a3api.wolterskluwer.es

Respuesta si HTTP.200 OK:

{
    "hasErrors": false,
    "content": "Bearer eyJhbGciOiJIUzUxMVCJ9.eyJzdWIiOiJqbG9wZXpAd2...zw05gwwUlH3-i9uw",
    "errors": []
}

Si el code facilitado no es correcto la respuesta será un HTTP.401 Unauthorized. Si la aplicación informada es incorrecta devolverá un HTTP.404

Registrar la aplicación​

Con el Bearer token obtenido en el paso anterior, deberemos registrarlo para usarlo con tu aplicación. Deberás hacer una llamada POST al endpoint https://a3api.wolterskluwer.es/a3factura/api/modules/{applicationName} con los siguientes parámetros:

Parámetros en la url

  • applicationName: Nombre de tu aplicación (case-sensitive)

Parámetros por querystring

  • subscription-key: es tu clave de suscripción del developer portal.

Parámetros en los headers

  • Authorization: token obtenido en el paso anterior. Debe tener el formato "Bearer eyJhbGciOiJIUzUxMVCJ9.e..."
  • api-version: valor fijo 2.0

Parámetros en el body

  • price (opcional): Precio de la contratación (aplicación + usuarios).
POST /a3factura/api/modules/AppTest?subscription-key=2kxwf5rb7ffb65dd5 HTTP/1.1
Host: a3api.wolterskluwer.es
Content-Type: application/json
Authorization: Bearer eyJhbGci...lIj
api-version: 2.0
{"ok":true,"result":"MQA4ADAAYgAAGYAZQBkAD...gBkAGUAYwA2ADcANQBhAA==","messages":[]}
Atención

Es muy importante que guardes el valor del campo result ya que es la clave para poder generar a partir de ahora tokens de acceso para la empresa y usuario seleccionados.

Obtener token de aplicación​

Los pasos anteriores los deberás realizar una vez por cada usuario y empresa que se hayan autenticado. A partir de ahora y ya con los credenciales, podrás ir solicitando tokens de acceso a la aplicación con una petición POST al endpoint https://a3api.wolterskluwer.es/a3factura/api/token/applicationToken

Parámetros por querystring

  • subscription-key: es tu clave de suscripción del developer portal.

Parámetros en los headers

  • api-version: valor fijo 2.0

Parámetros en el body

  • applicationName: Nombre de tu aplicación (case-sensitive)
  • credentials: Credenciales (campo result) obtenidas en el registro de la aplicación.
POST /a3factura/api/token/applicationToken?subscription-key=2kxwf5rb7ffb65dd5 HTTP/1.1
Host: a3api.wolterskluwer.es
Content-Type: application/json
Api-Version: 2.0
Content-Length: 95

{"applicationName": "AppTest", "credentials":"MQA4ADAAYgAAGYAZQBkAD...gBkAGUAYwA2ADcANQBhAA=="}
"Bearer eyJhbGciOiJI...tmKbvQ"

Con el token de aplicación obtenido, ya podrás realizar cualquier petición a la API de a3factura. Por ejemplo, para obtener los clientes:

GET /a3factura/api/customers HTTP/1.1
Host: a3api.wolterskluwer.es
Ocp-Apim-Subscription-Key: 2kxwf5rb7ffb65dd5
Authorization: Bearer eyJhbGciOiJI...tmKbvQ
Api-Version: 2.0
Content-Type: application/json
[
    {
        "id": "02e1c97d-62ba-4448-b7f6-e9deeb2f1a65",
        "creationDate": "2010-01-01T00:00:00+00:00",
        "vatNumber": "34567891H",
        "vatNumberType": 2,
        "code": "       1",
        "name": "SPORTS ABC",
        "businessName": "SPORTS ABC",
        "web": "www.abcsports.es",
        "street": "CL. Muntaner, 12",
        "zipCode": "28001",
        "town": "MADRID",
        "province": "MADRID",
        "phone": "93.345.67.89",
        "mail": "comercial@abcsports.es",
        "businessStreet": "C. Joan Ambròs i Lloreda, 12, 3-2",
        "businessZipCode": "08100",
        "businessTown": "MOLLET DEL VALLES",
        "businessProvince": "BARCELONA",
        "businessPhone": "935709387",
        "businessMail": "epiglez@gmail.com",
        "accountCode": "43000001",
        "enabled": true
    },
    {
        "id": "3814907d-7ec1-4582-9ab7-9f3c068381e8",
        "creationDate": "2010-01-01T00:00:00+00:00",
        "vatNumber": "43496809Z",
        "vatNumberType": 2,
        "code": "       3",
        "name": "DEPORTES REUNIDOS, S.L.",
        "businessName": "DEPORTES REUNIDOS, S.L.",
        "web": "www.reunidos.es",
        "street": "CL. Rodriguez San Pedro, 2",
        "zipCode": "28001",
        "town": "MADRID",
        "province": "MADRID",
        "phone": "91.234.11.33",
        "mail": "comercial@reunidos.es",
        "businessStreet": "CL. Rodriguez San Pedro, 2",
        "businessZipCode": "28001",
        "businessTown": "MADRID",
        "businessProvince": "MADRID",
        "businessPhone": "91.234.11.33",
        "businessMail": "comercial@reunidos.es",
        "accountCode": "43000003",
        "enabled": true
    }

Validar un token de a3factura​

Si necesitas saber si un token es válido, puedes hacer una petición GET al endpoint https://a3api.wolterskluwer.es/a3factura/api/token/validateToken con los parámetros:

Parámetros por querystring

  • Authorization: token que quieres validar
  • subscription-key: es tu clave de suscripción del developer portal.

Parámetros en los headers

  • api-version: valor fijo 2.0
  • Authorization: token que quieres validar
GET /a3factura/api/token/validateToken?authorization=Bearer eyJhbGciOiJI...tmKbvQQ&subscription-key=2kxwf5rb7ffb65dd5 HTTP/1.1
Host: a3api.wolterskluwer.es
Authorization: Bearer eyJhbGciOiJI...tmKbvQ
api-version: 2.0

Devolverá:

  • HTTP.200 OK si el token es correcto
  • HTTP.401 Unauthorized si el token no es correcto
  • HTTP.498 Invalid token el token no tiene el formato de un token de a3factura

Obtener información de la aplicación registrada​

Si necesitas consultar la configuración de tu aplicación, puedes realizar una petición GET al endpoint https://a3api.wolterskluwer.es/a3factura/api/modules/{applicationName} con los parámetros:

Parámetros en la url

  • applicationName: Nombre de tu aplicación (case-sensitive)

Parámetros por querystring

  • subscription-key: es tu clave de suscripción del developer portal.

Parámetros en los headers

  • api-version: valor fijo 2.0
  • Authorization: token de aplicación
GET /a3factura/api/modules/AppTest?subscription-key=2kxwf5rb7ffb65dd5 HTTP/1.1
Host: a3api.wolterskluwer.es
Api-Version: 2.0
Authorization: Bearer eyJhbGciOiJI...tmKbvQ
{
    "application": {
        "id": "cfeb073e-06a8-11ee-be47-933d89eceaf8",
        "name": "AppTest"
    },
    "idcda": "12345",
    "companyName": "PRODUCTOS Y CONEXIONES ELÉCTRICAS, S.L.",
    "createdOn": "2023-06-08T14:33:30.400Z",
    "frontOfficeURL": null,
    "backOfficeURL": null,
    "price": 0.0000,
    "state": 3,
    "changeStateInfo": "Aplicación registrada",
    "credentials": "MQA4ADAAYgAAGYAZQBkAD...gBkAGUAYwA2ADcANQBhAA=="
}

Modificar información de la aplicación registrada​

Si necesitas modificar algún parámetro de la aplicación registrada puedes hacer una petición PUT al endpoint https://a3api.wolterskluwer.es/a3factura/api/modules/{applicationName} con los parámetros:

Parámetros en la url

  • applicationName: Nombre de tu aplicación (case-sensitive)

Parámetros por querystring

  • subscription-key: es tu clave de suscripción del developer portal.

Parámetros en los headers

  • api-version: valor fijo 2.0
  • Authorization: token de aplicación

Parámetros en el body

  • frontOfficeUrl: Url del frontoffice de la aplicación. Debe tener un formato válido y ser https.
    • Debe cumplir un formato de url correcto.
    • Debe ser https.
    • Será un campo obligatorio cuando el estado de la aplicación sea Active.
  • backOfficeURL: Url de backoffice de la aplicación. Debe tener un formato válido y ser https.
    • Debe cumplir un formato de url correcto
    • Debe ser https
  • price: Precio de la aplicación.
  • state: Estado en el que se encuentra la aplicación. Posibles valores:
    • 3 Configuring. Este estado será en el que se encuentre la aplicación después de hacer el POST y no será un valor al que se pueda volver.
    • 4 Active. En este estado, la aplicación será accesible por el usuario.
    • 5 Rejected. En este estado, la aplicación dejará de estar vinculada con a3factura y se eliminarán todas las relaciones y diccionarios creados.
    • 6 Baja en trámite
  • changeStateInfo: Campo de texto libre para informar de cualquier cambio de la aplicación.

Respuestas

  • 204 No content. Actualización correcta.
  • 422 No procesable. Ha habido algún error en la actualización.
  • 401 Unauthorized. El token no es correcto.
  • 404 NOT FOUND. La aplicación no existe.

Ejemplo:

curl --location --request PUT 'https://a3api.wolterskluwer.es/a3factura/api/modules/AppTest?subscription-key=2kxwf5rb7ffb65dd5' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 2.0' \
--header 'Authorization: BBearer eyJhbGciOiJI...tmKbvQ' \
--data '{
    "frontOfficeURL": "https://midominio.com/",
    "backOfficeURL": "https://midominio.com/back",
    "price": 1.0000,
    "state": 4,
    "changeStateInfo": "Aplicación registrada"    
}'
Última actualización en