Tipos de Eventos

Estos son los posibles eventos que puedes recibir a través de los webhooks de la API de Fint, junto con la estructura de datos de cada evento.

payment.created

`payment.created`

Este evento indica que un pago ha sido creado exitosamente. El origen del pago puede ser un registro manual o una transacción realizada por un usuario a través del portal utilizando cualquier método de pago disponible.

Ejemplo de Payload:

{
  "id": "webhook_local_da7beb710d61463bbd55209538b59a37",
  "event": "payment.created",
  "attempt": 3,
  "timestamp": 1716193401008,
  "externalReference": null,
  "data": {
    "paymentId": 22,
    "paymentMethod": "CREDIT_CARD",
    "isManual": false,
    "invoicesPaid": [{
      "id": 123,
      "externalReference": "ref-123",
      "uniqueId": "AAA-0000",
    }],
  }
}

Estructura de los Datos del Evento:

interface PaymentCreatedData {
  paymentId: number;
  paymentMethod: string;
  isManual: boolean;
  invoicesPaid: {
    id: number
    externalReference: string | null,
    uniqueId: string,
  }[];
}

Descripción de Campos:

paymentId (number): Identificador único del pago.
paymentMethod (string): Método de pago utilizado para realizar el pago.
isManual (boolean): Indica si el pago fue registrado manualmente por un usuario.
invoicesPaid (array): Lista de facturas pagadas con este pago.
- id (number): Identificador único de la factura.
- externalReference (string): Referencia externa asociada a la factura.
- uniqueId (string): Identificador único de la factura, compuesto por un prefijo y un número único. -

Para obtener más información sobre el pago podemos consultar el pago por id en la API.

contact.status

`contact.status`

Este evento notifica cambios en el estado del ciclo de vida de un contacto.

Ejemplo de Payload:

{
  "id": "webhook_local_da7beb710d61463bbd55209538b59a37",
  "event": "contact.status",
  "attempt": 1,
  "timestamp": 1716193401008,
  "externalReference": null,
  "data": {
    "contactId": 12345,
    "previousStatus": "NOT_DUE",
    "newStatus": "PAST_DUE",
    "timestamp": 1716193401008,
    "invoices": [
      {
        "invoiceId": 5678,
        "totalPending": "150.75",
        "expirationDate": "2024-05-20",
        "createdDate": "2024-04-20",
        "status": "PENDING",
        "externalReference": "ref-123"
      },
      {
        "invoiceId": 6789,
        "totalPending": "200.00",
        "expirationDate": "2024-05-22",
        "createdDate": "2024-04-22",
        "status": "PENDING",
        "externalReference": "ref-456"
      }
    ],
    "totalPending": "350.75",
    "metadata": {
      "customField1": "value1",
      "customField2": "value2"
    }
  }
}

Estructura de los Datos del Evento:

interface ContactStatusData {
  contactId: number;
  previousStatus: 'ACCOUNT_OPENED' | 'NOT_DUE' | 'PAST_DUE' | 'ACCOUNT_SETTLED' | 'INACTIVE';
  newStatus: 'ACCOUNT_OPENED' | 'NOT_DUE' | 'PAST_DUE' | 'ACCOUNT_SETTLED' | 'INACTIVE';
  timestamp: number;
  invoices?: InvoiceDetail[];
  totalPending?: string;
  metadata?: any;
  externalReference: string | null;
}

interface InvoiceDetail {
  invoiceId: number;
  totalPending: string;
  expirationDate: string;
  createdDate: string;
  status: 'PENDING' | 'PAID' | 'PARTIALLY_PAID';
  externalReference: string | null;
}

Descripción de Campos:

