Webhooks

Overview

Sistema de webhooks para notificar eventos del sistema a clientes externos mediante HTTP requests asíncronos.

La confiugracion del webhook se puede hacer por el Dashboard -> Integraciones en https://dashboard.cachicamo.app/store/integrations

Configuración por acción: Cada acción puede tener hasta 3 webhooks configurados
Reintentos automáticos: Hasta 5 intentos con 1 hora de espera entre cada uno

Documentación para Clientes (Webhooks que Recibirán)

Eventos Disponibles

Los siguientes eventos pueden ser configurados para recibir notificaciones:

1. `document.created`

Se dispara cuando se crea un documento (factura, nota de débito, nota de crédito, etc.).

Payload:

{
  "id": "invoice-uuid-here",
  "document_type": "INVOICE",
  "action": "document.created",
  "event_at": "2024-01-15T10:30:00Z"
}

Campos:

id (string): UUID del documento creado
document_type (string): Tipo de documento. Valores posibles:
- INVOICE: Factura
- DEBIT_NOTE: Nota de débito
- CREDIT_NOTE: Nota de crédito (refund)
- PROVIDER_INVOICE: Factura de proveedor
- PROVIDER_DEBIT_NOTE: Nota de débito de proveedor
- PROVIDER_CREDIT_NOTE: Nota de crédito de proveedor
- QUOTE: Cotización
action (string): Nombre del evento
event_at (string): Fecha y hora del evento en formato ISO 8601

Nota: Solo se envía el ID del documento, no el objeto completo. El cliente debe consultar el documento usando el ID si necesita más información.

2. `document.updated`

Se dispara cuando un documento cambia después de haber sido creado. El campo change dice qué fue lo que cambió, para poder filtrar el aviso sin consultar el documento en cada notificación.

Payload:

{
  "id": "invoice-uuid-here",
  "document_type": "INVOICE",
  "action": "document.updated",
  "change": "control_number_assigned",
  "event_at": "2024-01-15T10:35:00Z"
}

Campos:

id, document_type, action y event_at: iguales a los de document.created
change (string): qué cambió en el documento. Valores posibles:
- emitted: el documento salió de TO_EMIT y quedó emitido con su número. Ocurre cuando la máquina fiscal imprime después del intento inicial (el sistema reintenta cada 10 segundos) y cuando se confirma un borrador
- control_number_assigned: la imprenta digital entregó el número de control después de emitir. El documento ya existía y ya tenía su número; lo que llega ahora es el manual_control_number
- cancelled: el documento fue anulado
- header_edited: se corrigió el encabezado de un documento de compra o de un documento de venta escrito sobre talonario (número, número de control, fecha de emisión o contraparte)

Nota: change sólo viaja cuando el sistema sabe qué cambió. Un aviso sin change significa "algo cambió, consulta el documento".

Caso típico: cuando se emite por API contra una imprenta digital, la respuesta de POST /invoices/save_preview trae el documento con su número, pero el número de control puede llegar minutos después. En vez de reconsultar la factura cada cierto tiempo, hay que suscribirse a document.updated y atender los avisos con change igual a control_number_assigned.

3. `product.created`

Se dispara cuando se crea un nuevo producto.

Payload:

