Transacció

Definició de transacció

Una transacció és una acció realitzada sobre un document, com ara el seu enviament o recepció. Aquesta acció pot incloure la validació, el registre i el seguiment del document per garantir que es compleixen els requisits establerts i que el document es transfereix correctament.

Considerem un document

• Factura (simplificada, autofactura, ordinària)
• Pressupost
• Comanda
• Albarà
• Informe fiscal

Transaccions facturables

Qualsevol de les accions següents es considera una transacció facturable:

• Enviar un document.
• Rebre un document.
• Transformar un document per a la descàrrega (API i APP).

Excepcions

• Descarregar una còpia en PDF d’una factura emesa no es considera facturable.
• Els canvis d’estat no es consideren documents; per tant, les accions sobre canvis d’estat no compten com a transaccions.
• L’esdeveniment error_sending: Error d’enviament (Estat: Error, Corner C2) no es considera una transacció.

Casos específics

• Informe fiscal activat: Quan s’envia una factura i l’informe fiscal està activat, l’informe corresponent es genera i s’envia automàticament. Per tant, enviar una factura genera dues transaccions facturables.
• Cas Verifactu: Crear i enviar una factura amb Verifactu compta com dues transaccions facturables, una per a la factura i una per a l’informe fiscal. El “registre” compta tants registres com en conté. Un registre amb 10 registres compta com 10 transaccions individuals.
• Cas SDI: Quan s’envia una factura transfronterera, es cobra l’enviament de la factura a l’autoritat fiscal. En aquest cas, l’informe fiscal és la factura enviada a l’autoritat fiscal.

Endpoints d’API que generen una transacció facturable

• Enviar factura
• Crear una factura emesa (amb send_after_import: true)
• Importar una factura des d’un fitxer (amb send_after_import: true)
• Obtenir una factura amb un tipus de document específic (excepte en format PDF)
• Generar un informe fiscal des d’una factura
• Crear un informe fiscal
• Importar un informe fiscal
• Anul·lar un informe fiscal

Exemples d’altres endpoints d’API que actualment no generen una transacció facturable

• Crear una factura emesa (amb send_after_import: false)
• Importar una factura des d’un fitxer (amb send_after_import: false)
• Canviar l’estat de la factura
• Validació
• Marcar una factura com a reconeguda
• Cerca (Directori)

Comptadors de transaccions per tipus de document

Les transaccions es poden registrar comptant qualsevol dels esdeveniments següents (1 esdeveniment = 1 transacció).

Llista d’esdeveniments

• success_sending: Enviament correcte (Estat: Enviat, Corner C2)
• success_clearing: Procés de liquidació completat correctament (ZATCA)
• error_clearing: Error durant el procés de liquidació (ZATCA)
• notification_c2_state_downloaded: Factura descarregada. Correspon al corner C2. Quan el transport és “Descàrrega” i l’usuari fa clic al botó Emetre i Descarregar (Estat: Descarregat)

Sortida

Factures emeses de diferents tipus (sendable_type: Invoice)

Endpoints d’API:

• Enviar factura
• Importar factura (amb paràmetre send_after_import: true)

Esdeveniments:

• success_sending
• error_sending

Esdeveniments no relacionats amb l’API:

• notification_c2_state_downloaded

Pressupostos (sendable_type: Quote)

Endpoints d’API: Els pressupostos no es poden enviar via API.

Esdeveniments no relacionats amb l’API:

• success_sending
• error_sending

Albarans (sendable_type: DespatchAdvice)

Endpoints d’API: Els albarans no es poden enviar via API.

Esdeveniments no relacionats amb l’API:

• success_sending
• error_sending

Comandes (sendable_type: Order)

Endpoints d’API:

• Marcar com a processat (aquest endpoint no genera cap transacció)

Esdeveniments no relacionats amb l’API: En acceptar o rebutjar una comanda (només UI), s’envia una resposta de comanda que genera un d’aquests esdeveniments:

• success_sending
• error_sending

Informes fiscals (sendable_type: TaxReport)

Endpoints d’API:

• Enviar factura (si la factura requereix l’informe fiscal)
• Crear informe fiscal
• Importar informe fiscal
• Modificar informe fiscal
• Anul·lar informe fiscal
• Anul·lar informe fiscal (llegat)

Esdeveniments:

• success_sending
• error_sending
• success_clearing
• error_clearing

Notes: Quan tax_authority és Verifactu o TicketBAI (Bizkaia), a més d’enviar el TaxReport, també s’envia un Registre.

Registre

Endpoints d’API: Els mateixos que per a TaxReport.

Esdeveniments:

• success_sending
• error_sending

Entrada

Factures rebudes de diferents tipus (sendable_type: Invoice)

Es genera una transacció quan es rep una “factura rebuda”. Quan la factura rebuda es crea manualment o s’importa via la plataforma, no compta com a transacció.

Endpoints d’API:

• Importar factura (amb issued=false, corresponent a from_net: 'uploaded')

Comandes (sendable_type: Order)

Endpoints d’API: Les comandes no es poden generar ni enviar via API.

Notes: Es genera una transacció quan es rep una comanda. Quan s’importa via la plataforma, no compta com a transacció.

View_as

Cada vegada que es crida l’API view_as amb un paràmetre document_type diferent de “original” o “legal”, es genera una transacció. Es crea una nova transacció cada vegada que es genera un nou document des del nostre objecte de base de dades.

Tipus de documents no facturables

original — Retorna el document exactament tal com es va enviar o importar originalment, servit des de l’emmagatzematge. No té lloc cap regeneració.

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 — Retorna el document legal arxivat (p. ex., la versió signada i segellada) tal com s’ha emmagatzemat. No té lloc cap regeneració.

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 i pdf.invoice.signed — Tot i que el PDF es renderitza sota demanda, descarregar una còpia en PDF d’una factura emesa no es considera facturable.

Tipus de documents facturables

Qualsevol altre valor de document_type regenera el document en el format sol·licitat i compta com a transacció 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 només necessiteu recuperar el document que ja heu enviat o rebut, useu /as/legal o /as/original.

Com supervisar l’ús de les vostres transaccions

Si sou un Partner o Revenedor, podeu supervisar el consum de transaccions de cada grup d’integració directament des del portal de B2Brouter.

Quan aprovisioneu un grup d’integració, ja sigui perquè gestioneu un únic grup empresarial o opereu com a eDocSync, la manera més eficient de supervisar l’ús total i per compte de transaccions és a través del següent endpoint de l’API: GET /accounts

Exemple de petició

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'

Exemple de resposta

{
  "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
    }
  ]
}

Cada compte inclou:

• transactions_count → Transaccions consumides en el període de facturació actual.
• transactions_count_previous_period → Transaccions consumides en el període de facturació anterior.
• transactions_limit → Nombre màxim de transaccions incloses en la subscripció.

Controlant aquestes dades, podeu gestionar automàticament el consum de cada compte i el total global. Això us permet automatitzar els pagaments basats en el volum de transaccions per als vostres clients finals, o supervisar el vostre ús respecte a la quota acordada i augmentar el límit de transaccions abans de superar-lo.