NAV

Introducción

Esta guía de referencia te ayudará a implementar la API RESTful de POS CRM.

Changelog

Consulta aquí los cambios realizados en la API de POS CRM.

API Host

Todas las peticiones deben ser enviadas a esta URL mediante el protocolo HTTPS:

https://xyz.poscrm.es/api/v1

Códigos de estado de respuesta HTTP

Usamos los códigos de respuesta HTTP convencionales para indicar el éxito o el fracaso de una petición a la API. En general, los códigos en el rango 2xx indican éxito, los códigos en el rango 4xx indican un error que falló debido a la información proporcionada (por ejemplo, se omitió un parámetro requerido, una carga falló, etc.) y los códigos en el rango 5xx indican un error en nuestros servidores.

Resumen de los códigos principales

Código Descripción
200 - OK La petición se ha realizado correctamente.
400 - Bad Request La petición es incorrecta, a menudo debido a que falta un parámetro obligatorio.
401 - Unauthorized No se ha proporcionado un token válido de acceso a la API.
403 - Forbidden El token utilizado en la petición no tiene acceso al recurso solicitado de la API.
404 - Not Found El recurso solicitado no existe.
405 - Method Not Allowed El método solicitado es conocido por el servidor pero no se puede utilizar con el recurso solicitado de la API.
409 - Conflict La petición realizada tiene un conflicto con el estado actual del recurso solicitado de la API.
500, 502, 503, 504 - Server Errors Ha ocurrido un error interno en nuestros servidores

Formato de respuestas de la API

Si la petición es correcta, te devolveremos la siguiente estructura:

{
  "data": {}
}

Siempre que realices una petición correcta a la API obtendrás un JSON con el atributo data y un código de respuesta HTTP 200.

Si la petición es incorrecta, te devolveremos la siguiente estructura:

{
  "error": {
    "code": "ERROR-CODE",
    "http_code": 400,
    "message": "Error information"
  }
}

Por el contrario, las peticiones incorrectas devolverán un JSON con el atributo error y un código de respuesta diferente a HTTP 200.

Cómo autentificarse en la API

Ejemplo de autentificación válida:

{
  "data": {
    "token": "38c3c5930fef5662bb1829d5b1035d5c2bca8baa",
    "expires_in": 60,
    "expires_at": "2022-10-22 10:35:06 GMT"
  }
}

Ejemplo de una petición sin la cabecera 'Authorization', con un token inválido o un token caducado:

{
  "error": {
    "code": "UNAUTHORIZED",
    "http_code": 401,
    "message": "You must provide a valid access token."
  }
}

Para usar los métodos de la API, debes obtener un token de acceso válido. Una vez obtengas un token válido, deberás adjuntarlo en las cabeceras HTTP con cada petición que realices a la API y servirá para autentificarte en la API de POS CRM.

Para obtener un nuevo token, usa el método de autentificación

Si la autentificación es válida, obtendrás un token valido que expirará en cierto tiempo. Cuando el token expire, deberás pedir un nuevo token para seguir realizando peticiones a la API. Utiliza los atributos expires_in que te informa en cuantos minutos expirará el token y expires_at para conocer la fecha exacta de expiración del token.

Para realizar peticiones a los métodos de la API, debes adjuntar en las cabeceras de tu petición una cabecera X-Authorization y su valor será el valor del token que has obtenido.

X-Authorization: 38c3c5930fef5662bb1829d5b1035d5c2bca8baa

Modo mantenimiento

Respuesta devuelta si la plataforma está en modo mantenimiento:

{
  "error": {
    "code": "UNDER_MAINTENANCE",
    "http_code": 503,
    "message": "The platform is currently undergoing maintenance. Try again in a while."
  }
}

El modo mantenimiento nos sirve para actualizar la plataforma sin incidencias. Durante una actualización, no permitimos peticiones y recibirás una respuesta como la del ejemplo.

Normalmente, el modo mantenimiento sólo está activado durante unos minutos. Si haces una petición y te devolvemos el estado 503 del modo de mantenimiento, vuelve a realizar la petición más tarde.

Autentificación

Antes de realizar cualquier petición a la API, debes obtener un token válido. Una vez obtengas un token válido, podrás realizar peticiones a la API de POS CRM.

Obtener un token

Response 200

{
  "data": {
    "token": "38c3c5930fef5662bb1829d5b1035d5c2bca8baa",
    "expires_in": 60,
    "expires_at": "2022-10-22 14:11:39 GMT"
  }
}

Response 400 VALIDATION_FAIL

{
  "error": {
    "code": "VALIDATION_FAIL",
    "http_code": 400,
    "message": "The data validation is not correct. See validation_errors array.",
    "validation_errors": {
      "email": ["Field 'email' is required"]
    }
  }
}

Response 400 TOKEN_EXPIRED

{
  "error": {
    "code": "TOKEN_EXPIRED",
    "http_code": 400,
    "message": "The access token has expired."
  }
}

Response 400 NO_TOKEN

