Sincronización de datos de pedidos a través del backend (recomendado)
Para enviar datos de pedidos a CitrusAd, utilice un comando similar al siguiente. Tenga en cuenta que los datos del campo orders que se muestra a continuación son ficticios y se indican únicamente a modo de ejemplo. Todos estos ejemplos muestran la integración estándar.
¿Desea integrar un ID de vendedor del mercado?
Asegúrese de leer la sección sobre el sellerId del mercado más adelante.
Pedidos de un solo artículo
A continuación se muestra el contexto para un cliente que ha comprado un solo artículo:
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"orders": [
{
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"orderDate": "2021-12-02T15:00:00Z",
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"gtin": "9891998566P",
"quantity": 3,
"regularUnitPrice": "1.00",
"totalOrderItemPriceAfterDiscounts": "3.00"
}
]
}
]
}
Si se realiza correctamente, se devolverá el siguiente objeto:
HTTP/2 200
{
"orders": [
{
"adIds": null,
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"regularUnitPrice": 1.00,
"citrusDiscountAmount": null,
"gtin": "9891998566P",
"adId": "",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 3.00
}
],
"orderDate": "2021-12-02T15:00:00Z",
}
]
}
Formato de orderDate
En el formato anterior, orderDate se lee como hora UTC. Deberá sincronizar en UTC.
También puede establecer un desplazamiento para su zona horaria sustituyendo
Zpor el código+HH:MMrelevante para su zona horaria. Por ejemplo: "orderDate":“2021-12-02T15:00:00+10:00"especificará que la zona horaria es UTC+10.
Pedidos de varios artículos
A continuación se muestra el contexto para un cliente que ha comprado varios artículos; hay varios artículos en orderItems la matriz:
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"orders": [
{
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"orderDate": "2021-12-02T15:00:00Z",
"id": "abcti84ew-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"gtin": "9891998566P",
"quantity": 3,
"regularUnitPrice": "1.00",
"totalOrderItemPriceAfterDiscounts": "3.00"
}
]
},
{
"gtin": "351998532P",
"quantity": 1,
"regularUnitPrice": "2.50",
"totalOrderItemPriceAfterDiscounts": "2.50"
}
]
}
]
}
Si se realiza correctamente, se devolverá el siguiente objeto:
HTTP/2 200
{
"orders": [
{
"adIds": null,
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"regularUnitPrice": 1.00,
"citrusDiscountAmount": null,
"gtin": "9891998566P",
"adId": "",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 3.00
},
{
"regularUnitPrice": 2.50,
"citrusDiscountAmount": null,
"gtin": "351998532P",
"adId": "",
"quantity": 1,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 2.50
}
],
"orderDate": "2021-12-02T15:00:00Z",
}
]
}
Sincronización de varios pedidos
Si va a sincronizar varios pedidos, puede enviar hasta 100 elementos en lote con cada solicitud. La cantidad de solicitudes que puede realizar es ilimitada. El pedido de carga incorporado es el mismo que el resultado devuelto. Esto hace posible que los datos mantengan la coherencia con la representación del pedido en el backend.
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"orders": [
{
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"orderDate": "2021-12-02T15:00:00Z",
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"gtin": "9891998566P",
"quantity": 3,
"regularUnitPrice": "1.00",
"totalOrderItemPriceAfterDiscounts": "3.00"
}
]
},
{
"customerId": "rw3-v3ag-ol0",
"sessionId": "2m342-2dfe-0f",
"orderDate": "2021-12-02T15:00:00Z",
"id": "i32dm3e4-c158-43d78-43ww32x-m2ide3e3",
"orderItems": [
{
"gtin": "5431998566P",
"quantity": 2,
"regularUnitPrice": "2.00",
"totalOrderItemPriceAfterDiscounts": "4.00"
}
]
}
]
}
Si se realiza correctamente, se devolverá el siguiente objeto:
HTTP/2 200
{
"orders": [
{
"adIds": null,
"teamId": "8616fcd8-5821-4465-9609-401d93fdc800",
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"regularUnitPrice": 1.00,
"citrusDiscountAmount": null,
"gtin": "9891998566P",
"adId": "",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 3.00
}
],
"orderDate": "2021-12-02T15:00:00Z"
},
{
"adIds": null,
"teamId": "8616fcd8-5821-4465-9609-401d93fdc800",
"customerId": "rw3-v3ag-ol0",
"sessionId": "2m342-2dfe-0f",
"id": "i32dm3e4-c158-43d78-43ww32x-m2ide3e3",
"orderItems": [
{
"regularUnitPrice": 2.00,
"citrusDiscountAmount": null,
"gtin": "5431998566P",
"adId": "",
"quantity": 2,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 4.00
}
],
"orderDate": "2021-12-02T15:00:00Z"
}
]
}
ID de vendedor del mercado web
Si está incorporando vendedores del mercado, debe sincronizar el sellerId cuando corresponda al informar de pedidos. En caso de que el producto comprado no tenga un sellerId, se puede omitir.
Si no está incorporando vendedores del mercado web, no es necesario que especifique el ID de vendedor en el informe de pedido
A continuación se muestra un ejemplo de un pedido en el que un producto proviene de un vendedor del mercado y otro no es un producto del mercado:
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"orders": [
{
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"orderDate": "2021-12-02T15:00:00Z",
"id": "abcti84ew-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"gtin": "9891998566P",
"quantity": 3,
"regularUnitPrice": "1.00",
"totalOrderItemPriceAfterDiscounts": "3.00",
"sellerId": "10sa-3s33-j8e3"
}
]
},
{
"gtin": "351998532P",
"quantity": 1,
"regularUnitPrice": "2.50",
"totalOrderItemPriceAfterDiscounts": "2.50"
}
]
}
]
}
Sincronización de datos del pedido a través de frontend (no recomendado)
Si no puede sincronizar datos de pedidos a través del backend, CitrusAd admite una API abierta como se especifica a continuación. Se recomienda que esto solo se utilice cuando no sean posibles la integración del backend y las capacidades de sincronización de archivos.
La información de datos a través del frontend es un riesgo mayor que una integración del backend estándar.
Los integradores deben ser conscientes del riesgo de que, aunque el dominio de notificación no esté actualmente bloqueado por los bloqueadores de anuncios, podría estarlo en el futuro, momento en el que CitrusAd no se hará responsable de la pérdida de datos.
Especificación de la API abierta:
openapi: 3.0.1
info:
title: Citrus
version: 1.0.0
paths:
/v1/resource/third-o:
get:
tags:
- resource
summary: Report an order.
operationId: resource-third-o
parameters:
- in: query
name: key
description: |
(Publishable) API key.
schema:
type: string
required: true
- in: query
name: teaid
description: |
Team id.
schema:
type: string
required: false
- in: query
name: catid
description: |
Catalog id.
schema:
type: string
required: true
- in: query
name: ordid
description: |
Order id.
schema:
type: string
required: true
- in: query
name: ordts
description: |
Order timestamp as a string in RFC3339.
schema:
type: string
required: true
- in: query
name: sesid
description: |
Session id.
schema:
type: string
required: true
- in: query
name: cusid
description: |
Customer id.
schema:
type: string
- in: query
name: procods
description: |
Product codes. Related by index to pris and quas. The length must match pris and quas.
schema:
type: array
items:
type: string
examples:
uat:
value: [ "procods=7913494","procods=6815686" ]
summary: "product code list"
required: true
- in: query
name: pris
description: |
Prices as strings. Related by index to itsids and quas. The length must match pris and quas.
schema:
type: array
items:
type: string
examples:
uat:
value: [ "pris=7913494","pris=6815686" ]
summary: "prices list"
required: true
- in: query
name: quas
description: |
Quantities as strings. Related by index to itsids and pris. The length must match itsids and pris.
schema:
type: array
items:
type: string
examples:
uat:
value: [ "quas=7913494","quas=6815686" ]
summary: "quantity list"
required: true
responses:
200:
description: Successful operation.
content:
application/json:
schema:
type: object
400:
description: Invalid input.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
401:
description: Invalid credentails.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
403:
description: Insufficient permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
500:
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- apiKey: []
components:
schemas:
ErrorResponse:
type: object
properties:
error:
type: object
properties:
message:
type: string
securitySchemes:
apiKey:
type: apiKey
name: Authorization
in: header
Si no está seguro de los términos descritos en esta sección, visite la página de referencia.
Recuperación de información del pedido
Si desea verificar la información del pedido dentro de CitrusAd, realizará una solicitud GET a la API /orders/ con la ID del pedido.
GET $BASE_URL/v1/orders/<ORDER_ID> HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
Recuperará toda la información relacionada con el pedido almacenada en el sistema de CitrusAd.
En el caso de que no se encuentre el pedido, es probable que no se haya incorporado al sistema de CitrusAd.