Introducción

Dashboard

Introducción

Guía para los primeros pasos en FiscalPOP

Que es FiscalPOP?

FiscalPOP es un API en protocolo REST para facturación electrónica con compatibilidad universal. (Language agnostic)
FiscalPOP no requiere ninguna biblioteca, dependencia o instalable y puedes utilizarlo con cualquier lenguaje de programación actual tanto en front-end como en back-end o directamente en tu desarrollo móbil.

A través de FiscalPOP podrás ofrecer soluciones de facturación electrónica customizables para tus propios desarrollos sin importar qué tan grandes o chicos sean.
Nosotros entregamos las herramientas necesarias para una integración mínima y sencilla tanto para front-end, back-end o WebServices a cualquier nivel: (Java, Python , Node, Objective-C, Ruby, etc.)

Requisitos

Iniciar las pruebas de integración es muy sencillo, no hay requisitos especiales. Sin embargo, para facturación real, es necesario obtener tu fiel y de ella tu CSD (Certificado de Sello Digital), sólo sigue los pasos que se indican a continuación según la etapa en que te encuentres.

Requisitos para iniciar integración con tu sistema

Para pruebas de integración, nosotros te daremos archivos *.cer y *.key de pruebas.
Estos archivos son el certificado y llave del CSD (Certificado de sello digital) de pruebas, los cuales son diferentes a tu FIEL, pero con la misma terminación.

Contraseña de la llave: 12345678a

Para producción, es necesario contar con tus archivos *.cer y *.key de tu FIEL, sin embargo, es necesario convertir tu archivo *.cer de tu FIEL a un certificado de sello digital.
Obtener el certificado de sello digital es muy sencillo, solamente hay que usar el programa de Certifica del SAT para obtenerlo a partir de tu *.cer original.

Para revisar si tus archivos *.cer y *.key son correctos, necesitas contar con la biblioteca de openssl en tu computadora local.

En MacOS y Linux

Comunmente ya viene instalada en entornos UNIX (Mac OS y Linux), revisa que esté en tu $PATH ejecutando:

En Windows

Sigue estas instrucciones para instalarlo en tu CLI Instalar Openssl desde sourceforge.net

Revisar versión openssl instalada
    
myuser@mycomputer:~$ openssl version
OpenSSL 1.0.2g  1 Mar 2016

Revisar que tu certificado es sello digial

En el directorio donde está tu certificadl del SAT ejecuta el siguiente comando:

    
myuser@mycomputer:~$ openssl x509 -inform DER -in certificadoSat.cer -subject -noout
...OU=Servidor 

El certificado de sello digital a diferencia del certificado del SAT contiene el campo mostrado arriba (OU=Servidor).
Si tu archivo presenta este campo, ya estas listo para facturar en producción, de lo contrario, es necesario convertirlo usando la aplicación de Certifica del SAT

Requisitos para emitir facturas reales (modo producción)

Todo cliente que desea emitir facturas a través de servicios externos al portal del SAT deben obtener su CSD a partir de su FIEL. Para ello deben seguir los siguientes pasos:

  1. Cita para obtener tu FIEL: También conocida como e.firma, consta de dos archivos ( .cer y .key) que obtienes haciendo una cita en el sat.

  2. Descargar Certifica: Antes conocido como SOLCEDI, es una aplicación de JAVA del SAT que te permitirá crear tu solicitud de Certificados de Sello Digital (CSD). En el portal del SAT puedes descargar la aplicación
    NOTA: Para ejecutar esta aplicación es necesario contar con java -version 1.8+, para saber si cuentas con java, ejecuta >$ java -version desde tu consola. Si es versión 1.8+ ya estás listo, de lo contrario descarga JVM.

  3. Ejecuta Certifica: Para ejecutar el programa llamamos >$ java -jar Certifica.jar desde nuestra consola. Al ejecutar el programa, damos click en la opción Solicitud de certificados de sello digital (CSD). Nos pedirá nuestro Certificado de firma electrónica vigente *.cer , el cual lo obtuvimos de nuestra cita para obtener la FIEL.

  4. Llenar los campos: En el paso siguiente veremos que nos pide Nombre de la sucursal y Contraseña de la clave privada. El nombre de sucursal se refiere a tener más de una sucursal que emita facturas, y nos permite identificar quien la firmó. Si tu empresa no cuenta con sucursales, te recomendamos usar "Matriz" en este campo. La contraseña que usemos será para nuestra llave del CSD, puedes usar la misma contraseña de tu FIEL si lo deseas.

  5. Enviar solicitud (SDG): al terminar guardaremos un archivo con terminación *.sdg, este lo utilizamos para solicitar nuestro CSD en el portal Certisat Web, siguiendo las instrucciones que nos muestra (Envío de solicitud de certificados de sello digital).

  6. Último paso: Una vez descargados los archivos, veremos que el CSD cuenta con dos archivos, un .key y un .cer, éstos son los archivos que se agregan a tu cliente en FiscalPOP.
    NOTA: Es común tener que esperar 5 días posteriores a obtener tu CSD para poder facturar

