Integración de Inventarios

Apexquotations permite conectar sistemas de inventario externos (ERP, CRM, eCommerce) mediante una capa de integración flexible. En lugar de requerir código personalizado para cada proveedor, utilizamos un sistema de configuración basado en JSON almacenado en base de datos.

Autenticación

Soportamos múltiples métodos de autenticación para conectarnos a tu API. El método se selecciona al crear la integración en el panel administrativo.

None

Para APIs públicas que no requieren credenciales.

Bearer Token

Envía el token en el header Authorization: Bearer <token>.

Basic Auth

Codifica usuario:password en Base64 en el header Authorization.

API Key

Claves personalizadas en Headers o Query Params (configurable en JSON).

Mapeo JSON (Field Mapping)

El corazón de la integración es el campo fieldMapping. Este JSON define cómo Apexquotations debe construir la petición (Request) y cómo interpretar la respuesta (Response).

Estructura Base

{
  "request": {
    // Configuración de la petición
  },
  "response": {
    // Configuración de la respuesta
  }
}

Objeto Request

searchParam (string): Nombre del parámetro de query string para búsqueda (ej. "q", "search", "query").
headers (object): Headers estáticos adicionales (ej. Accept: application/json).
apiKey (object, opcional): Para auth tipo ApiKey manual.
- in: "header" o "query".
- name: Nombre del campo (ej. "X-API-KEY").

Objeto Response

Define cómo extraer los datos del JSON devuelto por tu API.

root (string, opcional): Ruta al array de productos si la respuesta no es un array directo (ej. "data.results").
fields (object): Mapeo de campos internos a externos.
- externalId: ID único del producto.
- name: Nombre/Descripción del producto.
- price: Precio unitario.
- stock: Cantidad disponible.

Nota sobre Paths: Los valores de path pueden ser strings ("price") o arrays de strings para rutas anidadas (["attributes", "price"]).

Ejemplos de Configuración

Ejemplo 1: API Simple (Array en raíz)

API que devuelve [{"id": 1, "name": "Producto", "price": 100}]

{
  "request": {
    "searchParam": "q"
  },
  "response": {
    "fields": {
      "externalId": { "path": "id", "required": true },
      "name": { "path": "name", "required": true },
      "price": { "path": "price", "transform": "number", "required": true },
      "stock": { "path": "stock", "default": 0 }
    }
  }
}

Ejemplo 2: API Compleja (Anidada con Auth custom)

API que devuelve {"data": {"items": [...]}} y requiere API Key en header.

{
  "request": {
    "searchParam": "search_term",
    "headers": {
      "X-Custom-Header": "valor-fijo"
    },
    "apiKey": {
      "in": "header",
      "name": "X-Auth-Token"
    }
  },
  "response": {
    "root": "data.items",
    "fields": {
      "externalId": { "path": "uuid", "required": true },
      "name": { "path": ["attributes", "title"], "required": true },
      "price": { "path": ["pricing", "final_price"], "transform": "number", "required": true },
      "stock": { "path": ["inventory", "total"], "transform": "number", "default": 0 }
    }
  }
}