> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cobrix.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Modelos compartidos

> Diccionario de objetos reutilizados por pagos, checkout y documentos

Los webhooks generales comparten un envelope estable y varios objetos dentro de `data`. Esta página evita repetir tablas extensas en cada evento.

## Envelope general

```json theme={null}
{
  "id": "evt_40544883-5dd6-420d-960a-f473ec2a754a",
  "event": "payment.succeeded",
  "created_at": "2026-07-14T16:00:00.000Z",
  "api_version": "2025-01-21",
  "data": {}
}
```

| Campo         | Tipo     | Uso                                                  |
| ------------- | -------- | ---------------------------------------------------- |
| `id`          | string   | Identificador estable para deduplicar el evento.     |
| `event`       | string   | Tipo que selecciona el manejador correspondiente.    |
| `created_at`  | ISO 8601 | Momento en que Cobrix construyó el payload.          |
| `api_version` | string   | Versión del contrato del envelope.                   |
| `data`        | object   | Datos específicos descritos en la página del evento. |

## `customer`

| Campo                             | Tipo      | Nulable | Significado                                                          |
| --------------------------------- | --------- | ------- | -------------------------------------------------------------------- |
| `companyCustomerId`               | string    | No      | Cliente dentro de la empresa.                                        |
| `name`, `email`, `phone`, `taxId` | string    | Sí      | Identidad disponible del cliente.                                    |
| `externalRef`, `customerCode`     | string    | Sí      | Correlación con sistemas externos.                                   |
| `metadata`, `customFieldsData`    | object    | Sí      | Datos adicionales configurados.                                      |
| `labels`                          | string\[] | No      | Etiquetas actuales.                                                  |
| `status`, `type`                  | string    | Sí      | Estado y tipo de relación.                                           |
| `address`                         | object    | Sí      | `street`, `city`, `state`, `postalCode` y `country`, todos nulables. |

## `payment`

| Campo                                                      | Tipo          | Nulable | Significado                                  |
| ---------------------------------------------------------- | ------------- | ------- | -------------------------------------------- |
| `id`, `companyId`                                          | string        | No      | Pago y empresa propietarios.                 |
| `companyCustomerId`, `checkoutSessionId`, `subscriptionId` | string        | Sí      | Relaciones del pago.                         |
| `status`, `reconciliationStatus`                           | string        | Sí      | Estado persistido y conciliación.            |
| `amount`, `amountMinor`, `currency`                        | number/string | Sí      | Monto en unidades mayores, menores y moneda. |
| `referenceAmountMinor`, `referenceCurrency`                | number/string | Sí      | Resultado de conversión.                     |
| `provider`, `providerChargeId`                             | string        | Sí      | Proveedor y transacción externa.             |
| `paymentReference`, `paymentReferenceMasked`               | string        | Sí      | Referencia y versión enmascarada.            |
| `hasPaymentReference`, `hasProof`                          | boolean       | No      | Presencia de referencia y comprobante.       |
| `paidAt`, `valueDate`, `createdAt`, `updatedAt`            | ISO 8601      | Sí      | Fechas financieras y operativas.             |
| `exchange`                                                 | object        | Sí      | Conversión aplicada.                         |

## `paymentMethod`

| Campo                     | Tipo          | Significado                                                               |
| ------------------------- | ------------- | ------------------------------------------------------------------------- |
| `kind`, `method`, `label` | string o null | Identidad técnica, valor de dominio y etiqueta.                           |
| `channel`                 | string        | Canal `automatic`, `manual`, `proof` o `unknown`.                         |
| `provider`                | string o null | Proveedor asociado.                                                       |
| `isManual`                | boolean       | Indica captura administrativa/manual.                                     |
| `requiresReconciliation`  | boolean       | Indica que el pago todavía requiere revisión.                             |
| `receiver`                | object o null | Cuenta receptora con teléfono y documento enmascarados.                   |
| `receiverCheck`           | object o null | Resultado de comparación OCR: estado, confianza y campos coincidentes.    |
| `submitted`               | object o null | Datos enviados por el cliente, siempre enmascarados cuando son sensibles. |
| `review.requiresReview`   | boolean       | Señal consolidada para revisión manual.                                   |
| `review.reasons`          | string\[]     | Razones legibles por máquina.                                             |
| `review.ocrVerdict`       | string o null | `approve_recommended` o `needs_review`.                                   |
| `review.ocrConfidence`    | number o null | Confianza OCR de 0 a 100.                                                 |

## `exchange`

| Campo                  | Tipo     | Significado                                                       |
| ---------------------- | -------- | ----------------------------------------------------------------- |
| `targetCurrency`       | string   | Moneda destino.                                                   |
| `rate`                 | number   | Tasa usada; moneda origen dividida por esta tasa produce destino. |
| `rateDate`             | ISO 8601 | Fecha efectiva.                                                   |
| `rateSource`           | string   | Fuente como `bcv_usd`, `manual` o `api_auto`.                     |
| `convertedAmount`      | number   | Monto convertido en unidades mayores.                             |
| `convertedAmountMinor` | number   | Monto convertido en unidades menores.                             |

## Documento compacto en pagos

| Campo                   | Tipo            | Significado                                    |
| ----------------------- | --------------- | ---------------------------------------------- |
| `invoiceId`             | string          | Identificador técnico del documento en Cobrix. |
| `invoiceNumber`         | string opcional | Número visible del documento.                  |
| `externalInvoiceId`     | string opcional | Correlación externa conservada.                |
| `source`                | string opcional | Sistema que originó el documento.              |
| `currency`              | string          | Moneda del documento.                          |
| `appliedAmountMinor`    | string opcional | Monto aplicado.                                |
| `remainingBalanceMinor` | string opcional | Saldo después de aplicar.                      |

<Info>
  Los campos son aditivos: tu parser debe ignorar propiedades desconocidas y tolerar `null` donde el contrato lo permita.
</Info>