# Certificación para producción Source: https://docs.cobrix.co/api-guides/certification Lista de aceptación antes de usar datos y pagos reales ## Matriz mínima en sandbox Autenticación válida, llave revocada y scope insuficiente Firma válida, firma alterada y timestamp vencido Idempotencia repetida y conflicto por cuerpo diferente Creación, consulta, actualización y cancelación de documentos de cobro Pago aplicado, tasa certificada y consulta del resultado Webhook válido, firma inválida, duplicado y reintento Rate limiting y respeto de `Retry-After` ## Requisitos del receptor de webhooks * HTTPS con certificado válido. * Conservación del cuerpo crudo. * Comparación timing-safe de firmas. * Respuesta rápida antes de ejecutar lógica pesada. * Deduplicación durable por ID o combinación de evento y recurso. * Monitoreo de errores y capacidad de reprocesar eventos. ## Paso a producción 1. Crea el partner y la llave nuevamente en producción. 2. Replica únicamente los scopes aprobados. 3. Configura el webhook productivo y su secreto propio. 4. Cambia `COBRIX_BASE_URL` a `https://api.cobrix.co/api`. 5. Ejecuta un smoke test de bajo monto y verifica API, ledger, checkout y webhook. 6. Rota cualquier credencial usada durante la certificación si fue compartida fuera del gestor de secretos. # Elegir la API correcta Source: https://docs.cobrix.co/api-guides/choose-api Decide por capacidad, contrato y efecto financiero No elijas por el nombre del recurso. Elige por el flujo que controla tu sistema y por la unidad monetaria que ya maneja. Usa la **API de integraciones** si necesitas upsert de clientes y documentos, filtros por cursor, links para varios documentos o pagos dirigidos a cobros concretos. Usa la **API pública de documentos de cobro** si quieres crear un documento y recibir inmediatamente su cobro vigente con un contrato compacto en `snake_case`. Usa `verified-payments` cuando tu sistema confirma un pago externo y Cobrix debe aplicarlo al ledger. La API pública de documentos también acepta `PAID_FROM_PROVIDER`, pero únicamente para el saldo completo. Configura webhooks después de elegir la API. No mezcles la fórmula de firma general con la firma específica de documentos públicos. ## Comparación directa | Decisión | API de integraciones | API pública de documentos de cobro | | --------------- | -------------------------------------------------- | -------------------------------------------------------------- | | Base | `/integrations/v1/{companyId}` | `/v1/invoices` | | Forma de campos | `camelCase` | `snake_case` | | Montos | Unidades menores: `2025` = USD 20,25 | Unidades mayores: `20.25` = USD 20,25 | | Seguridad | Bearer + timestamp + firma HMAC | Bearer | | Idempotencia | `Idempotency-Key` en todos los `POST` | `x-idempotency` al crear | | Cliente | Recurso explícito con ID externo | Resolución automática por la cédula/RIF enviada en `reference` | | Pagos | Aplicación por documentos; admite tasa certificada | Pago completo; no admite parcialidad | ## Recorridos recomendados Crea o actualiza la identidad externa. Envía líneas y montos en unidades menores. Selecciona uno o varios documentos abiertos. Procesa pago y aplicación financiera de forma idempotente. Envía la cédula o RIF en `reference`, la identidad del documento en `provider_id` y el monto en unidades mayores. Usa `payment.payment_link` devuelto por Cobrix. Un `PUT` reemplaza el checkout y ajusta el ledger. Recibe `invoice.paid` o anula con `DELETE`. Reporta el pago por `verified-payments` si trabajas con documentos sincronizados. Para un documento público usa `PAID_FROM_PROVIDER` con `provider_payment_id`. Nunca envíes un monto superior al saldo abierto. `/v1/invoices` crea o reutiliza automáticamente al cliente dentro de la empresa de la API key. El portal busca por la identidad fiscal interna y muestra todos sus documentos vinculados; no requiere un request adicional de clientes ni un campo nuevo. No copies payloads entre ambas APIs. Los nombres, unidades, autenticación, idempotencia y errores son contratos distintos. # Cobrix para desarrolladores Source: https://docs.cobrix.co/api-guides/developer-platform Integra clientes, documentos de cobro, pagos y webhooks con Cobrix
Cobrix Developer Platform

De tu sistema al cobro, sin piezas ocultas.

Sincroniza clientes y cartera, genera links, registra pagos verificados o usa la API compacta de documentos de cobro. Cada capacidad está organizada igual que en el drawer de permisos de tu empresa.

