Documentación de FactuSync API

API REST para emitir comprobantes electrónicos autorizados por el SRI Ecuador. Firma XAdES-BES, cola con reintentos, RIDE PDF y webhooks incluidos.

Autenticación

Todas las solicitudes deben incluir el header X-API-Key: <API_KEY>.

Las API Keys se gestionan desde el dashboard de FactuSync.

• documents:write — Crear documentos
• documents:emit — Emitir al SRI
• documents:read — Consultar documentos y RIDE
• documents:ride — Descargar RIDE PDF
• cancellations:write — Solicitar anulaciones
• cancellations:approve — Aprobar anulaciones
• validation:read — Validar RUC
• queue:read — Consultar cola de emisión
• queue:retry — Reintentar jobs fallidos de la cola
• webhooks:manage — Gestionar webhooks
• signature:manage — Gestionar la firma electrónica (.p12): subir, rotar y consultar estado del certificado

Ambientes

Las claves de API tienen dos prefijos:

• fsk_live_... → Producción — Emite documentos reales al SRI
• fsk_test_... → Sandbox — Ambiente de certificación del SRI

URL base

https://api.factusync.jipsoft.com/

Flujo de emisión

Ciclo de vida del documento

Estados por los que pasa un comprobante desde su creación hasta la autorización del SRI.

Flujo de gestión de firma (.p12)

Endpoints

Base: https://api.factusync.jipsoft.com — Toca un endpoint para ver el scope requerido y un ejemplo de request/response.

# Scope: documents:write
POST /documents
{
  "documentTypeCode": "01",
  "establishment": "001",
  "emissionPoint": "001",
  "payload": {
    "recipientIdentificationType": "04",
    "recipientIdentificationNumber": "0992339411001",
    "recipientName": "ACME Corp S.A.",
    "recipientEmail": "[email protected]",
    "accountingRequired": "SI",
    "items": [
      {
        "mainCode": "PROD-001",
        "description": "Tornillo hexagonal 1/4 x 2 galvanizado",
        "quantity": 100,
        "unitPrice": 0.15,
        "discount": 0,
        "taxes": [
          { "taxCode": "2", "taxRateCode": "4", "taxableBase": 15.00, "taxRate": 15, "taxAmount": 2.25 }
        ]
      }
    ],
    "totals": { "subtotalTaxable": 15.00, "totalTax": 2.25, "grandTotal": 17.25 },
    "payments": [ { "paymentMethodCode": "01", "amount": 17.25 } ]
  },
  "externalReference": "POS-SALE-12345"
}

# 200 OK
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "DRAFT",
  "documentTypeCode": "01",
  "establishment": "001",
  "emissionPoint": "001",
  "sequenceNumber": null,
  "accessKey": null,
  "createdAt": "2026-06-24T15:30:00.000Z"
}

# Scope: documents:read
GET /documents/{id}

# 200 OK
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "AUTHORIZED",
  "sequenceNumber": 1,
  "accessKey": "2406202601...",
  "documentTypeCode": "01",
  "establishment": "001",
  "emissionPoint": "001",
  "updatedAt": "2026-06-24T15:32:10.000Z"
}

# Scope: documents:emit  (the document must be in DRAFT)
POST /documents/{id}/emit

# 200 OK
{ "jobId": "42", "status": "queued" }

# 409 INVALID_STATE_TRANSITION if not DRAFT.
# If REJECTED, call POST /documents/{id}/retry first, then emit again.

# Scope: cancellations:write  (multipart/form-data)
POST /cancellations?documentId={uuid}
fields:
  cancelReasonCode = 01            # 01..05 (SRI reasons)
  cancelReason     = "Error en datos del comprador"
  annulmentPdf     = <file.pdf>    # required SRI annulment PDF

# 200 OK
{
  "cancellationId": "uuid",
  "status": "PENDING_APPROVAL",
  "cancelReasonCode": "01",
  "cancelReasonDescription": "Error en el llenado del comprobante",
  "hasAnnulmentPdf": true
}

# Scope: validation:read
GET /validation/ruc/{id}

# 200 OK
{
  "id": "0992339411001",
  "source": "cipherbyte",
  "active": true,
  "legalName": "ACME Corp S.A.",
  "tradeName": "ACME",
  "taxStatus": "ACTIVO"
}

# Scope: signature:manage  (multipart/form-data, max 100 KB)
POST /integration/signature
fields:
  file        = <certificate.p12>
  p12Password = <password>

# 201 Created (no private material is ever returned)
{
  "active": {
    "subject": "CN=...",
    "serial": "1234567890",
    "issuedAt": "2026-06-01T00:00:00.000Z",
    "expiresAt": "2027-06-01T00:00:00.000Z",
    "createdAt": "2026-06-24T15:30:00.000Z",
    "lifecycle": "ACTIVE",
    "daysRemaining": 341
  }
}

# Scope: signature:manage
GET /integration/signature

# 200 OK
{
  "active": {
    "subject": "CN=...",
    "serial": "1234567890",
    "expiresAt": "2027-06-01T00:00:00.000Z",
    "lifecycle": "ACTIVE",
    "daysRemaining": 341
  }
}

Ejemplos de código

Crear y emitir una factura (cURL)

