Operaciones

Catálogo SAT

Referencia de operaciones por API

Guía para integraciones por API en FiscalPOP, todos los requests son en formato JSON a excepción de subir archivos del SAT.

Registro de usuarios

Los usuarios son la cuenta principal de tu servicio de facturación, cada usuario (cuenta) puede tener un número ilimitado de clientes (RFCs) según el plan que maneje.

Los usuarios creados en FiscalPOP son universales, esto implica que los entornos de producción y pruebas (sandbox) no dependen del tipo de usuario o plan creado, sino del tipo de clientes que configuras dentro de tu cuenta.
Las facturas de clientes tipo pruebas no tienen costo.

Crear tu usuario por API

API endpoint
    
POST: https://api.fiscalpop.com/api/v1/registration/signup
    
Cuerpo del request (req.body, application/json)
    
{
    "name":"Gabriel Balsa",
    "email":"contacto@ejemplo.mx",
    "password":"*****",
    "phone":"+524423339876", // Campo opcional, pero aumenta la seguridad de tus pagos
}
    

Al registrar tu usuario, recibirás un token de validación a tu correo con una liga para activar tu usuario; Sin embargo, ya podrás acceder a tu dashboard con este usuario.

Respuesta correcta
    
{
    "name": "Gabriel Balsa",
    "email": "contacto@ejemplo.mx",
    "password": "12345", // Password regresa visible
    "phone": "+524423339876",
    "createdAt": "2018-09-06T21:11:42.264Z",
    "masterToken": "b4a52fd8-19f6-4eac-83d7-18e98f7722dd", // Tu token principal
    "planType": 0,
    "credit": 0,
    "emailValid": false
}
    

Validar tu usuario (activar)

Recibirás el siguiente correo con el token de validación (en negritas). Para realizar la activación utiliza el token en el siguiente GET request

API endpoint
    
GET: https://api.fiscalpop.com/api/v1/registration/validate/:validationToken
    
Respuesta correcta
    
Validation completed & user enabled!
    

Operaciones clientes

Existen dos diferentes tipos de entorno para clientes:

Agregar nuevo cliente

API endpoint
    
POST: https://api.fiscalpop.com/api/v1/clients/create/:masterToken
    
Cuerpo del request (req.body, application/json)
    
{
    "rfc": "ACO560518KW7", // Puedes tener el mismo RFC varias veces en clientes tipo pruebas
    "regimenFiscal": "601",
    "nombre": "HORACIO LLANOS",
    "lugarExpedicion": "06700",
    "isProduction":false  // Determina si el cliente es prueba (false) o producción (true)
}
    

Una vez creado el cliente, éste podrá ser editado pero no podrás cambiarlo de pruebas a producción; sin embargo, todo proceso que pasa satisfactoriamente el modo de pruebas, pasará en modo productivo de igual manera.

Respuesta correcta
    
{
    "rfc": "ACO560518KW7",
    "regimenFiscal": "601",
    "nombre": "HORACIO LLANOS",
    "lugarExpedicion": "06700",
    "isProduction": false,
    "authToken": "03708435-6157-45b7-a542-f0483b24cff7", // Token único de cliente emisor
    "masterToken": "b4a52fd8-19f6-4eac-83d7-18e98f7722dd"
}
    

El authToken será utilizado para todas las operaciónes a nombre del cliente, tal como emitir, cancelar y buscar facturas, así como consultar los catálogos del SAT a través de nuestro API.

Editar cliente

API endpoint
    
POST: https://api.fiscalpop.com/api/v1/clients/update/:masterToken/:authToken
    
Cuerpo del request (req.body, application/json)
    
{
    "nombre": "HORACIO LLANOS",
    "lugarExpedicion": "06700"
    "regimenFiscal": "601"
}
    

Éstos son los únicos campos que pueden ser editados.

Respuesta correcta
    