18operaciones públicas
12scopes de integración
2protocolos de webhooks
## Empieza por la capacidad que necesitas
Identidades externas vinculadas al `source` de la llave. Seis endpoints compactos para documentos y checkout. Upsert, consulta y anulación auditada de documentos. Sesiones de pago para documentos abiertos seleccionados. Pagos verificados, consultas y tasas certificadas. Requests, errores y contexto operativo visibles en el panel. `whatsapp_events:read` · tablero por semana, mes o fechas, con histórico y confirmaciones de la empresa.
## APIs públicas, una sola credencial Consulta confirmaciones y totales con Bearer y `whatsapp_events:read`. **Endpoint:** `GET /api/v1/whatsapp/events` · empresa obtenida de la llave. Usa `report.summary` para tarjetas y `report.daily` para el gráfico. Filtra con `dateFrom` y `dateTo`; consulta el [ejemplo completo de tablero y períodos](/api-guides/whatsapp-daily). Úsala para sincronización bidireccional de clientes, documentos, links y pagos. Requiere Bearer, firma HMAC y `Idempotency-Key` en cada `POST`. **Base:** `/api/integrations/v1/{companyId}` · **Montos:** unidades menores. Úsala cuando el sistema externo ya trabaja con un contrato compacto de documentos de cobro. Requiere Bearer y `x-idempotency` al crear. **Base:** `/api/v1/invoices` · **Montos:** unidades mayores de la moneda de la empresa. Recibe cambios de estado de forma asíncrona. Cobrix ofrece un protocolo general y otro específico para documentos públicos; cada uno tiene su propia fórmula de firma.
Compara casos de uso, unidades monetarias, seguridad y efectos financieros antes de implementar.
# Idempotencia Source: https://docs.cobrix.co/api-guides/idempotency Reintentos seguros en las APIs públicas de Cobrix La idempotencia evita duplicar clientes, documentos, pagos y asientos financieros cuando una solicitud se repite por timeout o pérdida de conexión. ## API de integraciones Todos los `POST` bajo `/integrations/v1` requieren: ```http theme={null} Idempotency-Key: 2cf0b8d1-3388-47ea-8b67-bc11e7de4efe ``` La clave se almacena por empresa, llave, método y ruta. El mismo cuerpo reproduce la respuesta original; reutilizarla con un cuerpo diferente devuelve un conflicto. ## API pública de documentos de cobro La creación usa un header distinto: ```http theme={null} x-idempotency: 2cf0b8d1-3388-47ea-8b67-bc11e7de4efe ``` * Misma llave y mismo cuerpo: devuelve el documento original con `201`. * Misma llave y cuerpo diferente: `409 idempotency_error`. * Header ausente: `409 idempotency_error`. * Con `provider_id`, la identidad del documento es `provider + provider_id`. * Sin `provider_id`, Cobrix usa `provider + sha256(x-idempotency)`. * Dos documentos del mismo cliente deben usar un `provider_id` o una clave de idempotencia diferente. ## Recomendaciones 1. Genera una clave UUID por operación de negocio, no por intento HTTP. 2. Conserva la clave hasta recibir una respuesta definitiva. 3. Reintenta timeouts y errores `5xx` con backoff exponencial. 4. No reutilices una clave para otro documento o pago. 5. Conserva exactamente el mismo cuerpo serializado al reintentar requests firmados. # Firma de solicitudes Source: https://docs.cobrix.co/api-guides/request-signing HMAC-SHA256 para la API de integraciones Además del Bearer, cada request a `/integrations/v1` debe incluir una firma HMAC-SHA256 calculada con la misma llave API. ## Headers ```http theme={null} Cobrix-Timestamp: 1784044800 Cobrix-Signature: v1=HEXADECIMAL_HMAC_SHA256 ``` `Cobrix-Timestamp` usa segundos Unix y debe estar dentro de una ventana de cinco minutos. ## Cadena firmada ```text theme={null} {timestamp}.{METHOD}.{path_with_query}.{raw_body} ``` * `METHOD` en mayúsculas. * `path_with_query` comienza en `/integrations/v1` e incluye el query string en su orden original. * `raw_body` es el cuerpo exacto enviado. En `GET` es una cadena vacía. * La firma se envía como `v1={hex}`. ```javascript Node.js theme={null} import crypto from 'node:crypto' function signRequest({ secret, timestamp, method, path, rawBody = '' }) { const payload = `${timestamp}.${method.toUpperCase()}.${path}.${rawBody}` const signature = crypto .createHmac('sha256', secret) .update(payload) .digest('hex') return `v1=${signature}` } ``` ```python Python theme={null} import hashlib, hmac def sign_request(secret, timestamp, method, path, raw_body=''): payload = f'{timestamp}.{method.upper()}.{path}.{raw_body}' digest = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest() return f'v1={digest}' ``` ## Errores de firma | Código | Causa | | ---------------------------- | ---------------------------------------------- | | `missing_timestamp` | No se envió `Cobrix-Timestamp`. | | `timestamp_out_of_tolerance` | El timestamp está fuera de cinco minutos. | | `missing_signature` | No se envió una firma `v1`. | | `invalid_signature` | El método, ruta, cuerpo o secreto no coincide. | Firma el JSON antes de enviarlo y usa ese mismo texto como body. Volver a serializarlo puede cambiar espacios u orden y producir una firma inválida. # Reporte de WhatsApp Source: https://docs.cobrix.co/api-guides/whatsapp-daily Ejemplos por semana, mes y rango de fechas; tarjetas, gráfico y confirmaciones con una sola llamada Usa **`GET /api/v1/whatsapp/events`** con la llave de la empresa y el permiso `whatsapp_events:read`. Esta única respuesta contiene el reporte completo y su detalle paginado. Cobrix obtiene la empresa de la llave; no necesitas un token de Meta ni enviar `companyId`. ## Primera consulta ```bash theme={null} curl --get 'https://api.cobrix.co/api/v1/whatsapp/events' \ --header "Authorization: Bearer $COBRIX_API_KEY" \ --data-urlencode 'dateFrom=2026-09-01T00:00:00-04:00' \ --data-urlencode 'dateTo=2026-09-10T23:59:59.999-04:00' \ --data-urlencode 'page=1' \ --data-urlencode 'limit=20' ``` ## Construye el tablero * **Tarjetas:** `report.summary.sent`, `delivered`, `read` y `failed`. * **Gráfico y tabla diaria:** `report.daily`, ordenado por fecha ascendente. * **Detalle de confirmaciones:** `events`, con `page`, `limit` y `totalPages`. El reporte incluye las estadísticas importadas de Meta y las confirmaciones disponibles en una sola serie. No necesitas combinar fuentes ni consultar otro endpoint. `report.history` indica la disponibilidad y las cifras del histórico incluido, como respaldo del reporte. ### Ejemplo: tablero de una empresa con histórico Para el período **14 de agosto a 10 de septiembre de 2026**, el siguiente ejemplo muestra 4.256 enviados y 4.198 entregados. Usa la llave de la empresa correspondiente; son cifras de ejemplo para ese período, no totales actuales de todas las empresas. | Tarjeta | Valor | Campo | | ---------- | ----- | -------------------------- | | Enviados | 4.256 | `report.summary.sent` | | Entregados | 4.198 | `report.summary.delivered` | | Leídos | — | `report.summary.read` | | Fallidos | — | `report.summary.failed` | Respuesta completa del mismo endpoint: ```json theme={null} { "coverage": { "status": "partial", "unit": "events", "attribution": "confirmed" }, "events": [], "summary": { "read": 0, "sent": 0, "total": 0, "failed": 0, "delivered": 0 }, "report": { "daily": [ { "date": "2026-09-04", "read": null, "sent": 4, "failed": null, "source": "meta_analytics", "delivered": 4 }, { "date": "2026-09-06", "read": null, "sent": 1, "failed": null, "source": "meta_analytics", "delivered": 1 }, { "date": "2026-09-07", "read": null, "sent": 2863, "failed": null, "source": "meta_analytics", "delivered": 2814 }, { "date": "2026-09-08", "read": null, "sent": 13, "failed": null, "source": "meta_analytics", "delivered": 26 }, { "date": "2026-09-09", "read": null, "sent": 0, "failed": null, "source": "meta_analytics", "delivered": 2 }, { "date": "2026-09-10", "read": null, "sent": 1375, "failed": null, "source": "meta_analytics", "delivered": 1351 } ], "history": { "sent": 4256, "delivered": 4198, "availability": "available" }, "summary": { "read": null, "sent": 4256, "failed": null, "delivered": 4198 }, "timezone": "America/Caracas" }, "page": 1, "limit": 20, "totalPages": 0 } ``` **`events: []` no contradice las tarjetas.** En este ejemplo hay estadísticas históricas agregadas, pero no confirmaciones individuales recuperadas para ese período. El `summary` original cuenta ese detalle y permanece en cero; las tarjetas usan **`report.summary`**. No sumes `summary` ni `report.history` a `report.summary`: el reporte ya está combinado. ## Contrato y significado de las cifras El `summary` original sigue contando **eventos almacenados**, incluidos callbacks repetidos. Paginar no cambia sus totales. `report.summary` cuenta una observación por `messageId` y estado dentro del filtro, más el histórico que corresponda. Un mensaje puede tener varios estados: no sumes enviados y entregados como mensajes distintos. Para evitar duplicar cifras, un día importado sustituye las observaciones de envío y entrega del **mismo número emisor y empresa**. Se utiliza la fecha del estado informada por Meta para detectar la superposición, o la recepción si falta esa fecha. Las observaciones de otros emisores o empresas se conservan. Una estadística histórica no crea destinatarios, `messageId` ni eventos ficticios. Los días observados se agrupan por recepción en Cobrix. Los importados corresponden al día estadístico de Meta. Ambos se muestran en `America/Caracas`; `source` identifica `events`, `meta_analytics` o `mixed`. La serie contiene días con datos; un día ausente no prueba que no hubo envíos. `null` significa información no disponible. Si el histórico no incluye lecturas o fallos, esos totales permanecen `null`; no se presentan como cero. Las entregas diarias pueden superar los envíos por entregas de mensajes anteriores. La diferencia entre ambas cifras no demuestra fallos. ## Esta semana, este mes o un rango de fechas La API recibe **`dateFrom` y `dateTo`**. Los botones «Esta semana» y «Este mes» son opciones del tablero: tu aplicación calcula las fechas y las envía. No existen parámetros `week`, `month` ni `period`. Por ejemplo, si hoy fuera **12 de septiembre de 2026**, con semanas de lunes a domingo y calendario de `America/Caracas`: | Opción del tablero | `dateFrom` | `dateTo` | | ---------------------------- | --------------------------- | ------------------------------- | | Hoy | `2026-09-12T00:00:00-04:00` | `2026-09-12T23:59:59.999-04:00` | | Esta semana | `2026-09-07T00:00:00-04:00` | `2026-09-13T23:59:59.999-04:00` | | Este mes | `2026-09-01T00:00:00-04:00` | `2026-09-30T23:59:59.999-04:00` | | Rango del ejemplo histórico | `2026-08-14T00:00:00-04:00` | `2026-09-10T23:59:59.999-04:00` | | Todo el histórico disponible | Omitir | Omitir | El final de semana o mes puede ser posterior a hoy: la respuesta sólo contiene datos disponibles al consultar. Para un período **hasta hoy**, usa el final del día actual; para cortar en este instante, usa su fecha y hora exactas, teniendo en cuenta la exclusión de días históricos parciales. ```bash theme={null} # Esta semana en el ejemplo: lunes 7 a domingo 13 de septiembre. curl --get 'https://api.cobrix.co/api/v1/whatsapp/events' \ --header "Authorization: Bearer $COBRIX_API_KEY" \ --data-urlencode 'dateFrom=2026-09-07T00:00:00-04:00' \ --data-urlencode 'dateTo=2026-09-13T23:59:59.999-04:00' \ --data-urlencode 'limit=20' ``` Para consultar el mes, reemplaza ambas fechas por las de «Este mes». Para un rango personalizado, usa las fechas del selector. Se admite enviar sólo uno de los límites; el extremo omitido queda sin restricción. Usa `--data-urlencode` o `URLSearchParams` para codificar correctamente las fechas y teléfonos. ## Filtros | Parámetro | Uso | | -------------------- | --------------------------------------------------------------------------------------------------- | | `dateFrom`, `dateTo` | Fechas ISO 8601 con segundos y zona horaria, límites inclusivos. Un rango invertido devuelve `422`. | | `status` | `sent`, `delivered`, `read` o `failed`. Omitir para todos. | | `phone` | Coincidencia parcial del teléfono, hasta 64 caracteres. | | `page` | Página del detalle, desde 1. | | `limit` | Eventos por página: 20 por defecto, máximo 100. | Conserva los [filtros y errores originales](/api-reference/categories/whatsapp): `dateFrom`, `dateTo`, `phone`, `status`, `page` y `limit`. Las fechas requieren zona horaria y los límites son inclusivos sobre la recepción de los eventos. Sin fechas, consulta el histórico disponible. La página sólo afecta al detalle; el reporte cubre todo el resultado. El histórico sólo permite días completos y estados enviados o entregados. Con `phone`, `read` o `failed`, el reporte utiliza las confirmaciones individuales disponibles y marca `report.history.availability: "unsupported_filter"`. Un estado seleccionado deja los demás contadores del reporte en cero. Para incluir un día histórico completo, consulta desde `00:00:00-04:00` hasta `23:59:59.999-04:00`. Los días históricos parciales se omiten y se indica `partial_days_excluded`; las confirmaciones individuales dentro del intervalo permanecen disponibles. `no_data` indica que no hay histórico importado para ese filtro. La página, los totales y el reporte se obtienen de la misma instantánea de lectura. El límite sigue siendo **60 solicitudes por minuto por llave**; respeta `Retry-After` ante `429`. Las confirmaciones se distinguen de la [entrega de webhooks de Cobrix al integrador](/guides/webhooks/delivery). Ninguna cifra de este reporte representa pagos recibidos. ## Cómo mostrar lecturas y fallos * **`null` → «—» o «No disponible»:** el histórico incluido no proporciona esa métrica. No conviertas `null` a cero. * **`0` → «0»:** no hay confirmaciones de ese estado en el resultado disponible; no garantiza que se hayan recibido todas las confirmaciones de Meta. * **Número positivo:** conteo disponible para el filtro seleccionado. Si un día histórico tiene lecturas o fallos desconocidos, el total de esa métrica también queda en `null`, aunque haya confirmaciones recientes. La tabla diaria permite ver cuáles días sí tienen el dato. Con un filtro de estado, los otros estados se ponen en cero porque están excluidos del resultado. Desde que los envíos estén asociados a la empresa y sus confirmaciones lleguen a Cobrix, un período nuevo sin histórico incompleto permite contar enviados, entregados, leídos y fallidos. Una confirmación puede llegar después del envío. No leer un mensaje, no recibir una lectura o no tener confirmación de entrega no equivale a un fallo. ## Ejemplo de integración del tablero Este ejemplo de **JavaScript en el servidor** recibe las fechas del selector, realiza una llamada y prepara los campos del tablero. Guarda `COBRIX_API_KEY` en el servidor y resuelve la llave desde la empresa autorizada en tu aplicación; no la incluyas en JavaScript público ni en la URL. ```javascript theme={null} async function consultarTablero({ desde, hasta, status, phone, page = 1 }) { const apiKey = process.env.COBRIX_API_KEY; if (!apiKey) throw new Error('Falta configurar COBRIX_API_KEY'); const url = new URL('https://api.cobrix.co/api/v1/whatsapp/events'); // Desde y hasta son fechas YYYY-MM-DD del selector en Caracas. if (desde) url.searchParams.set('dateFrom', `${desde}T00:00:00-04:00`); if (hasta) url.searchParams.set('dateTo', `${hasta}T23:59:59.999-04:00`); if (status) url.searchParams.set('status', status); if (phone) url.searchParams.set('phone', phone); url.searchParams.set('page', String(page)); url.searchParams.set('limit', '20'); const response = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` }, cache: 'no-store', signal: AbortSignal.timeout(15000), }); if (!response.ok) { const error = new Error(`Cobrix respondió HTTP ${response.status}`); error.status = response.status; error.retryAfter = response.headers.get('Retry-After'); throw error; } const data = await response.json(); if (!data.report) throw new Error('Reporte no disponible en la respuesta'); return { tarjetas: data.report.summary, dias: data.report.daily, eventos: data.events, paginacion: { page: data.page, limit: data.limit, totalPages: data.totalPages }, }; } const tablero = await consultarTablero({ desde: '2026-09-01', hasta: '2026-09-30' }); const mostrarConteo = (valor) => valor === null ? '—' : valor.toLocaleString('es-VE'); console.log(mostrarConteo(tablero.tarjetas.sent)); console.log(mostrarConteo(tablero.tarjetas.read)); // Grafica tablero.dias por date, con las series sent y delivered. // La tabla de detalle usa tablero.eventos. ``` Al cambiar fechas, empresa, estado o teléfono, vuelve a `page=1` y consulta de nuevo. Cancela o descarta respuestas anteriores para que una consulta lenta no reemplace el filtro actual. No sustituyas un error HTTP por tarjetas en cero. Para actualización periódica, una consulta por minuto mientras el tablero está visible es suficiente como punto de partida. Coordina las consultas que compartan la misma llave, evita solicitudes superpuestas y ante `429` espera los segundos de `Retry-After` antes de reintentar. El ejemplo realiza una sola consulta; no crea un temporizador automáticamente. Los datos cambian cuando llegan nuevas confirmaciones o se incorpora evidencia. Para seguimiento de detalle, deduplica por `id` y vuelve a consultar fechas recientes: la paginación entre llamadas no congela el conjunto de datos. No se garantiza la reconstrucción de confirmaciones históricas no recibidas. # Catálogo de capacidades Source: https://docs.cobrix.co/api-reference/catalog Todos los endpoints organizados como en el drawer de permisos
Mapa de la API