{
  "error": {
    "code": "NO_TOKEN",
    "http_code": 400,
    "message": "No access token has been received."
  }
}

Response 403 USER_NOT_VALID

{
  "error": {
    "code": "USER_NOT_VALID",
    "http_code": 403,
    "message": "The user you are trying to access with does not have permission to access the API."
  }
}

Response 404 NOT_FOUND

{
  "error": {
    "code": "NOT_FOUND",
    "http_code": 404,
    "message": "The email and password sent do not match any active user."
  }
}

Obtén un token válido para poder realizar peticiones a la API.

HTTP Request

POST https://xyz.poscrm.es/api/v1/login

Body parameters

Parameter Description
user string (required) Example: demo
Un usuario asociado a un acceso activo a la API de POS CRM.
password string (required) Example: mypassword
Una contraseña válida.

Clientes

Métodos para administrar los clientes de la plataforma.

Obtener todos los clientes

Response 200

{
  "data": [
    {
      "id": "1",
      "email": "[email protected]",
      "gender_id": "1",
      "gender_name": "Hombre",
      "dni": "11111111H",
      "name": "Customer",
      "first_surname": "First surname",
      "second_surname": "Second surname",
      "birthday": "1970-01-01",
      "age_range_id": "6",
      "age_range_name": "46 a 55 años",
      "phone": "963111222",
      "mobile_phone": "600111222",
      "address_type_id": "7",
      "address_type_name": "Calle",
      "address_name": "Main Street",
      "address_number": "10",
      "address_door_number": "10",
      "address_urbanization": "Villas Country",
      "address_postal_code": "46001",
      "address_city": "Valencia",
      "address_province_id": "48",
      "address_province_name": "Valencia",
      "address_country_id": "15",
      "address_country_name": "España",
      "consent_management_url": "http://lopd.me/5R4R2d1",
      "consent_management_qr": "http://lopd.me/5R4R2d1",
      "has_legal_signature": "1",
      "tags": [],
      "created_at": "2022-10-22 12:26:10",
      "updated_at": "2022-10-22 17:05:33"
    },
    {
      "id": "2",
      "email": "[email protected]",
      "gender_id": "2",
      "dni": "22222222A",
      "name": "Customer 2",
      "first_surname": "First surname",
      "second_surname": "Second surname",
      "birthday": "1990-01-01",
      "age_range_id": "4",
      "age_range_name": "26 a 35 años",
      "phone": "",
      "mobile_phone": "611222333",
      "address_type_id": "7",
      "address_type_name": "Calle",
      "address_name": "Second Street",
      "address_number": "2",
      "address_door_number": "5",
      "address_urbanization": "",
      "address_postal_code": "28001",
      "address_city": "Madrid",
      "address_province_id": "32",
      "address_province_name": "Madrid",
      "address_country_id": "15",
      "address_country_name": "España",
      "consent_management_url": "http://lopd.me/5R4R2d1",
      "consent_management_qr": "http://lopd.me/5R4R2d1",
      "has_legal_signature": "0",
      "tags": ["cliente_nuevo"],
      "created_at": "2022-10-22 12:26:10",
      "updated_at": "2022-10-22 17:05:33"
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "count": 2,
      "per_page": 10,
      "current_page": 0,
      "total_pages": 1
    }
  }
}

Response 400 WRONG_ARGS

{
  "error": {
    "code": "WRONG_ARGS",
    "http_code": 400,
    "message": "Field 'email' must be a valid email."
  }
}

Response 401 FORBIDDEN

{
  "error": {
    "code": "FORBIDDEN",
    "http_code": 403,
    "message": "Forbidden: You don't have permission to make this request."
  }
}

Response 500 INTERNAL_ERROR

{
  "error": {
    "code": "INTERNAL_ERROR",
    "http_code": 500,
    "message": "Internal error."
  }
}

Este método te permite obtener todos los clientes de la plataforma.

HTTP Request

GET https://xyz.poscrm.es/api/v1/marketing/customers

URL parameters

Parameter Description
email string (optional) Example: [email protected]
Envia este parámetro si deseas buscar clientes por email sin tener en cuenta mayúsculas y minúsculas.
mobile_phone string (optional) Example: 600111222
Envia este parámetro si deseas buscar clientes por número de móvil.
page integer (optional) Example: 1
Indica el número de página de resultados a obtener. * Nota: El valor inicial es 0.
per_page integer (optional) Default: 10 Example: 20
Indica el número de resultados por página que quieres obtener.

Obtener un cliente

Response 200