{
    "rfc": "ACO560518KW7",
    "regimenFiscal": "601",
    "nombre": "HORACIO LLANOS",
    "isProduction": false,
    "authToken": "03708435-6157-45b7-a542-f0483b24cff7",
    "masterToken": "b4a52fd8-19f6-4eac-83d7-18e98f7722dd",
    "lugarExpedicion": "06700"
}
    

Borrar cliente

API endpoint
    
POST: https://api.fiscalpop.com/api/v1/clients/remove/:masterToken
    
Cuerpo del request (req.body, application/json)
    
{
    "authToken": "03708435-6157-45b7-a542-f0483b24cff7"
}
    
Respuesta correcta
    
{
    "removed": true,
    "authToken": "03708435-6157-45b7-a542-f0483b24cff7"
}
    

Buscar clientes

API endpoint
    
GET: https://api.fiscalpop.com/api/v1/clients/find/:masterToken
    
Respuesta correcta
    
[
    {
        "rfc": "ACO560518KW7",
        "regimenFiscal": "601",
        "nombre": "HORACIO LLANOS",
        "isProduction": false,
        "authToken": "03708435-6157-45b7-a542-f0483b24cff7",
        "masterToken": "b4a52fd8-19f6-4eac-83d7-18e98f7722dd",
        "lugarExpedicion": "06700"
    }
]
    

De este modo podrás obtener todos los clientes asignados a tu cuenta de integración. En esta ruta, los cientes contienen el campo de masterToken.

Obtener perfil de cliente

API endpoint
    
GET: https://api.fiscalpop.com/api/v1/clients/findBy/:authToken
    
Respuesta correcta
    
{
    "rfc": "ACO560518KW7",
    "regimenFiscal": "601",
    "nombre": "HORACIO LLANOS",
    "isProduction": false,
    "authToken": "03708435-6157-45b7-a542-f0483b24cff7",
    "lugarExpedicion": "06700"
}

    

Solamente se responde con el perfil del cliente, el masterToken no será visible nunca por esta ruta.

Billing clientes

API endpoint
    
GET: https://api.fiscalpop.com/api/v1/clients/billing/find/:masterToken
    
Respuesta correcta
    
[
    {
        "masterToken": "659ddcb1-799b-4149-86e8-1b8b54bb56ec",
        "month": 7,
        "year": 2018,
        "paid": false,
        "type": "service", // service | subscription
        "createdAt": "2018-08-22T05:52:12.565Z",
        "owed": 0,
        "owedTax": 0,
        "paidDate": null,
        "stamped": 0,
        "canceled": 0,
        "stampedTest": 3,
        "distribution": [
            {
                "authToken": "25519f51-8710-4c37-a16e-38da5abcf314",
                "month": 7,
                "rfc": "ACO560518KW7",
                "year": 2018,
                "canceled": 0,
                "stamped": 3
            }
        ]
    }
]
    

Operaciones CFDI

La funcionalidad principal de FiscalPOP. El schema de CFDI es muy sencillo de elaborar y campos innecesarios son eliminados u opcionales (tales como definir el total, etc.), el único reto está en obtener las claves del catálogo del SAT indicadas para cada campo.

Emitir facturas

Dependiendo del authToken que utilices para facturar, se intentará emitir una factura de pruebas o una real.
Si el authToken pertenece a un cliente de pruebas, la factura siempre será simulada, si pertenece a un cliente de producción, ésta será una factura real.

API endpoint
    
POST: https://api.fiscalpop.com/api/v1/cfdi/stamp/:authToken
    
Campos mínimos del request CFDI (req.body, application/json)
    
{
    "formaPago": "01",
    "metodoPago": "PUE",
    "lugarExpedicion": "06700",
    "receptor": {
        "nombre": "Mostrador",
        "rfc": "XAXX010101000",
        "usoCFDI": "G03"
    },
    "conceptos": [
        {
            "claveProdServ": "10101500",
            "claveUnidad": "KGM",
            "cantidad": 1,
            "descripcion": "PROYECTO ILUMINACION MASCAREÑO",
            "valorUnitario": 2000,
            "impuestos": [
                {
                    "type": "iva",
                    "retencion": false,
                    "tasa": 0.16
                }
            ]
        }
    ]
}
    
