Integración vía API REST para Proveedores

  1. Introducció
  2. Mètode d’autenticació
  3. Entorns
  4. Operacions
    1. Enviament d’una factura 2. Consulta de les dades d’una factura 3. Consulta de l’històric d’estats d’una factura
      1. Obtenció del rebut electrònic de factura
      2. Consulta d’estats pendents de descàrrega
      3. Eliminació d’estats pendents de descàrrega
      4. Consulta de les entitats adherides a eFACT
      5. Consulta del detall d’una entitat eFACT
  5. Definició dels objectes de resposta
    1. Factura 2. HistoricEstatsFactura 3. EstatsPendents
    2. ReceptorsEfact
    3. ReceptorEfact
    4. EstatPendent
    5. Estat
    6. EstatDetallat
    7. RelacioDir3
    8. CentreAdministratiu
    9. DadesRegistre
    10. DadesMotiuRebuig
  6. Annexos
    1. Codis de resposta del servei
    2. Possibles estats d’una factura
    3. Tipus mime admesos

Introducció

Aquest document pretén descriure l’API REST per a la integració de les plataformes emissores amb el hub d’eFACT, amb l’objectiu de substituir la integració actual per FTP i al web service SOAP de proveïdors.

Mètode d’autenticació

L’autenticació es farà mitjançant l’ús de tokens JWT. Aquests tokens contenen tota la informació necessària per fer les tasques d’autenticació i autorització del peticionari. Els camps necessaris als tokens JWT seran els següents:

Un cop emplenat el token, aquest s’haurà de signar amb l’algorisme HMAC-SHA256, utilitzant una clau secreta que serà assignada pel servei de suport en el procés d’alta o migració de la plataforma emissora. Aquesta clau haurà de ser custodiada de manera segura per part de l’integrador i no haurà de viatjar mai dins d’una petició o capçalera HTTP.

A continuació, es mostra un exemple de token JWT en clar, abans de codificar a Base64:

A continuació hi ha un desplegable amb l'explicació de descripció de la imatge

Explicació textual de la imatge ### SEGMENT I L'algorisme de signatura emprat per protegir el token, així com el tipus de token. Només es suportarà l'algoritme HS256 i el tipus de token JWT. ```json { "alg": "HS256", "typ": "JWT" } ``` ### SEGMENT II Dades d'autenticació i autorització comentades anteriorment. ```json { "iss": "hub_0012", "aud": "efact", "iat": 1516239022, "nbf": 1516239022, "exp": 1516239042 } ``` ### SEGMENT III Signatura del token, necessària per verificar que no ha estat alterat, així com la seva autenticitat. ``` 3oGx4zGJy7YfYTIiBiPNBPCUGrC8oNlKQaGHSO4D5M0 ``` ### Notes Els segments van delimitats per punts, de manera que trobem el primer segment, un punt, el segon segment, un punt i el tercer segment.

Un cop generat el token, aquest s’inclourà a la capçalera HTTP ‘Authorization’ de la següent manera:

A continuació hi ha un desplegable amb l'explicació de descripció de la imatge

Explicació textual de la imatge La cadena que hi ha a continuació és una concatenació dels tres segments un cop codificat a Base64 ``` eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJBUFawMDAxIiwic3ViIjoiOTgyMTkyMDAwMiIsInVzZXIiOiIxMTExMTEwMTExMUgiLCJvYW1pIjoiSm9zZXZA9zZXAgSm9zZXAgSm9zZXAiOjE1MTYyMzkwMjIsIm5iZiI6MTUxMTUxOTAyMiwiZXhwIjoxNTE2MjM5MDQyfQ.3oGx4zGJy7YfYTIiBiPNBPCUGrC8oNlKQaGHSO4D5M0 ```

A l’exemple de capçalera HTTP amb el token JWT es mostren els diferents segments del token pintats de diferent color. Com es pot observar, els segments estan separats per un punt.

Entorns

A continuació, s’indica l’URL base del servei segons l’entorn:

Operacions

Enviament d’una factura

Aquesta operació permet l’enviament d’una factura i, opcionalment, dels seus documents adjunts al servei eFACT. A la mateixa petició s’informaran tant la factura com els seus possibles documents adjunts, tenint en compte les restriccions següents:

Path relatiu de l’operació: /factura

Petició

POST [urlServicio]/factura

A continuació, s’indiquen tots les possibles dades susceptibles de ser informats al JSON de petició d’enviament d’una factura:

Exemple de petició d’enviament de factura:

{
	"correuElectronic": "a@a.com",
	"face": false,
	"factura": {
		"nom”: "F24-00182.xml",
		"contingut": "PD94bWwgdmVi9MLTAwVMHls8sDADSQBAyc2lvlOkZhY3R1cRQ1Cl5DrgkmFlPg…"
	},
	"adjunts": [
		{
			"nom": "adjunt1.pdf",
			"mime": "application/pdf",
			"contingut": "UEsDBBQAAAAIALuJNVCiVMHls8sDADSQBAALAAAAYXR0YWNoMS5wZGbMWQVQG8w…"
		}
	]
}

Resposta

Si la petició s’ha dut a terme amb èxit (codi HTTP “200”) es tornarà un objecte Factura (fitxer de tipus application/json). A continuació, es mostra un exemple de resposta:

{
	"correuElectronic": "a@a.com",
	"face": false,
	"id": "159732145",
	"dataRecepcio": "2024-11-05T12:03:54+01:00",
	"numero": "F2411-0018",
	"serie": "A",
	"dataExpedicio": "2024-11-05",
	"import": 1542.75,
	"proveidor": {
		"nif": "ESR0599999J",
		"nom": "Proveïdor de pruebas"
	},
	"receptor": {
		"nif": "ESQ1111112G",
		"nom": "ENS FORMACIO B",
		"dir3": {
			"oficinaComptable": {
				"codi": "A987654321",
				"nom": "ENS FORMACIO B"
			},
			"organGestor": {
				"codi": "A987654321",
				"nom": "ENS FORMACIO B"
			},
			"unitatTramitadora": {
				"codi": "A987654321",
				"nom": "ENS FORMACIO B"
			}
		}
	},
	"estat": {
		"codi": "SENT",
		"codiNumneric": "1000",
		"data": "2024-11-05T12:03:54+01:00"
	},
	"adjunts": [
		{
			"nom": "adjunt1.pdf",
			"mime": "application/pdf"
		}
	]
}

Consulta de les dades d’una factura

Aquesta operació permet obtenir les dades de la factura corresponent a l’identificador de factura especificat com a paràmetre. Si la factura té documents adjunts associats, també es tornen les seves dades.

Path relatiu de l’operació: /factura/:id

Petició

paràmetre descripció
id Identificador de la factura que es vol consultar.

GET [urlServicio]/factura/159732145

Resposta

Si la petició s’ha dut a terme amb èxit (codi HTTP “200”) es tornarà un objecte Factura (fitxer de tipus application/json). A continuació, es mostra un exemple de resposta:

{
	"correuElectronic": "a@a.com",
	"face": false,
	"id": "159732145", 
	"dataRecepcio": "2024-11-05T12:03:54+01:00",
	"numero": "F2411-0018",
	"serie": "A",
	"dataExpedicio": "2024-11-05",
	"import": 1542.75,
	"proveidor": {
		"nif": "ESR0599999J",
		"nom": "Proveïdor de pruebas"
	},
	"receptor": {
		"nif": "ESQ1111112G",
		"nom": "ENS FORMACIO B",
		"dir3": {
			"oficinaComptable": {
				"codi": "A987654321",
				"nom": "ENS FORMACIO B"
         	},
			"organGestor": {
				"codi": "A987654321",
				"nom": "ENS FORMACIO B"
			},
			"unitatTramitadora": {
				"codi": "A987654321",
				"nom": "ENS FORMACIO B"
			}
		}
	},
	"registre": {
		"numero": "E2023000064",
		"data": "2024-11-05T12:04:02.000+01:00"
	},
	"motiuRebuig": {
		"codi": "DF01",
		"descripcio": "Descipcio Motiu"
	},
	"estat": {
		"codi": "REJECTED",
		"codiNumneric": "2600",
		"data": "2024-11-18T10:03:54+01:00"
	},
	"adjunts": [
		{
			"nom": "1.pdf",
			"mime": "application/pdf"
		}
	]
}

Consulta de l’històric d’estats d’una factura

Aquesta operació permet obtenir tots els estats pel que ha passat la factura corresponent a l’identificador de factura especificat com a paràmetre.

Path relatiu de l’operació: /historicEstatsFactura/:id

Petició

paràmetre descripció
id Identificador de la factura que es vol consultar.

GET [urlServicio]/historicEstatsFactura/159732145

Resposta

Si la petició s’ha dut a terme amb èxit (codi HTTP “200”) es tornarà un objecte HistoricEstatsFactura (fitxer de tipus application/json). A continuació, es mostra un exemple de resposta:

{
	"id": "159732145",
	"estats": [
		{
			"codi": "SENT",
			"codiNumeric": "1000",
			"data": "2024-11-05T12:03:54+01:00"            
		},
		{
			"codi": "REGISTERED",
			"codiNumeric": "1200",
			"data": "2024-11-05T12:04:35.000+01:00",
			"registre": {
				"numero": "E2023000064",
				"data": "2024-11-05T12:04:02.000+01:00"
			}
		}
	]
}

Obtenció del rebut electrònic de factura

Aquesta operació permet obtenir el rebut electrònic corresponent a l’identificador de factura especificat com a paràmetre.

Path relatiu de l’operació: /factura/:id/rebut

Petició

paràmetre descripció
id Identificador de la factura de la qual es vol obtenir el rebut electrònic.

GET [urlServei]/factura/12345/rebut

Resposta

Si la petició s’ha dut a terme amb èxit (codi HTTP “200”), es tornarà un fitxer de tipus application/pdf corresponent al rebut electrònic de la factura especificada com a paràmetre.

Consulta d’estats pendents de descàrrega

Aquesta operació permet obtenir els canvis d’estat pendents de descàrrega per a la plataforma associada a l’usuari que realitza la petició. Retorna un màxim de 500 estats. Si hi hagués més estats a tornar del màxim establert, s’indicarà en l’atribut de tipus booleà mesEstats de la resposta. De manera opcional es permetrà filtrar pel NIF de l’entitat emissora.

Path relatiu de l’operació: /estats-pendents

Petició

paràmetre descripció
nifProveidor Paràmetre opcional. NIF de l’entitat emissora, associada a la plataforma corresponent a l’usuari que realitza la petició, per a la qual obtenir els canvis d’estat pendents de descàrrega.

GET [urlServicio]/estats-pendents

GET [urlServicio]/estats-pendents?nifProveidor=XXXXXXXX

Resposta

Si la petició s’ha dut a terme amb èxit (codi HTTP “200”) es tornarà un objecte EstatsPendents (fitxer de tipus application/json). A continuació, es mostra un exemple de resposta:

{
	"mesEstats": false,
	"estats": [
		{
			"id": "1597",
			"idFactura": "159732145",
			"estat": {
				"codi": "REGISTERED",
				"codiNumneric": "1200",
				"data": "2024-11-05T12:04:35.000+01:00",
				"registre": {
					"numero": "E2023000064",
					"data": "2024-11-05T12:04:02.000+01:00"
				}
			}
		}
	]
}

Quant a la data de pagament d’una factura (dataPagament), per als casos en els quals no es disposi d’una data de pagament concreta informada pel receptor, es considerarà com a data de pagament la data d’estat (atribut data) de l’estat “pagada” (PAID) corresponent.

Eliminació d’estats pendents de descàrrega

Aquesta operació permet actualitzar l’estat especificat com “descarregat”, de manera que ja no es tingui en compte per l’operació de consulta d’estats pendents de descàrrega (GET [urlServicio]/estats-pendents).

Path relatiu de l’operació: /estats-pendents/:id

Petició

paràmetre descripció
id Identificador de l’estat que es vol marcar com descarregat.

DELETE [urlServicio]/estats-pendents/1602

Resposta

Si la petició s’ha dut a terme amb èxit, simplement es torna el codi HTTP “200”.

Consulta de les entitats adherides a eFACT

Aquesta operació permet obtenir les dades principals de les entitats adherides al servei eFACT.

Path relatiu de l’operació: /receptors

Petició

GET [urlServicio]/receptors

Resposta

Si la petició s’ha dut a terme amb èxit (codi HTTP “200”) es tornarà un objecte ReceptorsEfact (fitxer de tipus application/json). A continuació, es mostra un exemple de resposta:

{
	"receptors": [
		{
			"nif": "ESQ1111111I",
			"nom": "ENS FORMACIO A",
		},
		{
			"nif": "ESQ1111112G",
			"nom": "ENS FORMACIO B",
		},
		…
	]
}

Consulta del detall d’una entitat eFACT

Aquesta operació permet obtenir la informació detallada (adreça, dir3, etc.) per a l’entitat del servei eFACT especificada.

Path relatiu de l’operació: /receptors

Petició

paràmetre descripció
nif NIF de l’entitat del servei eFACT per a la qual realitzar la consulta.

GET [urlServicio]/receptors/:nif

Resposta

Si la petició s’ha dut a terme amb èxit (codi HTTP “200”) es tornarà un objecte ReceptorEfact (fitxer de tipus application/json). A continuació, es mostra un exemple de resposta:

{
	"nif": "ESQ1111111I",
	"nom": "ENS FORMACIO A",
	"direccio": {
		"carrer": "Passatge de la Concepció, 11",
		"localitat": "Barcelona",
		"provincia": "Barcelona",
		"codiPostal": "08008"
	}
	"dir3": [
		{
			"oficinaComptable": {
				"codi": "A00000000",
				"nom": "ENS FORMACIO A"
			},
			"organGestor": {
				"codi": "A00000000",
				"nom": "ENS FORMACIO A"
			},
			"unitatTramitadora": {
				"codi": "A00000000",
				"nom": "ENS FORMACIO A"
			}
		}
	]
}

Definició dels objectes de resposta

Factura

A continuació, es descriuen tots els possibles atributs d’un objecte Factura:

HistoricEstatsFactura

A continuació, es descriuen tots els possibles atributs d’un objecte HitoricEstatsFactura:

EstatsPendents

A continuació, es descriuen tots els possibles atributs d’un objecte EstatsPendents:

ReceptorsEfact

A continuació, es descriuen tots els possibles atributs d’un objecte ReceptorsEfact:

ReceptorEfact

A continuació, es descriuen tots els possibles atributs d’un objecte ReceptorEfact:

EstatPendent

A continuació, es descriuen tots els possibles atributs d’un objecte EstatPendent:

Estat

A continuació, es descriuen tots els possibles atributs d’un objecte Estat:

EstatDetallat

A continuació, es descriuen tots els possibles atributs d’un objecte EstatDetallat:

RelacioDir3

A continuació, es descriuen tots els possibles atributs d’un objecte RelacioDir3:

CentreAdministratiu

A continuació, es descriuen tots els possibles atributs d’un objecte CentreAdministratiu:

DadesRegistre

A continuació, es descriuen tots els possibles atributs d’un objecte DadesRegistre:

DadesMotiuRebuig

A continuació, es descriuen tots els possibles atributs d’un objecte DadesMotiuRebuig:

Annexos

Codis de resposta del servei

El servei tornarà algun dels codis d’estat de resposta HTTP següents:

En cas d’error, el servei tornarà un fitxer de tipus application/json, amb el contingut següent:

{
	"codiError": 9999,
	"descripcioError": "descripció error" 
}

A continuació, es detallen els possibles errors que pot tornar el servei:

Errors d’autenticació (HttpStatus 401):

Errors de recurs no trobat (HttpStatus 404):

Errors de validació (HttpStatus: 400):

Errors genèrics (HttpStatus 500):

Possibles estats d’una factura

A continuació, es detallen els estats pels quals pot passar una factura al servei, en l’ordre coherent d’ocurrència:

Codi d’estat eFACT Codi d’estat númeric
(BOE A-2014-10660)		 Descripció
SENT 1000 Factura lliurada al servei eFACT.
Aquest estat el genera el servei eFACT de manera automàtica.
REGISTERED 1200 La factura ha estat registrada administrativament, proporcionant un número i data de registre, tant al proveïdor com a l’entitat.
Aquest estat el genera el servei eFACT de manera automàtica.
DELIVERED 1200 La factura ha estat lliurada a l’entitat destinatària.
Aquest estat és opcional i el genera l’entitat receptora de la factura.
ANNOTATED 1300 La factura ha estat verificada i registrada al registre comptable de factures (RCF), generant un número de registre comptable que cal proporcionar al proveïdor.
Aquest estat és obligatori i l’ha de generar l’entitat receptora de la factura.
RECEIVED 1300 La factura ha estat rebuda a la unitat de destinació.
Aquest estat és opcional i el genera l’entitat receptora de la factura.
ACCEPTED 1300 La factura ha estat conformada.
Aquest estat és opcional i el genera l’entitat receptora de la factura.
RECOGNISED 2400 L’obligació de pagament derivada de la factura ha estat reconeguda i comptabilitzada.
Aquest estat és obligatori i l’ha de generar l’entitat receptora de la factura.
PAID 2500 La factura ha estat pagada.
Aquest estat és obligatori i l’ha de generar l’entitat receptora de la factura.
REJECTED 2600 La factura ha estat rebutjada. S’ha d’indicar al proveïdor el motiu del rebuig.
En cas que calgui rebutjar una factura, aquest estat és obligatori i l’ha de generar:
- L’entitat receptora de la factura, sempre que la factura li hagi estat lliurada pel servei eFACT.
- El servei eFACT, en qualsevol altre cas (error de validació de signatura/certificat, error de registre, etc.).

Una factura es pot rebutjar (estat REJECTED) en qualsevol moment, excepte si està en estat PAID.

Els estats PAID i REJECTED són estats finals i, un cop actualitzada a un d’aquests estats, s’entén que la gestió de la factura ja ha finalitzat.

Tipus mime admesos

A continuació, s’indiquen els tipus mime admesos per a documents adjunts: