Webhooks

Envíe notificaciones de eventos en tiempo real desde facturapy.me a servicios externos. Elija el tipo de evento, luego agregue su URL de punto final, token secreto y nombre su nuevo webhook.

Un webhook consta de:
  • Una URL donde el evento del webhook sera enviado.
  • Un tipo de evento que sera enviado a la URL especificada.
  • Un Token Secreto, que puede ser usado para verificar los datos enviados.

Cuando un webhook es disparado, una petición POST será hecha a la URL configurada junto a datos en formato JSON específicos para el tipo de evento.

Administrando Webhooks

Los Webhooks pueden ser administrados desde su perfil en facturapy.me en la pestaña Integraciones

Eventos Soportados

Los eventos soportados a la fecha son:

  • Producto Creado
  • Producto Modificado
  • Stock
  • DTE Emitido
  • DTE Recibido
  • Carga de Folios
  • Anulación de Folios
  • Certificado Digital por Vencer
  • Certificado Digital Vencido

Política de Reenvío

Se considerará como errónea una petición si no recibimos ninguna respuesta 2xx (http code 200-299) dentro de los 30 segundos posteriores al envío del webhook.

Si una petición falla, reintentaremos realizarla nuevamente 3 veces cada 30 segundos.

Verificando la firma del Webhook

Cada evento webhook es firmado via HMAC usando el token secreto del webhook. El algoritmo usado para generar la firma es HMAC-SHA256. Esta firma es enviada en cada petición en la cabecera como X-FACTURAPYME-SIGNATURE.

Ejemplos:

PHP

<?php
const WEBHOOK_SECRET = 'montana';
function verificaFirma($body, $signature) {
    $digest = hash_hmac('sha256', $body, WEBHOOK_SECRET);
    return $signature === $digest;
}
if (!verificaFirma(file_get_contents('php://input'), $_SERVER['HTTP_X_FACTURAPYME_SIGNATURE'])) {
    //Error de verificación
    return;
}
//verificación Correcta
//Magic Goes Here...

Node.js

const WEBHOOK_SECRET = 'montana';
const crypto = require('crypto');
const express = require('express');
const bodyParser = require('body-parser');
const app = express();
app.use(bodyParser.raw({
    type: '*/*'
}));

function verificaFirma(req) {
    const payload = req.body;
    const signature = req.get('x-facturapyme-signature') || '';
    const digest = crypto
        .createHmac('sha256', WEBHOOK_SECRET)
        .update(payload)
        .digest('hex');
    return signature === digest;
};
app.post('/webhook', (req, res) => {
    if (!verificaFirma(req)) {
        //Error de verificación
        res.status(200).send('.');
        return;
    }
    //verificación Correcta
    //Magic Goes Here...
    res.status(200).send('..');
});
app.listen(3000);

Python

import hmac
from hashlib import sha256
from flask import Flask, request
WEBHOOK_SECRET = 'montana'
app = Flask(__name__)

def verificaFirma():
    digest = hmac.new(bytes(WEBHOOK_SECRET, 'utf-8'), msg=request.data, digestmod=sha256)
    return digest.hexdigest() == request.headers.get('x-facturapyme-signature')

@app.route('/webhook', methods=['POST'])
def webhook():
    if not verificaFirma():
        #Error de verificación
        return '.'
    #verificación Correcta
    #Magic Goes Here...
    return '..'

Datos de Eventos Webhook

Cada evento enviado tiene la siguiente cabecera

Cabecera eventos
Atributo Tipo Descripción
evento String Tipo de evento
fecha Numérico Fecha de generación del evento. Formato Y-m-d H:i:s
empresa String RUT de la empresa cliente de facturapy.me
data Array Array con los datos del evento

Evento Producto Creado
producto:creado

Este evento se genera cuando se crea un nuevo producto en la plataforma

Datos enviados
Atributo Tipo Descripción
id Numérico Id del producto
barcode String Código de barra o código interno del producto
producto String Nombre del Producto
familia Objeto Familia del producto. Ver más abajo
precio Numérico Precio de venta del producto
exento Booleano Indica si el producto esta exento de IVA
Objeto Familia
Atributo Tipo Descripción
id Numérico Id de la familia
nombre String Nombre de la familia
Ejemplo 
{
    "evento": "producto:creado",
    "fecha": "2020-11-17 15:40:33",
    "empresa": "76538242-4",
    "data": [
        {
            "id": 44,
            "barcode": "EMP001",
            "producto": "Empanadas",
            "familia": {
                "id": "4",
                "nombre": "Producto Genérico"
            },
            "precio": 1500,
            "exento": false
        }
    ]
}

Evento Producto Modificado
producto:actualizado

Este evento se genera cuando se modifican los productos en la plataforma

Los datos enviados son los mismos que los del evento anterior. Ver arriba

Ejemplo 
{
    "evento": "producto:actualizado",
    "fecha": "2020-11-17 15:40:33",
    "empresa": "76538242-4",
    "data": [
        {
            "id": 44,
            "barcode": "EMP001",
            "producto": "Empanadas",
            "familia": {
                "id": "4",
                "nombre": "Producto Genérico"
            },
            "precio": 1600,
            "exento": false
        }
    ]
}

Evento Stock
stock

Este evento se genera cuando se modifican el stock de algún producto en la plataforma