# 1. Create draft
curl -X POST https://api.factusync.jipsoft.com/documents \
  -H "X-API-Key: fsk_live_eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "documentTypeCode": "01",
    "establishment": "001",
    "emissionPoint": "001",
    "payload": {
      "recipientIdentificationType": "04",
      "recipientIdentificationNumber": "0992339411001",
      "recipientName": "ACME Corp S.A.",
      "items": [
        {
          "mainCode": "PROD-001",
          "description": "Tornillo hexagonal 1/4 x 2 galvanizado",
          "quantity": 100,
          "unitPrice": 0.15,
          "discount": 0,
          "taxes": [
            { "taxCode": "2", "taxRateCode": "4", "taxableBase": 15.00, "taxRate": 15, "taxAmount": 2.25 }
          ]
        }
      ],
      "totals": { "subtotalTaxable": 15.00, "totalTax": 2.25, "grandTotal": 17.25 },
      "payments": [ { "paymentMethodCode": "01", "amount": 17.25 } ]
    },
    "externalReference": "POS-SALE-12345"
  }'

# 2. Emit to SRI (document must be DRAFT; if REJECTED use POST .../retry first)
curl -X POST https://api.factusync.jipsoft.com/documents/{id}/emit \
  -H "X-API-Key: fsk_live_eyJ..."

# 3. Check status
curl https://api.factusync.jipsoft.com/documents/{id} \
  -H "X-API-Key: fsk_live_eyJ..."

Con Node.js / TypeScript

import axios from 'axios';

const client = axios.create({
  baseURL: 'https://api.factusync.jipsoft.com',
  headers: { 'X-API-Key': 'fsk_live_eyJ...' },
});

// Create draft invoice
const { data: doc } = await client.post('/documents', {
  documentTypeCode: '01',
  establishment: '001',
  emissionPoint: '001',
  payload: {
    recipientIdentificationType: '04',
    recipientIdentificationNumber: '0992339411001',
    recipientName: 'ACME Corp S.A.',
    items: [
      {
        mainCode: 'PROD-001',
        description: 'Tornillo hexagonal 1/4 x 2 galvanizado',
        quantity: 100,
        unitPrice: 0.15,
        discount: 0,
        taxes: [{ taxCode: '2', taxRateCode: '4', taxableBase: 15.0, taxRate: 15, taxAmount: 2.25 }],
      },
    ],
    totals: { subtotalTaxable: 15.0, totalTax: 2.25, grandTotal: 17.25 },
    payments: [{ paymentMethodCode: '01', amount: 17.25 }],
  },
  externalReference: 'POS-SALE-12345',
});

// Emit (DRAFT only). After REJECTED: await client.post(`/documents/${doc.id}/retry`)
await client.post(`/documents/${doc.id}/emit`);

Verificar estado y obtener RIDE

// Poll until authorized (with timeout)
async function waitForAuth(id: string, maxAttempts = 20): Promise<string> {
  for (let i = 0; i < maxAttempts; i++) {
    const { data } = await client.get(`/documents/${id}`);
    if (data.status === 'AUTHORIZED') return data.accessKey;
    if (data.status === 'REJECTED') throw new Error('Rejected by SRI'); // fix payload, POST /documents/:id/retry, then poll again
    await new Promise(r => setTimeout(r, 3000));
  }
  throw new Error('Timeout waiting for authorization');
}

// Download RIDE
const rideResponse = await client.get(`/documents/${id}/ride`, {
  responseType: 'arraybuffer',
});
fs.writeFileSync('ride.pdf', rideResponse.data);

Códigos de error

Los errores se devuelven con el envoltorio { code, message }. El campo code es estable; úsalo para el manejo programático.

Estados HTTP comunes: 401 UNAUTHORIZED (API Key faltante o inválida), 403 FORBIDDEN (falta el scope), 404 NOT_FOUND, 402 para límites de plan o billing, 409 INVALID_STATE_TRANSITION.

Webhooks

FactuSync puede enviar eventos HTTP a tu servidor cuando el estado de un documento cambia.

Eventos disponibles

• document.authorized — El SRI autorizó el comprobante
• document.rejected — El SRI rechazó el comprobante
• document.cancelled — La anulación del comprobante fue confirmada por el SRI
• document.failed — El comprobante pasó a Dead-Letter Queue tras 5 reintentos
• document.notification.resent — Se reenvió la notificación del comprobante

Registrar un endpoint

curl -X POST https://api.factusync.jipsoft.com/webhooks \
  -H "X-API-Key: fsk_live_eyJ..." \
  -d '{
    "url": "https://your-system.com/webhooks/factusync",
    "events": ["document.authorized", "document.rejected"],
    "secret": "s3cr3t_very_long_32_bytes_minimum"
  }'

Verificar la firma

Cada llamada incluye el header X-FactuSync-Signature: sha256=<hmac>.

import { createHmac } from 'crypto';

function verifySignature(body: string, secret: string, header: string): boolean {
  const expected = 'sha256=' + createHmac('sha256', secret).update(body).digest('hex');
  return expected === header;
}

// Express.js
app.post('/webhooks/factusync', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-factusync-signature'] as string;
  if (!verifySignature(req.body.toString(), process.env.WEBHOOK_SECRET!, sig)) {
    return res.status(401).send('Invalid signature');
  }
  const event = JSON.parse(req.body.toString());
  console.log('Event:', event.event, event.documentId);
  res.sendStatus(200);
});

Reintentos automáticos

• Intento 1 — Inmediato
• Intento 2 — 30 segundos
• Intento 3 — 5 minutos
• Intento 4 — 30 minutos