Skip to content

API de facturación electrónica

Modo de operación

El envío de información a la API de facturación se hace mediante un POST HTTPS a la URL:

https://api.facturaselectronicas.biz/UUID/COMANDO

Donde:

  • UUID es el código de su empresa proporcionado por Paperclip.
  • COMANDO es el comando a ejecutar.

La peticion POST debe contener dos cabeceras HTTP adicionales:

  • X-Token: Token de acceso proporcionado por Paperclip.
  • X-Formato: Formato en el cual se enviará la información, detallada en el siguiente apartado.

Librerías

PHP

Puedes usar la librería a través de composer, ejecutando este comando dentro de tu proyecto:

$ composer require paperclip/facturas-electronicas

Formatos aceptados

La API de Facturación Electrónica soporta 2 formatos para el envío de la información: texto y json:

texto

Los datos son proporcionados usando líneas texto simples. Cada línea tiene el formato propiedad: valor. Para colecciones (arrays), como los ítems de la factura, se usa el formato nombrearreglo-sec-propiedad, donde:

  • nombrearreglo es el nombre de la propiedad que es un arreglo,
  • sec es un número secuencial, que es el índice del elemento del arreglo, y
  • propiedad es el nombre de cada propiedad dentro del arreglo.

Ejemplo de una factura:

tipo: f
serie: F001
numero: 21
fecha: 2017-06-14
tipo_doc: r
numero_doc: 20123456780
razon_social: ABC CONSULTORES S.A.C.
direccion: AV. PROBANDO 123 ICA ICA ICA
moneda: PEN
total_gravado: 84.75
total_igv: 15.25
items-1-unidad: NIU
items-1-cantidad: 1
items-1-codigo: 98765
items-1-descripcion: ESCUDO DE VIBRANIUM
items-1-precio_unitario: 41
items-1-valor_unitario: 34.75
items-1-valor_venta: 34.75
items-1-igv: 6.25
items-1-afectacion_igv: 10
items-2-unidad: NIU
items-2-cantidad: 1
items-2-codigo: 43210
items-2-descripcion: LAWGIVER MK II
items-2-precio_unitario: 49
items-2-valor_unitario: 41.53
items-2-valor_venta: 41.53
items-2-igv: 7.47
items-2-afectacion_igv: 10

json

Debe ser un objeto JSON correctamente formateado, usando comillas dobles para todos las cadenas de caracteres, incluyendo el nombre de las propiedades. La factura anterior se vería así:

{"tipo":"f","serie":"F001","numero":"21","fecha":"2017-06-14","tipo_doc":"r","numero_doc":"20123456780","razon_social":"ABC CONSULTORES S.A.C.","direccion":"AV. PROBANDO 123 ICA ICA ICA","moneda":"PEN","total_gravado":84.75,"total_igv":15.25,"items":{"1":{"unidad":"NIU","cantidad":1,"codigo":"98765","descripcion":"ESCUDO DE VIBRANIUM","precio_unitario":41,"valor_unitario":34.75,"valor_venta":34.75,"igv":6.25,"afectacion_igv":10},"2":{"unidad":"NIU","cantidad":1,"codigo":"43210","descripcion":"LAWGIVER MK II","precio_unitario":49,"valor_unitario":41.53,"valor_venta":41.53,"igv":7.47,"afectacion_igv":10}}}

Sobre los cálculos numéricos.

Todos los campos numéricos aceptan una cantidad arbitraria de decimales, y con todos los decimales se realizarán los cálculos cuando sea necesario. Después de realizar los cálculos, todos los números serán redondeados a 2 o 3 decimales, según sea el requerimiento de la SUNAT.

Sobre las propiedades

Todas las propiedades son obligatorias, salvo se indique lo contrario. Sus valores pueden ser de los siguientes tipos:

  • Numérico: Hasta 15 dígitos de longitud, incluyendo el punto decimal.
  • Entero: Hasta 15 dígitos, sin parte decimal.
  • Caracter: Uno o más caracteres alfanuméricos, en formato UTF-8.
  • Fecha: En formato AAAA-MM-DD.
  • Booleano: Cualquier valor distinto de vacío o del número 0, es tomado como Verdadero. Usualmente las propiedades booleanas son opcionales, y su valor por defecto es Falso, salvo se indique lo contrario.

Comandos

El comando a ejecutar se colocará al final de la URL de la API. E.g. para ejecutar el comando emitir, la petición HTTP deberá realizarse a una URL similar a esta:

https://api.facturaselectronicas.biz/uuid-abc123-456-789/emitir

Los comandos aceptados por la API de facturación son:

  • emitir: Genera un nuevo comprobante, ya sea factura, boleta, o sus notas correspondientes.
  • baja: Solicita la baja (anulación) un comprobante.
  • consultarruc: Obtiene información sobre un RUC, o un DNI con empresa.
  • consultarticket: Consulta el estado de un ticket de una transacción diferida de la SUNAT.
  • correo: Envia el PDF y el XML por correo electrónico a los destinatarios especificados.
  • hola: Comando para realizar pruebas de comunicación.

Valores de retorno

Todos los comandos retornan variables con valores en el formato que fue recibido los parámetros (e.g. texto, o JSON). Todas las respuestas contienen una variable llamada estado, que puede tener el valor ok o error.

Si el valor de estado es error, estas variables serán añadidas al retorno del comando:

  • codigo_error: Un nombre constante que identifica al error.
  • descripcion_error: Explicación del error.
  • descripcion_extra: Información extra sobre lo que causó el error, usualmente referida a la información recibida.

Si hubiese un error de más bajo nivel (e.g. un JSON mal formado), el valor HTTP de retorno será 500, con el mensaje de error en el cuerpo de la respuesta.