Documentación

Modo de operación

El envío de información a la API de facturación se hace mediante un POST HTTP a una dirección, dependiendo si es para hacer pruebas (modo "desarrollo"), o para realizar una emisión real del CPE (modo "producción")

Para realizar envíos de prueba, ya sea en modo desarrollo o producción, debes usar la siguiente URL:

https://api-testing.facturaselectronicas.biz/<UUID>/<COMANDO>

Para la emisión final de los comprobantes de pago en modo producción, debes usar una URL similar a:

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

Donde:

• <UUID> es el código de identificación de la empresa, que también le será proporcionado en el correo de bienvenida.

• <COMANDO> es el comando a ejecutar.

Nota: La URL exacta y completa le llegará en el correo de bienvenida cuando registre su cuenta de prueba en el facturador.

Cabeceras HTTP

La petición POST debe contener estas dos cabeceras HTTP:

• Content-Type: Formato en el cual se enviará la información: text/plain o application/json, detallada en el siguiente apartado. E.g.:

  Content-Type: application/json

• Authorization: Token de acceso proporcionado por Paperclip, usando el prefijo "Bearer". E.g.:

  Authorization: Bearer b9ac7897a8c7e89dc7b8ae56bdabc67687ce68b7dc87c6fabcd8b7c6ae76cbf8

Formatos aceptados

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

text/plain

Los datos son proporcionados usando líneas texto simples. Cada línea tiene el formato propiedad: valor. Puedes ver ejemplos del formato en la página "Ejemplos"; cada ejemplo está escrito en formato texto, asi como en JSON.

Para colecciones (arrays), como los ítems de la factura, se usa el formato nombrecolección-sec-propiedad, donde:

• nombrecolección es el nombre de la propiedad que es una colección,
• sec es un número secuencial, que es el índice del elemento de la colección, y
• propiedad es el nombre de cada propiedad dentro de la colección.

Nota: Cuando la respuesta de un comando incluya colecciones (como el caso de la variable de retorno sunat_observacionesen el comando "emitir"), no incluirá el número de secuencia, solo aparecerá el mismo nombre de la propiedad repetida cuantos elementos tenga la colección. Ejemplo:

estado: ok
valor_resumen: a2ArXgMakKz81ZTs1A+fLqhe0hg=
codigo_descarga: a5145b10b2a252d9fc4a3aa22ab5fe7f7f71f326
codigo_documento: 20410044448-01-F001-1
sunat_respuesta: 0
sunat_descripcion: La Factura numero F001-1, ha sido aceptada
sunat_observacion: 4287 - El precio unitario de la operación que está informando difiere de los cálculos realizados en base a la información remitida - Error en la linea: 1: 4287 (nodo: "cac:AlternativeConditionPrice/cbc:PriceAmount" valor: "11114.72")
sunat_observacion: 4287 - El precio unitario de la operación que está informando difiere de los cálculos realizados en base a la información remitida - Error en la linea: 2: 4287 (nodo: "cac:AlternativeConditionPrice/cbc:PriceAmount" valor: "122228.29")

En esta respuesta del comando emitir, sunat_observacion es una colección de dos elementos.

application/json

Debe ser un objeto JSON correctamente formateado, usando comillas dobles para todos las cadenas de caracteres, incluyendo el nombre de las propiedades.

Ejemplos

En la página "Ejemplos" hay una lista de varios tipos de comprobantes, emitidos en ámbos formatos.

Librerías

PHP

Documentación: paperclip/facturas-electronicas

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.
• Carácter: 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 llamada a 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 de débito o crédito.
• baja: Solicita la baja (anulación) un comprobante.
• consultar_ruc: Obtiene información sobre un RUC, o un DNI con empresa.
• correo: Envia el PDF y el XML por correo electrónico a los destinatarios especificados.
• hola: Comando para realizar pruebas de comunicación.

Códigos y variables de retorno

Si el comando ejecutado fue exitoso, la API devolverá un código HTTP 200, y en el cuerpo de la respuesta estará la variable "estado" con el valor "ok", además de las variables y valores de retorno del comando (si es que hay), en el formato especificado en la cabecera HTTP de la petición (i.e. text/plain o application/json).

Si el comando hubiera fallado, la API devolverá un código HTTP 4xx dependiendo del tipo de error que ocasionó el fallo. El cuerpo de la respuesta tendrá al menos las siguientes variables en el formato especificado en la cabecera HTTP de la petición (i.e. text/plain o application/json):

• estado: Tendrá el valor "error".
• codigo_error: Nombre fijo que identifica al error.
• descripcion_error: Explicación del error.
• descripcion_extra: Información particular sobre lo que causó el error. Puede tener un valor vacío.

Según el tipo de error, el código HTTP que devolverá el error será uno de estos:

• 400: Errores de sintaxis o valores incorrectos en las propiedades enviadas.
• 403: Errores de autorización, como UUID o token inválido.
• 405: Cuando hay una conexión que no es por HTTP POST. El formato de la respuesta a este error siempre será JSON.
• 406: Errores en los parámetros iniciales de la conexión, o en la configuración de la cuenta. E.g. formato desconocido, envío de comprobante a la URL de producción cuando la cuenta aun no ha sido pasada a producción, etc.
• 500: Ha sucedido un error inesperado. El administrador del sistema ya habrá sido advertido. Si te comunicas con nosotros, por favor pásanos el valor de descripcion_extra, para poder facilitar la búsqueda de la causa del problema.