Imágenes de aplicación Certifica del SAT ( izquierda: pantalla inicio, derecha: pasos)

Quick Start

Para interactuar con el API de FiscalPOP es necesario poder usar JSON requests, practicamente todos los lenguajes de programación pueden usar este formato; sin embargo, recomendamos que mientras te familiarizas con el sistema utilices herramientas como Postman.

Para propósitos de esta guía, usuario es tu cuenta de FiscalPOP y cliente es cada uno de los RFCs que des de alta para facturación independiente

Crear y validar tu usuario

Si no te has registrado todavía puedes realizar el siguiente request:

    
POST https://api.fiscalpop.com/api/v1/registration/signup

// Body [raw] (application/json)
{
    "email":"user@example.com",
    "name":"Mónica Galindo",
    "password":*******,
    "phone":"+521-5536-2877" // Requerido para contacto de emergencia y sistema de pago (más adelante)
} 

Respuesta
    
// Respuesta regresa en JSON en formato texto
{
    "email":"user@example.com",
    "name":"Mónica Galindo",
    "password":*******,
    "phone":"+521-5536-2877",
    "createdAt": "2018-08-31T02:44:12.537Z",
    "masterToken":"1234-5678-90123-1213",// Esta es la clave principal de tu usuario para todas las operaciones
    "planType":0,
    "credit":0,
    "emailValid":false // No se ha validado el usuario todavía
}
    

El masterToken:... es la clave principal para todas las operaciones de alto nivel.
Es recomendable anotarla o guardala, si la pierdes, puedes consultarla en la sección de Pagos del Dashboard de FiscalPOP

Recibirás un correo de validación con un link para activar tu usuario, una vez realizado este paso ya podrás realizar todas las funciones de tu plan.

Crear tu primer cliente

Para realizar las siguientes operaciones requieres el masterToken de tu usuario, generado en la etapa anterior.

    
POST https://api.fiscalpop.com/api/v1/clients/create/:masterToken

// Body [raw] (application/json)
{
    "rfc": "ACO560518KW7",  // Puedes tener más de un mismo RFC
    "regimenFiscal": "601",
    "nombre": "HORACIO LLANOS",
    "produccion":false, // Los clientes creados con production:false simularán facturas (Importante)
    "lugarExpedicion":06700 El código postal del cliente (Emisor)
}

Respuesta
    
// Respuesta regresa en JSON en formato texto
{
    "rfc":"ACO560518KW7",
    "nombre":"HORACIO LLANOS",
    "regimenFiscal:"601",
    "isProduction":false,
    "createdAt": "2018-08-31T02:44:12.537Z",
    "masterToken": "1234-5678-90123-1213",
    "authToken":"1234-5678-90123-1213", // Este token se usará para sus operaciones en API
    "planType":0,
    "credit":0,
    "emailValid":false // No se ha validado el usuario todavía
}
    

El authToken obtenido del cliente es similar al masterToken del usuario excepto por una gran diferencia:
Todos los datos de tus clientes estan restringidos a sus propios authToken, por lo que no hay forma que puedan obtener acceso a datos de otros clientes o el mismo usuario.

Debido a la restricción de acceso por authToken individual, es seguro colocarla dentro de la aplicación o entorno de tu cliente / integración sin riesgo de seguridad.

Esto facilita que delegues la clave de acceso a aplicaciones o servidores que estén fuera de tu control, tales como desarrollos bajo contrato o para terceros.

El dueño de la cuenta (usuario) tendrá control sobre los clientes a nivel cuenta, ya que el masterToken es el único que controla pagos, creación y eliminación de usuarios, límites de facturación, etc.
Por lo que es posible utilizar FiscalPOP desde soluciones particulares de facturación hasta tu propio servicio completo de facturación electrónica.

Subir los archivos CER y KEY del SAT a tu cliente

Para subir los archivos por medio de API es necesario realizarlo en formato multipart/form-data (form-dat en Postman).
Este es el único API que no es JSON en todo FiscalPOP, esto debido a que el formato multipart/form-data es el comportamiento default que realiza una forma de HTML al emplear método POST.

