API para socios

Autenticación OAuth 2.0

📘

OAuth 2.0 solo está disponible en el endpoint /ads

Al integrar los informes de pedidos a través de API, deberá integrar el endpoint /orders con autenticación básica y su clave API secreta.

ID de cliente y secreto de cliente

La client_id y la client_secret serán proporcionados por el administrador técnico de su cuenta. El secreto del cliente es privado y no debe compartirse.

Solicitud de tokens de acceso

Para obtener un token de acceso, debe enviar una solicitud que contenga los datos de client_id y client_secret. Para ello, el minorista debe realizar una solicitud POST al endpoint del servidor de autorización de CitrusAd:

https://$BASE_URL/v1/oauth2/token

📘

/oauth2/token solo proporciona el token relevante. Utilizará estos tokens para interactuar con los distintos endpoints de integración.

Su solicitud requerirá una autorización básica enviada a través del encabezado de solicitud de autorización que contenga los datos client_id y client_secret codificados en base64 del minorista:

Authorization: "Basic" + base64encode(client_id + ":" + client_secret)

Deberá añadir el siguiente parámetro utilizando el formato application/x-www-form-urlencoded en el cuerpo de la solicitud HTTP:

grant_type=client_credentials

La solicitud tendrá el siguiente aspecto:

POST https://$BASE_URL/v1/oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64 encoded id+key>
grant_type=client_credentials

Recepción del token de acceso

La respuesta contendrá la siguiente información:

  • access_token: el token de acceso que se utilizará para llamar a las API de CitrusAd
  • expires_in: la cantidad, en segundos, hasta que caduque el token de acceso.
  • token_type: el tipo de token devuelto. Siempre será portador en este caso.

A continuación se muestra una respuesta de muestra.

{
  "access_token": "xxxxx.yyyyy.zzzzz",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Uso del token

Para realizar llamadas contra los endpoints de la API de CitrusAd, simplemente añada el token de acceso generado en el encabezado de Autorización de la solicitud.
Authorization: “Bearer “ <access_token>

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Bearer <access_token>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
         ["category:Cupboard/Snacks"]
    ],
    "options": {
                             "filterMode": "AndOr"
                             },
    "maxNumberOfAds": 3
}

Errores de solicitud

Cliente no válido

Si la client_id o el client_secret enviados en la solicitud son incorrectos, recibirá una respuesta como esta:

{
  "error": "invalid_client"
}

Asegúrese de estar utilizando las credenciales correctas. Compruebe de nuevo sus client_id y client_secret y asegúrese de que está utilizando la autorización básica correctamente al llamar al punto final /token.
##Solicitud no válida
Se devolverá un error de solicitud no válida desde el servidor de autorización si a la solicitud le falta un parámetro requerido, incluye un valor de parámetro no válido, incluye un parámetro más de una vez o tiene formato incorrecto.

{
  "error": "invalid_request"
}

Asegúrese de:

  • Incluir solo grant_type=client_credentials en el cuerpo de la solicitud
  • Establecer el Content-Type correcto al encabezado de la solicitud