Documentación de API REST para Integraciones

Integra tu aplicación con Facturación Electrónica. Este API de Pagos & Facturas te permite emitir todos los tipos de comprobantes electrónicos: facturas, retenciones, notas de crédito, liquidación de compras y guías de remisión.

El API está diseñado como un servicio web REST. De esta manera resulta sencillo conversar con nuestra interfaz utilizando cualquier librería en cualquier lenguaje que provea un cliente HTTP, ya que utilizamos componentes del estándar como los verbos y los códigos de respuesta.

Todos las operaciones responden en formato JSON, incluso los errores.

Pagos & Facturas se encarga de todo el proceso de emisión del comprobante. El proceso de emisión bajo condiciones normales, toma entre 3 a 5 segundos. Luego de ese período bastará con consultar el comprobante para conocer su estado.

Proceso de emisión

Comprende las siguientes fases:

Creación: Se registra el comprobante para posterior referencia.
Firmado: Utilizando el certificado de firma electrónica y un algoritmo de firma digital, el comprobante es firmado para que el SRI pueda verificar su legitimidad.
Envío SRI: El comprobante es enviado al SRI para ser procesado.
Consulta de autorización SRI: Luego de un período de espera, Pagos & Facturas consulta la autorización del comprobante.
Envío por email: Se envía el comprobante al correo del receptor del comprobante, si una dirección de correo electrónico válida fue provista al momento de emitir el comprobante.

Tablas de Referencia

Para el desarrollo de esta API se tomaron en consideración las siguiente tablas las mismas que tienen que ser revisadas para el envió del JSON.

Tipos de Formas de Pago

Código	Forma de Pago
01	SIN UTILIZACION DEL SISTEMA FINANCIERO
15	COMPENSACIÓN DE DEUDAS
16	TARJETA DE DÉBITO
17	DINERO ELECTRÓNICO
18	TARJETA PREPAGO
19	TARJETA DE CRÉDITO
20	OTROS CON UTILIZACION DEL SISTEMA FINANCIERO
21	ENDOSO DE TÍTULOS

Tipos de Documento

Código	Tipo de identificación
04	RUC
05	CÉDULA
06	PASAPORTE
08	IDENTIFICACION DEL EXTERIOR

Estados de Comprobante

Código	Estado del Comprobante
N	NOTIFICADO
F	FIRMADO
A	ANULADO

Tipos de Ambiente

Código	Ambiente del Sistema
1	DESARROLLO
2	PRODUCCIÓN

Tipos de documentos

Código	Documento
01	FACTURA
03	LIQUIDACIÓN DE COMPRA
04	NOTAS DE CRÉDITO
41	REEMBOLSOS
06	GUÍAS DE REMISIÓN
07	RETENCIONES

Tipos Impuestos

Código	Impuesto
1	RENTA
2	IVA

Impuestos

Tipo de Impuesto	Descripción	Código de Impuesto	Porcentaje de Impuesto
2	0%(Retención en cero)	7	0
2	0%(No procede retención)	8	0
2	5%	4580	5
2	10%	9	10
2	20%	10	20
2	30%	1	30
2	50%	11	50
2	70%	2	70
2	100%	3	100

Autenticación

Para obtener la clave del API, inicia sesión con tu cuenta en pagosyfacturas.com, ve a la opción Perfil y la sección "API Key". Pagos & Facturasotorga a cada cliente las siguientes credenciales:

ID de Cliente (AppId) es usado en cada invocación del API.
Clave Secreta (AppSecret) se usa para hacer cálculos de Hashing y enviar estos en las credenciales.

Formato del Header en la invocación del API

Todas las llamadas al API deben tener los siguientes campos en el Header.

Campo 'Content-Type'

"application/json"

Campo 'AppId'

Hash alfanumérico entregado por Pagos & Facturas

Campo 'Seed'

Fecha y hora actual en formato GMT

Ej: 2020-08-23T07:58:30.996
Ejemplo de uso en php: date('c');

Campo 'Nonce'

Cadena alfanumérica random generada por cada llamada desde el cliente

Ej: HSKI234KJ483JF

Campo 'Token'

Se concatenan el 'Nonce', el 'Seed', el 'AppSecret' y todo esto se lo codifica con algoritmo SHA1 y a su vez codificado en Base64:

Base64(Sha1(Nonce+Seed+AppSecret))

Ejemplo de formato de Header

"AppId" : "V1oW1RHpw8GtxwGoIkuq",
"Token" : "NjNhYWFjY2U5YTU3MGJkNjJkZmQyYzhkMDNmOGE4Y2Y5M2M1OWQ2Yg==",
"Seed" : "2020-08-23T07:58:30.996",
"Nonce" : "a2pmdTc4dWpyaGZ5dA=="

Consulta de Comprobantes

Listado de comprobantes generados.

ACTION: https://api.pagosyfacturas.com/api/billing/list/
REQUEST BODY:

{      "company":"0916293723001", //RUC DE LA EMPRESA      "fechaDesde":1595264400, //FECHA CONVERTIDA A FORMATO UNIX TIMESTAMP      "fechaHasta":1612051200, //FECHA CONVERTIDA A FORMATO UNIX TIMESTAMP      "pageSize":10, //CANTIDAD DE REGISTROS POR LA CONSULTA      "page":1, //PAGINA ACTUAL DE LA CONSULTA      "tipoDoc":"ALL", //ALL (Todos los documentos), FACTURA, NOTACREDITO, RETENCION, GUIA      "order":"DESC" //ORDENADO POR FECHA DESC (Descendente), ASC (Ascendente) }

RESPONSE:

Emisión de Facturas

Operación

https://api.pagosyfacturas.com/api/billing/create/

Para la emisión de una factura se debe enviar la información completa del comprobante en el cuerpo del requerimiento en formato JSON.

{      "company":"XXXXXXX001", //RUC DE LA EMPRESA     "person":{      "document":"09XXXXXX39", // CI, RUC DE LA PERSONA      "documentType":"05", //TIPO DE DOCUMENTO [TABLA DE TIPOS DE DOCUMENTO]      "name":"John Charles",      "surname":"Doe Smith",      "email":"[email protected]",      "mobile":"093249049",      "address":{                 "street":"La joya",                 "city":"Guayaquil",                 "country":"EC"                } },     "items":[              {                  "sku":"PRO06",                  "name":"PC Desktop 4Ghz", "qty":1,                  "price":10.00,                  "discount":0.00, "subtotal":10.00, "tax":1.20,                  "total":11.20              },              {                  "sku":"PRO05", "name":"OTRO PRODUCTO",                  "qty":1,                  "price":10.00,                  "discount":0.00, "subtotal":10.00, "tax":1.20,                  "total":11.20              }             ],     "billingParameters":{                   "establecimiento":"001",                   "ptoEmision":"002",                   "infoAdicional": [  //Información adicional del comprobante                                       {                                           "key":"email",                                          "value":"[email protected]"                                        },                                        {                                          "key":"direccion",                                          "value":"Guayaquil, una calle y la que cruza"                                       }                                    ],      "formaPago":"01",     "plazoDias":"30"                           },      "userAgent":"PyF Api/1" }

Respuestas

Retorna un objeto tipo factura que incluye parámetro status y message, el cual identifica si fue exitoso o fallido.

Mensaje Exitoso

{      "status": {              "status": "success",              "message": "",              "reason": "",              "date": "2021-01-30T12:38:29-05:00"                },              "requestId": "472",             "comprobante": "001-002-000000010" //NUMERO DE COMPROBANTE GENERADO }

Mensaje Fallido

{      "status": {              "status": "failure",              "message": "601. No ha especificado el Auth-Key.",              "reason": "",              "date": "2021-01-30T12:38:29-05:00"                },              "requestId": "472",             "comprobante": ""}

Consulta de RIDE

Consulta de la representación impresa del documento electrónico (RIDE).

ACTION: https://api.pagosyfacturas.com/api/billing/ride/FACTURA_XXXXXXX001_001-001-000000249
REQUEST BODY: Vacío
RESPONSE: Octet-Stream

Consulta de XML

Consulta de representación XML de los comprobantes.

ACTION: https://api.pagosyfacturas.com/api/xml/ride/FACTURA_XXXXXXX001_001-001-000000249
REQUEST BODY: Vacío
RESPONSE: Archivo XML

Consultar detalle de Factura

ACTION: https://api.pagosyfacturas.com/api/billing/FACTURA_XXXXXXX001_001-002-000000009
REQUEST BODY: Vacío
RESPONSE:

{           "status": {                  "status": "success",                  "message": "", "reason": "",                  "date": "1/30/2021 12:53:08 PM"                     },           "details": {                  "compania": "0916293723001",                  "numeroComprobante": "001-002-000000009",                  "estado": "N",                  "establecimiento": "001",                  "puntoEmision": "002",                  "secuencial": "000000009",                  "codigoDocumento": "01",                  "rucReceptor": "0923021539",                  "razonSocialReceptor": "John Doe",                  "claveDeAcceso": "2001202101091629372300110010020000000091234567812",                  "autorizacion": "2001202101091629372300110010020000000091234567812",                  "fecha": "2021-01-20T16:59:02.723",                  "correos": "[email protected]",                  "ambiente": 1,                  "codigoFormaPago": "01",                  "valorTotalSinImpuesto": 20,                  "valorImpuesto": 2.4,                  "valorTotal": 22.4,                  "detallesfactura": [                              {                                     "codigo": "2",                                     "descripcion": "PC Desktop 4Ghz",                                     "cantidad": 1,                                     "precioUnitario": 10,                                     "descuento": 0,                                     "precioTotalSinImpuesto": 10,                                     "tarifa": "12",                                     "baseImponible": 10,                                    "iva": 1.2000000476837158                              },                             {                                  "codigo": "2",                                  "descripcion": "OTRO PRODUCTO",                                  "cantidad": 1,                                 "precioUnitario": 10,                                  "descuento": 0,                                  "precioTotalSinImpuesto": 10,                                  "tarifa": "12",                                  "baseImponible": 10,                                  "iva": 1.2000000476837158                              }                                        ],          "log": [                            {                                  "fecha": "2021-01-20T16:59:48.023",                                  "proceso": "Notificación",                                  "mensaje": "Documento notificado"                            },                           {                                  "fecha": "2021-01-20T16:59:45.557",                                  "proceso": "Autorización SRI",                                  "mensaje": "Autorizado"                            },                           {                                  "fecha": "2021-01-20T16:59:42.057",                                  "proceso": "Envío SRI",                                  "mensaje": "Documento recibido"                             },                           {                                  "fecha": "2021-01-20T16:59:02.717",                                  "proceso": "Firma", "mensaje": "Documento firmado"                             }                  ]                 } }