Datos enviados
Atributo Tipo Descripción
Los datos enviados son los mismos que los de los eventos anteriores. Ver arriba
bodega Numérico Id de la bodega
stock Numérico Cantidad de inventario del producto
Ejemplo 
{
    "evento": "stock",
    "fecha": "2020-11-17 15:40:33",
    "empresa": "76538242-4",
    "data": [
        {
            "id": 44,
            "barcode": "EMP001",
            "producto": "Empanadas",
            "familia": {
                "id": 4,
                "nombre": "Producto Genérico"
            },
            "precio": 1600,
            "exento": false,
            "bodega": 1,
            "stock": 42
        }
    ]
}

DTE Emitido
dte:emitido

Este evento se genera cuando se crea un documento tributario en la plataforma

Datos enviados
Atributo Tipo Descripción
folio Numérico Folio del documento emitido
tipo Numérico Tipo de documento emitido. Ver listado más abajo
pdf Url Link para descargar el documento en formato PDF
Tipo de Documentos Electrónicos
  • 33 Factura
  • 34 Factura exenta
  • 39 Boleta
  • 41 Boleta exenta
  • 43 Liquidación factura
  • 46 Factura de compra
  • 52 Guía de despacho
  • 56 Nota de débito
  • 61 Nota de crédito
  • 110 Factura de exportación
  • 111 Nota de débito de exportación
  • 112 Nota de crédito de exportación
Ejemplo 
{
    "evento": "dte:emitido",
    "fecha": "2020-11-17 15:40:33",
    "empresa": "76538242-4",
    "data": [
        {
            "folio": 209,
            "tipo": 33,
            "pdf": "https://ruta_documento_electronico_en_formato_pdf..."
        }
    ]
}

DTE Recibido
dte:recibido

Este evento se genera cuando se recibe un documento tributario en la plataforma

Datos enviados
Atributo Tipo Descripción
rut_emisor String RUT del Proveedor (Emisor del Documento)
fecha_emision Fecha Fecha de emisión del documento recibido. Formato Y-m-d
folio Numérico Folio del documento recibido
tipo Numérico Tipo de documento recibido. Ver listado más arriba
neto Numérico Total Neto del documento
iva Numérico IVA Total del documento
total Numérico Total Bruto del documento
xml Url Link para descargar el documento en formato XML
pdf Url Link para descargar el documento en formato PDF
Ejemplo 
{
    "evento": "dte:recibido",
    "fecha": "2020-11-17 15:40:33",
    "empresa": "76538242-4",
    "data": [
        {
            "rut_emisor":"60803000-K",
            "fecha_emision":"2020-11-17",
            "folio": 10042004,
            "tipo": 33,
            "neto": 16790,
            "iva": 3190,
            "total": 19980,
            "xml": "https://ruta_documento_electronico_en_formato_xml..."
            "pdf": "https://ruta_documento_electronico_en_formato_pdf..."
        }
    ]
}

Carga de Folios
caf:cargado

Este evento se genera cuando se cargan folios en la plataforma

Datos enviados
Atributo Tipo Descripción
tipo Numérico Tipo de documento. Ver listado arriba
desde Numérico Folio inicial
hasta Numérico Folio final
fecha_asignacion Fecha Fecha de asignación de folios. Formato Y-m-d
fecha_vencimiento Fecha Fecha en que vencen los folios. Formato Y-m-d
Ejemplo 
{
    "evento": "caf:cargado",
    "fecha": "2020-11-17 15:40:33",
    "empresa": "76538242-4",
    "data": [
        {
            "tipo": 33,
            "desde": 111,
            "hasta": 610,
            "fecha_asignacion": "2020-11-17",
            "fecha_vencimiento": "2021-05-16"
        }
    ]
}

Anulación de Folios
caf:anulado

Este evento se genera cuando se anulan folios en la plataforma

Datos enviados
Atributo Tipo Descripción
tipo Numérico Tipo de documento. Ver listado arriba
desde Numérico Folio inicial
hasta Numérico Folio final
Ejemplo 
{
    "evento": "caf:anulado",
    "fecha": "2020-11-17 15:40:33",
    "empresa": "76538242-4",
    "data": [
        {
            "tipo": 33,
            "desde": 69,
            "hasta": 110
        }
    ]
}

Certificado Digital por Vencer
cert:por-vencer

Este evento se genera cuando el certificado digital esté por vencer.

Datos enviados
Atributo Tipo Descripción
dias Numérico Cantidad de días que queda para que venza el certificado digital
fecha_vencimiento Fecha Hora Fecha de vencimiento del certificado digital. Formato Y-m-d H:i:s
Ejemplo 
{
    "evento": "cert:por-vencer",
    "fecha": "2020-11-17 15:40:33",
    "empresa": "76538242-4",
    "data": [
        {
            "dias": 14,
            "fecha_vencimiento": "2020-12-01 15:40:30"
        }
    ]
}

Certificado Digital Vencido
cert:vencido

Este evento se genera cuando el certificado esta vencido

Datos enviados
Atributo Tipo Descripción
dias Numérico Cantidad de días que lleva vencido el certificado digital
fecha_vencimiento Fecha Hora Fecha de vencimiento del certificado digital. Formato Y-m-d H:i:s
Ejemplo 
{
    "evento": "cert:por-vencer",
    "fecha": "2020-11-17 15:40:33",
    "empresa": "76538242-4",
    "data": [
        {
            "dias": 10,
            "fecha_vencimiento": "2020-11-07 15:40:06"
        }
    ]
}