Encuentra el endpoint desde su permiso.

La navegación replica las categorías de Configuración → Integraciones → Llaves API. Así puedes pasar del permiso seleccionado al endpoint, payload, respuesta y error asociado sin traducir conceptos.

2endpoints de clientes
9operaciones de cobro y pago
6endpoints de documentos públicos
## Categorías del drawer
`customers:read` · `customers:write` `public_invoices:read` · `public_invoices:write` `collection_documents:read` · `collection_documents:write` `collection_document_checkouts:write` `verified_payments:write` · `payments:read` · `certified_rates:write` `integration_logs:read` controla la consulta desde el producto; no agrega un endpoint público. `whatsapp_events:read` · un endpoint para tarjetas, actividad diaria e histórico de Meta; filtros por semana, mes o fechas mediante `dateFrom` y `dateTo`.
## Mapa permiso → operación | Categoría | Scope | Operaciones habilitadas | | ---------------------------------- | --------------------------------------------------------------------- | ----------------------: | | Clientes | `customers:read` / `customers:write` | 2 | | API pública de documentos de cobro | `public_invoices:read` / `public_invoices:write` | 6 | | Documentos de cobro | `collection_documents:read` / `collection_documents:write` | 4 | | Links de cobro | `collection_document_checkouts:write` | 1 | | Pagos | `verified_payments:write` / `payments:read` / `certified_rates:write` | 4 | | WhatsApp | `whatsapp_events:read` | 1 | | Auditoría | `integration_logs:read` | Superficie UI | El catálogo suma 18 operaciones públicas. Auditoría aparece porque forma parte del drawer de permisos, pero su acceso actual es una experiencia del panel de Cobrix, no una ruta para integradores. # Auditoría Source: https://docs.cobrix.co/api-reference/categories/audit Investiga solicitudes recientes sin exponer credenciales ni secretos
La categoría de soporte del drawer no representa un endpoint adicional.

`integration_logs:read` habilita la consulta de actividad desde el producto Cobrix. Los integradores siguen usando los 18 endpoints públicos documentados en las demás categorías.

