Constanza Accounting API

Constanza is the accounting, CFDI invoicing, and AI services hub for the RBS ecosystem.

Base URL: https://constanza.redbroomsoftware.com

Overview

Constanza provides:

CFDI 4.0 Stamping: SAT-compliant electronic invoicing
Multi-Tenant Accounting: Transaction recording, reconciliation
AI Expense Classification: Automatic categorization
Ecosystem Billing: Cross-app billing operations
Certificate Management: FIEL and CSD handling
Open Banking: Bank sync and transaction import

Authentication

http

Authorization: Bearer <api_key>
Content-Type: application/json
X-Ecosystem-Org-ID: eco_123  # Required for org-scoped operations

Key Endpoints

CFDI Stamping

Endpoint	Method	Description
`/api/cfdi/stamp`	POST	Stamp new CFDI
`/api/cfdi/:uuid`	GET	Get CFDI details
`/api/cfdi/:uuid/xml`	GET	Download XML
`/api/cfdi/:uuid/pdf`	GET	Download PDF
`/api/cfdi/:uuid/cancel`	POST	Cancel CFDI
`/api/cfdi/validate`	POST	Validate before stamping

Transactions

Endpoint	Method	Description
`/api/transactions`	GET	List transactions
`/api/transactions`	POST	Create transaction
`/api/transactions/:id`	GET	Get transaction
`/api/transactions/:id/classify`	POST	AI classification
`/api/transactions/bulk-classify`	POST	Batch AI classification

Certificates

Endpoint	Method	Description
`/api/certificates`	GET	List certificates
`/api/certificates`	POST	Upload certificate
`/api/certificates/:id/validate`	POST	Validate with SAT

Ecosystem Billing

Endpoint	Method	Description
`/api/billing/record`	POST	Record billable event
`/api/billing/invoice`	POST	Generate billing CFDI
`/api/billing/summary`	GET	Get billing summary

AI Services

Endpoint	Method	Description
`/api/ai/classify`	POST	Classify single transaction
`/api/ai/classify/batch`	POST	Batch classification
`/api/ai/suggest-account`	POST	Suggest accounting code

Code Examples

Stamp a CFDI (Ingreso)

typescript

const response = await fetch('https://constanza.redbroomsoftware.com/api/cfdi/stamp', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
    'X-Ecosystem-Org-ID': 'eco_123'
  },
  body: JSON.stringify({
    tipo_comprobante: 'I',  // I=Ingreso, E=Egreso, T=Traslado, P=Pago, N=Nomina
    serie: 'A',
    folio: '1001',
    fecha: '2026-01-26T12:00:00',
    forma_pago: '03',  // 03=Transferencia
    metodo_pago: 'PUE',  // PUE=Pago en una exhibicion
    moneda: 'MXN',

    emisor: {
      rfc: 'EMP123456789',
      nombre: 'Mi Empresa SA de CV',
      regimen_fiscal: '601'
    },

    receptor: {
      rfc: 'XAXX010101000',
      nombre: 'PUBLICO EN GENERAL',
      uso_cfdi: 'S01',  // Sin efectos fiscales
      domicilio_fiscal_receptor: '06600',
      regimen_fiscal_receptor: '616'
    },

    conceptos: [
      {
        clave_prod_serv: '80101500',  // Servicios de consultoría
        cantidad: 1,
        clave_unidad: 'E48',  // Unidad de servicio
        unidad: 'Servicio',
        descripcion: 'Consultoría empresarial - Enero 2026',
        valor_unitario: 10000.00,
        importe: 10000.00,
        objeto_imp: '02',  // Si objeto de impuesto
        impuestos: {
          traslados: [
            {
              base: 10000.00,
              impuesto: '002',  // IVA
              tipo_factor: 'Tasa',
              tasa_o_cuota: 0.16,
              importe: 1600.00
            }
          ]
        }
      }
    ]
  })
});

const result = await response.json();

if (result.success) {
  const { uuid, xml_url, pdf_url, cadena_original, sello_sat } = result;
  console.log(`CFDI stamped: ${uuid}`);
  console.log(`XML: ${xml_url}`);
  console.log(`PDF: ${pdf_url}`);
} else {
  console.error(`Stamping failed: ${result.error}`);
  // result.sat_errors contains specific SAT validation errors
}

Stamp a Payment CFDI (Complemento de Pago)

typescript

const response = await fetch('https://constanza.redbroomsoftware.com/api/cfdi/stamp', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
    'X-Ecosystem-Org-ID': 'eco_123'
  },
  body: JSON.stringify({
    tipo_comprobante: 'P',  // Pago
    serie: 'P',
    folio: '501',

    emisor: {
      rfc: 'EMP123456789',
      nombre: 'Mi Empresa SA de CV',
      regimen_fiscal: '601'
    },

    receptor: {
      rfc: 'CLI987654321',
      nombre: 'Cliente SA de CV',
      uso_cfdi: 'CP01',
      domicilio_fiscal_receptor: '03100',
      regimen_fiscal_receptor: '601'
    },

    pagos: [
      {
        fecha_pago: '2026-01-25T10:30:00',
        forma_pago: '03',  // Transferencia
        moneda: 'MXN',
        monto: 11600.00,
        num_operacion: 'REF123456',

        documentos_relacionados: [
          {
            id_documento: 'ABC12345-1234-1234-1234-123456789012',  // UUID del CFDI original
            serie: 'A',
            folio: '1001',
            moneda: 'MXN',
            num_parcialidad: 1,
            imp_saldo_ant: 11600.00,
            imp_pagado: 11600.00,
            imp_saldo_insoluto: 0.00,
            objeto_imp: '02',
            equivalencia: 1
          }
        ]
      }
    ]
  })
});