contactId (number): Identificador único del contacto.
previousStatus (string): Estado anterior del contacto (ACCOUNT_OPENED, NOT_DUE, PAST_DUE, ACCOUNT_SETTLED, INACTIVE).
newStatus (string): Nuevo estado del contacto (ACCOUNT_OPENED, NOT_DUE, PAST_DUE, ACCOUNT_SETTLED, INACTIVE).
timestamp (number): Marca de tiempo del cambio de estado.
invoices (opcional): Lista de facturas vencidas que el contacto adeuda.
- invoiceId (number): Identificador de la factura.
- totalPending (string): Monto adeudado de la factura.
- expirationDate (string): Fecha de vencimiento de la factura.
- createdDate (string): Fecha de emisión de la factura.
- status (string): Estado actual de la factura (PENDING, PAID, PARTIALLY_PAID).
totalPending (opcional): Suma total de todas las facturas vencidas.
metadata (opcional): Objeto de datos personalizados añadidos por el usuario al crear el contacto. Este campo puede contener cualquier información adicional relevante para el usuario.
externalReference (opcional): Referencia externa que se asocia al contacto al momento de la creación.

Al subscribirnos a contact.status nos llegará una notificación por cada cambio de estado.

Más información sobre los estados de un contacto en la documentación de Contactos.

Más eventos próximamente.

Ejemplo de implementación

Para manejar estos webhooks en tu código, puedes usar una estructura genérica y luego verificar el tipo de evento para deserializar los datos específicos del evento.

Ejemplo en TypeScript:

function handleWebhook<T>(webhookBody: WebhookBody<T>) {
  switch (webhookBody.event) {
    case "payment.created":
      const paymentData = webhookBody.data as PaymentCreatedData;
      // Manejar el evento de pago creado
      break;
    case "contact.status":
      const contactStatusData = webhookBody.data as ContactStatusData;
      // Manejar el evento de cambio de estado del contacto
      break;
    // Agregar más casos según nuevos eventos
    default:
      console.error("Evento desconocido:", webhookBody.event);
  }
}

On this page

Ejemplo de implementación

Estos son los posibles eventos que puedes recibir a través de los webhooks de la API de Fint, junto con la estructura de datos de cada evento.

payment.created

`payment.created`

Ejemplo de Payload:

{
  "id": "webhook_local_da7beb710d61463bbd55209538b59a37",
  "event": "payment.created",
  "attempt": 3,
  "timestamp": 1716193401008,
  "externalReference": null,
  "data": {
    "paymentId": 22,
    "paymentMethod": "CREDIT_CARD",
    "isManual": false,
    "invoicesPaid": [{
      "id": 123,
      "externalReference": "ref-123",
      "uniqueId": "AAA-0000",
    }],
  }
}

Estructura de los Datos del Evento:

interface PaymentCreatedData {
  paymentId: number;
  paymentMethod: string;
  isManual: boolean;
  invoicesPaid: {
    id: number
    externalReference: string | null,
    uniqueId: string,
  }[];
}

Descripción de Campos:

paymentId (number): Identificador único del pago.
paymentMethod (string): Método de pago utilizado para realizar el pago.
isManual (boolean): Indica si el pago fue registrado manualmente por un usuario.
invoicesPaid (array): Lista de facturas pagadas con este pago.
- id (number): Identificador único de la factura.
- externalReference (string): Referencia externa asociada a la factura.
- uniqueId (string): Identificador único de la factura, compuesto por un prefijo y un número único. -

Para obtener más información sobre el pago podemos consultar el pago por id en la API.

contact.status

`contact.status`

Este evento notifica cambios en el estado del ciclo de vida de un contacto.

Ejemplo de Payload:

{
  "id": "webhook_local_da7beb710d61463bbd55209538b59a37",
  "event": "contact.status",
  "attempt": 1,
  "timestamp": 1716193401008,
  "externalReference": null,
  "data": {
    "contactId": 12345,
    "previousStatus": "NOT_DUE",
    "newStatus": "PAST_DUE",
    "timestamp": 1716193401008,
    "invoices": [
      {
        "invoiceId": 5678,
        "totalPending": "150.75",
        "expirationDate": "2024-05-20",
        "createdDate": "2024-04-20",
        "status": "PENDING",
        "externalReference": "ref-123"
      },
      {
        "invoiceId": 6789,
        "totalPending": "200.00",
        "expirationDate": "2024-05-22",
        "createdDate": "2024-04-22",
        "status": "PENDING",
        "externalReference": "ref-456"
      }
    ],
    "totalPending": "350.75",
    "metadata": {
      "customField1": "value1",
      "customField2": "value2"
    }
  }
}

