Caracol Consumer API

Caracol exposes a Consumer API for integration with Cookie Monster portal.

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

---

Overview

The Consumer API allows Cookie Monster to:

• Link consumers by phone/email across tenants
• Fetch portal branding configuration
• Display product catalogs
• Show order history
• Process invoice requests

---

Authentication

All requests must include:

X-API-Key: <COOKIE_MONSTER_API_KEY>
X-Source-App: cookie-monster
Content-Type: application/json

The API key is verified against the COOKIE_MONSTER_API_KEY environment variable.

---

Consumer Linking

Find by Phone

Find consumer accounts linked to a phone number across all portal-enabled tenants.

GET /api/consumer/link/by-phone?phone={phone}

Query Parameters:

Parameter	Type	Required	Description
phone	string	Yes	Phone number (any format)

Phone Normalization:

• 5512345678 → 5512345678 (10 digits)
• +52 55 1234 5678 → 5512345678 (strips country code)
• 521 55 1234 5678 → 5512345678 (strips mobile prefix)

Response:

{
  "matches": [
    {
      "tenantId": "tenant-abc123",
      "tenantName": "Tacos El Rey",
      "thirdPartyId": "tp-xyz789"
    }
  ]
}

Find by Email

GET /api/consumer/link/by-email?email={email}

Same response format as phone lookup.

---

Portal Branding

Get Branding

Fetch portal configuration for a tenant.

GET /api/consumer/tenants/{tenantId}/branding

Response:

{
  "tenantId": "tenant-abc123",
  "name": "Tacos El Rey",
  "slug": "tacos-el-rey",
  "branding": {
    "logoUrl": "https://storage.../logo.png",
    "brandColor": "#7C3AED",
    "welcomeMessage": "Bienvenido a nuestro portal",
    "tagline": "Los mejores tacos de la ciudad"
  },
  "contact": {
    "phone": "+52 55 1234 5678",
    "email": "contacto@tacoselrey.com",
    "whatsapp": "+52 55 1234 5678"
  },
  "features": {
    "showCatalog": true,
    "allowInvoiceRequests": true,
    "showOrderHistory": true
  }
}

---

Product Catalog

List Products

Get active products for a tenant.

GET /api/consumer/tenants/{tenantId}/catalog

Query Parameters:

Parameter	Type	Default	Description
category	string	-	Filter by category ID
limit	number	50	Max products to return

Response:

{
  "products": [
    {
      "id": "prod-123",
      "name": "Taco al Pastor",
      "description": "Delicioso taco con piña",
      "price": 25.00,
      "imageUrl": "https://storage.../taco.jpg",
      "category": "Tacos",
      "isActive": true
    }
  ],
  "total": 42
}

Get Single Product

GET /api/consumer/tenants/{tenantId}/catalog/{productId}

---

Order History

List Orders

Get order history for a consumer.

GET /api/consumer/tenants/{tenantId}/consumers/{consumerId}/orders

Query Parameters:

Parameter	Type	Default	Description
limit	number	50	Max orders to return

Response:

{
  "orders": [
    {
      "id": "sale-abc123",
      "dailySaleNumber": 42,
      "date": "2026-01-28T14:30:00Z",
      "total": 350.00,
      "items": [
        {
          "name": "Taco al Pastor",
          "quantity": 5,
          "unitPrice": 25.00,
          "total": 125.00
        }
      ],
      "paymentMethod": "card",
      "hasInvoice": false,
      "invoiceRequested": false
    }
  ]
}

---

Invoice History

List Invoices

Get invoices for a consumer.

GET /api/consumer/tenants/{tenantId}/consumers/{consumerId}/invoices

Response:

{
  "invoices": [
    {
      "id": "cfdi-xyz789",
      "uuid": "ABC12345-ABCD-1234-ABCD-123456789ABC",
      "folio": "A-1234",
      "date": "2026-01-28T15:00:00Z",
      "total": 350.00,
      "pdfUrl": "https://constanza.../invoice.pdf",
      "xmlUrl": "https://constanza.../invoice.xml"
    }
  ]
}

---

Invoice Requests

Create Invoice Request

Request an invoice for a past order.

POST /api/consumer/tenants/{tenantId}/invoice-requests

Request Body:

{
  "orderId": "sale-abc123",
  "billingData": {
    "rfc": "XAXX010101000",
    "razonSocial": "PUBLICO EN GENERAL",
    "email": "cliente@example.com",
    "usoCfdi": "G03",
    "regimenFiscal": "616",
    "codigoPostal": "06600"
  }
}

Required Fields:

Field	Description
rfc	Tax ID (RFC)
razonSocial	Legal name
email	Email for invoice delivery
usoCfdi	CFDI usage code
regimenFiscal	Tax regime code
codigoPostal	Postal code

Response:

{
  "success": true,
  "requestId": "req-abc123"
}

Error Cases:

• 400 - Order already has invoice
• 400 - Missing required billing fields
• 404 - Order not found or doesn't belong to tenant

---

Error Handling

All errors follow the standard format:

{
  "error": "Error message",
  "success": false
}

Error Codes

HTTP Status	Error	Description
401	Unauthorized	Invalid API key or X-Source-App
400	Phone number required	Missing phone parameter
400	Datos incompletos	Missing orderId or billingData
400	Esta orden ya tiene factura	Order already invoiced
404	Orden no encontrada	Order doesn't exist or wrong tenant
500	Internal server error	Database or server error

---

Related Documentation

• Cookie Monster Portal - Consumer portal that calls this API
• Constanza CFDI API - Invoice stamping service
• Ecosystem Status - Integration status matrix