Solverline API Pública

Introducción

La API de Solverline permite que cualquier tienda web, e-commerce o sistema externo se conecte con tu cuenta y envíe pedidos directamente. Cada pedido puede convertirse en una proforma (para revisarla antes de facturar) o en una factura electrónica autorizada por el SRI de forma inmediata.

Inicio rápido — 3 pasos

POST /api/v1/oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "slv_tu_client_id",
  "client_secret": "slv_secret_tu_secret"
}

POST /api/v1/public/pedido
Authorization: Bearer eyJhbGci...
Content-Type: application/json

{
  "modo": "proforma",
  "referencia_externa": "ORDER-001",
  "cliente": {
    "identificacion": "0912345678",
    "razon_social": "JUAN PEREZ",
    "email": "juan@ejemplo.com"
  },
  "items": [
    {
      "descripcion": "CAMISA TALLA M",
      "cantidad": 2,
      "precio_unitario": 25.00,
      "iva": 15
    }
  ]
}

Autenticación

Solverline usa OAuth 2.0 Client Credentials. Tu tienda se autentica con un client_id y client_secret para obtener un access_token temporal.

Flujo completo

1. Tu tienda → POST /oauth/token con client_id + client_secret
2. Solverline → devuelve access_token (1h) + refresh_token (30d)
3. Tu tienda → usa access_token en Authorization: Bearer {token}
4. Token expira → POST /oauth/token con grant_type=refresh_token
5. Solverline → devuelve nuevo access_token + refresh_token

POST /oauth/token

Obtiene un access token usando tus credenciales o renueva uno existente con el refresh token.

{
  "access_token": "eyJhbGci...",
  "refresh_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "catalogo:read pedidos:write"
}

{
  "grant_type": "refresh_token",
  "refresh_token": "eyJhbGci..."
}

GET /oauth/me

Verifica que tu token es válido y muestra a qué empresa pertenece.

{
  "empresa_id": "7eea...",
  "empresa": "MI EMPRESA S.A.",
  "ruc": "1713371993001",
  "scopes": "catalogo:read pedidos:write",
  "expires_at": "2026-05-13T00:15:03+00:00"
}

GET /public/catalogo

Devuelve los productos de tu empresa en Solverline con precios y stock actuales.

GET /api/v1/public/catalogo?buscar=camisa&con_stock=true&pagina=1
Authorization: Bearer eyJhbGci...

{
  "total": 537,
  "pagina": 1,
  "por_pagina": 50,
  "productos": [
    {
      "id": "9be40d...",
      "codigo": "CAM-001",
      "sku": "CAM-M-AZUL",
      "descripcion": "CAMISA MANGA CORTA TALLA M",
      "precio": 25.00,
      "pvp2": 22.00,
      "pvp3": null,
      "unidad_medida": "UNIDAD",
      "iva": "4",
      "categoria": "ROPA",
      "stock": 15,
      "tipo": "producto"
    }
  ]
}

POST /public/pedido

Crea un pedido desde tu tienda web. Solverline lo procesa como proforma (requiere aprobación) o como factura electrónica inmediata.

{
  "modo": "proforma",
  "referencia_externa": "ORDER-2026-001",
  "forma_pago": "16",
  "webhook_url": "https://miweb.com/api/solverline-webhook",
  "cliente": {
    "identificacion": "0912345678",
    "razon_social": "MARIA GARCIA",
    "email": "maria@ejemplo.com",
    "telefono": "0991234567",
    "direccion": "AV. AMAZONAS N23-45, QUITO"
  },
  "items": [
    {
      "descripcion": "CAMISA MANGA CORTA TALLA M",
      "cantidad": 2,
      "precio_unitario": 25.00,
      "iva": 15
    },
    {
      "sku": "PANT-L-NEGRO",
      "descripcion": "PANTALON TALLA L NEGRO",
      "cantidad": 1,
      "iva": 15
    }
  ],
  "notas": "Entrega a domicilio"
}

