Back
Developers
What is it
About us
Terms of use
Privacy policy
Subscribed companies
Presentation video (spanish)
Prices
5. Developers

Developers

NuestraFactura.com, with a simple API, allows to upload invoices issued by any software that generates PDF files.

1. Generation of the required files

2. Sending files to the FTP server

3. Defintion of the XML file

4. Interpreted code

5. Examples

a. Simple sending (an invoice)

b. Multiple sending (several invoices)

1. Generation of the required files

For every invoice that we want to send to Nuestrafactura.com we will must generate a PDF file and an XML one.

The PDF file is the invoice in digital format, as it will be printed.

The XML file contains information of the associated invoice. You can see the exact definition of the XML file in point 3. Definition of the XML file.

The name of both files PDF and XML will be the same (except the extension).

The name of these files cannot repeat. We have to avoid collision between other invoices. For example, it could be:

SSS_FFFFFF-YYYYMMDD-CCCCC

where:

SSS_FFFFFF:

Series and Invoice number

YYYYMMDD:

Date

CCCCC:

Client

2. Sending files to the FTP server

For each sending, a folder with PDF and XML files will be created. The name of the folder shall be unique, to avoid collisions in case of there are several users realising simultaneous sendings.

For example, it could be:

YYYYMMDD-HHNNSSZZZ-IDTERMINAL

where:

YYYYMMDD:

Date

HHNNSSZZZ:

Time

IDTERMINAL:

Terminal identifier

Once we have sent all the PDF and XML files, an empty file named “OK” will be created and sent. This file will be used to indicate that the files have been sent and these can be processed by Nuestrafactura.com.

3. Definition of the XML file

<?xml version="1.0" encoding="UTF-8"?>

<NuestraFactura Version="1.00"

                DateTime="20121106122110"

                Origin="Programme name"

                User="Username">

  <Emisor NIF="Issuer’s Id Number"

          Nombre="Issuer’s Name"/>

  <Documento>

    <Receptor NIF="Recipient’s Id Number"

              Nombre="Recipient’s Name"

              Email="recipient@mail.com"/>

    <DocInfo Fichero="010673-20120110-09029.pdf"

             Kind="Facturas"

             Ejercicio="2012"

             Identificador="169973"

             Documento="10.673"

             Fecha="20120110"

             Importe="26550"

             Descripcion="Invoice comment"/>

  </Documento>

  <Envio Descripcion="Sending comment"

         Documentos="1"

         Importe="26550"

         Bytes="78713"

         Notificar="1"/>

</NuestraFactura>

Node <NuestraFactura> 

Attribute

Type

Optional

Comment

Version

texto

NO

Version of the XML format.

DateTime

texto

NO

Date and time generation in that format: yyyymmddhhnnss.

Origin

texto

NO

Name of the programme that generates the sending.

User

texto

NO

User that makes the sending.

Node <Emisor>

Atributo

Tipo

Opcional

Comentario

NIF

texto

NO

Issuer’s Id Number

Nombre

texto

NO

Issuer’s Company’s Name

Node <Receptor>

Atributo

Tipo

Opcional

Comentario

NIF

texto

NO

Recipient’s Id Number

Nombre

texto

NO

Recipient’s Company’s Name

Email

texto

NO

Recipient’s email

Node <DocInfo>

Atributo

Tipo

Opcional

Comentario

Fichero

texto

NO

PDF’s name that goes with this XML. Look up point 1. Generation of the required files for more details.

Kind

texto

NO

Type of document. The only supported type is: Facturas

Ejercicio

número

NO

Fiscal year in format yyyy (4 digits)

Identificador

texto

YES

Internal code of the document in the origin software. It has to be constant and unique.

Documento

texto

NO

Document number correctly formatted. For example: ABO/100.050

Fecha

texto

NO

Document date in this format yyyymmdd

Importe

número

NO

Total amount of the document. Convert to cents (multiply by 100 values in Euros)

Descripcion

texto

NO

Descriptive information about the document.

Node <Envio>

Atributo

Tipo

Opcional

Comentario

Descripcion

texto

YES