Porqué es la única llamada que no es JSON?

La respuesta sencilla es que este proceso solamente se debe repetir una vez por cliente en varios años y estos archivos son delicados e importantes.

La razón técnica es debido a que los archivos por form-data se envían como Stream. Si se quisera emplear JSON de todas formas, habría que convertir el archivo a ArrayBuffer o similar. Lo cual requeriría emplear new FormData() o new FileReader() en Browser u otros procesos de encriptación binaria en servidor.

Debido a ello, determinamos que subir los archivos desde tu Dashboard de FiscalPOP o utilizar un <form enctype="multipart/form-data"> en HTML sería más apropiado. Si necesitas otro proceso para subir tus archivos del SAT, envíanos un mensaje a soporte@fiscalpop.com y explícanos la razón y con gusto te apoyamos.

Ejemplo de HTML para subir tus archivos usando multipart/form-data
    
// Se muestran dos forms, una para cer y otra para key
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo para subir CER y KEY</title>
</head>
<body>
<h3>CER UPLOAD</h3>
    <form action="https://api.fiscalpop.com/api/v1/upload/cer/:authToken" enctype="multipart/form-data" method="post">
    <input type="file" name="upload" multiple>
        <input type="submit" value="Upload">
        </form>
    <h3>KEY UPLOAD</h3>
    <form action="https://api.fiscalpop.com/api/v1/upload/key/:authToken" enctype="multipart/form-data" method="post">
    <input type="file" name="upload" multiple>
    <input type="text" name="password" placeholder="Password">
    <input type="submit" value="Upload">
    </form>
</body>
</html>

Cómo subir tus archivos usando tu Dashboard de FiscalPOP

En los bloques de Certificado y Llave, subir tus archivos respectivamente

Emitir tu primera factura

Es necesario haber creado tu usuario, tu primer cliente de pruebas y haber cargado tu certificado y llave de pruebas del SAT.

