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. Por tanto, enviar una factura genera dos transacciones facturables.
• Caso Verifactu: Crear y enviar una factura con Verifactu cuenta como dos transacciones facturables, una por la factura y otra por el informe fiscal. El “ledger” cuenta tantos registros como contiene. Un ledger con 10 registros cuenta como 10 transacciones individuales.
• 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.

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

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

Cada vez que se llama a la API view_as con un parámetro document_type diferente de “original” o “legal”, se genera una transacción. Se crea una nueva transacción cada vez que se genera un nuevo documento desde nuestro objeto de base de datos.

Tipos de documento no facturables

original — Devuelve el documento exactamente tal como se envió o importó originalmente, servido desde el almacenamiento. No se produce ninguna regeneración.

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

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.

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}'

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.

Tipos de documento facturables

Cualquier otro valor de document_type regenera el documento en el formato solicitado y cuenta como una transacción facturable.

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.