Descriptive information about the sending.

Documentos

número

NO

Number of documents in the sending

Importe

número

NO

Total amount of all documents included in the sending. Convert to cents (multiply by 100 values in Euros)

Bytes

número

NO

Number of bytes of all PDF files

Notificar

número

YES

If it has to be sent an email notification to the RECIPIENT. Possible values: [1 = YES | 0 = NO]

The information of ENVIO includes information of the group of all PDF files that are sent. Nuestrafactura.com will use this information when processing the files to ensure that all the expected files are received.

In a multiple sending (several invoices), the information of ENVIO will be the same for all the XML files of the sending.

4. Interpreted code

An example in an interpreted code of the required processes for sending invoices at NuestraFactura.com.

for each invoice

 to generate PDF file;

 to accumulate number of documents;

 to accumulate total amount;

 to accumulate total bytes;

end for;

for each invoice

 to generate XML file;

end for;

to connect to FTP;

to create sending folder;

to send PDF and XML files;

to create and send OK file;

5. Example

a. Simple sending (an invoice)

Folder:        20121106-122110046-500123

PDF:        101340-20121103-01397.pdf

XML:        101340-20121103-01397.xml

OK:        ok

<?xml version="1.0" encoding="UTF-8"?>

<NuestraFactura Version="1.00" DateTime="20121106122110"

                Origin="SisFactu" User="José">

  <Emisor NIF="B12345678" Nombre="OUR GARAGE, S.L."/>

  <Documento>

    <Receptor NIF="X23456789" Nombre="ELECTRICTY, S.L."

              Email="administration@electricitymail.com"/>

    <DocInfo Fichero="101340-20121103-01397.pdf" Kind="Facturas"

             Ejercicio="2012" Identificador="1234" Documento="101.340"

             Fecha="20121103" Importe="8495"

             Descripcion="Revision"/>

  </Documento>

  <Envio Descripcion="" Documentos="1" Importe="8495"

         Bytes="78713" Notificar="1"/>

</NuestraFactura>

b. Multiple sending (several invoices)

Folder:                20121106-122243366-500123

PDF:                001020-20121015-01039.pdf

XML:                001020-20121015-01039.xml

PDF:                M_000752-20121031-05002.pdf

XML:                M_000752-20121031-05002.xml

OK:                ok

<?xml version="1.0" encoding="UTF-8"?>

<NuestraFactura Version="1.00" DateTime="20121106122243"

                Origin="SisFactu" User="José">

  <Emisor NIF="B12345678" Nombre="OUR GARAGE, S.L."/>

  <Documento>

    <Receptor NIF="B23456789" Nombre="TRANSPORTS BOX, S.L."

              Email="admin@transportsmail.com"/>

    <DocInfo Fichero="001020-20121015-01039.pdf" Kind="Facturas"

             Ejercicio="2012" Identificador="1235" Documento="1.020"

             Fecha="20121015" Importe="46550"

             Descripcion="Tyre changes"/>

  </Documento>

  <Envio Descripcion="Monthly invoicing" Documentos="2" Importe="276550"

         Bytes="157220" Notificar="1"/>

</NuestraFactura>

<?xml version="1.0" encoding="UTF-8"?>

<NuestraFactura Version="1.00" DateTime="20121106122243"

                Origin="SisFactu" User="José">

  <Emisor NIF="B12345678" Nombre="OUR GARAGE, S.L."/>

  <Documento>

    <Receptor NIF="B34567890" Nombre="CAR RENTING, S.L."

              Email="admin@rentingmail.com"/>

    <DocInfo Fichero="M_000752-20121031-05002.pdf" Kind="Facturas"

             Ejercicio="2012" Identificador="1236" Documento="M/752"

             Fecha="20121031" Importe="230000"

             Descripcion="Fleet revisin (10 cars)"/>

  </Documento>

  <Envio Descripcion="Monthly invoicing" Documentos="2" Importe="276550"

         Bytes="157220" Notificar="1"/>

</NuestraFactura>

Notice that the information of ENVIO of both XML files, is exactly the same.


Last revision: 26, November 2012