Reciba avisos con webhooks

Qué es un webhookCopiar enlace a esta sección

Un webhook es una dirección de su servidor a la que Fiscalisto le manda un aviso cada vez que algo cambia en una factura o constancia de retenciones de su cuenta API. Así su sistema no tiene que preguntar a cada rato: por ejemplo, se entera cuando el cliente acepta una cancelación días después de pedirla. Cada aviso trae el comprobante completo, igual que GET /v1/invoices/{id} o GET /v1/retentions/{id}. También hay avisos cuando termina un lote, cuando un cliente manda sus datos fiscales y cuando termina una descarga del SAT (Descarga del SAT terminada o Descarga del SAT fallida).

Los avisos que mandamos son:

• Factura timbrada (invoice.stamped).
• Factura rechazada (invoice.failed): el SAT o el PAC no la aceptaron.
• Factura cancelada (invoice.canceled).
• Cancelación en espera del cliente (invoice.cancellation_pending).
• Cancelación rechazada (invoice.cancellation_rejected): el cliente dijo que no o la solicitud venció; puede pedirla otra vez.
• Constancia de retenciones timbrada (retention.stamped), Constancia de retenciones rechazada (retention.failed) y Constancia de retenciones cancelada (retention.canceled): una constancia se cancela en el momento, sin esperar al receptor.
• Lote de facturas terminado (invoice_batch.completed): ya no queda ninguna factura del lote por timbrar; trae cuántas se timbraron y cuántas no.

Paso a pasoCopiar enlace a esta sección

1. Abra Webhooks en el modo que necesita y pulse Nuevo webhook.
2. En Dirección escriba la ruta de su servidor que recibirá los avisos; debe empezar con https y ser accesible desde internet. La Descripción es opcional.
3. En Eventos deje Todos o elija Solo algunos y márquelos. Pulse Agregar webhook.
4. Aparece el Secreto del webhook (empieza con whsec_). Guárdelo en su servidor: con él verifica que cada aviso viene de Fiscalisto. Puede verlo después con Ver secreto.
5. En su servidor verifique la firma con el SDK de Fiscalisto para TypeScript, Python, PHP, .NET, Go o Java, o en otros lenguajes con la librería standardwebhooks. En Cómo verificar la firma, en la misma pantalla, elija TypeScript, Python, PHP, C#, Go o Java para ver el ejemplo, y responda con un código 200 en menos de 15 segundos. Procese el aviso después de responder.

Probar su servidorCopiar enlace a esta sección

Para probar su código sin timbrar, elija Mandar evento de prueba en el menú del webhook, escoja el Evento y pulse Mandar. Le mandamos ese aviso una sola vez, firmado como los reales, con una factura de ejemplo (sus id no existen), aunque el webhook no escuche ese evento. En la misma ventana ve el código que contestó su servidor, Lo que contestó y Lo que recibió. Pulse Mandar otro después de cada cambio en su código. Su sistema puede hacer lo mismo con POST /v1/webhook_endpoints/{id}/test.

EjemploCopiar enlace a esta sección

Su tienda guarda las facturas al timbrarlas, pero las cancelaciones las acepta el cliente días después. Agrega un webhook solo con Factura cancelada y Cancelación rechazada. Cuando llega invoice.canceled, su sistema marca el pedido como cancelado sin consultar nada; si llega invoice.cancellation_rejected, avisa a su equipo para hablar con el cliente.

Si los avisos no lleganCopiar enlace a esta sección

Abra Ver entregas en el menú del webhook: cada intento dice el código que respondió su servidor o el error (sin respuesta, redirección). Si su servidor no responde 200, reintentamos durante un día: a los 5 segundos, 5 minutos, 30 minutos, 2, 5 y 10 horas. Cuando su servidor ya funcione, use Reenviar en la entrega. Un webhook que falla todos los reintentos queda Fallando, y si sigue así 5 días se apaga solo (Apagado); vuelva a prenderlo con Encender. Para cambiar el secreto use Cambiar secreto y elija en El secreto actual deja de firmar cuándo se apaga el anterior: En 24 horas o En 1 hora le da tiempo de poner el nuevo en su servidor sin rechazar avisos, porque mientras tanto cada aviso trae las dos firmas. Si cree que se filtró, elija Ahora mismo y ponga el nuevo enseguida. Todos los avisos de los últimos 30 días están en Eventos, y su sistema los consulta con GET /v1/events.