RBS Ecosystem APIs

Welcome to the Red Broom Software ecosystem API documentation. This guide provides a unified entry point to all RBS services.

---

Services Overview

Service	Purpose	Base URL
Camino	CRM, marketing, OAuth2 SSO	https://camino.redbroomsoftware.com
Colectiva	Payments, subscriptions, billing	https://colectiva.redbroomsoftware.com
Constanza	Accounting, CFDI invoicing	https://constanza.redbroomsoftware.com

---

Authentication

All APIs support multiple authentication methods:

API Keys (Recommended for Server-to-Server)

Authorization: Bearer <your_api_key>
Content-Type: application/json

API keys are created in Colectiva with specific permissions:

• payments:* - Payment operations
• subscriptions:* - Subscription management
• wallet:* - Wallet operations
• ecosystem:* - Organization management
• developer_access - Developer support access

OAuth2 (For User-Context Operations)

Camino serves as the OAuth2 provider for the ecosystem.

Authorization URL: https://camino.redbroomsoftware.com/oauth/authorize
Token URL: https://camino.redbroomsoftware.com/oauth/token

Supports PKCE for public clients.

Session Cookies (Web Applications)

For browser-based applications using Firebase or Supabase auth.

---

Common Headers

Authorization: Bearer <api_key>
Content-Type: application/json
X-Ecosystem-Org-ID: eco_123       # Optional: scope to specific organization
X-App-Source: cosmos-pet          # Optional: identify calling application
X-Idempotency-Key: unique-id      # Recommended: for safe retries

---

OpenAPI Specifications

Full API references are available as OpenAPI 3.1.0 specifications:

• Camino API - CRM, leads, marketing campaigns, OAuth2
• Colectiva API - Payments, subscriptions, wallets, trust accounts
• Constanza API - Accounting, CFDI stamping, transactions

Viewing OpenAPI Specs

You can view these specs using:

• Swagger Editor - Paste the YAML content
• Redocly - Beautiful documentation view
• VS Code with OpenAPI extension

---

Quick Start Examples

Create a Payment (Colectiva)

const response = await fetch('https://colectiva.redbroomsoftware.com/api/payments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 1000.00,
    currency: 'MXN',
    method: 'card',
    description: 'Monthly subscription',
    customer_email: 'cliente@example.com'
  })
});

const { payment_id, status, checkout_url } = await response.json();

Stamp a CFDI (Constanza)

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',  // Ingreso
    receptor: {
      rfc: 'XAXX010101000',
      nombre: 'PUBLICO EN GENERAL',
      uso_cfdi: 'S01'
    },
    conceptos: [{
      descripcion: 'Servicios profesionales',
      cantidad: 1,
      valor_unitario: 1000.00,
      clave_prod_serv: '80101500'
    }]
  })
});

const { uuid, xml, pdf_url } = await response.json();

Get Lead Details (Camino)

const response = await fetch('https://camino.redbroomsoftware.com/api/leads/lead_123', {
  headers: {
    'Authorization': `Bearer ${API_KEY}`
  }
});

const lead = await response.json();

---

Error Handling

All APIs use consistent error response format:

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": {
    "field": "Additional context"
  }
}

Common Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Invalid or missing API key
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource doesn't exist
VALIDATION_ERROR	400	Invalid request data
RATE_LIMITED	429	Too many requests
INTERNAL_ERROR	500	Server error (retry with backoff)

---

Rate Limits

Service	Rate Limit	Burst
Colectiva	100 req/min	20 req/sec
Constanza	60 req/min	10 req/sec
Camino	120 req/min	30 req/sec

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200

---

Webhooks

For async operations, apps send webhooks to notify of events.

See Webhook Documentation for:

• Payload structure
• Event types
• Signature verification
• Retry policy

---

SDKs & Tools

Postman Collection

Coming soon - Pre-configured collection with all endpoints

TypeScript Types

Generated types available in each project's codebase:

• Camino: src/lib/types/database.types.ts
• Constanza: src/lib/types/

---

Support

• Technical Issues: Check project README files
• API Questions: Review OpenAPI specs
• Integration Help: See Integration Guide

---

Related Documentation

• Webhook Integration
• SSO/OAuth2 Flow
• Decision Events
• Ecosystem Architecture