Para Desarrolladores

API, Webhooks y MCP de FacturaCR

Integre su tienda, CRM o asistente de IA con la facturación electrónica de Costa Rica. Funciona en modo demostración con los datos de ejemplo ya cargados.

Autenticación

Cree una clave en el panel (API y Webhooks, solo dueño o administrador). Se muestra una sola vez. Envíela en cada petición; las claves pueden ser de solo lectura o de lectura y escritura.

Authorization: Bearer fcr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Endpoints de la API v1

GET    /api/v1/clientes?pagina=1&por_pagina=20&q=texto
GET    /api/v1/clientes/{id}
POST   /api/v1/clientes
PATCH  /api/v1/clientes/{id}

GET    /api/v1/productos      (mismos parámetros)
POST   /api/v1/productos
PATCH  /api/v1/productos/{id}

GET    /api/v1/documentos?estado=aceptado
GET    /api/v1/documentos/{id | clave de 50 dígitos}
POST   /api/v1/documentos     (emite; los comprobantes no se editan)

GET    /api/v1/metricas       (ventas, IVA y por cobrar del mes en colones)

Las listas responden { datos, paginacion: { pagina, por_pagina, total, paginas } }. por_pagina máximo 100.

Ejemplos con curl

curl https://SU-DOMINIO/api/v1/clientes?q=Soda -H "Authorization: Bearer $CLAVE"

curl -X POST https://SU-DOMINIO/api/v1/clientes -H "Authorization: Bearer $CLAVE" -H "Content-Type: application/json" \
  -d '{"nombre":"Soda La Esquina S.A.","tipo_identificacion":"02","identificacion":"3101123456","correo":"facturas@soda.cr","telefono":"22223333","dias_credito":30}'

curl -X PATCH https://SU-DOMINIO/api/v1/productos/ID -H "Authorization: Bearer $CLAVE" -H "Content-Type: application/json" \
  -d '{"precio":12500}'

curl -X POST https://SU-DOMINIO/api/v1/documentos -H "Authorization: Bearer $CLAVE" -H "Content-Type: application/json" -d '{
  "tipo":"04","cliente_id":null,"condicion_venta":"01","medio_pago":"01","moneda":"CRC","tipo_cambio":1,
  "lineas":[{"cabys":"8314100000000","descripcion":"Servicio","unidad":"Sp","cantidad":1,"precio_unitario":10000,
    "descuento":0,"tarifa":13,"tarifa_codigo":"08","exoneracion":0,"es_servicio":true}]}'

Errores

400 JSON o identificador inválido · regla de negocio
401 Falta la clave o está revocada
403 La clave no tiene permiso de escritura
404 Recurso o registro no encontrado
405 Operación no permitida (editar un comprobante)
422 Datos inválidos → { "error": "Datos inválidos", "detalle": [{ "campo": "correo", "mensaje": "..." }] }

Webhooks Salientes

Eventos: documento.creado, documento.aceptado, documento.rechazado, cliente.creado, cliente.actualizado, producto.creado, producto.actualizado, webhook.recibido. Se reintenta hasta 3 veces ante errores 5xx, 429 o de red; cada entrega queda en el registro del panel.

POST https://su-sistema.com/webhook
X-Event: documento.aceptado
X-Signature: sha256=5f2c...e9

{
  "evento": "documento.aceptado",
  "fecha": "2026-10-05T14:03:11.000Z",
  "datos": { "id": "…", "clave": "50605102600310112345600100001010000000123100000001", "estado": "aceptado" }
}

Cómo Verificar la Firma

// Node.js
import crypto from "node:crypto";
const esperada = "sha256=" + crypto.createHmac("sha256", SECRETO).update(cuerpoCrudo).digest("hex");
const valida = crypto.timingSafeEqual(Buffer.from(esperada), Buffer.from(req.headers["x-signature"]));

# Python
import hmac, hashlib
esperada = "sha256=" + hmac.new(SECRETO.encode(), cuerpo_crudo, hashlib.sha256).hexdigest()
valida = hmac.compare_digest(esperada, request.headers["X-Signature"])

Webhooks Entrantes

Envíe eventos a FacturaCR firmando el cuerpo con el secreto de entrada que aparece en el panel. Cada evento queda registrado y dispara webhook.recibido.

CUERPO='{"evento":"pedido.pagado","pedido":"A-1001","monto":25000}'
FIRMA=$(printf '%s' "$CUERPO" | openssl dgst -sha256 -hmac "$SECRETO_ENTRADA" -hex | sed 's/^.* //')
curl -X POST "https://SU-DOMINIO/api/v1/webhooks/in?empresa=ID_EMPRESA" \
  -H "Content-Type: application/json" -H "X-Signature: sha256=$FIRMA" -d "$CUERPO"

Conectar el MCP a Claude

El servidor MCP está en /mcp (HTTP) y usa la misma clave API. Herramientas: listar, buscar, ver, crear, actualizar y resumen_metricas. Con una clave de solo lectura, crear y actualizar quedan bloqueadas.

{
  "mcpServers": {
    "facturacr": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://SU-DOMINIO/mcp", "--header", "Authorization: Bearer ${FACTURACR_CLAVE}"],
      "env": { "FACTURACR_CLAVE": "fcr_su_clave" }
    }
  }
}

Pegue esto en claude_desktop_config.json (Claude Desktop → Ajustes → Desarrollador) y reinicie Claude. En clientes con soporte HTTP directo use la URL /mcp con la cabecera Authorization.

curl -X POST https://SU-DOMINIO/mcp -H "Authorization: Bearer $CLAVE" -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"resumen_metricas","arguments":{}}}'