{
  "modo": "factura",
  "referencia_externa": "ORDER-2026-002",
  "cliente": {
    "identificacion": "1713371993001",
    "razon_social": "EMPRESA ABC S.A.",
    "email": "contabilidad@empresaabc.com"
  },
  "items": [
    {
      "descripcion": "SERVICIO DE CONSULTORIA",
      "cantidad": 1,
      "precio_unitario": 500.00,
      "iva": 15
    }
  ]
}

{
  "modo": "proforma",
  "proforma_id": "c68b28...",
  "numero_proforma": "PRO-2026-009",
  "referencia_externa": "ORDER-2026-001",
  "subtotal": 50.00,
  "total_iva": 7.50,
  "total": 57.50,
  "estado": "pendiente",
  "url_ver": "https://facturacion.solverline.com/empresas/.../proformas/..."
}

{
  "modo": "factura",
  "proforma_id": "ef81...",
  "numero_proforma": "PRO-2026-010",
  "referencia_externa": "ORDER-2026-002",
  "subtotal": 500.00,
  "total_iva": 75.00,
  "total": 575.00,
  "estado": "aprobada_pendiente_factura",
  "mensaje": "Proforma creada y marcada para facturación. Se procesará automáticamente."
}

GET /public/pedido/{referencia}

Consulta el estado de un pedido usando la referencia_externa que enviaste al crearlo.

GET /api/v1/public/pedido/ORDER-2026-001
Authorization: Bearer eyJhbGci...

{
  "referencia_externa": "ORDER-2026-001",
  "proforma_id": "c68b28...",
  "numero_proforma": "PRO-2026-009",
  "estado": "pendiente",
  "total": 57.50,
  "fecha": "2026-05-12",
  "url_proforma": "https://facturacion.solverline.com/...",
  "factura_id": null,
  "numero_factura": null,
  "clave_acceso_sri": null,
  "url_pdf": null
}

Guía — JavaScript / Fetch

Ejemplo completo para integrar Solverline en cualquier página web usando JavaScript moderno.

// 1. Obtener token (guardar en localStorage o sessionStorage)
async function obtenerToken(clientId, clientSecret) {
  const res = await fetch('https://facturacion.solverline.com/api/v1/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      grant_type: 'client_credentials',
      client_id: clientId,
      client_secret: clientSecret
    })
  })
  const data = await res.json()
  localStorage.setItem('slv_token', data.access_token)
  localStorage.setItem('slv_refresh', data.refresh_token)
  return data.access_token
}

// 2. Enviar pedido
async function enviarPedido(pedido) {
  const token = localStorage.getItem('slv_token')
  const res = await fetch('https://facturacion.solverline.com/api/v1/public/pedido', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify(pedido)
  })
  if (!res.ok) throw new Error((await res.json()).detail)
  return res.json()
}

// 3. Uso
const resultado = await enviarPedido({
  modo: 'proforma',
  referencia_externa: `ORDER-${Date.now()}`,
  cliente: {
    identificacion: '0912345678',
    razon_social: 'JUAN PEREZ',
    email: 'juan@ejemplo.com'
  },
  items: [{
    descripcion: 'PRODUCTO EJEMPLO',
    cantidad: 1,
    precio_unitario: 100.00,
    iva: 15
  }]
})
console.log('Proforma creada:', resultado.numero_proforma)

Guía — PHP

Ejemplo para integrar Solverline en un sitio PHP o tienda personalizada.

<?php
// 1. Obtener token
function obtenerToken($clientId, $clientSecret) {
    $ch = curl_init('https://facturacion.solverline.com/api/v1/oauth/token');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode([
            'grant_type'    => 'client_credentials',
            'client_id'     => $clientId,
            'client_secret' => $clientSecret
        ])
    ]);
    $resp = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $resp['access_token'];
}

// 2. Enviar pedido
function enviarPedido($token, $pedido) {
    $ch = curl_init('https://facturacion.solverline.com/api/v1/public/pedido');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/json',
            'Authorization: Bearer ' . $token
        ],
        CURLOPT_POSTFIELDS => json_encode($pedido)
    ]);
    $resp = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $resp;
}