integration\_logs:read
## Qué puedes investigar Método, ruta, ambiente, timestamp, partner, llave identificada por prefijo y payload sanitizado. Código HTTP, duración, `requestId`, código de error y respuesta sanitizada. Clave protegida, repetición compatible o conflicto de payload y resultado reproducido. Evento, intento, destino, código HTTP, latencia y próximo reintento sin revelar el secreto. ## Flujo de diagnóstico Todas las respuestas de error de la API de integraciones incluyen `error.requestId`. En documentos públicos, conserva también fecha, método e identificador público. Entra a **Configuración → Integraciones**, abre el partner o llave correspondiente y consulta su actividad reciente. Revisa scope, headers, firma, idempotencia, tipos, campos obligatorios y unidades monetarias antes de reenviar. Comparte `requestId`, ambiente, método, ruta y hora. Nunca envíes la API key completa, la firma ni el secreto del webhook. Abre el detalle sanitizado y revisa el campo señalado. Confirma especialmente fechas ISO 8601, enteros `Minor`, moneda, source, identificadores externos y suma de líneas. Una llave válida aún puede carecer del scope de la operación, pertenecer a otra empresa o estar asociada a otro `source`. Primero identifica si el conflicto proviene de idempotencia, referencia duplicada, estado financiero o una operación en recuperación. Reintenta con la misma clave solo si el cuerpo es idéntico. Bearer tokens completos, secretos de webhooks y material criptográfico se ocultan. Los payloads sensibles deben aparecer sanitizados según el rol autorizado. Para soporte, el prefijo visible de la llave y el `requestId` son suficientes para correlacionar una petición sin compartir la credencial completa. # Links de cobro Source: https://docs.cobrix.co/api-reference/categories/checkout-links Crea sesiones de checkout sobre documentos abiertos
Convierte uno o varios documentos abiertos en una experiencia de pago.

La sesión reúne documentos compatibles y devuelve un `checkoutUrl` listo para entregar al cliente final.

collection\_document\_checkouts:write
## Operación disponible | Permiso del drawer | Método y ruta | | ------------------ | -------------------------------------------------------------------------- | | Crear links | `POST /integrations/v1/{companyId}/collection-documents/checkout-sessions` | Todos deben pertenecer al mismo cliente, `source` y moneda, y conservar saldo pendiente. `expiresInHours` acepta de 1 a 720 horas. Si lo omites, Cobrix utiliza 72 horas. Conserva `sessionId`, `token`, `checkoutUrl` y `amountMinor` para soporte y trazabilidad. Usa webhooks generales para conocer el avance del checkout y del pago sin consultar en un bucle. Cobrix devuelve `404` o `409` según el estado. Consulta primero el detalle del documento y usa el `requestId` para soporte. Una sesión no puede mezclar carteras distintas. Separa los documentos en checkouts independientes. Conserva el mismo `Idempotency-Key` solo cuando reenvíes exactamente el mismo cuerpo. Para otra selección crea una clave nueva. Abre el playground con payload, respuesta y códigos HTTP. Verifica firmas y procesa eventos de checkout y pago. # Documentos de cobro Source: https://docs.cobrix.co/api-reference/categories/collection-documents Sincroniza cuentas por cobrar con importes en unidades menores
La cartera operativa del sistema externo dentro de Cobrix.

Cada documento pertenece a un `source`, un cliente y una moneda. Los campos terminados en `Minor` son enteros en unidades menores: `2000` representa USD 20,00.

collection\_documents:read collection\_documents:write
## Operaciones | Permiso del drawer | Scope | Método y ruta | | ----------------------------- | ---------------------------- | ------------------------------------------------------------------------------------ | | Listar y consultar documentos | `collection_documents:read` | `GET /integrations/v1/{companyId}/collection-documents` | | Listar y consultar documentos | `collection_documents:read` | `GET /integrations/v1/{companyId}/collection-documents/{externalDocumentId}` | | Crear, actualizar y anular | `collection_documents:write` | `POST /integrations/v1/{companyId}/collection-documents/upsert` | | Crear, actualizar y anular | `collection_documents:write` | `POST /integrations/v1/{companyId}/collection-documents/{externalDocumentId}/cancel` | Envía `source`, `externalDocumentId`, `customerExternalId`, datos del cliente, fechas, moneda y líneas. `totalMinor`, si se incluye, debe ser coherente con las líneas. Filtra por estado, cliente, documento, source, moneda, saldo, rangos de emisión o vencimiento y `updatedSince`. Usa `cursor` para continuar. Consulta saldos, líneas, aplicaciones y estado operativo usando el identificador externo del documento. La anulación es auditada e idempotente. Si el documento tiene aplicaciones incompatibles, Cobrix responde conflicto para conservar el ledger. ## Orden recomendado de sincronización Ejecuta primero el upsert de Clientes con la misma pareja `source` + `externalCustomerId`. Conserva estable `externalDocumentId` y usa un `Idempotency-Key` único por intención de escritura. Usa el detalle o `updatedSince` para confirmar saldo y evitar depender solo de la respuesta inicial. El documento abierto puede alimentar las categorías Links de cobro y Pagos. Revisa líneas, cliente embebido, fechas y validaciones monetarias. Explora la paginación por cursor y todos los filtros soportados. # Clientes Source: https://docs.cobrix.co/api-reference/categories/customers Sincroniza la identidad del cliente antes de crear documentos y pagos
La misma categoría que ves en el drawer de permisos.

Registra o actualiza clientes externos y consulta su estado dentro de la integración. La identidad estable es la combinación de `source` y `externalCustomerId`.

customers:read customers:write
## Operaciones | Permiso del drawer | Scope | Método y ruta | | --------------------------- | ----------------- | ---------------------------------------------------- | | Listar clientes | `customers:read` | `GET /integrations/v1/{companyId}/customers` | | Crear y actualizar clientes | `customers:write` | `POST /integrations/v1/{companyId}/customers/upsert` | Envía `source`, `externalCustomerId`, `type` y `name`. También puedes conservar `email`, `phone`, `taxId`, `customerCode` y `metadata`. El upsert es seguro para sincronizaciones periódicas: la misma identidad actualiza el cliente existente. El `POST` requiere `Idempotency-Key`, firma del request y Bearer. Filtra por `search`, `externalCustomerId`, `source`, `updatedSince` o `status`. La paginación usa `cursor` y `limit`; conserva el cursor devuelto para obtener la siguiente página. ## Identidad que no debe cambiar Usa el mismo identificador configurado al crear el partner. No lo cambies entre sincronizaciones. `externalCustomerId` debe seguir apuntando a la misma persona o empresa durante toda su vida útil. Los documentos, links y pagos posteriores deben utilizar el mismo `customerExternalId`. Verifica que la llave pertenezca al `companyId`, que conserve el `source` autorizado y que tenga `customers:read` o `customers:write` según la operación. La identidad o la idempotencia entró en conflicto con una solicitud anterior. Busca el `requestId` en Auditoría y compara el payload enviado. La referencia interactiva muestra cada campo, código HTTP y ejemplo ejecutable. # API pública de documentos de cobro Source: https://docs.cobrix.co/api-reference/categories/invoices Crea, consulta, actualiza y cierra documentos con reglas financieras explícitas
Una fachada de cobro compacta para sistemas que ya controlan su cartera.

Los montos usan unidades mayores de la moneda configurada en la empresa. Por ejemplo, `amount: 20` representa USD 20 cuando la empresa opera en USD.

