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 vostre 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: Registreu-vos aquí
• Permisos d’API (sol·liciteu-los via tiquet de suport: Obrir un tiquet)
• En cas de dubte sobre el procés de registre, consulteu la Guia d’usuari.

Si encara heu de crear el compte o activar els transports de recepció, seguiu:

• 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 vostre propi compte).

1) Ingerir factures rebudes

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

Si ja teniu el fitxer de factura rebuda (per exemple, per a proves, migracions o reompliments), podeu importar-lo amb Importar una factura des d’un fitxer. Useu 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; recordeu 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, useu l’endpoint Llista d’estats de factura disponibles.

3) Obtenir els detalls de la factura

Per obtenir la factura en format JSON useu l’endpoint Obtenir una factura. Afegiu 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é podeu 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

Useu 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

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

Useu l’endpoint Canviar estat de factura. Podeu afegir el Body Param reason per especificar el motiu del rebuig. Si la factura ha arribat per correu electrònic, afegiu 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, consulteu la Referència de l’API.