Estructura de los Datos del Evento:

interface ContactStatusData {
  contactId: number;
  previousStatus: 'ACCOUNT_OPENED' | 'NOT_DUE' | 'PAST_DUE' | 'ACCOUNT_SETTLED' | 'INACTIVE';
  newStatus: 'ACCOUNT_OPENED' | 'NOT_DUE' | 'PAST_DUE' | 'ACCOUNT_SETTLED' | 'INACTIVE';
  timestamp: number;
  invoices?: InvoiceDetail[];
  totalPending?: string;
  metadata?: any;
  externalReference: string | null;
}

interface InvoiceDetail {
  invoiceId: number;
  totalPending: string;
  expirationDate: string;
  createdDate: string;
  status: 'PENDING' | 'PAID' | 'PARTIALLY_PAID';
  externalReference: string | null;
}

Descripción de Campos:

contactId (number): Identificador único del contacto.
previousStatus (string): Estado anterior del contacto (ACCOUNT_OPENED, NOT_DUE, PAST_DUE, ACCOUNT_SETTLED, INACTIVE).
newStatus (string): Nuevo estado del contacto (ACCOUNT_OPENED, NOT_DUE, PAST_DUE, ACCOUNT_SETTLED, INACTIVE).
timestamp (number): Marca de tiempo del cambio de estado.
invoices (opcional): Lista de facturas vencidas que el contacto adeuda.
- invoiceId (number): Identificador de la factura.
- totalPending (string): Monto adeudado de la factura.
- expirationDate (string): Fecha de vencimiento de la factura.
- createdDate (string): Fecha de emisión de la factura.
- status (string): Estado actual de la factura (PENDING, PAID, PARTIALLY_PAID).
totalPending (opcional): Suma total de todas las facturas vencidas.
metadata (opcional): Objeto de datos personalizados añadidos por el usuario al crear el contacto. Este campo puede contener cualquier información adicional relevante para el usuario.
externalReference (opcional): Referencia externa que se asocia al contacto al momento de la creación.

Al subscribirnos a contact.status nos llegará una notificación por cada cambio de estado.

Más información sobre los estados de un contacto en la documentación de Contactos.

Más eventos próximamente.

Ejemplo de implementación

Para manejar estos webhooks en tu código, puedes usar una estructura genérica y luego verificar el tipo de evento para deserializar los datos específicos del evento.

Ejemplo en TypeScript:

function handleWebhook<T>(webhookBody: WebhookBody<T>) {
  switch (webhookBody.event) {
    case "payment.created":
      const paymentData = webhookBody.data as PaymentCreatedData;
      // Manejar el evento de pago creado
      break;
    case "contact.status":
      const contactStatusData = webhookBody.data as ContactStatusData;
      // Manejar el evento de cambio de estado del contacto
      break;
    // Agregar más casos según nuevos eventos
    default:
      console.error("Evento desconocido:", webhookBody.event);
  }
}

On this page

Ejemplo de implementación

Tipos de Eventos

`payment.created`

Descripción de Campos:

`contact.status`

Descripción de Campos:

Ejemplo de implementación

Contactos - Operaciones Básicas

Contactos - Gestión de Items

Contactos - Gestión de Tags

Contactos - Estados

Contactos - Notas

Etiquetas (Tags)

Facturas

Pagos

Webhook

Tipos de Eventos

`payment.created`

Descripción de Campos:

`contact.status`

Descripción de Campos:

Ejemplo de implementación

​Ejemplo de implementación

Contactos - Operaciones Básicas

Contactos - Gestión de Items

Contactos - Gestión de Tags

Contactos - Estados

Contactos - Notas

Etiquetas (Tags)

Facturas

Pagos

Webhook

​Ejemplo de implementación

Ejemplo de implementación

Ejemplo de implementación