FactuSync API Documentation

REST API to emit electronic vouchers authorized by Ecuador's SRI. XAdES-BES signature, retry queue, RIDE PDF and webhooks included.

Authentication

All requests must include the header X-API-Key: <API_KEY>.

API Keys are managed from the FactuSync dashboard.

• documents:write — Create documents
• documents:emit — Emit to SRI
• documents:read — Query documents and RIDE
• documents:ride — Download RIDE PDF
• cancellations:write — Request cancellations
• cancellations:approve — Approve cancellations
• validation:read — Validate RUC
• queue:read — Query emission queue
• queue:retry — Retry failed queue jobs
• webhooks:manage — Manage webhooks
• signature:manage — Manage the electronic signature (.p12): upload, rotate, and check certificate status

Environments

API keys use two prefixes:

• fsk_live_... → Production — Emits real documents to SRI
• fsk_test_... → Sandbox — SRI certification environment

Base URL

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

Emission flow

Document lifecycle

The states a document moves through from creation to SRI authorization.

Signature management flow (.p12)

Endpoints

Base: https://api.factusync.jipsoft.com — Tap an endpoint to see its required scope and a request/response example.

# 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
  }
}

Code examples

Create and emit an invoice (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..."

With 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`);

Check status and download 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);

Error codes

Errors are returned with the { code, message } envelope. The code field is stable; use it for programmatic handling.

Common HTTP statuses: 401 UNAUTHORIZED (missing or invalid API Key), 403 FORBIDDEN (missing scope), 404 NOT_FOUND, 402 for plan or billing limits, 409 INVALID_STATE_TRANSITION.

Webhooks

FactuSync can send HTTP events to your server when a document status changes.

Available events

• document.authorized — SRI authorized the voucher
• document.rejected — SRI rejected the voucher
• document.cancelled — The voucher annulment was confirmed by SRI
• document.failed — Voucher moved to Dead-Letter Queue after 5 retries
• document.notification.resent — The voucher notification was resent

Register an 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"
  }'

Verify the signature

Each call includes the 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);
});

Automatic retries

• Attempt 1 — Immediate
• Attempt 2 — 30 seconds
• Attempt 3 — 5 minutes
• Attempt 4 — 30 minutes