Skip to content

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.fabo.dev/v1/<UUID>/<COMANDO>

Los comprobantes de prueba estarán disponibles al menos 24 horas, después serán eliminados.

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

https://api.fabo.dev/v1/<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 dos 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 por cada elementos que tenga la colección. Ejemplo:

1
2
3
4
5
6
7
8
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/fabo

Sobre los cálculos numéricos

Todos los campos numéricos aceptan una cantidad arbitraria de decimales. Si la documentación indica que se realizará algún cálculo, al finalizar el mismo todos los valores 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 los parámetros booleanos 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.fabo.dev/v1/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: Envía el comprobante de pago y sus documentos relacionados por correo electrónico.
  • hola: Comando para realizar pruebas de comunicación.

Códigos y variables de retorno

Si la ejecución del comando fue exitoso o resultó en un error, la API devolverá un código HTTP y opcionalmente en el cuerpo de la respuesta información sobre el comando o el error.

Cuando el comando fue ejecutado satisfactoriamente

La API devolverá un código HTTP 200, con las variables y valores de retorno del comando en el cuerpo de la respuesta, en el formato especificado en la cabecera HTTP de la petición (i.e. text/plain o application/json).

Algunos comandos que no retornan valores (como correo) devolverán el código HTTP 204.

Cuando el comando falló

Si el comando no se completó por algún error, 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):

  • codigo_error: Identificador único del 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.

En caso suceda un error inesperado, la API devolverá el código HTTP 500, y alertará al administrador para revisar el problema. Te pedimos te comuniques con nosotros enviándonos el valor de descripcion_extra, para facilitar la reparación del problema.