{
  "data": {
    "id": "1",
    "email": "[email protected]",
    "gender_id": "1",
    "gender_name": "Hombre",
    "dni": "11111111H",
    "name": "Customer",
    "first_surname": "First surname",
    "second_surname": "Second surname",
    "birthday": "1970-01-01",
    "age_range_id": "6",
    "age_range_name": "46 a 55 años",
    "phone": "963111222",
    "mobile_phone": "600111222",
    "address_type_id": "7",
    "address_type_name": "Calle",
    "address_name": "Main Street",
    "address_number": "10",
    "address_door_number": "10",
    "address_urbanization": "Villas Country",
    "address_postal_code": "46001",
    "address_city": "Valencia",
    "address_province_id": "48",
    "address_province_name": "Valencia",
    "address_country_id": "15",
    "address_country_name": "España",
    "consent_management_url": "http://lopd.me/5R4R2d1",
    "consent_management_qr": "http://lopd.me/5R4R2d1",
    "has_legal_signature": "1",
    "tags": [],
    "created_at": "2022-10-22 12:26:10",
    "updated_at": "2022-10-22 17:05:33"
  }
}

Response 400 WRONG_ARGS

{
  "error": {
    "code": "WRONG_ARGS",
    "http_code": 400,
    "message": "ID must be an integer."
  }
}

Response 401 FORBIDDEN

{
  "error": {
    "code": "FORBIDDEN",
    "http_code": 403,
    "message": "Forbidden: You don't have permission to make this request."
  }
}

Response 500 INTERNAL_ERROR

{
  "error": {
    "code": "INTERNAL_ERROR",
    "http_code": 500,
    "message": "Internal error."
  }
}

Este método te permite obtener un cliente de la plataforma.

HTTP Request

GET https://xyz.poscrm.es/api/v1/marketing/customers/{id}

URL parameters

Parameter Description
id integer (required) Example: 10
ID del cliente a obtener.

Crear un cliente

Response 200

{
  "data": {
    "id": 1,
    "created_at": "2021-05-22 12:26:10",
    "updated_at": "2021-06-22 17:05:33"
  }
}

Response 400 VALIDATION_FAIL

{
  "error": {
    "code": "VALIDATION_FAIL",
    "http_code": 400,
    "message": "The data validation is not correct. See validation_errors array.",
    "validation_errors": {
      "email": ["Field 'email' is required"]
    }
  }
}

Response 401 FORBIDDEN

{
  "error": {
    "code": "FORBIDDEN",
    "http_code": 403,
    "message": "Forbidden: You don't have permission to make this request."
  }
}

Response 500 INTERNAL_ERROR

{
  "error": {
    "code": "INTERNAL_ERROR",
    "http_code": 500,
    "message": "Internal error."
  }
}

Este método te permite crear un cliente en la plataforma. Para poder crear un cliente, como mínimo, se necesita o el campo email o el campo mobile_phone.

HTTP Request

POST https://xyz.poscrm.es/api/v1/marketing/customers

Body parameters

Parameter Description
email string (required) Example: [email protected]
Email del cliente.
dni string (optional) Example: 11111111H
DNI del cliente.
name string (optional) Example: John
Nombre del cliente.
first_surname string (optional) Example: Doe
Primer apellido del cliente.
second_surname string (optional) Example: Doe
Segundo apellido del cliente.
phone string (optional) Example: 963111222
Número de teléfono del cliente.
mobile_phone string (optional) Example: 963111222
Número de teléfono móvil del cliente.
birthday string (optional) Example: 1970-01-01
Fecha de nacimiento del cliente.
gender_id string (optional)
Género del cliente.

Posibles valores:
  • 2: Hombre
  • 3: Mujer
address_type string (optional)
Tipo de la dirección del cliente.

Posibles valores:
  • 1: Alameda
  • 2: Avenida
  • 3: C. Comercial
  • 4: Callejón
  • 5: Camino
  • 6: Cañada
  • 7: Calle
  • 8: Carrera
  • 9: Carretera
  • 10: Cuesta
  • 11: Glorieta
  • 12: Pasadizo
  • 13: Pasaje
  • 14: Paseo
  • 15: Plaza
  • 16: Rambla
  • 17: Ronda
  • 18: Sendero
  • 19: Travesía
  • 20: Urbanización
  • 21: Vía
address_name string (optional) Example: Main street
Nombre de la dirección del cliente.
address_number integer (optional) Example: 10
Número de la dirección del cliente.
address_door_number integer (optional) Example: 10
Número de puerta de la dirección del cliente.
address_urbanization string (optional) Example: Villas Country
Urbanización de la dirección del cliente.
address_postal_code string (optional) Example: 46001
Código postal de la dirección del cliente.
address_city string (optional) Example: Valencia
Ciudad de la dirección del cliente.
address_province string (optional) Example: Valencia
Provincia de la dirección del cliente.
address_country string (optional) Example: España
País de la dirección del cliente.

Actualizar un cliente

Response 200

{
  "data": {
    "id": 1,
    "created_at": "2021-05-22 12:26:10",
    "updated_at": "2021-06-22 17:05:33"
  }
}

Response 400 VALIDATION_FAIL

{
  "error": {
    "code": "VALIDATION_FAIL",
    "http_code": 400,
    "message": "The data validation is not correct. See validation_errors array.",
    "validation_errors": {
      "email": ["Field 'email' is required"]
    }
  }
}

Response 401 FORBIDDEN