public\_invoices:read public\_invoices:write
## Operaciones | Permiso del drawer | Scope | Método y ruta | Resultado | | ---------------------------- | ----------------------- | --------------------------------- | ----------------------------------------- | | Consultar documentos | `public_invoices:read` | `GET /v1/invoices` | Lista, filtra y ordena | | Consultar documentos | `public_invoices:read` | `GET /v1/invoices/{invoiceId}` | Detalle, estado y cobro vigente | | Crear, actualizar y eliminar | `public_invoices:write` | `POST /v1/invoices` | Crea documento y checkout | | Crear, actualizar y eliminar | `public_invoices:write` | `PUT /v1/invoices/{invoiceId}` | Actualiza según estado financiero | | Crear, actualizar y eliminar | `public_invoices:write` | `DELETE /v1/invoices/{invoiceId}` | Anula o informa pago externo | | Crear, actualizar y eliminar | `public_invoices:write` | `DELETE /v1/invoices` | Programa eliminación masiva de pendientes | ## Qué representa `reference` `POST /v1/invoices` tiene un único contrato: | Campo | Significado | | --------------- | ----------------------------------------------------------------- | | `reference` | Cédula o RIF del cliente | | `provider_id` | Identidad estable del documento en el sistema de origen | | `x-idempotency` | Identidad documental de respaldo cuando no se envía `provider_id` | Cobrix busca o crea al cliente únicamente dentro de la empresa de la API key y guarda su identidad fiscal para que el portal pueda localizarlo. No hace falta llamar a un endpoint adicional de clientes. ```json theme={null} { "reference": "V-12345678", "provider": "erp_acme", "provider_id": "DOC-90871", "amount": 25, "name": "Servicio de internet" } ``` Cobrix conserva el valor exacto de `reference` en la respuesta y en los webhooks. Solo normaliza una copia para resolver la identidad fiscal. Si esa identidad es ambigua dentro de la empresa, la creación devuelve `409` y no crea ni mueve el documento. Una referencia que no represente una cédula o RIF devuelve `422`. Varios documentos pueden compartir la misma identidad del cliente: ```json theme={null} [ { "reference": "V-12345678", "provider": "erp_acme", "provider_id": "DOC-001", "amount": 25, "name": "Servicio de julio" }, { "reference": "V12345678", "provider": "erp_acme", "provider_id": "DOC-002", "amount": 30, "name": "Servicio de agosto" } ] ``` Ambas quedan vinculadas al mismo cliente, pero conservan cobros, estados y cancelaciones independientes. Sin pagos aplicados, el `PUT` puede cambiar datos informativos y monto. Si cambia el monto, Cobrix registra el ajuste financiero, invalida el checkout anterior y devuelve uno nuevo. La actualización se rechaza con `409`, código `10009` y `errors.payment`. No se modifica el documento, checkout ni ledger. `PAID`, `CONCILIATED` y `PAID_FROM_PROVIDER` aceptan únicamente cambios informativos. `amount` debe coincidir con el total liquidado. `DELETE_FROM_PROVIDER` y `FAILED` no aceptan `PUT`. La respuesta es `409` con el detalle en `errors.status`. ## Reglas que protegen el ledger ### Nombre y correo En creación y actualización, `name` admite entre **2 y 100 caracteres**. `email` es opcional: puedes omitirlo, enviar `""` o solo espacios. Cobrix recorta los espacios externos y valida el correo únicamente si queda contenido (formato de correo válido y máximo 200 caracteres). No genera ni completa direcciones. En una actualización, omitirlo o enviarlo vacío **conserva el correo existente**; no lo borra. Un nombre de un carácter o un correo con contenido inválido devuelve `422` con el detalle del campo, sin cambiar las reglas financieras. | Entrada | Creación | Actualización | | ----------------------------------------- | ------------------------------ | ------------------------------- | | `name: "Al"` | Válido | Válido | | `name: "A"` o más de 100 caracteres | `422`, error en `name` | `422`, error en `name` | | Sin `email`, `email: ""` o `email: " "` | Aceptado; no inventa un correo | Conserva el correo existente | | `email: " qa@example.test "` | Guarda `qa@example.test` | Actualiza a `qa@example.test` | | `email: "correo-invalido"` | `422`, error en `email` | `422`, no modifica el documento | Ejemplo de creación con nombre de dos caracteres y sin correo: ```json theme={null} { "reference": "V-12345678", "provider": "erp_pruebas", "provider_id": "QA-DOC-001", "amount": 1, "name": "Al" } ``` Envía el ejemplo únicamente con una identidad sintética reservada en sandbox y una clave `x-idempotency` nueva. `PUT` no es una actualización parcial: conserva los campos obligatorios `reference`, `amount` y `name`. Aceptar los datos de contacto no modifica las restricciones de documentos con pagos. `provider` identifica el origen financiero y no puede cambiar después de crear el documento. Enviarlo con contenido en un `PUT` devuelve `422` con el detalle en `errors.provider`. `provider_id` identifica el documento y no puede cambiar después de crearlo. Si no se envía, Cobrix deriva la identidad de `x-idempotency`. `reference` puede variar de formato únicamente si sigue representando la misma cédula o RIF. Un documento pagado conserva su monto liquidado. Puedes corregir nombre, descripción, teléfono, email o vencimiento, pero no reabrir ni reescribir el pago. Esta API espera el pago completo del documento. Las recargas de saldo o Wallet pertenecen a otro flujo y no deben modelarse como abonos parciales. Informa que el proveedor eliminó el documento. Cobrix anula los cobros pendientes; si existe dinero aplicado, protege el ledger y rechaza la operación. Informa un pago realizado fuera de Cobrix. Envía `reason: PAID_FROM_PROVIDER` y `provider_payment_id`; Cobrix aplica por la vía financiera oficial hasta el saldo abierto. `POST /v1/invoices` requiere `x-idempotency`. Repetir la misma clave y el mismo cuerpo reproduce el resultado; reutilizarla con otro cuerpo devuelve conflicto. Consulta el DTO `snake_case`, filtros, respuestas y errores exactos. Procesa `invoice.created`, `invoice.paid` e `invoice.canceled`. # Pagos Source: https://docs.cobrix.co/api-reference/categories/payments Reporta pagos verificados, consulta su aplicación y completa conversiones certificadas
Una entrada financiera controlada, no una simple actualización de estado.

Los montos usan unidades menores. Cobrix valida documentos, saldo, moneda e idempotencia antes de aplicar el pago al ledger.