// 3. Uso
$token = obtenerToken('slv_tu_client_id', 'slv_secret_tu_secret');
$resultado = enviarPedido($token, [
    'modo'               => 'proforma',
    'referencia_externa' => 'ORDER-' . time(),
    'cliente' => [
        'identificacion' => '0912345678',
        'razon_social'   => 'JUAN PEREZ',
        'email'          => 'juan@ejemplo.com'
    ],
    'items' => [[
        'descripcion'    => 'PRODUCTO EJEMPLO',
        'cantidad'       => 1,
        'precio_unitario'=> 100.00,
        'iva'            => 15
    ]]
]);
echo 'Proforma: ' . $resultado['numero_proforma'];

Guía — WooCommerce

Integra Solverline con tu tienda WordPress/WooCommerce para que cada compra genere automáticamente una proforma en Solverline.

<?php
// Enviar pedido a Solverline cuando se crea un pedido en WooCommerce
add_action('woocommerce_checkout_order_created', 'enviar_a_solverline');

function enviar_a_solverline($order) {
    $CLIENT_ID     = 'slv_tu_client_id';
    $CLIENT_SECRET = 'slv_secret_tu_secret';

    // 1. Obtener token
    $token_resp = wp_remote_post(
        'https://facturacion.solverline.com/api/v1/oauth/token',
        ['body' => json_encode([
            'grant_type'    => 'client_credentials',
            'client_id'     => $CLIENT_ID,
            'client_secret' => $CLIENT_SECRET
        ]), 'headers' => ['Content-Type' => 'application/json']]
    );
    $token = json_decode(wp_remote_retrieve_body($token_resp))->access_token;

    // 2. Construir items
    $items = [];
    foreach ($order->get_items() as $item) {
        $items[] = [
            'descripcion'     => strtoupper($item->get_name()),
            'cantidad'        => $item->get_quantity(),
            'precio_unitario' => $item->get_subtotal() / $item->get_quantity(),
            'iva'             => 15
        ];
    }

    // 3. Enviar pedido
    $pedido = [
        'modo'               => 'proforma',
        'referencia_externa' => 'WOO-' . $order->get_id(),
        'cliente'            => [
            'identificacion' => get_post_meta($order->get_id(), '_billing_ruc', true) ?: '9999999999999',
            'razon_social'   => strtoupper($order->get_billing_first_name() . ' ' . $order->get_billing_last_name()),
            'email'          => $order->get_billing_email(),
            'telefono'       => $order->get_billing_phone(),
            'direccion'      => strtoupper($order->get_billing_address_1())
        ],
        'items' => $items
    ];

    $resp = wp_remote_post(
        'https://facturacion.solverline.com/api/v1/public/pedido',
        ['body' => json_encode($pedido),
         'headers' => ['Content-Type' => 'application/json', 'Authorization' => 'Bearer ' . $token]]
    );

    // 4. Guardar referencia en el pedido WooCommerce
    $resultado = json_decode(wp_remote_retrieve_body($resp));
    if (!empty($resultado->numero_proforma)) {
        $order->add_order_note('Solverline: Proforma ' . $resultado->numero_proforma . ' creada.');
        update_post_meta($order->get_id(), '_solverline_proforma', $resultado->proforma_id);
    }
}

Webhooks — Notificaciones automáticas

Si envías un webhook_url en tu pedido, Solverline notificará a esa URL automáticamente cuando el estado del pedido cambie.

Payload que recibe tu URL

POST https://miweb.com/api/solverline-webhook
Content-Type: application/json

{
  "modo": "proforma",
  "proforma_id": "c68b28...",
  "numero_proforma": "PRO-2026-009",
  "referencia_externa": "ORDER-2026-001",
  "subtotal": 50.00,
  "total_iva": 7.50,
  "total": 57.50,
  "estado": "pendiente"
}

Ejemplo de receptor en Node.js / Express

app.post('/api/solverline-webhook', (req, res) => {
  const { referencia_externa, estado, numero_proforma, total } = req.body

  console.log(`Pedido ${referencia_externa} → estado: ${estado}`)

  if (estado === 'convertida') {
    // La factura fue emitida — actualizar tu BD
    actualizarPedido(referencia_externa, 'facturado')
  }

  res.json({ ok: true })
})

Códigos de error

Todos los errores devuelven un JSON con el campo detail explicando el problema.

{ "detail": "Credenciales inválidas" }

Errores comunes