{
  "error": {
    "code": "FORBIDDEN",
    "http_code": 403,
    "message": "Forbidden: You don't have permission to make this request."
  }
}

Response 404 NOT_FOUND

{
  "error": {
    "code": "NOT_FOUND",
    "http_code": 404,
    "message": "Customer not found with ID: 1."
  }
}

Response 500 INTERNAL_ERROR

{
  "error": {
    "code": "INTERNAL_ERROR",
    "http_code": 500,
    "message": "Internal error."
  }
}

Este método te permite actualizar un cliente en la plataforma. Para poder actualizar un cliente, como mínimo, se necesita el campo email.

HTTP Request

PUT https://xyz.poscrm.es/api/v1/marketing/customers/{id}

URL parameters

Parameter Description
id integer (required) Example: 10
ID del cliente.

Body parameters

Parameter Description
email string (optional) Example: [email protected]
Email del cliente.
dni string (optional) Example: 11111111H
DNI del cliente.
name string (optional) Example: John
Nombre del cliente.
first_surname string (optional) Example: Doe
Primer apellido del cliente.
second_surname string (optional) Example: Doe
Segundo apellido del cliente.
phone string (optional) Example: 963111222
Número de teléfono del cliente.
mobile_phone string (optional) Example: 963111222
Número de teléfono móvil del cliente.
birthday string (optional) Example: 1970-01-01
Fecha de nacimiento del cliente.
gender_id string (optional)
Género del cliente.

Posibles valores:
  • 2: Hombre
  • 3: Mujer
address_type string (optional)
Tipo de la dirección del cliente.

Posibles valores:
  • 1: Alameda
  • 2: Avenida
  • 3: C. Comercial
  • 4: Callejón
  • 5: Camino
  • 6: Cañada
  • 7: Calle
  • 8: Carrera
  • 9: Carretera
  • 10: Cuesta
  • 11: Glorieta
  • 12: Pasadizo
  • 13: Pasaje
  • 14: Paseo
  • 15: Plaza
  • 16: Rambla
  • 17: Ronda
  • 18: Sendero
  • 19: Travesía
  • 20: Urbanización
  • 21: Vía
address_name string (optional) Example: Main street
Nombre de la dirección del cliente.
address_number integer (optional) Example: 10
Número de la dirección del cliente.
address_door_number integer (optional) Example: 10
Número de puerta de la dirección del cliente.
address_urbanization string (optional) Example: Villas Country
Urbanización de la dirección del cliente.
address_postal_code string (optional) Example: 46001
Código postal de la dirección del cliente.
address_city string (optional) Example: Valencia
Ciudad de la dirección del cliente.
address_province string (optional) Example: Valencia
Provincia de la dirección del cliente.
address_country string (optional) Example: España
País de la dirección del cliente.

Pedidos

Métodos para administrar los pedidos de la plataforma.

Obtener todos los pedidos

Response 200

{
  "data": [
    {
      "id": "1",
      "sale_number": "10",
      "store_id": "5",
      "store_name": "Castellana",
      "seller_id": "2",
      "seller_name": "María González",
      "sales_series": "AA",
      "sale_date": "2022-10-01 13:23:13",
      "finished": "1",
      "order_reference": "JH235KJ",
      "order_state": "Processing",
      "total": "30.24",
      "total_tax_excl": "24.99",
      "total_discount": "0",
      "total_units": "1",
      "payment_method": "Redsys",
      "customer_id": "1",
      "delivery_address_dni": "11111111H",
      "delivery_address_customer_name": "John",
      "delivery_address_customer_lastname": "Smith",
      "delivery_address_company": "My company",
      "delivery_address_name": "Main Street",
      "delivery_address_address_postal_code": "46001",
      "delivery_address_address_city": "Valencia",
      "delivery_address_address_province": "Valencia",
      "delivery_address_address_country": "España",
      "delivery_address_phone": "961222333",
      "delivery_address_mobile_phone": "611222333",
      "carrier": "My carrier",
      "created_at": "2021-05-01 13:23:13",
      "updated_at": "2021-05-01 13:23:13"
    },
    {
      "id": "2",
      "sale_number": "11",
      "store_id": "5",
      "store_name": "Castellana",
      "seller_id": "2",
      "seller_name": "María González",
      "sales_series": "AA",
      "sale_date": "2022-10-01 13:23:13",
      "finished": "1",
      "order_reference": "JH235KJ",
      "order_state": "Processing",
      "total": "30.24",
      "total_tax_excl": "24.99",
      "total_discount": "0",
      "total_units": "1",
      "payment_method": "Redsys",
      "customer_id": "1",
      "delivery_address_dni": "11111111H",
      "delivery_address_customer_name": "John",
      "delivery_address_customer_lastname": "John",
      "delivery_address_company": "My company",
      "delivery_address_name": "Main Street",
      "delivery_address_address_postal_code": "46001",
      "delivery_address_address_city": "Valencia",
      "delivery_address_address_province": "Valencia",
      "delivery_address_address_country": "España",
      "delivery_address_phone": "961222333",
      "delivery_address_mobile_phone": "611222333",
      "carrier": "My carrier",
      "created_at": "2021-05-01 13:23:13",
      "updated_at": "2021-05-01 13:23:13"
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "count": 2,
      "per_page": 10,
      "current_page": 0,
      "total_pages": 1
    }
  }
}