Respuesta correcta
    
{
    "uuid": "3407BE43-651B-45B2-A721-D41295ED587B", // El UUID de la factura para identificarla 
    "created": "2018-09-07T17:54:26.150Z",
    "json": { // JSON structure del CFDI, útil para construír un PDF con los campos completos de la factura
        "@": {
            "xmlns:cfdi": "http://www.sat.gob.mx/cfd/3",
            "xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance",
            "xsi:schemaLocation": "http://www.sat.gob.mx/cfd/3 http://www.sat.gob.mx/sitio_internet/cfd/3/cfdv33.xsd",
            "Version": "3.3",
            "Serie": "A",
            "Folio": "01",
            "Fecha": "2018-09-07T12:54:25",
            "TipoDeComprobante": "I",
            "FormaPago": "01",
            "MetodoPago": "PUE",
            "LugarExpedicion": "06700",
            "SubTotal": "2000.00",
            "Total": "2320.00",
            "Moneda": "MXN",
            "Sello": "Eh49rUg0RiMsNmuiNwGay3oxWt9+Y16s+Ui9bq5+jzSicfkxPfUdCumYsAOndQRfUUK+cuWn1gCWBa/guFY1hwJYvFg/5X4gAZ...",
            "Certificado": "MIIF6zCCA9OgAwIBAgIUMjAwMDEwMDAwMDAzMDAwMDU2OTIwDQYJKoZIhvcNAQELBQAwggFmMSAwHgYDVQQDDBdBLkMu...",
            "NoCertificado": "20001000000300005692"
        },
        "cfdi:Emisor": {
            "@": {
                "Nombre": "Horacio Llanos",
                "Rfc": "ACO560518KW7",
                "RegimenFiscal": "601"
            }
        },
        "cfdi:Receptor": {
            "@": {
                "Nombre": "Mostrador",
                "Rfc": "XAXX010101000",
                "UsoCFDI": "G03"
            }
        },
        "cfdi:Conceptos": {
            "cfdi:Concepto": [
                {
                    "@": {
                        "ClaveProdServ": "10101500",
                        "ClaveUnidad": "KGM",
                        "Cantidad": "1",
                        "Descripcion": "PROYECTO ILUMINACION MASCAREÑO",
                        "ValorUnitario": "2000.00",
                        "Importe": "2000.00"
                    },
                    "cfdi:Impuestos": {
                        "cfdi:Traslados": {
                            "cfdi:Traslado": [
                                {
                                    "@": {
                                        "Base": "2000.00",
                                        "Impuesto": "002",
                                        "TipoFactor": "Tasa",
                                        "TasaOCuota": "0.160000",
                                        "Importe": "320.00"
                                    }
                                }
                            ]
                        }
                    }
                }
            ]
        },
        "cfdi:Impuestos": {
            "@": {
                "TotalImpuestosTrasladados": "320.00"
            },
            "cfdi:Traslados": {
                "cfdi:Traslado": [
                    {
                        "@": {
                            "Impuesto": "002",
                            "TipoFactor": "Tasa",
                            "TasaOCuota": "0.160000",
                            "Importe": "320.00"
                        }
                    }
                ]
            }
        }
    },
    "xml": ".....", // El XML string que se envía al receptor tal cual
    "authToken": "25519f51-8710-4c37-a16e-38da5abcf314",
    "status": true,
    "sandbox": false
}
    

Cancelar facturas

Existen dos procesos para cancelar facturas actualmente, basado en el nuevo lineamiento del SAT sobre aceptación de cancelación.
El procedimiento de API es el mismo para ambas; Sin embargo, en algunos casos la factura será cancelada inmediatamente y en otras tendrá que ser confirmada por el receptor en su buzón fiscal (Portal SAT) en los siguientes 3 días, de no hacerlo, la factura se considerará cancelada.

API endpoint
    
POST: https://api.fiscalpop.com/api/v1/cfdi/cancel/:authToken
    
Campos del request (req.body, application/json)
    
{"uuids": ["96AF6CF8-7D56-41AD-B63B-80F531A311E5"]}

Respuesta correcta
    
{
    "folios": [
        {
            "estatus": 201,
            "uuid": "3407BE43-651B-45B2-A721-D41295ED587B"
        }
    ],
    "fecha": "2018-09-07T18:34:17.000Z",
    "rfcEmisor": "ACO560518KW7"
}
    

Buscar facturas

1) Obtener las últimas 50 facturas de cada cliente, tal cual fueron emitidas.

API endpoint
    
GET: https://api.fiscalpop.com/api/v1/cfdi/find/:authToken
    
Respuesta correcta
    
[
    {
        "created": "2018-09-07T17:54:26.150Z",
        "_id": "5b92bb525df39c7e2712ee05",
        "uuid": "3407BE43-651B-45B2-A721-D41295ED587B",
        "json": {...},
        "xml":"...",
        "authToken": "25519f51-8710-4c37-a16e-38da5abcf314",
        "status": false,
        "sandbox": false
    }
]
    

2) Obtener todos los datos de una sola factura para un cliente, tal cual fué emitida, mediante su UUID.

API endpoint
    
GET: https://api.fiscalpop.com/api/v1/cfdi/find/:authToken/:uuid
    
Respuesta correcta
    
[
    {
        "created": "2018-09-07T17:54:26.150Z",
        "_id": "5b92bb525df39c7e2712ee05",
        "uuid": "3407BE43-651B-45B2-A721-D41295ED587B",
        "json": {...},
        "xml":"...",
        "authToken": "25519f51-8710-4c37-a16e-38da5abcf314",
        "status": false,
        "sandbox": false
    }
]
    

3) Obtener todas las facturas de cada cliente, en un rango de fechas.

El xml se elimina de la búsqueda y el json solo tendrá los datos aqui mostrados.
Hacemos esto para minimizar el tamaño de la transferencia.

Nota: Si deseas obtener los datos de una factura individual dentro de una búsqueda de cientos de facturas o más, te aconsejamos Hacer una búsqueda por rango y posteriormente usar la búsqueda por uuid de la factura que deseas obtener todos los datos.

API endpoint
    
GET: https://api.fiscalpop.com/api/v1/cfdi/findBy/:authToken/:start/:end
    
Respuesta correcta
    
[
    {
        "created": "2018-09-07T17:54:26.150Z",
        "_id": "5b92bb525df39c7e2712ee05",
        "uuid": "3407BE43-651B-45B2-A721-D41295ED587B",
        "json": {
            "@": {
                "Version": "3.3",
                "Serie": "A",
                "Folio": "01",
                "Fecha": "2018-12-04T18:50:40",
                "TipoDeComprobante": "I",
                "FormaPago": "03",
                "MetodoPago": "PUE",
                "LugarExpedicion": "06700",
                "SubTotal": "400.00",
                "Total": "421.33",
                "Moneda": "MXN"
            },
            "cfdi:Emisor": {
                "@": {
                    "Nombre": "Horacio Llanos",
                    "Rfc": "ACO560518KW7",
                    "RegimenFiscal": "601"
                }
            },
            "cfdi:Receptor": {
                "@": {
                    "Nombre": "Mostrador",
                    "Rfc": "XAXX010101000",
                    "UsoCFDI": "I06"
                }
            }
        }
        "authToken": "25519f51-8710-4c37-a16e-38da5abcf314",
        "status": false,
        "sandbox": false
    }
]