{
  "payload": {
    "uuid": "product-uuid-here",
    "name": "Producto Ejemplo",
    // ....
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "action": "product.created",
  "event_at": "2024-01-15T10:30:00Z"
}

Nota: Se envía el objeto completo del producto con todos sus campos.

4. `product.updated`

Se dispara cuando se actualiza un producto o cuando se crea/actualiza un precio del producto.

Payload:

{
  "payload": {
    "uuid": "product-uuid-here",
    "name": "Producto Actualizado",
    // ....
  },
  "action": "product.updated",
  "event_at": "2024-01-15T10:35:00Z"
}

Nota: Se envía el objeto completo del producto actualizado.

5. `stock.updated`

Se dispara cuando se actualiza el stock de un producto (inventario).

Payload:

{
  "payload": {
    "user_uuid": "user-uuid-here",
    "store_uuid": "store-uuid-here",
    "product_uuid": "product-uuid-here",
    "quantity_billable": 100.0,
    "quantity_available": 95.0,
    "quantity_locked": 5.0,
    "quantity_transit": 0.0,
    "warehouse_location": "A-1-2",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:35:00Z"
  },
  "action": "stock.updated",
  "event_at": "2024-01-15T10:35:00Z"
}

6. `document_to_pay.created`

Se dispara cuando se crea un documento por pagar (cuenta por cobrar o por pagar).

Payload:

{
  "payload": {
    "uuid": "document-to-pay-uuid",
    "document_uuid": "invoice-uuid-here",
    "document_type": "INVOICE",
    "status": "PENDING",
    "user_uuid": "user-uuid-here",
    "store_uuid": "store-uuid-here",
    "customer_uuid": "customer-uuid-here",
    "description": "Factura pendiente de pago",
    "currency_uuid": "currency-uuid-here",
    "amount_pending": 100000,
    "original_amount": 100000,
    "amount_payed": 0,
    "is_collect": true,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "action": "document_to_pay.created",
  "event_at": "2024-01-15T10:30:00Z"
}

7. `document_to_pay.updated`

Se dispara cuando cambia el monto pendiente de un documento por pagar ya existente, porque el documento que lo originó se modificó.

Payload: el mismo objeto de document_to_pay.created, con los montos ya recalculados.

{
  "payload": {
    "uuid": "document-to-pay-uuid",
    "document_uuid": "invoice-uuid-here",
    "document_type": "INVOICE",
    "status": "PENDING",
    "amount_pending": 80000,
    "original_amount": 100000,
    "amount_payed": 20000,
    "updated_at": "2024-01-15T10:32:00Z"
  },
  "action": "document_to_pay.updated",
  "event_at": "2024-01-15T10:32:00Z"
}

8. `document_to_pay.payment`

Se dispara cuando se registra un pago parcial o total de un documento por pagar.

Payload:

{
  "payload": {
    "uuid": "payment-uuid-here",
    "document_to_pay_uuid": "document-to-pay-uuid",
    "payment_method_uuid": "payment-method-uuid",
    "currency_uuid": "currency-uuid-here",
    "document_total_payment": 50000,
    "origin_total_payment": 50000,
    "created_at": "2024-01-15T10:35:00Z"
  },
  "action": "document_to_pay.payment",
  "event_at": "2024-01-15T10:35:00Z"
}

9. `document_to_pay.payment_cancelled`

Se dispara cuando se anula un pago ya registrado de un documento por pagar. El monto vuelve a quedar pendiente.

Payload: el mismo objeto de document_to_pay.payment, el del pago que se anuló.

{
  "payload": {
    "uuid": "payment-uuid-here",
    "document_to_pay_uuid": "document-to-pay-uuid",
    "payment_method_uuid": "payment-method-uuid",
    "currency_uuid": "currency-uuid-here",
    "document_total_payment": 50000,
    "origin_total_payment": 50000,
    "created_at": "2024-01-15T10:35:00Z"
  },
  "action": "document_to_pay.payment_cancelled",
  "event_at": "2024-01-15T11:05:00Z"
}

10. `document_to_pay.payed`

Se dispara cuando un documento por pagar se marca como completamente pagado.

Payload:

{
  "payload": {
    "uuid": "document-to-pay-uuid",
    "document_uuid": "invoice-uuid-here",
    "document_type": "INVOICE",
    "status": "PAID",
    "amount_pending": 0,
    "amount_payed": 100000,
    "payed_at": "2024-01-15T10:40:00Z"
  },
  "action": "document_to_pay.payed",
  "event_at": "2024-01-15T10:40:00Z"
}

11. `retained.reference_assigned`

Se dispara cuando se asigna un reference a una retención de factura de venta.

Payload:

{
  "payload": {
    "uuid": "retained-uuid-here",
    "tax_uuid": "tax-uuid-here",
    "invoice_uuid": "invoice-uuid-here",
    "reference": "REF-001",
    "status": "ASSIGNED",
    "retained_type": "WITHHELD_BY_SUPPLIER",
    "retained_amount": 10000,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:35:00Z"
  },
  "action": "retained.reference_assigned",
  "event_at": "2024-01-15T10:35:00Z"
}

12. `retained.group_created`

Se dispara cuando se crea un comprobante de retención para facturas de compra.

Payload:

{
  "payload": {
    "uuid": "retained-uuid-here",
    "tax_uuid": "tax-uuid-here",
    "invoice_uuid": "invoice-uuid-here",
    "taxes_retained_group_uuid": "group-uuid-here",
    "reference": "GRP-001",
    "status": "ASSIGNED",
    "retained_type": "WITHHELD_BY_ME",
    "retained_amount": 10000,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:35:00Z"
  },
  "action": "retained.group_created",
  "event_at": "2024-01-15T10:35:00Z"
}

13. `retained.group_cancelled`

Se dispara cuando se anula un comprobante de retención.

Payload:

{
  "payload": {
    "uuid": "retained-uuid-here",
    "tax_uuid": "tax-uuid-here",
    "invoice_uuid": "invoice-uuid-here",
    "taxes_retained_group_uuid": "group-uuid-here",
    "status": "CANCELLED",
    "cancel_reason": "Error en el comprobante",
    "cancelled_at": "2024-01-15T10:40:00Z",
    "retained_amount": 10000
  },
  "action": "retained.group_cancelled",
  "event_at": "2024-01-15T10:40:00Z"
}

14. `retained.cancelled`

Se dispara cuando se anula una retención individual.

Payload:

{
  "payload": {
    "uuid": "retained-uuid-here",
    "tax_uuid": "tax-uuid-here",
    "invoice_uuid": "invoice-uuid-here",
    "status": "CANCELLED",
    "cancel_reason": "Error en la retención",
    "cancelled_at": "2024-01-15T10:40:00Z",
    "retained_amount": 10000
  },
  "action": "retained.cancelled",
  "event_at": "2024-01-15T10:40:00Z"
}

Formato del Mensaje HTTP

Cuando se recibe un webhook, el sistema enviará una petición HTTP con:

Método: El configurado en method (típicamente POST)
URL: La configurada en destination
Headers: Los headers personalizados configurados. Nota: El sistema siempre establece Content-Type: application/json automáticamente, ignorando cualquier valor de Content-Type que se configure en los headers personalizados.
Body: El payload JSON con payload, action y event_at

Ejemplo de petición HTTP:

POST https://example.com/webhook HTTP/1.1
Content-Type: application/json
X-Custom-Header: value

{
  "payload": {
    "uuid": "product-uuid-here",
    "name": "Producto Ejemplo",
    ...
  },
  "action": "product.created",
  "event_at": "2024-01-15T10:30:00Z"
}

Características del Sistema

Reintentos Automáticos

Si un webhook falla, se reintenta automáticamente hasta 5 veces
Intervalo entre reintentos: 1 hora
Estados de destino:
- pending: Pendiente de envío
- retry: Falló y será reintentado
- sent: Enviado exitosamente
- failed: Falló después de 5 intentos

Overview​

Documentación para Clientes (Webhooks que Recibirán)​

Eventos Disponibles​

1. document.created​

2. document.updated​

3. product.created​

4. product.updated​

5. stock.updated​

6. document_to_pay.created​

7. document_to_pay.updated​

8. document_to_pay.payment​

9. document_to_pay.payment_cancelled​

10. document_to_pay.payed​

11. retained.reference_assigned​

12. retained.group_created​

13. retained.group_cancelled​

14. retained.cancelled​

Formato del Mensaje HTTP​

Características del Sistema​

Reintentos Automáticos​

Overview

Documentación para Clientes (Webhooks que Recibirán)

Eventos Disponibles

1. `document.created`

2. `document.updated`

3. `product.created`

4. `product.updated`

5. `stock.updated`

6. `document_to_pay.created`

7. `document_to_pay.updated`

8. `document_to_pay.payment`

9. `document_to_pay.payment_cancelled`

10. `document_to_pay.payed`

11. `retained.reference_assigned`

12. `retained.group_created`

13. `retained.group_cancelled`

14. `retained.cancelled`

Formato del Mensaje HTTP

Características del Sistema

Reintentos Automáticos