Response 400 WRONG_ARGS

{
  "error": {
    "code": "WRONG_ARGS",
    "http_code": 400,
    "message": "ID must be an integer."
  }
}

Response 401 FORBIDDEN

{
  "error": {
    "code": "FORBIDDEN",
    "http_code": 403,
    "message": "Forbidden: You don't have permission to make this request."
  }
}

Response 500 INTERNAL_ERROR

{
  "error": {
    "code": "INTERNAL_ERROR",
    "http_code": 500,
    "message": "Internal error."
  }
}

Este método te permite obtener todos los pedidos de la plataforma.

HTTP Request

GET https://xyz.poscrm.es/api/v1/retail/orders

URL parameters

Parameter Description
customer_id integer (optional) Example: 10
Envia este parámetro si deseas buscar pedidos de un cliente en concreto.
min_date date (optional) Format: Y-m-d Example: 2022-10-01
Envia este parámetro si deseas buscar pedidos que se hayan realizado en una fecha igual o superior a la indicada en este parámetro.
max_date date (optional) Format: Y-m-d Example: 2022-10-31
Envia este parámetro si deseas buscar pedidos que se hayan realizado en una fecha inferior o igual a la indicada en este parámetro.
page integer (optional) Example: 1
Indica el número de página de resultados a obtener.
per_page integer (optional) Default: 10 Example: 20
Indica el número de resultados por página que quieres obtener.

Obtener un pedido

Response 200

{
  "data": {
    "id": "1",
    "sale_number": "10",
    "store_id": "5",
    "store_name": "Castellana",
    "seller_id": "2",
    "seller_name": "María González",
    "sales_series": "AA",
    "sale_date": "2022-10-01 13:23:13",
    "finished": "1",
    "order_reference": "JH235KJ",
    "order_state": "Processing",
    "total": "30.24",
    "total_tax_excl": "24.99",
    "total_discount": "0",
    "total_units": "1",
    "payment_method": "Redsys",
    "customer_id": "1",
    "delivery_address_dni": "11111111H",
    "delivery_address_customer_name": "John",
    "delivery_address_customer_lastname": "Smith",
    "delivery_address_company": "My company",
    "delivery_address_name": "Main Street",
    "delivery_address_address_postal_code": "46001",
    "delivery_address_address_city": "Valencia",
    "delivery_address_address_province": "Valencia",
    "delivery_address_address_country": "España",
    "delivery_address_phone": "961222333",
    "delivery_address_mobile_phone": "611222333",
    "carrier": "My carrier",
    "created_at": "2021-05-01 13:23:13",
    "updated_at": "2021-05-01 13:23:13"
  }
}

Response 400 WRONG_ARGS

{
  "error": {
    "code": "WRONG_ARGS",
    "http_code": 400,
    "message": "ID must be an integer."
  }
}

Response 401 FORBIDDEN

{
  "error": {
    "code": "FORBIDDEN",
    "http_code": 403,
    "message": "Forbidden: You don't have permission to make this request."
  }
}

Response 500 INTERNAL_ERROR

{
  "error": {
    "code": "INTERNAL_ERROR",
    "http_code": 500,
    "message": "Internal error."
  }
}

Este método te permite obtener un pedido de la plataforma.

HTTP Request

GET https://xyz.poscrm.es/api/v1/retail/orders/{id}

URL parameters

Parameter Description
id integer (optional) Example: 10
ID del pedido a obtener.

Crear un pedido

Response 200

{
  "data": {
    "id": 1,
    "created_at": "2021-05-01 13:23:13",
    "updated_at": "2021-05-01 13:23:13"
  }
}

Response 400 VALIDATION_FAIL

{
  "error": {
    "code": "VALIDATION_FAIL",
    "http_code": 400,
    "message": "The data validation is not correct. See validation_errors array.",
    "validation_errors": {
      "date": ["Field 'date' is required"]
    }
  }
}

Response 401 FORBIDDEN

{
  "error": {
    "code": "FORBIDDEN",
    "http_code": 403,
    "message": "Forbidden: You don't have permission to make this request."
  }
}

Response 500 INTERNAL_ERROR

{
  "error": {
    "code": "INTERNAL_ERROR",
    "http_code": 500,
    "message": "Internal error."
  }
}

Este método te permite crear un pedido de la plataforma.

HTTP Request

POST https://xyz.poscrm.es/api/v1/retail/orders

URL parameters

Parameter Description
transaction_origin string (required)
Dato que indica dónde se ha producido la venta.

Posibles valores:
  • crm
  • eci
  • icg
  • magento
  • prestashop
  • sap
  • shopify
  • woocommerce
order_number integer (optional) Example: 12
Número del pedido.
reference string (required) Example: JH235KJ
Referencia del pedido.
date string (required) Format: Y-m-d H:i:s Example: 2021-05-01 10:23:17
Fecha del pedido.
state string (optional) Example: Processing
Estado del pedido.
total double (required) Example: 26.99
Importe total del pedido.
total_tax_excl double (required) Example: 26.99
Importe total sin impuestos del pedido.
total_discount double (optional) Example: 4.99
Importe total de los descuentos aplicados al pedido.
payment_method string (required) Example: Redsys
Forma de pago utilizada al realizar el pedido.
customer_id integer (required) Example: 10
ID del cliente que ha realizado el pedido.
delivery_address object (optional)
Datos de la dirección de entrega del pedido.
(El objeto debe estar codificado en JSON.)

Valores del objeto:
  • dni string Example: 11111111H
  • name string Example: John
  • lastname string Example: Doe
  • company string Example: My company
  • address_name string Example: Main Street
  • address_postal_code string Example: 46001
  • address_city string Example: Valencia
  • address_province string Example: Valencia
  • address_country string Example: España
  • phone string Example: 961222333
  • mobile_phone string Example: 611222333
carrier string (optional) Example: My carrier
Transportista utilizado en el pedido.
products array (required)
Productos utilizados en el pedido.
(El array de objetos debe estar codificado en JSON.)

Valores de los objetos del array:
  • reference string Example: 35431D
  • barcode string Example: 3385115154421
  • name string Example: Product 1
  • quantity integer Example: 1
  • unit_price double Example: 10
  • unit_price_tax_excl string Example: 8.26
  • tax double Example: 21
  • total double Example: 10
  • total_tax_excl double Example: 8.26
  • total_discount double Example: 2.99

Actualizar un pedido

Response 200

{
  "data": {
    "id": 1,
    "created_at": "2021-05-01 13:23:13",
    "updated_at": "2021-05-01 13:43:14"
  }
}

Response 400 VALIDATION_FAIL

{
  "error": {
    "code": "VALIDATION_FAIL",
    "http_code": 400,
    "message": "The data validation is not correct. See validation_errors array.",
    "validation_errors": {
      "date": ["Field 'date' is required"]
    }
  }
}

Response 401 FORBIDDEN

{
  "error": {
    "code": "FORBIDDEN",
    "http_code": 403,
    "message": "Forbidden: You don't have permission to make this request."
  }
}

Response 500 INTERNAL_ERROR

{
  "error": {
    "code": "INTERNAL_ERROR",
    "http_code": 500,
    "message": "Internal error."
  }
}

Este método te permite actualizar un pedido de la plataforma.

HTTP Request

PUT https://xyz.poscrm.es/api/v1/retail/orders/{id}

URL parameters

Parameter Description
id integer (required) Example: 10
ID del pedido.

Body parameters

Parameter Description
reference string (optional) Example: JH235KJ
Referencia del pedido.
date string (required) Example: 2021-05-01 10:23:17
Fecha del pedido.
state string (optional) Example: Processing
Estado del pedido.
total double (required) Example: 26.99
Importe total del pedido.
total_tax_excl double (required) Example: 26.99
Importe total sin impuestos del pedido.
total_discount double (optional) Example: 4.99
Importe total de los descuentos aplicados al pedido.
payment_method double (required) Example: Redsys
Forma de pago utilizada al realizar el pedido.
customer_id integer (optional) Example: 10
ID del cliente que ha realizado el pedido.
delivery_address object (optional)
Datos de la dirección de entrega del pedido.
(El objeto debe estar codificado en JSON.)

Valores del objeto:
  • dni string Example: 11111111H
  • name string Example: John
  • lastname string Example: Doe
  • company string Example: My company
  • address_name string Example: Main Street
  • address_postal_code string Example: 46001
  • address_city string Example: Valencia
  • address_province string Example: Valencia
  • address_country string Example: España
  • phone string Example: 961222333
  • mobile_phone string Example: 611222333
carrier string (optional) Example: My carrier
Transportista utilizado en el pedido.
products array (required)
Productos utilizados en el pedido.
(El array de objetos debe estar codificado en JSON.)

Valores de los objetos del array:
  • reference string Example: 35431D
  • barcode string Example: 3385115154421
  • name string Example: Product 1
  • quantity integer Example: 1
  • unit_price double Example: 10
  • unit_price_tax_excl string Example: 8.26
  • tax double Example: 21
  • total double Example: 10
  • total_tax_excl double Example: 8.26
  • total_discount double Example: 2.99

Obtener los productos de un pedido

Response 200