Para emitir una factura, no es necesario llenar el campo de emisor, este se obtiene del authToken de tu cliente usado en el Request siguiente:

    
POST https://api.fiscalpop.com/api/v1/cfdi/stamp/:authToken
// Puedes obtener el authToken buscando clientes o en tu dashboard

    
// Body raw (application/json)
{
    "formaPago": "01",
    "metodoPago": "PUE",
    "lugarExpedicion": "06700",
    "receptor": {
        "nombre": "Mostrador",
        "rfc": "XAXX010101000",
        "usoCFDI": "G03"
    },
    "conceptos": [
        {
            "claveProdServ": "39111806",
            "claveUnidad": "H87",
            "cantidad": 1,
            "descripcion": "PROYECTO ILUMINACION",
            "valorUnitario": 2000,
            "impuestos": [
                {
                    "type": "iva",
                    "tasa": 0.16,
                    "retencion": false
                }
            ]
        }
    ]
    

Los campos superiores son los mínimos necesarios para emitir una factura, nuestra herramienta de facturar en el Dashboard te facilitará a editar tus primeros JSON para una integración más sencilla.

Los conceptos, así como los impuestos en cada concepto son arrays.
Cada concepto puede tener más de un impuesto, tal como IVA trasladado ("retencion": false) e ieps trasladado en el caso de bebidas alcohólicas.

Respuesta correcta
    
// Respuesta de factura correcta
{
    "uuid":"ED761AAE-ACCE-4A66-B75A-A8A5D1A40067",
    "created": "2018-09-03T19:37:48.807Z",
    "json":{...},
    "xml":"...",
    "authToken":"21109f91-3310-4d53-a16e-38da5abcf314",
    "status": true,
    "sandbox": false
}
    

El valor de XML es el string literal para enviar el XML por correo, el JSON es la construcción del XML en formato JSON y puede ser empleado para interpretar el XML de forma esquemática o generar un PDF customizado.
El uuid es el ID único de tu factura, y se empleará para identificarla o cancelarla.

Respuesta incorrecta
    
// Los errores y validaciones negativas se muestran e badRequests[]
{
    "status": "",
    "code": "C-1102",
    "message": "Los siguientes elementos presentan valores equivocados: conceptos.claveProdServ",
    "badRequests": [
            {
                "formaPago": {
                    "code": "G-1030",
                    "message": "La propiedad formaPago es obligatoria, debe ser...",
                    "explanation": "formaPago debe contener el código según la ...
                    "moreInfo": "https://docs.misfacturas.mx/docs/errors/G-1030"
                }
            },
            {
                "conceptos": [
                    {
                        "code": "C-1102",
                        "message": "No se encontró la clave de producto o servicio",
                        "explanation": "Asegúrese que la clave de producto o servicio...",
                        "moreInfo": "https://docs.misfacturas.mx/docs/errors/C-1102",
                        "element": "0|clave usada: 3911806",
                        "property": "claveProdServ"
                    }
                ]
            }
    ],
    "requested": {...}

    

Las respuestas de error son explicativas y detalladas, ya que muestran el elemento y la propiedad que ha fallado, adicionalmente cada error que se encuentre en badRequests, tendrá una liga a una sección de errores, donde podrás consultarlo a más detalle si es necesario.

Los errores son fáciles de formatear y mostrar en tu intefráz o aquella de tu integración. Hay de dos tipos:

    
badRequests[]:{key:cfdiProperty}:{value:{code, message, explanation,moreInfo}}
// Cada objeto de bad requests tiene una propiedad como key su valor
// es un objeto si la propiedad no es un array (como forma de pago)

    
badRequests[]:{key:cfdiProperty}:[]{value:{code, message, explanation,moreInfo}}
// Cada objeto de bad requests tiene una propiedad como key su valor
// es un array con objetos si la propiedad es un array (como conceptos)
    

Cancelar tu primera factura

Es necesario contar con los UUIDs de la factura a cancelar, este UUID se recibe en la respuesta de la factura al timbrarse correctamente.

        
POST https://api.fiscalpop.com/api/v1/cfdi/cancel/:authToken
// Puedes obtener el authToken buscando clientes o en tu dashboard
    
    
// Body raw (application/json)
{"uuids": ["CA9BC26F-73A6-467C-81B9-774402436E28"]}
    

Puedes mandar más de un UUID en formato de String[] tal como se muestra arriba.

Respuesta correcta
    
// El status 200, 201 indica que se canceló correctamente
{
    "folios": [
        {
            "estatus": 201,
            "uuid": "CA9BC26F-73A6-467C-81B9-774402436E28"
        }
    ],
    "fecha": "2018-09-03T20:47:36.000Z",
    "rfcEmisor": "ACO560518KW7"
}

    

Entorno Pruebas / Producción

En FiscalPOP, crear datos de producción o pruebas depende del tipo de cliente que se genere.
Los clientes de tipo "produccion":false siempre serán de pruebas de integración, todas sus facturas serán simuladas. Sin embargo, el proceso de facturación de un cliente simulado es exactamente el mismo que el de producción, si una factura pasa la simulación pasará un timbrado de producción también.

Cuando tu integración esté avanzada, es recomendable tener tanto un cliente de pruebas y uno de producción, de esta forma, el único cambio en tu plataforma es modificar el authToken y cambiar el de pruebas por aquél de producción. Ya que los clientes creados no pueden intercambiarse de pruebas a producción (o viceversa).

Una vez que estés listo para facturar en producción, habrá que crear un cliente con los mismos datos y el campo "produccion":true junto con sus archivos de SAT originales, todas las facturas que emita este cliente serán reales


POST https://api.fiscalpop.com/api/v1/clients/create/:masterToken
// Body [raw] (application/json)
{
    "rfc": "ACO560518KW7",  // Puedes tener más de un mismo RFC
    "regimenFiscal": "601",
    "nombre": "HORACIO LLANOS",
    "produccion":false, // Los clientes creados con production:false simularán facturas
    "lugarExpedicion":06700 El código postal del cliente (Emisor)
}

Recomendaciones de configuración de clientes

Idealmente, deberías de tener un cliente de prueba para cada tipo de integración o por cada RFC, esto te permite utilizar el debugger (En plan integrador solamente) para resolver rápidamente los errores durante prueba de integración, los cuales pueden originarse de manera diferente según su enviroment. (E.g.)

(Arriba) Horacio Llanos tiene dos tipos de integraciónes (móvil y web App), aunque un solo RFC.
El desarrollo de su web App es diferente a aquel del móvil, debido a que son procesos diferentes y queremos eliminar todos los posibles bugs durante el desarrollo, hay un cliente de pruebas para el Móvil y otro para el Web App.

Una vez que esté listo el desarrollo de ambos, cambiaríamos el authToken tanto en la Web App como en el móvil, por aquel de producción (23319f51...).

Todas las facturas emitidas o canceladas por clientes de pruebas son gratuitas y no se cargarán al final de mes.

Contador de facturas de prueba y producción en tablero de tu Dashboard