Integració via WS per Registres Comptables de Factures (RCF)

  1. Introducció
  2. Mètode d’autenticació
    1. Connectivitat
    2. Autenticació i autorització
  3. Operacions
    1. Consulta de factures pendents
    2. Consulta de dades d’una factura
    3. Obtenció del fitxer d’una factura
    4. Obtenció del fitxer d’un document adjunt
    5. Obtenció del rebut electrònic de factura
    6. Obtenció de l’històric d’estats d’una factura
    7. Actualització d’estats de factura
    8. Consulta d’adjunts pendents
    9. Eliminació d’adjunts pendents de descàrrega
    10. Consulta de les entitats adherides a una plataforma 11. Codis de resposta del servei
    11. Llistat d’errors
  4. Estats de factura
  5. Com donar-se d’alta al servei
  6. Entorns

Introducció

Aquest document pretén descriure l’API REST per a la integració de les plataformes receptores amb el hub d’eFACT, amb l’objectiu de substituir la integració actual per FTP.

Mètode d’autenticació

Connectivitat

S’establirà un sistema de filtres d’IPs per origen, de manera que només es permeti l’accés al servei des d’IPs l’origen de les quals estigui dins dels admesos.

Autenticació i autorització

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:

• iss: aquest camp (Issuer) estableix l’emissor del token i cal informar-hi el codi o nom d’usuari que identifica l’integrador. Aquesta dada serà assignada pel servei de suport al procés d’alta o migració de la plataforma receptora.

• aud: aquest camp (Audience) estableix el servei al qual va dirigit el token. D’aquesta manera s’evita l’ús indegut de tokens generats per a altres serveis. Aquest camp haurà de contenir el literal “efact”.

• nbf: aquest camp (Not Before) conté la data, expressada en format epoch amb precisió de segons, a partir de la qual el token entrarà en vigor. Aquest mecanisme es preveu per poder emetre tokens que començaran a ser vàlids en un instant futur. Normalment aquest camp contindrà la data actual.

• iat: aquest camp (Issued At) conté la data d’emissió, en format epoch amb precisió de segons, del token.

• exp: Aquest camp (Expires At) conté la data d’expiració, en format epoch amb precisió de segons, del token. És recomanable emetre els tokens amb una vigència d’uns pocs segons per evitar-ne un ús indegut en cas de robatori. El temps màxim d’expiració permès és de 300 segons (5 minuts).

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

Operacions

Consulta de factures pendents

Aquesta operació permet obtenir les factures pendents de descarregar per a la plataforma associada a l’usuari que realitza la petició. Retorna un màxim de 500 factures. De manera opcional, es permetrà filtrar pel NIF de l’entitat i/o pel codi d’oficina comptable.

NOTA: un cop processades, és necessari marcar les factures com “descarregades”. Per a això, s’ha d’actualitzar l’estat de les factures a DELIVERED o ANNOTATED (veure operació Actualització d’estats d’una factura). Si no es fa això, les factures sempre quedaran com a pendents de descàrrega i es tornarien obtenir com a resultat de l’execució d’aquesta operació.

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

Petició

paràmetre descripció
nif: Paràmetre opcional. NIF de l’entitat per a la qual es volen obtenir les factures pendents de descàrrega.
oficinaComptable: Paràmetre opcional. Codi de l’oficina comptable per a la qual es volen obtenir les factures pendents de descàrrega.

Exemple petició:

GET [urlServei]/factures-pendents?nif=XXXXXXXX

GET [urlServei]/factures-pendents?oficinaComptable=ZZZZZZZZZ

GET [urlServei]/factures-pendents?nif=XXXXXXXX&oficinaComptable=ZZZZZZZZZ

Resposta

Si la petició s’ha dut a terme amb èxit (codi HTTP “200”) es tornarà un missatge de tipus application/json amb el contingut següent:

Exemple resposta:

{
	"mesFactures": false,  
	"factures": [
		{
			"id": "159732145",
			"nif": "ESQ1111112G",
			"oficinaComptable": "A987654321",
			"organGestor": "A987654321",
			"unitatTramitadora": "A987654321"
		},
		{
			"id": "159732146",
			"nif": "ESQ1111112G",
			"oficinaComptable": "A987654321",
			"organGestor": "A987654321",
			"unitatTramitadora": "A987654321"
		}
	]
}

Consulta de 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 retornen les dades d’aquests.

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

Petició

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

Exemple petició:

GET [urlServei]/factura/12345

Resposta

Si la petició s’ha dut a terme amb èxit (codi HTTP “200”) es tornarà un missatge de tipus application/json amb el contingut següent:

Exemple resposta:

{
	"numeroFactura": "F2310-001",
	"dataFactura": "2023-10-25",
	"importFactura": 1542.75,
	"nifProveidor": "ESR0599999J",
	"nomProveidor": "Entidad de pruebas",
	"nif": "ESQ1111112G",
	"nom": "ENS FORMACIO B",
	"numeroRegistre": "E2023000064",
	"dataRegistre": "2023-10-25T16:25:02.000+02:00",
	"estat": "REJECTED",
	"dataEstat": "2023-10-26T12:03:54+02:00",
	"codiMotiuRebuig": "2134",
	"descripcioMotiuRebuig": "Descipcio Motiu",
	"adjunts": [
		{
			"idAdjunt": "159731005",
			"nom": "1.pdf"
		}
	]
}

Obtenció del fitxer d’una factura

Aquesta operació permet obtenir el fitxer de la factura corresponent a l’identificador de factura especificat com a paràmetre.

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

Petició

paràmetre descripció
id: Identificador de la factura a descarregar.

Exemple petició:

GET [urlServei]/factura/12345/facturae

Resposta

Si la petició s’ha dut a terme amb èxit (codi HTTP “200”), es retornarà un fitxer de tipus “application/xml” corresponent a la factura sol·licitada.

Obtenció del fitxer d’un document adjunt

Aquesta operació permet obtenir el fitxer del document adjunt corresponent a l’identificador del document adjunt i l’identificador de factura especificats com a paràmetres.

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

Petició

paràmetre descripció
id: Identificador de la factura a què està associat el document adjunt.
idAdjunt: Identificador del document adjunt a descarregar

Exemple petició:

GET [urlServei]/factura/12345/adjunts/12348

Resposta

Si la petició s’ha dut a terme amb èxit (codi HTTP “200”) es tornarà el fitxer del document adjunt sol·licitat. A la capçalera Content-type s’especificarà el tipus mime corresponent.

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 voleu obtenir el vostre rebut electrònic.

Exemple petició:

GET [urlServei]/factura/12345/rebut

Resposta

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

Obtenció de l’històric d’estats d’una factura

Aquesta operació permet obtenir l’històric d’estats corresponent a l’identificador de factura especificat com a paràmetre.

En la secció Estats de factura es descriuen els estats pels quals pot passar una factura i com ha de ser flux d’actualització d’estats d’una factura.

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

Petició

paràmetre descripció
id: Identificador de la factura de la qual voleu obtenir el vostre històric d’estats.

Exemple petició:

GET [urlServei]/factura/12345/estats

Resposta

Si la petició s’ha dut a terme amb èxit (codi HTTP “200”) es tornarà un fitxer de tipus application/json amb el contingut següent:

Exemple resposta:

{
	"estats": 
	[
		{
			"estat": "REGISTERED",
			"codiEstat": "1200",
			"dataEstat": "2023-10-25T16:25:06+02:00",
			"numeroRegistre": "E2023000064",
			"dataRegistre": "2023-10-25T16:25:02.000+02:00"
		},
		{
			"estat": "REJECTED",
			"codiEstat": "2600",
			"dataEstat": "2023-10-26T12:03:05+02:00",
			"codiMotiuRebuig": "2134",
			"descripcioMotiuRebuig": "Descipcio Motiu"
		}
	]
}

Pel que fa a la data de pagament d’una factura (dataPagament), per als casos de factures anteriors a la integració per aquest API REST en què no es disposi d’una data de pagament concreta informada pel receptor, es considerarà com a data de pagament la mateixa data d’estat (dataEstat) de l’estat “pagada” (PAID) corresponent.

Actualització d’estats de factura

Aquesta operació té dues funcions:

Els estats de les factures només poden ser els següents: DELIVERED, ANNOTATED, RECEIVED, ACCEPTED, RECOGNISED, PAID i REJECTED. Si s’intenta actualitzar una factura a un estat diferent, es tornarà un error indicant que l’actualització d’estat especificada no està permesa.

L’estat REGISTERED el genera automàticament eFACT i indica que la factura ja ha entrat al registre administratiu de l’entitat. Aquest estat implica la següent informació sobre les dades del registre d’entrada:

Obligatòriament, les entitats han d’informar els estats següents: ANNOTATED, RECOGNISED, PAID i, en cas de rebuig, REJECTED. La resta dels estats es consideren opcionals. A més, cal tenir en compte el següent:

La seqüència d’estats coherent d’una factura hauria de ser la següent:

  1. REGISTERED (eFACT)
  2. ANNOTATED
  3. RECOGNISED
  4. PAID

En la secció Estats de factura es descriuen els estats pels quals pot passar una factura i com ha de ser flux d’actualització d’estats d’una factura.

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

Petició

paràmetre descripció
id: Identificador de la factura de la qual voleu obtenir el vostre històric d’estats.

Exemple petició:

PATCH [urlServei]/factura/12345

Tot seguit, s’indiquen totes les possibles dades susceptibles de ser informades.

{
	"estat": "",
	"codiMotiuRebuig": "",
	"descripcioMotiuRebuig": "",
	"numeroRegistreRCF": "", 
	"dataPagament": ""
}

Tots els camps són opcionals, excepte el camp “estat” i els especificats anteriorment com a obligatoris per a un determinat estat:

Exemple de fitxer JSON per actualitzar una factura rebutjada (REJECTED):

{
	"estat": "REJECTED",
	"codiMotiuRebuig": "E01",
	"descripcioMotiuRebuig": "No s'ha especificat el número d'expedient"
}

Exemple de fitxer JSON per actualitzar una factura a registrada a RCF(ANNOTATED):

{
	"estat": "ANNOTATED ",
	"numeroRegistreRCF": "RCF-2023-89584"
}

Exemple de fitxer JSON per actualitzar una factura a reconeguda l’obligació del pagament (RECOGNISED):

{
	"estat": "RECOGNISED "
}

Exemple de fitxer JSON per actualitzar una factura com a pagada (PAID):

{
	"estat": "PAID",
	"dataPagament": "2023-11-30"
}

Resposta

Si la petició s’ha dut a terme amb èxit, es torna un JSON amb les dades de la factura actualitzada. L’estructura d’aquest JSON seria exactament la mateixa que la que s’especifica al punt 2 per a l’operació “Consulta de dades d’una factura”.

Consulta d’adjunts pendents

Atès que es poden rebre documents adjunts en qualsevol moment posterior a l’enviament de les factures associades, aquesta operació permet obtenir els documents adjunts pendents de descarregar per a la plataforma associada a l’usuari que fa la petició. Retorna un màxim de 500 documents adjunts. De manera opcional, es permetrà filtrar pel NIF de l’entitat i/o pel codi d’oficina comptable.

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

Petició

paràmetre descripció
nif: Paràmetre opcional. NIF de l’entitat associada a la plataforma corresponent a l’usuari que fa la petició per al qual es volen obtenir les documents adjunts pendents de descàrrega.
oficinaComptable: Paràmetre opcional. Codi d’oficina comptable associat a la plataforma corresponent a l’usuari que realitza la petició per al qual es volen obtenir les documents adjunts pendents de descàrrega.

Exemple petició:

GET [urlServei]/adjunts-pendents?nif=XXXXXXXX

GET [urlServei]/adjunts-pendents?oficinaComptable=ZZZZZZZZZ

GET [urlServei]/adjunts-pendents?nif=XXXXXXXX&oficinaComptable=ZZZZZZZZZ

Resposta

Si la petició s’ha dut a terme amb èxit (codi HTTP “200”) es tornarà un fitxer de tipus application/json amb el contingut següent:

Exemple resposta:

{
	"mesAdjunts": false,  
	"adjunts": [
		{
			"idAdjunt": "159731025",
			"idFactura": "159731027",
			"nom": "2.pdf"
		},
		{
			"idAdjunt": "159731026",
			"idFactura": "159731027",
			"nom": "1.pdf"
		},
		{
			"idAdjunt": "159732161",
			"idFactura": "159732145",
			"nom": "1.xlsx"
		},
	]
}

Eliminació d’adjunts pendents de descàrrega

Aquesta operació permet actualitzar com a descarregat l’adjunt especificat, de manera que ja no sigui tingut en compte per l’operació de consulta d’adjunts pendents de descàrrega (GET [urlServei]/adjunts-pendents).

Path relatiu de l’operació: /adjunts-pendents/:idAdjunt

Petició

paràmetre descripció
idAdjunt: Identificador del document adjunt que es vol marcar com a descarregat.

Exemple petició:

DELETE [urlServei]/adjunts-pendents/2755

Resposta

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

Consulta de les entitats adherides a una plataforma

Aquesta operació permet obtenir les dades principals de les entitats adherides a la plataforma associada a l’usuari que realitza la petició.

Path relatiu de l’operació: /ens

Petició

GET [urlServei]/ens

Resposta

Si la petició s’ha dut a terme amb èxit (codi HTTP “200”) es tornarà un fitxer de tipus application/json amb el contingut següent:

Exemple resposta:

{
	"ens": [
		{
			"nif": "ESQ1111112G",
			"nom": "ENS FORMACIO B",
			"ine10": "7996100002"
		}
	]
}

Codis de resposta del servei

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

Llistat d’errors

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

{
	"codiError": 9999,
	"descripcioError": "descripcio 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):

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

Com donar-se d’alta al servei

Entorns

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