Transacción

Definición de transacción

Una transacción es una acción realizada sobre un documento, como su envío o recepción. Esta acción puede incluir la validación, el registro y el seguimiento del documento para garantizar que se cumplen los requisitos establecidos y que el documento se transfiere correctamente.

Consideramos un documento

• Factura (simplificada, autofactura, ordinaria)
• Presupuesto
• Pedido
• Albarán
• Informe fiscal

Transacciones facturables

Cualquiera de las siguientes se considera una transacción facturable:

• Enviar un documento.
• Recibir un documento.
• Transformar un documento para su descarga (API y APP).

Excepciones

• Descargar una copia en PDF de una factura emitida no se considera facturable.
• Los cambios de estado no se consideran documentos; por tanto, las acciones sobre cambios de estado no se contabilizan como transacciones.
• El evento error_sending: Error de envío (Estado: Error, Esquina C2) no se considera una transacción.

Casos específicos

• Informe fiscal habilitado: Cuando se envía una factura y el informe fiscal está habilitado, el informe correspondiente se genera y envía automáticamente. Que ese informe se facture o no depende de la autoridad fiscal; consulta Facturación por autoridad fiscal más abajo.
• Caso SDI: Cuando se envía una factura transfronteriza, se cobra el envío de la factura a la autoridad fiscal. En este caso, el informe fiscal es la factura enviada a la autoridad fiscal.

Facturación por autoridad fiscal

Habilitar el informe fiscal automático no tiene el mismo coste en todos los regímenes. Tres de ellos facturan una transacción por informe; los otros dos no facturan el informe o lo facturan de forma agregada:

Autoridad fiscal	Facturación del informe fiscal	Efecto por factura
Verifactu	Una transacción por informe fiscal	Enviar una factura genera dos transacciones facturables
TicketBAI	Una transacción por informe fiscal	Enviar una factura genera dos transacciones facturables
SII	Una transacción por informe fiscal	Enviar una factura genera dos transacciones facturables
KSeF	No se factura	Ninguna transacción adicional
DGFiP	Una transacción por ledger	Ninguna transacción por factura, una por declaración agregada

Ledgers. En Verifactu y TicketBAI, un ledger cuenta tantas transacciones como registros contiene: un ledger con 10 registros cuenta como 10 transacciones individuales. Esto no se aplica a las otras dos autoridades que usan ledgers. En DGFiP, el ledger entero cuenta como una sola transacción, y en KSeF el ledger no se factura.

Las declaraciones F10 de la DGFiP se agrupan por periodo civil según el régimen de IVA del declarante. Cada declaración agrupada genera una única transacción, con independencia del número de facturas que contenga: una declaración con 200 facturas cuenta igual que una con dos.

Endpoints de la API que generan una transacción facturable

• Enviar factura
• Crear una factura emitida (con send_after_import: true)
• Importar una factura desde un archivo (con send_after_import: true)
• Obtener una factura con un tipo de documento específico (excepto en formato PDF)
• Generar un informe fiscal a partir de una factura
• Crear un informe fiscal
• Importar un informe fiscal
• Anular un informe fiscal

Nota: los cuatro endpoints de informe fiscal anteriores se facturan según la autoridad fiscal. Consulta Facturación por autoridad fiscal.

Ejemplos de otros endpoints de la API que actualmente no generan una transacción facturable

• Crear una factura emitida (con send_after_import: false)
• Importar una factura desde un archivo (con send_after_import: false)
• Cambiar el estado de una factura
• Validación
• Marcar una factura como reconocida
• Búsqueda (Directorio)

Contadores de transacciones por tipo de documento

Las transacciones pueden registrarse contando cualquiera de los siguientes eventos (1 evento = 1 transacción).

Lista de eventos

• success_sending: Envío exitoso (Estado: Enviado, Esquina C2)
• success_clearing: Proceso de liquidación completado con éxito (ZATCA)
• error_clearing: Error durante el proceso de liquidación (ZATCA)
• notification_c2_state_downloaded: Factura descargada. Corresponde a la esquina C2. Cuando el transporte es “Descarga” y el usuario hace clic en el botón Emitir y Descargar (Estado: Descargada)

Salientes

Facturas emitidas de diferentes tipos (sendable_type: Invoice)

Endpoints de la API:

• Enviar factura
• Importar factura (con el parámetro send_after_import: true)

Eventos:

• success_sending
• error_sending

Eventos no relacionados con la API:

• notification_c2_state_downloaded

Presupuestos (sendable_type: Quote)

Endpoints de la API: Los presupuestos no se pueden enviar a través de la API.

Eventos no relacionados con la API:

• success_sending
• error_sending

Albaranes (sendable_type: DespatchAdvice)

Endpoints de la API: Los albaranes no se pueden enviar a través de la API.

Eventos no relacionados con la API:

• success_sending
• error_sending

Pedidos (sendable_type: Order)

Endpoints de la API:

• Marcar como procesado (este endpoint no genera ninguna transacción)

Eventos no relacionados con la API: Al aceptar o rechazar un pedido (solo desde la interfaz), se envía una respuesta de pedido que genera uno de estos eventos:

• success_sending
• error_sending

Informes fiscales (sendable_type: TaxReport)

Endpoints de la API:

• Enviar factura (si la factura requiere el informe fiscal)
• Crear informe fiscal
• Importar informe fiscal
• Modificar informe fiscal
• Anular informe fiscal
• Anular informe fiscal (legacy)

Eventos:

• success_sending
• error_sending
• success_clearing
• error_clearing

Notas: Cuando tax_authority es Verifactu o TicketBAI (Bizkaia), además de enviar el TaxReport, también se envía un Ledger.

Ledger

Endpoints de la API: Los mismos que para TaxReport.

Eventos:

• success_sending
• error_sending

Entrantes

Facturas recibidas de diferentes tipos (sendable_type: Invoice)

Se genera una transacción cuando se recibe una “factura recibida”. Cuando la factura recibida se crea manualmente o se importa a través de la plataforma, no se contabiliza como una transacción.

Endpoints de la API:

• Importar factura (con issued=false, correspondiente a from_net: 'uploaded')

Pedidos (sendable_type: Order)

Endpoints de la API: Los pedidos no se pueden generar ni enviar a través de la API.

Notas: Se genera una transacción cuando se recibe un pedido. Cuando se importa a través de la plataforma, no se contabiliza como una transacción.

View_as

Llamar a GET /invoices/{id}/as/{document_type_code} genera una nueva transacción facturable siempre que el documento se genere de nuevo a partir de los datos de la factura subyacente. Los siguientes valores de document_type_code son excepciones y no generan ninguna transacción:

• original — devuelve el documento exactamente tal como se envió o importó originalmente, servido desde el almacenamiento. No se produce ninguna regeneración.
• legal — devuelve el documento legal archivado (p. ej., la versión firmada y con sello de tiempo) tal como está almacenado. No se produce ninguna regeneración.
• pdf.invoice y pdf.invoice.signed — aunque el PDF se renderiza bajo demanda, descargar una copia en PDF de una factura emitida no se considera facturable.

Para cualquier otro valor (p. ej., xml.ubl.invoice.bis3, xml.facturae.3.2.2, etc.), se registra una nueva transacción en cada llamada, porque el documento se regenera a partir del objeto de base de datos.

curl --request GET \
  --url https://api.b2brouter.net/invoices/{id}/as/legal \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}'

curl --request GET \
  --url https://api.b2brouter.net/invoices/{id}/as/xml.ubl.invoice.bis3 \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}'

Nota: Si solo necesitas recuperar el documento que ya enviaste o recibiste, usa /as/legal o /as/original en su lugar.

Cómo monitorizar el uso de tus transacciones

Si eres un Partner o Reseller, puedes monitorizar el consumo de transacciones de cada grupo de integración directamente desde el portal de B2Brouter.

Cuando aprovisionas un grupo de integración, ya sea porque gestionas un único grupo empresarial o porque operas como eDocSync, la forma más eficiente de monitorizar el uso total y por cuenta de las transacciones es a través del siguiente endpoint de la API: GET /accounts

Ejemplo de solicitud

curl --request GET \
  --url 'https://api-staging.b2brouter.net/accounts?offset=0&limit=25' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

Ejemplo de respuesta

{
  "accounts": [
    {
      "id": 12345,
      "name": "Ejemplo S.L.",
      ...
      "transactions_count": 24,
      "transactions_count_previous_period": 41,
      "transactions_limit": 100
    },
    {
      "id": 23456,
      "name": "Muster GmbH",
      ...
      "transactions_count": 32,
      "transactions_count_previous_period": 9,
      "transactions_limit": 100
    },
    {
      "id": 34567,
      "name": "Esempio S.r.l.",
      ...
      "transactions_count": 124,
      "transactions_count_previous_period": 326,
      "transactions_limit": 100
    }
    ...
  ]
}

Cada cuenta incluye:

• transactions_count → Transacciones consumidas en el período de facturación actual.
• transactions_count_previous_period → Transacciones consumidas en el período de facturación anterior.
• transactions_limit → Número máximo de transacciones incluidas en la suscripción.

Controlando estos datos, puedes gestionar automáticamente el consumo de cada cuenta y el total general. Esto te permite automatizar los pagos en función del volumen de transacciones para tus clientes finales, o monitorizar tu uso respecto a la cuota acordada y aumentar tu límite de transacciones antes de superarlo.