API de pedidos

Antes de empezar

Lo que necesitas tener a mano.

La API trabaja sobre HTTPS y usa JSON tanto en la petición como en la respuesta. Todas las llamadas se hacen contra tu dominio de Sofycon:

BASE https://www.sofycon.com/rest/api/v2

Necesitas una clave de API (apiKey) asociada a tu cuenta. Si todavía no la tienes, pídela a tu comercial en comercial@sofycon.com.

Trata la clave como una contraseña. No la publiques en código de cliente (JavaScript de tu web, apps móviles) ni en repositorios: cualquiera con esa clave puede crear pedidos a tu nombre.

Autenticación

Cabecera apiKey en todas las peticiones.

La autenticación se hace con una cabecera HTTP. No hay OAuth ni tokens que caduquen: se envía la misma clave en cada llamada.

Cabecera	Dónde	Valor
`apiKey`	header	Tu clave de API
`Content-Type`	header	`application/json`

Si la clave falta o no es válida, la petición no crea ningún pedido. Comprueba que la cabecera se llama exactamente apiKey, respetando mayúsculas y minúsculas.

Crear pedido

Da de alta un pedido con sus líneas y su dirección de envío.

POST https://www.sofycon.com/rest/api/v2/order

El cuerpo de la petición es un objeto JSON con una única clave order, que contiene el array de productos y los datos de envío. El cuerpo es obligatorio.

Campos del pedido

Contenido del objeto order.

Productos

Campo	Tipo		Descripción
`products`	array	Obligatorio	Líneas del pedido. Cada elemento es un objeto con la referencia y la cantidad.
`products[].part_number`	string	Obligatorio	Referencia del producto (la del fabricante, tal y como aparece en la ficha).
`products[].quantity`	integer	Obligatorio	Número de unidades.

Dirección de envío

Campo	Tipo		Descripción
`shipping_firstname`	string	Obligatorio	Nombre de quien recibe.
`shipping_lastname`	string	Obligatorio	Apellidos de quien recibe.
`shipping_company`	string	Obligatorio	Empresa destinataria.
`shipping_address_1`	string	Obligatorio	Calle, número, piso.
`shipping_address_2`	string	Opcional	Segunda línea de dirección (nave, polígono, referencias).
`shipping_city`	string	Obligatorio	Población.
`shipping_postcode`	string	Obligatorio	Código postal.
`shipping_province`	string	Obligatorio	Provincia.
`shipping_country`	string	Obligatorio	País.
`shipping_telephone`	string	Obligatorio	Teléfono de contacto para la entrega.

Sobre la referencia del producto: el ejemplo oficial de la API envía la referencia en part_number, mientras que el esquema publicado la nombra sku. Usa part_number, que es lo que aparece en el ejemplo de llamada, y confirma con tu comercial si tu integración necesita el otro nombre.

Ejemplos

Una llamada completa, lista para copiar.

Cuerpo de la petición

{
  "order": {
    "products": [
      {
        "part_number": "KL4541XDMDR",
        "quantity": 1
      }
    ],
    "shipping_firstname": "test",
    "shipping_lastname": "test",
    "shipping_company": "test",
    "shipping_address_1": "test",
    "shipping_address_2": "test",
    "shipping_city": "test",
    "shipping_postcode": "00000",
    "shipping_country": "test",
    "shipping_province": "test",
    "shipping_telephone": "test"
  }
}

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "apiKey: XXXXXXXX" \
  -d '{ \
    "order": { \
      "products": [ \
        { \
          "part_number": "KL4541XDMDR", \
          "quantity": 1 \
        } \
      ], \
      "shipping_firstname": "test", \
      "shipping_lastname": "test", \
      "shipping_company": "test", \
      "shipping_address_1": "test", \
      "shipping_address_2": "test", \
      "shipping_city": "test", \
      "shipping_postcode": "00000", \
      "shipping_country": "test", \
      "shipping_province": "test", \
      "shipping_telephone": "test" \
    } \
  }' \
  https://www.sofycon.com/rest/api/v2/order

PHP

<?php
$payload = [
    'order' => [
        'products' => [
            ['part_number' => 'KL4541XDMDR', 'quantity' => 1],
        ],
        'shipping_firstname' => 'Nombre',
        'shipping_lastname'  => 'Apellidos',
        'shipping_company'   => 'Mi Empresa S.L.',
        'shipping_address_1' => 'Calle Ejemplo 1',
        'shipping_city'      => 'Madrid',
        'shipping_postcode'  => '28001',
        'shipping_province'  => 'Madrid',
        'shipping_country'   => 'España',
        'shipping_telephone' => '913682224',
    ],
];

$ch = curl_init('https://www.sofycon.com/rest/api/v2/order');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json', 'apiKey: XXXXXXXX'],
    CURLOPT_POSTFIELDS     => json_encode($payload),
]);
$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);
echo $status === 200 ? 'Pedido '.$data['order_id'] : 'Error: '.$response;

Respuestas

Qué devuelve la API.

200 Pedido creado correctamente. Devuelve el identificador del pedido, disponible en formato JSON o XML.

{
  "order_id": 44
}

Campo	Tipo	Descripción
`order_id`	integer	Número de pedido asignado. Guárdalo: es el que aparece en tu historial de pedidos y el que necesitarás para cualquier consulta.

405 Datos no válidos (Invalid input). Revisa que el JSON esté bien formado, que estén todos los campos obligatorios y que las referencias de producto existan.

¿Necesitas ayuda?

Para solicitar tu clave de API, resolver dudas de integración o dar de alta referencias, escríbenos a comercial@sofycon.com o llámanos al 913 682 224.

Puedes consultar tus pedidos creados por API, como cualquier otro, en tu área de cliente.

Documentación para clientes