Skip to main content
POST
/
webhooks
Crear webhook
curl --request POST \
  --url https://api.tupana.ai/v1/webhooks \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "master_entity_id": 123,
  "url": "https://mi-sistema.com/webhook/callback",
  "events": [
    "document.issued",
    "document.delivered",
    "document.rejected"
  ],
  "secret": "mi-clave-secreta-super-segura",
  "is_active": true
}
'
{
  "id": 1,
  "url": "https://mi-sistema.com/webhook/callback",
  "events": [
    "document.issued",
    "document.delivered",
    "document.rejected"
  ],
  "events_display": [
    "Emitido",
    "Entregado",
    "Rechazado SII"
  ],
  "secret": "mi-clave-secreta-super-segura",
  "is_active": true,
  "last_status_code": null,
  "last_sent_at": null,
  "success_rate": 0,
  "last_delivery": null,
  "created_at": "2025-01-13T11:00:00Z",
  "updated_at": "2025-01-13T11:00:00Z"
}
Crea un nuevo webhook para recibir notificaciones automáticas cuando ocurren eventos relacionados con documentos. El webhook se asocia con una entidad específica del usuario autenticado.

​
¿Para qué se usa?

Crea un nuevo webhook para recibir notificaciones automáticas cuando ocurren eventos relacionados con documentos. Útil para:
  • Configurar notificaciones automáticas cuando se emiten documentos
  • Recibir alertas cuando documentos son aceptados o rechazados por el SII
  • Integrar con sistemas externos para procesamiento automático de documentos
  • Monitorear el estado de entrega de documentos importantes

​
Qué hace

  • Crea un nuevo webhook asociado a una entidad específica
  • Configura la URL de callback que recibirá las notificaciones
  • Define los eventos específicos que se notificarán (emitido, entregado, rechazado, pagado, cancelado)
  • Permite configurar una clave secreta para verificar la autenticidad de las notificaciones
  • Establece el estado inicial del webhook (activo o inactivo)

​
Ejemplos de uso

  • Notificaciones de emisión: Configurar un webhook para recibir notificaciones cada vez que se emite un documento
  • Integración con ERP: Conectar el sistema con un ERP externo para procesar documentos automáticamente
  • Alertas de rechazo: Recibir notificaciones inmediatas cuando el SII rechaza un documento

​
Consideraciones Importantes

​
Entidad maestra

Debes especificar el master_entity_id de la entidad para la cual quieres crear el webhook. El usuario debe tener acceso a la entidad especificada.

​
Validación de URL

No puede existir un webhook con la misma URL para la misma entidad. Si intentas crear un webhook duplicado, recibirás un error de validación.

​
Eventos disponibles

  • document.issued - Documento emitido exitosamente
  • document.delivered - Documento entregado al receptor
  • document.rejected - Documento rechazado por el SII
  • document.paid - Documento pagado
  • document.unpaid - Documento revertido de pagado a no pagado
  • document.cancelled - Documento cancelado

Authorizations

​
Authorization
string
header
required

API Key para autenticación. Debe proporcionarse en el header Authorization con el formato: 'Api-Key YOUR-API-KEY' (incluye el prefijo 'Api-Key ' seguido de tu API key)

Body

application/json
​
master_entity_id
integer
required

ID de la entidad maestra para la cual se crea el webhook

Example:

123

​
url
string<uri>
required

URL del endpoint que recibirá las notificaciones

​
events
enum<string>[]
required

Lista de eventos a notificar

Minimum array length: 1
Available options:
document.issued,
document.delivered,
document.rejected,
document.paid,
document.unpaid,
document.cancelled
​
secret
string

Clave secreta para verificar la autenticidad de las notificaciones

Maximum string length: 255
​
is_active
boolean
default:true

Si el webhook está activo

Response

Webhook creado exitosamente

​
id
integer

ID único del webhook

​
url
string<uri>

URL del endpoint que recibe las notificaciones

​
events
enum<string>[]

Lista de eventos configurados

Available options:
document.issued,
document.delivered,
document.rejected,
document.paid,
document.unpaid,
document.cancelled
​
events_display
string[]

Nombres legibles de los eventos

Example:
["Emitido", "Entregado", "Rechazado SII"]
​
secret
string | null

Clave secreta para verificar notificaciones

​
is_active
boolean

Si el webhook está activo

​
last_status_code
integer | null

Último código HTTP de respuesta

​
last_sent_at
string<date-time> | null

Fecha de último envío

​
success_rate
number<float>

Tasa de éxito de entregas (0-100)

Required range: 0 <= x <= 100
​
last_delivery
object

Información de la última entrega

​
created_at
string<date-time>

Fecha de creación

​
updated_at
string<date-time>

Fecha de última actualización