BillptCreateInvoiceFromShopify

Descripción

Recibe el payload de un pedido Shopify (desde un webhook o nodo anterior) y crea automáticamente un documento fiscal en Bill.pt. Gestiona el flujo completo:

1. Busca el contacto del cliente por email en Bill.pt — lo crea desde billing_address si no existe
2. Resuelve los IDs de impuesto IVA cruzando los rates de tax_lines de Shopify con un grupo DataStore de impuestos
3. Calcula precios netos (eliminando IVA cuando taxes_included: true)
4. Crea el documento (FT, FR, ORC o NC) con la serie correcta

Configuración

Campo	Tipo	Requerido	Descripción
credentials_id	credentials	Si	Credencial Bill.pt
document_type	select	Si	FT (Factura), FR (Fatura-Recibo), ORC (Presupuesto), NC (Nota de Crédito)
tax_group	text	No	Nombre del grupo DataStore con el mapa de impuestos (ver sección Mapa de Impuestos)
default_tax_id	text	No	ID de impuesto fallback si no hay grupo DataStore o no hay coincidencia
series_group	text	No	Nombre del grupo DataStore con las series Bill.pt (row_data = objeto serie con id y nome)
series_name	text	No	Nombre de la serie a resolver desde el grupo DataStore (ej: FHPT)
series_id	text	No	ID numérico directo de la serie — tiene prioridad sobre series_name
use_order_date	select	No	Usar fecha del pedido Shopify (yes) o fecha actual (no). Default: yes. Usar no si aparece el error 292 (series comunicadas a AT pueden rechazar facturas backdateadas)
finalized	select	No	yes = documento finalizado (default), no = borrador
exchange_rate	text	No	Tipo de cambio respecto al EUR (default: 1). Solo para pedidos en moneda distinta a EUR
contact_id	text	No	Override: usar este contacto Bill.pt en lugar de buscar por email
observations	textarea	No	Observaciones adicionales. La referencia al pedido Shopify se anade siempre automáticamente

Credenciales

Requiere una credencial de tipo billpt con:

• API Token: Token de acceso a la API de Bill.pt
• Environment: production o sandbox

Mapa de Impuestos (DataStore)

Crea un grupo DataStore (ej: billpt_taxes) con los datos del nodo BillptGetTaxes. Cada fila debe tener row_data con el objeto completo de impuesto de Bill.pt (id, valor, nome).

El nodo hace coincidir cada tax_line de Shopify convirtiendo el rate decimal a porcentaje entero:

tax_line.rate Shopify	Convertido	valor coincide	imposto_id resuelto
0.23	23	IVA 23	33891
0.13	13	IVA 13	33892
0.06	6	IVA 6	33893

Orden de coincidencia: título del tax_line → entero porcentaje → string decimal → fallback default_tax_id.

Mapa de Series (DataStore)

Crea un grupo DataStore (ej: billpt_series) con los datos del nodo BillptGetSeries. Configura series_group: billpt_series y series_name: FHPT para resolver automáticamente el ID de serie.

Si series_id esta definido directamente, tiene prioridad.

Calculo de Precios

Cuando el pedido Shopify tiene taxes_included: true, el nodo extrae el precio neto antes de crear el documento:

precio_neto = precio_shopify / (1 + tax_rate)

Los descuentos (total_discount) se incorporan directamente en el precio unitario:

precio_neto_final = precio_neto - (total_discount / cantidad / (1 + tax_rate))

Los artículos con price == 0 se omiten.

Entrada

Entrada esperada: objeto Order de Shopify (desde webhook o API Shopify). Campos clave utilizados:

{
  "id": 6684429451477,
  "order_number": 14522,
  "email": "cliente@ejemplo.com",
  "taxes_included": true,
  "currency": "EUR",
  "created_at": "2025-03-24T10:00:00Z",
  "billing_address": {
    "name": "Juan Garcia",
    "address1": "Rua Exemplo 123",
    "city": "Lisboa",
    "zip": "1000-001",
    "country_code": "PT",
    "phone": "+351900000000"
  },
  "line_items": [
    {
      "title": "Nombre Producto",
      "price": "25.95",
      "quantity": 1,
      "total_discount": "0.00",
      "tax_lines": [{ "title": "IVA 23", "rate": 0.23, "price": "4.86" }]
    }
  ]
}

Salida

{
  "success": true,
  "document": { ... },
  "document_id": 789,
  "document_number": "FT FHPT/2025/1",
  "contact_id": 212478,
  "total": 25.95,
  "shopify_order_id": 6684429451477,
  "shopify_order_number": 14522,
  "message": "Documento FT FHPT/2025/1 creado para pedido Shopify 14522"
}

Error 292

El error {"error": ["292"]} de Bill.pt indica que la serie rechaza la fecha del documento. Ocurre con series comunicadas a la AT en Portugal cuando la fecha de la factura es demasiado antigua.

Solución: Establece use_order_date: no para usar la fecha actual en lugar de la fecha del pedido Shopify.

Notas

• Si no se encuentra el email del cliente en Bill.pt, se crea un contacto nuevo. La busqueda puede fallar silenciosamente si la API de Bill.pt no soporta el parámetro pesquisa — en ese caso siempre se crea un nuevo contacto.
• La referencia al pedido Shopify (Shopify Order #XXXXX) se anade siempre a las observaciones.
• Para pedidos en moneda no-EUR, configura exchange_rate con el tipo de cambio correspondiente.
• Usa finalized: no para crear borradores antes de finalizar.

Nodos Relacionados

• BillptGetTaxes - Obtener IDs de impuestos para construir el grupo DataStore
• BillptGetSeries - Obtener IDs de series para construir el grupo DataStore
• BillptGetContacts - Buscar contactos existentes
• BillptCreateDocument - Crear documentos manualmente
• BillptSendDocumentEmail - Enviar la factura por email
• BillptCreateReceipt - Crear recibo para la factura