verified\_payments:write payments:read certified\_rates:write
## Operaciones | Permiso del drawer | Scope | Método y ruta | | -------------------------- | ------------------------- | ------------------------------------------------------------------------------- | | Listar y consultar pagos | `payments:read` | `GET /integrations/v1/{companyId}/payments` | | Listar y consultar pagos | `payments:read` | `GET /integrations/v1/{companyId}/payments/{externalPaymentId}` | | Reportar pagos verificados | `verified_payments:write` | `POST /integrations/v1/{companyId}/verified-payments` | | Cargar tasas certificadas | `certified_rates:write` | `POST /integrations/v1/{companyId}/payments/{externalPaymentId}/certified-rate` | Envía `source`, `externalPaymentId`, cliente, `amountMinor`, moneda, `verifiedAt` y los documentos a aplicar. El header `Idempotency-Key` es obligatorio. Filtra por estado, estado operativo, pago externo, cliente, source, proveedor, moneda, rango de pago o `updatedSince`. Si el pago queda en `needs_certified_rate`, envía moneda y monto de referencia, `exchangeRateUsed`, fecha efectiva y distribución entre documentos. ## Estados operativos | Estado | Qué significa | Próxima acción | | ---------------------- | ---------------------------------------- | ---------------------------------------- | | `applied` | Pago aplicado completamente | Ninguna | | `partially_applied` | Solo parte pudo aplicarse | Consulta el detalle y saldo restante | | `credited` | Existe remanente registrado como crédito | Revisa `creditCreatedMinor` | | `needs_certified_rate` | Falta una tasa aprobada | Envía la tasa certificada | | `no_open_documents` | No había documentos aplicables | Corrige la selección antes de reintentar | | `already_processed` | La intención ya fue procesada | Reutiliza la respuesta existente | | `failed` | La aplicación no terminó | Busca `requestId` y detalle en Auditoría | No inventes una tasa ni reenvíes el pago con otro identificador para superar un conflicto. Consulta primero el pago existente; duplicar la intención puede producir una doble aplicación. Revisa distribución, moneda, timestamp y respuestas financieras. Confirma el resultado operativo antes de ejecutar acciones posteriores. # WhatsApp: confirmaciones y totales Source: https://docs.cobrix.co/api-reference/categories/whatsapp Consulta las confirmaciones de Meta de tu empresa con una sola llamada Consulta `GET /api/v1/whatsapp/events` con tu llave habitual y el permiso **`whatsapp_events:read`**. Actívalo en **Configuración → Integraciones → Llaves API**, al crear o editar la llave. Las llaves existentes no lo reciben automáticamente. La empresa se obtiene de la llave. El reporte incluye confirmaciones de todos sus orígenes: recordatorios automáticos, envíos desde Cobrix y otras integraciones, siempre que exista evidencia exacta de pertenencia. No necesitas enviar `companyId`, firma HMAC ni idempotencia. ## Primera consulta ```bash theme={null} curl --get 'https://api.cobrix.co/api/v1/whatsapp/events' \ --header "Authorization: Bearer $COBRIX_API_KEY" \ --data-urlencode 'dateFrom=2026-09-08T00:00:00-04:00' \ --data-urlencode 'dateTo=2026-09-08T23:59:59.999-04:00' \ --data-urlencode 'limit=20' ``` En sandbox usa `https://sandbox-api.cobrix.co/api/v1/whatsapp/events`. Cada despliegue consulta su propia base de datos. ## Leer el resultado ```json theme={null} { "events": [ { "id": "00000000-0000-4000-8000-000000000001", "messageId": "wamid.example", "status": "delivered", "recipientPhone": "584121234567", "receivedAt": "2026-09-08T14:30:00.000Z", "errorCode": null, "errorTitle": null } ], "summary": { "total": 1, "sent": 0, "delivered": 1, "read": 0, "failed": 0 }, "page": 1, "limit": 20, "totalPages": 1, "coverage": { "status": "partial", "unit": "events", "attribution": "confirmed" }, "report": { "timezone": "America/Caracas", "summary": { "sent": 0, "delivered": 1, "read": 0, "failed": 0 }, "daily": [ { "date": "2026-09-08", "sent": 0, "delivered": 1, "read": 0, "failed": 0, "source": "events" } ], "history": { "availability": "no_data", "sent": 0, "delivered": 0 } } } ``` * `report.summary` alimenta las tarjetas y `report.daily` el gráfico y la tabla por día. El histórico y la actividad disponible ya están combinados. * `events` contiene la página solicitada; el `summary` original cuenta los eventos almacenados de todo el resultado filtrado. * `status`, `phone`, `dateFrom` y `dateTo` se aplican también a los totales. Al filtrar `delivered`, los demás estados quedan en cero. * Los eventos se ordenan por recepción descendente y luego por identificador descendente. `page` empieza en 1; `limit` vale 20 por defecto y admite hasta 100. * Una página fuera del resultado devuelve `events: []` y conserva los totales. Sin eventos individuales, el `summary` original y `totalPages` son cero; `report` puede seguir incluyendo histórico agregado. * Las fechas filtran `receivedAt`, el instante en que Cobrix recibió la confirmación, con límites inclusivos. Incluye segundos y zona horaria; un rango invertido se rechaza. Sin fechas se consulta el histórico disponible. * `phone` busca una coincidencia parcial y admite hasta 64 caracteres. Usa `--data-urlencode` para conservar signos como `+`. Cada respuesta usa una misma instantánea para página, totales y reporte. Entre solicitudes pueden llegar eventos o incorporarse nueva evidencia; la paginación no es una exportación congelada del histórico. Para guardar registros, deduplica por `id` y vuelve a consultar períodos recientes. ## Semana, mes y fechas personalizadas Usa `dateFrom` y `dateTo` para todas estas opciones; la API no recibe `period`, `week` ni `month`. Tu tablero calcula los límites en la zona horaria elegida. Para días completos de Caracas, usa `00:00:00-04:00` y `23:59:59.999-04:00`. Consulta los [ejemplos de semana, mes y rango](/api-guides/whatsapp-daily#esta-semana-este-mes-o-un-rango-de-fechas). El histórico agregado sólo se incluye para días completos y sin filtro de teléfono; admite estados `sent` y `delivered`. Con `phone`, `read` o `failed` se consultan las confirmaciones individuales disponibles. `report.history.availability` explica las exclusiones. Paginar el detalle no cambia `report.summary` ni `report.daily`. ## Interpretar los estados | Estado | Significado | | ----------- | ----------------------------------------------------------- | | `sent` | Meta informó que el mensaje salió; no confirma entrega. | | `delivered` | Meta confirmó la entrega al destinatario. | | `read` | Meta confirmó una lectura. | | `failed` | Meta informó un error; consulta `errorCode` y `errorTitle`. | El `summary` original cuenta **eventos almacenados**, no mensajes únicos: un mismo `messageId` puede tener varios estados. No se incluyen pendientes, envíos en proceso ni otros estados almacenados fuera de estos cuatro valores. Sólo se exponen registros con una empresa de origen confirmada mediante evidencia exacta del mensaje o un emisor exclusivo verificado. Se excluyen coincidencias por teléfono, atribuciones ambiguas y eventos sin evidencia. El histórico puede ampliarse cuando se incorpore evidencia. La ausencia de un evento no demuestra fallo ni ausencia de envío. Para comparar con el panel, selecciona la misma empresa, fechas y filtros, y **Sólo empresa confirmada**. ## Límites y errores El límite independiente es de **60 solicitudes por minuto por llave**, en ventanas fijas compartidas entre réplicas. Las respuestas autorizadas incluyen `X-RateLimit-Limit`, `X-RateLimit-Remaining` y `X-RateLimit-Reset` (Unix, segundos). Un `429` incluye `Retry-After`; espera ese número de segundos. | HTTP | Motivo | | ------------- | -------------------------------------------------------- | | `401` | Llave inválida, revocada, vencida o integrador inactivo. | | `403` | Falta `whatsapp_events:read` o la empresa está inactiva. | | `422` | Filtro inválido, desconocido o rango invertido. | | `429` | Límite de solicitudes alcanzado. | | `500` / `503` | Error interno o limitador temporalmente no disponible. | Los errores usan el formato compacto `message`, `code`, `code_name` y, cuando corresponde, `errors`. La auditoría guarda metadatos operativos sin consultas, teléfonos, credenciales ni contenido de los eventos. ## Diferencia con los webhooks salientes Este endpoint consulta **confirmaciones de WhatsApp recibidas de Meta**. La [entrega de webhooks de Cobrix](/guides/webhooks/delivery) describe las llamadas de Cobrix al servidor del integrador. Una respuesta HTTP exitosa de ese servidor no demuestra que WhatsApp entregó o leyó el mensaje. ## Cobertura del reporte La respuesta incluye `coverage: { "status": "partial", "unit": "events", "attribution": "confirmed" }`. El `summary` original representa confirmaciones almacenadas con empresa acreditada, no el total de envíos ni mensajes únicos. `coverage` describe ese detalle; el alcance del histórico agregado se indica en `report.history`. Un resultado vacío no demuestra que no hubo envíos. La recuperación de evidencia histórica puede incorporar eventos que antes no tenían atribución. Los estados de aceptación en el servicio de envío y los recordatorios del calendario son medidas diferentes. Para comparar API y panel, usa la misma empresa, fechas de recepción y «Sólo empresa confirmada». Las confirmaciones de emisores que no hayan llegado a Cobrix no se pueden reconstruir a partir de una respuesta de aceptación de Meta. ## Tablero diario e histórico La misma respuesta de `GET /api/v1/whatsapp/events` incluye **`report.summary`** para las tarjetas y **`report.daily`** para el gráfico y la tabla. Combina el histórico importado y las confirmaciones disponibles sin duplicar el mismo emisor y día. El detalle `events`, su `summary` y la paginación conservan su contrato. Consulta el [ejemplo de tablero](/api-guides/whatsapp-daily). Los valores `read` y `failed` de `report` pueden ser `null` si el histórico incluido no tiene esas métricas. Muestra «No disponible»; no los conviertas a cero. Un período nuevo basado en confirmaciones individuales tiene conteos numéricos, sujetos a las confirmaciones recibidas. Si lo combinas con histórico incompleto, el total de la métrica desconocida sigue siendo `null`. # Crear o actualizar cliente Source: https://docs.cobrix.co/api-reference/clientes/crear-o-actualizar-cliente /openapi/integrations-v1.json post /integrations/v1/{companyId}/customers/upsert Crea, actualiza o reproduce sin cambios un cliente externo. `source` debe coincidir con el partner de la llave. # Listar clientes Source: https://docs.cobrix.co/api-reference/clientes/listar-clientes /openapi/integrations-v1.json get /integrations/v1/{companyId}/customers Lista clientes vinculados a integraciones con paginación por cursor, ordenados por última actualización descendente. # Anular documento Source: https://docs.cobrix.co/api-reference/documentos-de-cobro/anular-documento /openapi/integrations-v1.json post /integrations/v1/{companyId}/collection-documents/{externalDocumentId}/cancel Anula el documento por la ruta financiera oficial. Se rechaza si el estado o las aplicaciones no permiten cancelarlo. # Consultar documento Source: https://docs.cobrix.co/api-reference/documentos-de-cobro/consultar-documento /openapi/integrations-v1.json get /integrations/v1/{companyId}/collection-documents/{externalDocumentId} Devuelve líneas, saldo y pagos aplicados del documento dentro del source autorizado. # Crear o actualizar documento Source: https://docs.cobrix.co/api-reference/documentos-de-cobro/crear-o-actualizar-documento /openapi/integrations-v1.json post /integrations/v1/{companyId}/collection-documents/upsert Sincroniza un documento externo, su cliente y líneas. `totalMinor`, cuando se envía, debe corresponder con las líneas. # Listar documentos Source: https://docs.cobrix.co/api-reference/documentos-de-cobro/listar-documentos /openapi/integrations-v1.json get /integrations/v1/{companyId}/collection-documents Lista documentos externos con saldo y estado operativo. # Actualizar documento de cobro Source: https://docs.cobrix.co/api-reference/documentos-públicos/actualizar-documento-de-cobro /openapi/invoices-v1.json put /v1/invoices/{invoiceId} En `CREATED` sin pagos permite cambiar monto y datos, ajusta el ledger y reemplaza el checkout. Con pagos aplicados responde `409`. En `PAID`, `CONCILIATED` o `PAID_FROM_PROVIDER` solo permite datos informativos y exige el mismo monto. `provider` es inmutable. Requiere `public_invoices:write`. # Consultar documento de cobro Source: https://docs.cobrix.co/api-reference/documentos-públicos/consultar-documento-de-cobro /openapi/invoices-v1.json get /v1/invoices/{invoiceId} Devuelve el documento completo y la revisión vigente del cobro. Requiere `public_invoices:read`. # Crear documento de cobro Source: https://docs.cobrix.co/api-reference/documentos-públicos/crear-documento-de-cobro /openapi/invoices-v1.json post /v1/invoices Crea el documento central, su proyección pública y un checkout por el saldo completo. `reference` contiene la cédula o RIF del cliente; `provider_id` identifica el documento. `provider` debe coincidir con el source de la llave. Requiere `public_invoices:write`. # Eliminar documentos pendientes Source: https://docs.cobrix.co/api-reference/documentos-públicos/eliminar-documentos-pendientes /openapi/invoices-v1.json delete /v1/invoices Encola la eliminación asíncrona de documentos pendientes del partner. Omite documentos pagados o conciliados. Requiere `public_invoices:write`. # Eliminar o liquidar desde proveedor Source: https://docs.cobrix.co/api-reference/documentos-públicos/eliminar-o-liquidar-desde-proveedor /openapi/invoices-v1.json delete /v1/invoices/{invoiceId} Sin `reason` o con `DELETE_FROM_PROVIDER`, anula el documento y los checkouts pendientes, responde HTTP 204 y encola el webhook asíncrono `invoice.canceled`. El payload del evento refleja `invoice.status=DELETE_FROM_PROVIDER` e `invoice.payment.status=canceled`. Con `PAID_FROM_PROVIDER`, aplica exactamente el saldo abierto usando `provider_payment_id` y, después de persistir el pago y el saldo cero, encola exactamente un `invoice.paid`. Ese payload conserva `invoice.status=PAID_FROM_PROVIDER`, reporta `invoice.payment.status=APPROVED` y devuelve el identificador recibido en `invoice.payment.provider_id`. Rechaza documentos con pagos parciales o estados incompatibles. Requiere `public_invoices:write`. # Listar documentos de cobro Source: https://docs.cobrix.co/api-reference/documentos-públicos/listar-documentos-de-cobro /openapi/invoices-v1.json get /v1/invoices Devuelve una página de documentos del partner. Requiere `public_invoices:read`. # Crear link de cobro Source: https://docs.cobrix.co/api-reference/links-de-cobro/crear-link-de-cobro /openapi/integrations-v1.json post /integrations/v1/{companyId}/collection-documents/checkout-sessions Crea una sesión para documentos abiertos del mismo cliente y moneda. El source se obtiene de la llave. # Completar pago con tasa certificada Source: https://docs.cobrix.co/api-reference/pagos/completar-pago-con-tasa-certificada /openapi/integrations-v1.json post /integrations/v1/{companyId}/payments/{externalPaymentId}/certified-rate Continúa la aplicación de un pago `needs_certified_rate` con una conversión certificada y documentos explícitos. # Consultar pago Source: https://docs.cobrix.co/api-reference/pagos/consultar-pago /openapi/integrations-v1.json get /integrations/v1/{companyId}/payments/{externalPaymentId} Consulta un pago por el identificador estable enviado por el partner. # Listar pagos Source: https://docs.cobrix.co/api-reference/pagos/listar-pagos /openapi/integrations-v1.json get /integrations/v1/{companyId}/payments Lista pagos de integraciones y su estado operativo de aplicación. # Reportar pago verificado Source: https://docs.cobrix.co/api-reference/pagos/reportar-pago-verificado /openapi/integrations-v1.json post /integrations/v1/{companyId}/verified-payments Registra un pago confirmado por el partner y lo aplica únicamente a los documentos indicados. El límite es 60 solicitudes por minuto por llave. # Consultar confirmaciones de WhatsApp Source: https://docs.cobrix.co/api-reference/whatsapp/consultar-confirmaciones-de-whatsapp /openapi/whatsapp-v1.json get /v1/whatsapp/events Requiere whatsapp_events:read. La empresa se resuelve desde la llave Bearer. Una sola respuesta contiene events y summary originales (eventos almacenados), más report.summary y report.daily para el tablero combinado de histórico y actividad. Calcula semana o mes en el cliente usando dateFrom/dateTo; no admite period, week, month, companyId ni attribution. No requiere HMAC ni idempotencia. # Autenticación Source: https://docs.cobrix.co/authentication Llaves Bearer, scopes y aislamiento por empresa ## Bearer API key Todas las APIs públicas usan una llave creada desde el panel de la empresa: ```http theme={null} Authorization: Bearer cbx_live_REEMPLAZAR ``` La llave está vinculada a una empresa, un partner, un `source` y un conjunto de permisos. No envíes `companyId` en headers adicionales; la API de integraciones lo incluye en la ruta y comprueba que coincida con la llave. La API pública de documentos de cobro obtiene la empresa directamente de la credencial. ## Crear una llave En el dashboard de la empresa entra en **Configuración → Integraciones → Llaves API**. Selecciona **Crear partner y primera llave** e indica un `source` estable, por ejemplo `erp_acme`. Activa los scopes correspondientes a las operaciones que ejecutará el sistema externo. La llave completa se muestra una sola vez. Guárdala en un gestor de secretos. ## Scopes | Scope | Permite | | ------------------------------------- | ---------------------------------------------------------- | | `customers:read` | Listar clientes vinculados a integraciones. | | `customers:write` | Crear o actualizar clientes externos. | | `collection_documents:read` | Listar y consultar documentos de cobro. | | `collection_documents:write` | Crear, actualizar o anular documentos. | | `collection_document_checkouts:write` | Generar links de cobro. | | `verified_payments:write` | Reportar pagos verificados al ledger. | | `payments:read` | Listar y consultar pagos externos. | | `certified_rates:write` | Completar pagos que requieren tasa certificada. | | `public_invoices:read` | Listar y consultar documentos de cobro públicos. | | `public_invoices:write` | Crear, actualizar o eliminar documentos de cobro públicos. | ## Diferencias de seguridad * `/integrations/v1` exige además firma HMAC por request. Consulta [Firma de solicitudes](/api-guides/request-signing). * `/v1/invoices` usa únicamente el Bearer y `x-idempotency` al crear; no acepta firmas adicionales como requisito. ## Respuestas de autorización | HTTP | Significado | | ----- | --------------------------------------------------------------- | | `401` | Llave ausente, inválida, vencida o revocada. | | `403` | Empresa incorrecta, partner deshabilitado o scope insuficiente. | Usa la llave únicamente de servidor a servidor. No la expongas en aplicaciones móviles, JavaScript del navegador, capturas, tickets o logs. ## Consultas de WhatsApp `GET /api/v1/whatsapp/events` utiliza la misma llave Bearer con el permiso `whatsapp_events:read`. La empresa se resuelve desde la llave; no requiere HMAC ni idempotencia. Activa el permiso explícitamente en la llave. Consulta la [guía de confirmaciones](/api-reference/categories/whatsapp). # Ambientes Source: https://docs.cobrix.co/environments URLs de sandbox y producción ## URLs base | Ambiente | URL base | Datos | | -------------- | ----------------------------------- | --------------------------- | | **Sandbox** | `https://sandbox-api.cobrix.co/api` | Infraestructura QA aislada. | | **Producción** | `https://api.cobrix.co/api` | Operaciones y pagos reales. | El ambiente lo determina la URL. Una llave creada en sandbox solo existe en la infraestructura QA y no funciona en producción, aunque ambas usen el prefijo `cbx_live_`. ```bash .env theme={null} # Sandbox COBRIX_BASE_URL=https://sandbox-api.cobrix.co/api COBRIX_API_KEY=cbx_live_REEMPLAZAR # Producción # COBRIX_BASE_URL=https://api.cobrix.co/api # COBRIX_API_KEY=cbx_live_REEMPLAZAR ``` No copies una llave de sandbox a producción ni registres una credencial de pruebas en la base productiva. Cada ambiente requiere crear su propio partner y llave. ## Checkout Los enlaces de checkout se devuelven en `checkoutUrl` o `payment.payment_link`, según la API utilizada. Usa siempre la URL entregada en la respuesta; no construyas el dominio manualmente. # Importar el reporte de movimientos de Bancamiga Source: https://docs.cobrix.co/guides/banks/bancamiga Descarga el estado de cuenta de Bancamiga en CSV y subelo a Cobrix para conciliacion. Esta guia explica como descargar el estado de cuenta de Bancamiga en formato CSV y subirlo a Cobrix para revisar y aprobar pagos pendientes. ## Antes de comenzar * Debes tener acceso a la banca en linea de Bancamiga. * Tu cuenta de Cobrix debe estar activa. * Define las fechas del periodo que deseas conciliar. ## Exportar movimientos desde Bancamiga Inicia sesion en Bancamiga, entra a **Posicion Global** y haz clic en el numero de tu cuenta corriente para abrir sus movimientos. Cuenta corriente seleccionada en Bancamiga Dentro de la vista de movimientos, usa el boton **Exportar Movimientos** en la barra superior. Boton Exportar Movimientos en Bancamiga Ingresa las fechas **Desde** y **Hasta** correspondientes al periodo que quieres exportar. Rango de fechas para exportar movimientos en Bancamiga En el campo **Formato**, selecciona **CSV**. Este es el formato recomendado para la conciliacion automatica en Cobrix. Formato CSV seleccionado en Bancamiga Haz clic en **Exportar** y guarda el CSV descargado en tu equipo. Exportacion del archivo CSV en Bancamiga ## Subir el estado de cuenta a Cobrix Entra a Cobrix y abre la tarjeta o modulo **Conciliacion Bancaria**. Acceso a Conciliacion Bancaria en Cobrix En **Subir Estado de Cuenta**, arrastra el archivo CSV descargado de Bancamiga o haz clic en el area de carga para seleccionarlo. El tamano maximo permitido es 10 MB. Subida del archivo CSV de Bancamiga en Cobrix Verifica que el archivo sea correcto, agrega una descripcion opcional y haz clic en **Subir Estado de Cuenta**. Confirmacion de subida del estado de cuenta de Bancamiga Cobrix procesara el estado de cuenta y lo mostrara en la lista de estados de cuenta. Desde alli podras revisar las lineas detectadas y aprobar pagos pendientes. ## Preguntas frecuentes Cobrix acepta CSV y PDF. Para Bancamiga, usa CSV por su mayor precision en la lectura automatica. Lo ideal es hacerlo diariamente o cada pocos dias para mantener la conciliacion al dia. Verifica que sea un CSV y que no supere 10 MB. Si el problema persiste, contacta a soporte en [ayuda@cobrix.co](mailto:ayuda@cobrix.co). ## Para LLMs
Ver como un Markdown Preguntarle a Google
# Recaudos para apertura de cuenta juridica en Banco Plaza Source: https://docs.cobrix.co/guides/banks/banco-plaza-account-opening Lista de recaudos para preparar la apertura de una cuenta juridica en Banco Plaza. Prepara estos documentos antes de iniciar la solicitud de apertura de cuenta juridica en Banco Plaza. Revisa que cada recaudo este vigente, legible y coincida con los datos de la empresa. ## Documentos de la persona juridica * **Acta constitutiva y modificaciones:** copia del acta constitutiva y de la ultima modificacion estatutaria registrada. Debe evidenciar que la persona que abre la cuenta tiene facultades para hacerlo e incluir cambios de nombre, domicilio fiscal, accionistas o aumento de capital cuando aplique. * **RIF de la empresa:** RIF vigente, alineado con la razon social y la direccion actualizada. * **Declaracion de ISLR:** copia legible y completa de la ultima declaracion aplicable. Si fue presentada por internet, incluye el certificado electronico de recepcion. * **Autorizacion a terceros, si aplica:** documento que identifique a las personas autorizadas para movilizar la cuenta y las operaciones que pueden ejecutar. Puede ser una certificacion de junta directiva o una carta firmada por quien tenga facultades estatutarias. * **Referencias bancarias o comerciales:** para clientes de alto riesgo, prepara dos referencias. Pueden ser dos bancarias, dos comerciales o una bancaria y una comercial. ## Representantes legales o autorizados Cada representante legal o autorizado debe preparar recaudos de persona natural: * Cedula de identidad laminada, vigente o vencida. * RIF personal vigente con direccion actualizada. * Soporte de ingresos segun su actividad: constancia de trabajo, certificacion de ingresos, certificado digital del I.V.S.S. o constancia de estudio cuando aplique. * Cualquier documento adicional relacionado con su actividad que el banco solicite durante la revision. Los requisitos bancarios pueden cambiar sin previo aviso. Valida la lista final antes de acudir a la agencia o iniciar el tramite. ## Para LLMs
Ver como un Markdown Preguntarle a Google
# Exportar movimientos de Banesco e importarlos en Cobrix Source: https://docs.cobrix.co/guides/banks/banesco Descarga movimientos desde BanescoOnline y cargalos en Cobrix para conciliacion bancaria. Esta guia explica como descargar movimientos desde BanescoOnline en formato de texto e importarlos en Cobrix. Entra a BanescoOnline, ubica la cuenta que quieres conciliar y haz clic sobre el numero de cuenta para ver sus movimientos. Cuenta seleccionada en BanescoOnline En la vista de movimientos, marca la opcion por rango, define la fecha inicial y la fecha final, y luego haz clic en **Exportar**. Rango de fechas y opcion Exportar en BanescoOnline En el selector de formato, elige **Texto** y marca **Configurar Parametros (Formato Personalizado)**. Configura los parametros asi: * **Encabezado:** No * **Incluir codigo de cuenta de cliente:** No * **Delimitador:** `;` (punto y coma) No selecciones Quicken/Money, Excel ni otro formato distinto para este flujo. Formato de exportacion Texto en BanescoOnline Parametros de exportacion de texto para BanescoOnline Revisa la informacion mostrada por Banesco, haz clic en **Aceptar** y guarda el archivo en una carpeta facil de ubicar. Confirmacion de descarga en BanescoOnline En Cobrix, abre **Conciliacion**. En **Subir Estado de Cuenta**, selecciona la pestana **Texto** y sube el archivo descargado desde Banesco o pega su contenido en el campo de texto. Carga del reporte de Banesco en Cobrix Cuando la carga finalice, Cobrix procesara el reporte y lo mostrara en la lista de estados de cuenta. Desde alli podras revisar los movimientos listos, los que requieren revision y los que no tienen un pago asociado. Para Banesco, usa el archivo de texto original descargado desde el banco. Cambiarlo de formato antes de importarlo puede afectar la lectura de columnas. ## Para LLMs
Ver como un Markdown Preguntarle a Google
# Solicitar la API Key del Banco de Venezuela Source: https://docs.cobrix.co/guides/banks/bdv-api-key Obtiene las credenciales de la API de conciliacion automatica del Banco de Venezuela. Esta guia explica como solicitar la clave para integraciones del Banco de Venezuela y completar los datos necesarios para conectarla con Cobrix. ## Video tutorial