{
  "data": [
    {
      "sale_id": "1",
      "detail_line_number": "1",
      "product_id": "1",
      "reference": "35431D",
      "barcode": "3385115154421",
      "product_name": "Product 1",
      "quantity": "1",
      "unit_price": "7.5",
      "unit_price_tax_excl": "6.2",
      "tax": "21",
      "total": "7.5",
      "total_discount_perc": "10",
      "total_discount_eur": "0.75",
      "created_at": "2021-05-01 13:23:13",
      "updated_at": "2021-05-01 13:23:13"
    },
    {
      "sale_id": "1",
      "detail_line_number": "2",
      "product_id": "2",
      "reference": "35431E",
      "barcode": "3385115154422",
      "product_name": "Product 2",
      "quantity": "2",
      "unit_price": "10",
      "unit_price_tax_excl": "8.26",
      "tax": "21",
      "total": "20",
      "total_discount_perc": "0",
      "total_discount_eur": "0",
      "created_at": "2021-05-01 13:23:13",
      "updated_at": "2021-05-01 13:23:13"
    },
    {
      "sale_id": "1",
      "detail_line_number": "3",
      "product_id": "3",
      "reference": "35431F",
      "barcode": "",
      "product_name": "My Carrier",
      "quantity": "1",
      "unit_price": "3.99",
      "unit_price_tax_excl": "3.3",
      "tax": "21",
      "total": "3.99",
      "total_discount_perc": "0",
      "total_discount_eur": "0",
      "created_at": "2021-05-01 13:23:13",
      "updated_at": "2021-05-01 13:23:13"
    }
  ],
  "meta": {
    "pagination": {
      "total": "3",
      "count": 3,
      "per_page": 10,
      "current_page": 0,
      "total_pages": 1
    }
  }
}

Response 400 WRONG_ARGS

{
  "error": {
    "code": "WRONG_ARGS",
    "http_code": 400,
    "message": "ID must be an integer."
  }
}

Response 401 FORBIDDEN

{
  "error": {
    "code": "FORBIDDEN",
    "http_code": 403,
    "message": "Forbidden: You don't have permission to make this request."
  }
}

Response 500 INTERNAL_ERROR

{
  "error": {
    "code": "INTERNAL_ERROR",
    "http_code": 500,
    "message": "Internal error."
  }
}

Este método te permite obtener los productos de un pedido de la plataforma.

HTTP Request

GET https://xyz.poscrm.es/api/v1/orders/{id}/detail

URL parameters

Parameter Description
id integer (required) Example: 10
ID del pedido.

Programas de fidelidad

Métodos para administrar los programas de fidelidad de la plataforma.

Obtener todos los programas de fidelidad

Response 200

{
  "data": [
    {
      "id": "1",
      "name": "Programa de fidelidad 1",
      "expires": "0",
      "start_date": null,
      "end_date": null,
      "points_per_euro": "1",
      "points_expiration_days": "365",
      "created_at": "2021-01-01 09:00:00",
      "updated_at": "2021-01-01 09:00:00"
    },
    {
      "id": "2",
      "name": "Programa de fidelidad 2",
      "expires": "0",
      "start_date": null,
      "end_date": null,
      "points_per_euro": "1",
      "points_expiration_days": "365",
      "created_at": "2021-01-01 09:00:00",
      "updated_at": "2021-01-01 09:00:00"
    }
  ],
  "meta": {
    "pagination": {
      "total": "2",
      "count": 2,
      "per_page": 10,
      "current_page": 0,
      "total_pages": 1
    }
  }
}

Response 401 FORBIDDEN

{
  "error": {
    "code": "FORBIDDEN",
    "http_code": 403,
    "message": "Forbidden: You don't have permission to make this request."
  }
}

Response 500 INTERNAL_ERROR

{
  "error": {
    "code": "INTERNAL_ERROR",
    "http_code": 500,
    "message": "Internal error."
  }
}

Este método te permite obtener todos los pedidos de la plataforma.

HTTP Request

GET https://xyz.poscrm.es/api/v1/general/loyalty-programs

URL parameters

Parameter Description
page integer (optional) Example: 1
Indica el número de página de resultados a obtener.
per_page integer (optional) Default: 10 Example: 20
Indica el número de resultados por página que quieres obtener.

Obtener un programa de fidelidad

Response 200

{
  "data": {
    "id": "1",
    "name": "Programa de fidelidad 1",
    "expires": "0",
    "start_date": null,
    "end_date": null,
    "points_per_euro": "1",
    "points_expiration_days": "365",
    "created_at": "2021-01-01 09:00:00",
    "updated_at": "2021-01-01 09:00:00"
  }
}

Response 400 WRONG_ARGS

{
  "error": {
    "code": "WRONG_ARGS",
    "http_code": 400,
    "message": "ID must be an integer."
  }
}

Response 401 FORBIDDEN

{
  "error": {
    "code": "FORBIDDEN",
    "http_code": 403,
    "message": "Forbidden: You don't have permission to make this request."
  }
}

Response 500 INTERNAL_ERROR

{
  "error": {
    "code": "INTERNAL_ERROR",
    "http_code": 500,
    "message": "Internal error."
  }
}

Este método te permite obtener todos los pedidos de la plataforma.

HTTP Request

GET https://xyz.poscrm.es/api/v1/general/loyalty-programs/{id}

URL parameters

Parameter Description
id integer (optional) Example: 1
ID del programa de fidelidad a obtener.

Webhooks

Métodos para registrar datos de eventos externos a la plataforma.

Cómo autentificarse en los webhooks

Ejemplo de una petición sin la cabecera 'X-Authorization' o con un token inválido:

{
  "error": {
    "code": "UNAUTHORIZED",
    "http_code": 401,
    "message": "You must provide a valid access token."
  }
}

Para poder hacer uso de los webhooks debes incluir la cabecera X-Authorization con el token de acceso para webhooks que tengas asociado en el panel de gestión de accesos en la plataforma:

X-Authorization: b07722c63f4d675aff284ecc411d306953657

Nueva suscripción a newsletter

Response 200

{
  "data": {
    "id": "2",
    "created_at": "2021-05-01 13:23:13",
    "updated_at": "2021-05-01 13:23:13"
  }
}

Response 400 WRONG_ARGS

{
  "error": {
    "code": "VALIDATION_FAIL",
    "http_code": 400,
    "message": "The data validation is not correct. See validation_errors array.",
    "validation_errors": {
      "email": ["Field 'email' is required"]
    }
  }
}

Response 401 FORBIDDEN

{
  "error": {
    "code": "FORBIDDEN",
    "http_code": 403,
    "message": "Forbidden: You don't have permission to make this request."
  }
}

Response 500 INTERNAL_ERROR

{
  "error": {
    "code": "INTERNAL_ERROR",
    "http_code": 500,
    "message": "Internal error."
  }
}

Este método te permite registrar un cliente en la plataforma.

HTTP Request

POST https://xyz.poscrm.es/api/v1/webhooks/newsletter-subscription

Body parameters

Parameter Description
email string (required) Example: [email protected]
Email del cliente.
contact_consent integer (required) Example: 1
Indica si el cliente ha dado permiso para ser contactado.

Posibles valores:
  • 0: No
  • 1: Si
contact_consent_other_sites integer (optional) Example: 1
Indica si el cliente ha dado permiso para ser contactado por el resto de webs.

Posibles valores:
  • 0: No
  • 1: Si

Nuevo registro en área privada

Response 200

{
  "data": {
    "id": "2",
    "created_at": "2021-05-01 13:23:13",
    "updated_at": "2021-05-01 13:23:13"
  }
}

Response 400 WRONG_ARGS

{
  "error": {
    "code": "VALIDATION_FAIL",
    "http_code": 400,
    "message": "The data validation is not correct. See validation_errors array.",
    "validation_errors": {
      "email": ["Field 'email' is required"]
    }
  }
}

Response 401 FORBIDDEN

{
  "error": {
    "code": "FORBIDDEN",
    "http_code": 403,
    "message": "Forbidden: You don't have permission to make this request."
  }
}

Response 500 INTERNAL_ERROR

{
  "error": {
    "code": "INTERNAL_ERROR",
    "http_code": 500,
    "message": "Internal error."
  }
}

Este método te permite registrar un cliente en la plataforma.

HTTP Request

POST https://xyz.poscrm.es/api/v1/webhooks/private-area-registration

Body parameters

Parameter Description
email string (required) Example: [email protected]
Email del cliente.
name string (optional) Example: John
Nombre del cliente.
first_surname string (optional) Example: Doe
Primer apellido del cliente.
second_surname string (optional) Example: Doe
Segundo apellido del cliente.
contact_consent integer (required) Example: 1
Indica si el cliente ha dado permiso para ser contactado.

Posibles valores:
  • 0: No
  • 1: Si
contact_consent_other_sites integer (optional) Example: 1
Indica si el cliente ha dado permiso para ser contactado por el resto de webs.

Posibles valores:
  • 0: No
  • 1: Si

Añadir puntos de fidelidad

Response 200

{
  "data": {
    "id": "2",
    "points": "10",
    "created_at": "2021-05-01 13:23:13",
    "updated_at": "2021-05-01 13:23:13"
  }
}

Response 400 WRONG_ARGS

{
  "error": {
    "code": "VALIDATION_FAIL",
    "http_code": 400,
    "message": "The data validation is not correct. See validation_errors array.",
    "validation_errors": {
      "email": ["Field 'email' is required"]
    }
  }
}

Response 401 FORBIDDEN

{
  "error": {
    "code": "FORBIDDEN",
    "http_code": 403,
    "message": "Forbidden: You don't have permission to make this request."
  }
}

Response 500 INTERNAL_ERROR

{
  "error": {
    "code": "INTERNAL_ERROR",
    "http_code": 500,
    "message": "Internal error."
  }
}

Este método te permite añadir puntos de fidelidad a un cliente de la plataforma.

HTTP Request

POST https://xyz.poscrm.es/api/v1/webhooks/add-loyalty-points

Body parameters

Parameter Description
email string (required) Example: [email protected]
Email del cliente.
loyalty_program_id integer (required) Example: 10
ID del programa de fidelidad sobre el que hay que asociar la operación.
points integer (optional) Example: 1
Número de puntos de fidelidad que hay que añadir a la ficha del cliente.