Rebre, integrar i gestionar factures rebudes

Aquesta guia explica com:

• Rebre factures a través de diferents canals (Peppol, correu electrònic, b2brouter, càrregues).
• Integrar factures rebudes al teu sistema (JSON, PDF, fitxer original).
• Gestionar el cicle de vida de la factura (reconèixer, acceptar/rebutjar/pagada, etc.).

Requisits previs

• Una empresa amb un Identificador Fiscal (TIN) o Identificador d’Empresa (CIN) vàlid.
• Un compte registrat a l’entorn de prova de B2Brouter: Registra’t aquí
• Permisos d’API (sol·licita’ls via tiquet de suport: Obrir un tiquet)
• En cas de dubte sobre el procés de registre, consulta la Guia d’usuari.

Si encara has de crear el compte o activar els transports de recepció, segueix:

• Inici ràpid (configuració del compte): https://developer.b2brouter.net/docs/setting_up_guide#/
• Guia de transports: https://developer.b2brouter.net/docs/transports_guide/

Conceptes clau (evitar confusió d’IDs)

• ACCOUNT_ID s’usa únicament als endpoints /accounts/{ACCOUNT_ID}/....
• INVOICE_ID és l’identificador de factura usat als endpoints /invoices/{INVOICE_ID}....
• En una factura rebuda, invoice.contact és l’emissor/proveïdor (no el teu propi compte).

1) Ingerir factures rebudes

1.1 Importar un fitxer de factura rebuda (XML) (opcional)

Si ja tens el fitxer de factura rebuda (per exemple, per a proves, migracions o reompliments), pots importar-lo amb Importar una factura des d’un fitxer. Usa el paràmetre de consulta issued=false per importar-la com a ReceivedInvoice.

També és possible generar una factura rebuda amb JSON usant la crida Crear una factura; recorda indicar "type": "ReceivedInvoice".

1.2 Rebre factures a través dels transports

Un cop els transports estan activats per al compte, les factures arribaran automàticament (per exemple, des de Peppol o correu electrònic).

2) Llistar factures rebudes

Exemple de petició:

curl --request GET \
  --url 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices?type=ReceivedInvoice' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

Resposta d’exemple (extracte):

{
  "invoices": [
    { "id": 105337, "number": "2", "state": "new", "total": 107.1, "currency": "EUR" },
    { "id": 105332, "number": "1", "state": "received", "total": 178.5, "currency": "EUR" }
  ],
  "total_count": 2,
  "offset": 0,
  "limit": 25
}

Les factures rebudes poden tenir estats diferents: les factures importades apareixeran en estat “new” i les rebudes a través de transports normalment apareixeran en estat “received”. També podran tenir l’estat “invalid” si hi ha algun problema de validació.

Per comprovar tots els estats de factura disponibles, usa l’endpoint Llista d’estats de factura disponibles.

3) Obtenir els detalls de la factura

Per obtenir la factura en format JSON usa l’endpoint Obtenir una factura. Afegeix un Query Param per incloure informació de les línies:

Exemple de petició:

curl --request GET \
  --url 'https://api-staging.b2brouter.net/invoices/{INVOICE_ID}?include=lines' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

4) Descarregar el fitxer original de la factura

Per descarregar la factura legal original que s’ha rebut:

Exemple de petició:

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

També pots usar document_type_code com a pdf.invoice per generar una vista en PDF, o qualsevol altre document_type_code de Obtenir tipus de document per obtenir la factura en qualsevol format de factura electrònica.

5) Reconèixer la factura

Usa l’endpoint Marcar una factura com a reconeguda per evitar que la factura aparegui quan es llistarà la llista de factures rebudes.

6) Canviar l’estat de la factura

Canvia l’estat de la factura per informar el remitent que has “acceptat”, “rebutjat” o “pagat” la factura. També pots marcar la factura com a “anotada” per a seguiment intern.

Usa l’endpoint Canviar estat de factura. Pots afegir el Body Param reason per especificar el motiu del rebuig. Si la factura ha arribat per correu electrònic, afegeix el body param "commit": "with_mail" per informar el remitent.

Exemple de petició:

curl --request POST \
  --url https://api-staging.b2brouter.net/invoices/{INVOICE_ID}/mark_as \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "state": "refused",
    "reason": "Missing PO number"
  }'

Resposta d’exemple:

204 No Content

Per a més detalls, consulta la Referència de l’API.