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. Que aquest informe es facturi o no depèn de l’autoritat fiscal; consulta Facturació per autoritat fiscal més avall.
• 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.

Facturació per autoritat fiscal

Activar l’informe fiscal automàtic no té el mateix cost a tots els règims. Tres d’ells facturen una transacció per informe; els altres dos no facturen l’informe o el facturen de manera agregada:

Autoritat fiscal	Facturació de l’informe fiscal	Efecte per factura
Verifactu	Una transacció per informe fiscal	Enviar una factura genera dues transaccions facturables
TicketBAI	Una transacció per informe fiscal	Enviar una factura genera dues transaccions facturables
SII	Una transacció per informe fiscal	Enviar una factura genera dues transaccions facturables
KSeF	No es factura	Cap transacció addicional
DGFiP	Una transacció per ledger	Cap transacció per factura, una per declaració agregada

Ledgers. A Verifactu i TicketBAI, un ledger compta tantes transaccions com registres conté: un ledger amb 10 registres compta com 10 transaccions individuals. Això no s’aplica a les altres dues autoritats que fan servir ledgers. A DGFiP, el ledger sencer compta com una sola transacció, i a KSeF el ledger no es factura.

Les declaracions F10 de la DGFiP s’agrupen per període civil segons el règim d’IVA del declarant. Cada declaració agrupada genera una única transacció, independentment del nombre de factures que contingui: una declaració amb 200 factures compta igual que una amb dues.

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

Nota: els quatre endpoints d’informe fiscal anteriors es facturen segons l’autoritat fiscal. Consulta Facturació per autoritat 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

Cridar GET /invoices/{id}/as/{document_type_code} genera una nova transacció facturable sempre que el document es generi de nou a partir de les dades de la factura subjacent. Els següents valors de document_type_code són excepcions i no generen cap transacció:

• original — retorna el document exactament tal com es va enviar o importar originalment, servit des de l’emmagatzematge. No té lloc cap regeneració.
• legal — retorna el document legal arxivat (p. ex., la versió signada i segellada) tal com s’ha emmagatzemat. No té lloc cap regeneració.
• 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.

Per a qualsevol altre valor (p. ex., xml.ubl.invoice.bis3, xml.facturae.3.2.2, etc.), es registra una nova transacció a cada crida, perquè el document es regenera a partir de l’objecte de base de dades.

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 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.