Nuestrafactura - Information

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 y un fichero XML.

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. Definición del fichero XML.

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
IDTERMIANL:	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=Origin="Programme name"

User=User="Username">

<Emisor
NIF="Issuer’s Id Number"

Nombre="Issuer’s Name"/>

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

Attribute	Type	Optional	Comment
NIF	texto	NO	Issuer’s Id Number
Nombre	texto	NO	Issuer’s Company’s Name

Node <Receptor>

Attribute	Type	Optional	Comment
NIF	texto	NO	Recipient’s Id Number
Nombre	texto	NO	Recipient’s Company’s Name
Email	texto	NO	Recipient’s email

Node <DocInfo>

Attribute	Type	Optional	Comment
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 dígits)
Identificador	texto	NO	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)
Descripción	texto	NO	Descriptive information about the document.

Node <Envio>

Attribute	Type	Optional	Comment
Descripcion	texto	SI	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	SI	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.NuestraFactura.com usará esta información al procesar los ficheros para asegurarse de que se han recibido todos los ficheros esperados.

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)

Carpeta: 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é">

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

Email=
"gestion@electricidadmail.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. Envío múltiple (varias facturas)

Carpeta: 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é">

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

Email=
"admin@transportesmail.com"/>

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

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

Fecha="20121015"
Importe="46550"

Descripcion="Tyre changesáticos"/>

</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é">

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

Email=
"admin@alquilermail.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