AI Expense Classification

typescript

// Single classification
const response = await fetch('https://constanza.redbroomsoftware.com/api/ai/classify', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
    'X-Ecosystem-Org-ID': 'eco_123'
  },
  body: JSON.stringify({
    description: 'UBER EATS *2847293 CDMX',
    amount: 185.50,
    date: '2026-01-25',
    merchant: 'UBER EATS'
  })
});

const {
  category,        // 'Alimentos y bebidas'
  subcategory,     // 'Delivery'
  sat_code,        // '90101501'
  confidence,      // 0.94
  account_code,    // '6010' (suggested account)
  is_deductible,   // false (food delivery typically not deductible)
  notes            // 'Gasto personal - no deducible para empresa'
} = await response.json();

Batch Classification

typescript

const response = await fetch('https://constanza.redbroomsoftware.com/api/ai/classify/batch', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
    'X-Ecosystem-Org-ID': 'eco_123'
  },
  body: JSON.stringify({
    transactions: [
      { id: 'txn_1', description: 'OXXO CDMX 1234', amount: 45.00 },
      { id: 'txn_2', description: 'AMAZON.COM.MX', amount: 1299.00 },
      { id: 'txn_3', description: 'CFE SUMINISTRADOR', amount: 850.00 },
      { id: 'txn_4', description: 'TELCEL RECARGA', amount: 200.00 }
    ]
  })
});

const { results, usage } = await response.json();
// results: Array of classifications keyed by transaction id
// usage: { tokens: 2500, credits_used: 4 }

Record Ecosystem Billing Event

typescript

// When an app uses a billable service
const response = await fetch('https://constanza.redbroomsoftware.com/api/billing/record', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    ecosystem_org_id: 'eco_123',
    app: 'cosmos-pet',
    service: 'cfdi_stamping',
    quantity: 1,
    unit_price: 3.50,  // MXN per CFDI
    reference: 'cfdi_uuid_here',
    metadata: {
      tipo_comprobante: 'I',
      total: 11600.00
    }
  })
});

// Generate monthly billing CFDI
const invoiceRes = await fetch('https://constanza.redbroomsoftware.com/api/billing/invoice', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    ecosystem_org_id: 'eco_123',
    period: '2026-01',
    include_apps: ['cosmos-pet', 'constanza'],
    payment_method: '03'  // Transfer
  })
});

const { cfdi_uuid, total, line_items } = await invoiceRes.json();

Certificate Management

Upload CSD Certificate

typescript

const formData = new FormData();
formData.append('cer_file', cerFileBlob, 'certificate.cer');
formData.append('key_file', keyFileBlob, 'private.key');
formData.append('password', 'certificate_password');

const response = await fetch('https://constanza.redbroomsoftware.com/api/certificates', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'X-Ecosystem-Org-ID': 'eco_123'
  },
  body: formData
});

const { certificate_id, rfc, serial_number, valid_from, valid_until } = await response.json();

Webhooks Sent

Event	Trigger
`cfdi.stamped`	CFDI successfully stamped
`cfdi.cancelled`	CFDI cancelled
`cfdi.stamp_failed`	Stamping failed
`transaction.created`	New transaction recorded
`transaction.classified`	AI classification complete
`billing.invoice_created`	Billing CFDI generated

Webhook Payload Example

json

{
  "event": "cfdi.stamped",
  "timestamp": "2026-01-26T12:00:00Z",
  "data": {
    "uuid": "ABC12345-1234-1234-1234-123456789012",
    "tipo_comprobante": "I",
    "serie": "A",
    "folio": "1001",
    "total": 11600.00,
    "receptor_rfc": "XAXX010101000",
    "xml_url": "https://...",
    "pdf_url": "https://..."
  },
  "org_id": "eco_123"
}

SAT Error Codes

Common SAT validation errors:

Code	Description
`CFDI33101`	RFC receptor inválido
`CFDI33102`	Uso de CFDI no corresponde con régimen fiscal
`CFDI33103`	Clave de producto/servicio inválida
`CFDI33104`	Cálculo de impuestos incorrecto
`CFDI33105`	Fecha fuera de rango permitido
`CFDI40101`	CP del receptor no coincide con SAT

Rate Limits

Endpoint Type	Limit
CFDI stamping	60/min
AI classification	100/min
Read operations	300/min

Constanza Accounting API ​

Overview ​

Authentication ​

Key Endpoints ​

CFDI Stamping ​

Transactions ​

Certificates ​

Ecosystem Billing ​

AI Services ​

Code Examples ​

Stamp a CFDI (Ingreso) ​

Stamp a Payment CFDI (Complemento de Pago) ​

AI Expense Classification ​

Batch Classification ​

Record Ecosystem Billing Event ​

Certificate Management ​

Upload CSD Certificate ​

Webhooks Sent ​

Webhook Payload Example ​

SAT Error Codes ​

Rate Limits ​

Related ​

Constanza Accounting API

Overview

Authentication

Key Endpoints

CFDI Stamping

Transactions

Certificates

Ecosystem Billing

AI Services

Code Examples

Stamp a CFDI (Ingreso)

Stamp a Payment CFDI (Complemento de Pago)

AI Expense Classification

Batch Classification

Record Ecosystem Billing Event

Certificate Management

Upload CSD Certificate

Webhooks Sent

Webhook Payload Example

SAT Error Codes

Rate Limits

Related