Inicio

Guías

Referencia

Plugins

Facturación electrónica

Funcionamiento

El API para generación de factura electrónica de Openpay es parte de las funcionalidades que ofrece la plataforma para complementar el proceso de compra del usuario.

El proceso de generación se realiza de manera asíncrona, el comercio envía la petición de generación a Openpay para que se valide la petición y se dispare el proceso de generación y se tendrá como respuesta el resultado de la validación, una vez que se lanza el proceso de generación Openpay notificará al comercio a través de notificación (webhook) el resultado final de la generación.

Funcionamineto generacion factura electrónica

Requerimientos

Ambiente de Pruebas

  1. Enviar el merchant_id de la cuenta de pruebas de Openpay

Ambiente de Productivo

  1. Enviar el merchant_id de la cuenta productiva de Openpay
  2. Enviar la información fiscal del emisor del CFDI
  3. Enviar el CSD (Certificado de Sello Digital): llave privada, pública y contraseña que otorga el SAT para la emisión de CFDI
  4. Enviar el logotipo del comercio que se colocará en la representación impresa del CFDI (PDF)

Nota: Esta información deberá ser enviada únicamente a su ejecutivo de cuenta.

Configuración

Una vez recibida la información describa en el punto anterior, se habilitará en la cuenta la API de facturación y se podrá configurar la URL en donde desea recibir las notificaciones de la generación de CFDI. Ver sección de “Notificaciones” en este documento.

Para configurar la URL, ir a: Configuraciones -> Webhooks -> Agregar y seleccionar “Personalizar Eventos” y notificaciones de Facturas creadas y fallidas como se muestra en la siguiente imagen:

Funcionamineto generacion factura electrónica

Nota: La sección de eventos de “Facturas” solo estará disponible hasta que en su cuenta de Openpay que activado la API de facturación.

Endpoints

Los servicios de facturación se encuentran disponibles dentro de la API de Openpay y requieren la misma autenticación de los otros servicios. Para mas información sobre la autenticación consulte: http://www.openpay.mx/docs/api/?#autenticaci-n

Endpoints para facturación:

Acción

URL

Método

Generación de Factura

https://{enviroment}/v1/{merchant_id}/invoices/v33

POST

Listado de Facturas

https://{enviroment}/v1/{merchant_id}/invoices/v33

GET

Obtención de Factura

https://{enviroment}/v1/{merchant_id}/invoices/v33/{UUID}

GET

Cancelar Factura

https://{enviroment}/v1/{merchant_id}/invoices/v33/{UUID}

DELETE

Ambientes:

  • Pruebas: https://sandbox-api.openpay.mx
  • Producción: https://api.openpay.mx

Ejemplo:

POST:

https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/invoices/v33

DELETE:

https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/invoices/v33/92ACB752-0F17-427F-A007-A63DFC612036

Generación de CFDI

Para la generación de CDFI es necesario enviar un Objeto Generacion de CFDI. Los campos de este objeto deberán ser enviados en un mensaje JSON realizando una petición HTTP POST a la URL: https://{enviroment}/v1/{merchant_id}/invoices/v33

Lista de Objetos

Ejemplo de petición:

   {
        "subtotal": 2001.75,
        "total_trasladados": 320.28,
        "total": 2322.03,
        "tipo_de_cambio": 1,
        "forma_pago": "04",
        "hide_total_items": true,
        "hide_total_taxes": true,
        "complements": {
            "aerolineas": {
                "tua": 233.51,
                "otros_cargos": [
                    {
                        "codigo_cargo": "YQ",
                        "descripcion_cargo": "Asistencia TAR",
                        "importe": 51.00
                    }
                ]
            }
        },
        "moneda": "MXN",
        "conceptos": [
            {
                "clave": "78111500",
                "clave_unidad": "E54",
                "identificador": "6K9MVV CUAHUTEMOC BLANCO",
                "cantidad": 1,
                "unidad": "Viaje",
                "descripcion": "TRANSPORTACION AEREA DE QRO A MTY",
                "valor_unitario": 1744,
                "importe": 1744,
                "traslados": [
                    {
                        "impuesto": "002",
                        "base": 1744,
                        "tipo_factor": "Tasa",
                        "tasa": 0.16,
                        "importe": 279.04
                    }
                ]
            },
            {
                "clave": "78111500",
                "clave_unidad": "E54",
                "identificador": "6K9MVV CUAHUTEMOC BLANCO",
                "cantidad": 1,
                "unidad": "Viaje",
                "descripcion": "SEGURO DE CANCELACION",
                "valor_unitario": 257.75,
                "importe": 257.75,
                "traslados": [
                    {
                        "impuesto": "002",
                        "base": 257.75,
                        "tipo_factor": "Tasa",
                        "tasa": 0.16,
                        "importe": 41.24
                    }
                ]
            }
        ],
        "lugar_expedicion": "76090",
        "observaciones": "Si desea obtener su factura por el servicio de Asistencia TAR, ingrese a la siguiente dirección:\nhttp://masistencia.emitecliente.mx/index.php/clientefacturacion/generarFactura\nSi lo desea puede ingresar a esta dirección desde nuestro portal.",
        "serie": "TAR",
        "impuestos_traslado": [
            {
                "impuesto": "002",
                "tasa": 0.16,
                "importe": 320.28,
                "tipo_factor": "Tasa"
            }
        ],
        "impuestos_retencion": [],
        "folio": "024295",
        "receptor": {
            "nombre": "Alberto Montellano Sandoval",
            "rfc": "MOSA8311152G0",
            "email": "alberto.montellano@tcpip.tech",
            "uso_cfdi": "G03"
        },
        "invoice_id": "24295",
        "metodo_pago": "PUE",
        "tipo_comprobante": "I"
    }

Respuesta de solicitud de generación

Campo

Descripción

invoice_id

Identificador de la factura enviado en la solicitud

request_id

POST

date

POST

status

POST

fiscal_status

POST

message

POST

Ejemplo de petición:

   {
      "invoice_id": "order1234",
      "request_id": "7edd3834-81a7-4609-ac80-c0fd415c5723",
      "date": "2016-04-25T12:14:52-05:00",
      "status": "ok",
      "fiscal_status": "active",
      "message": "Cfdi generation started"
    }

Listado de CFDI

Para obtener un listado de los CFDI generados basta con realizar una petición HTTP GET a la URL del API de facturación. Esto obtendrá un listado de las últimas facturas generadas por el comercio, en order descendente de fecha de creación.

El API permite usar los parámetros limit y offset para listar los CFDI generados, pero se recomienda utilizar esta opción en conjunto con el parámetro creation.

Parámetros aceptados en la petición

Campo

Descripción

creation

Obtener CFDI con fecha de creación del día indicado. YYYY-MM-DD.

creation[gte]

Obtener CFDI con fecha de creación mayor o igual al día indicado. YYYY-MM-DD

creation[lte]

Obtener CFDI con fecha de creación menor o igual al día indicado. YYYY-MM-DD

id

Busca CFDI por su invoice_id

limit

Indica el número de resultados a obtener en el API, valor máximo 500. 10 por defecto.

offset

Indica el número de resultados iniciales a ignorar, usado en conjunto con limit para obtener más registros.

Campos de objetos de respuesta en listado de CFDI

Campo

Descripción

invoice_id

Identificador de la factura enviado en la solicitud

creation_date

Fecha en la que se solicitó la generación

issue_date

Fecha en que se envió a timbrar el CFDI

uuid

UUID único del CFDI

certificate_number

Número de certificado usado

receiver_rfc

RFC del Receptorregistros.

total

Total del CFDI

subtotal

Subtotal del CFDI

status

PENDING,OK,ERROR

fiscal_status

ACTIVE, CANCELLED

Ejemplo:

 

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/invoices/v33\
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -X GET

 

Obtención de un CFDI

Para obtener los datos de una factura exitosa, adjuntar el UUID al enviar un GET a la URL del API de facturación. Esto obtendrá los datos de un solo CFDI, con la opción de obtener las URL de descargas para el PDF y el XML.

Parámetros aceptados en la petición

Campo

Descripción

getUrls

Si el valor es true, obtiene las URL de descarga para el PDF y el XML. Estas URL tienen un tiempo de expiración por lo que deberán usarse inmediatamente.

Respuesta de CFDI

Campo

Descripción

invoice_id

Identificador de la factura enviado en la solicitud

creation_date

Fecha en la que se solicitó la generación

issue_date

Fecha en que se envió a timbrar el CFDI

uuid

UUID único del CFDI

certificate_number

Número de certificado usado

receiver_rfc

RFC del Receptorregistros.

total

Total del CFDI

subtotal

Subtotal del CFDI

status

PENDING,OK,ERROR

fiscal_status

ACTIVE, CANCELLED

public_xml_link

URL de descarga del XML. Solo se regresa si getUrls se envió con valor true

public_pdf_link

URL de descarga del PDF. Solo se regresa si getUrls se envió con valor true

link_expiration_date

Fecha de expiración de las URL. Regresada solo si getUrls se envió con valor true

Ejemplo:

 

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/invoices/v33/92ACB752-0F17-427F-A007-A63DFC612036\
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -X GET

 

Cancelación de CFDI

Para realizar la cancelación de un CFDI solo basta con realizar una petición HTTP DELETE a la URL del API de cancelación usando el UUID de la factura generada.

Ejemplo:

 

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/invoices/v33/92ACB752-0F17-427F-A007-A63DFC612036\
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -X DELETE

 

Notificaciones

Una vez que Openpay genere el CFDI se enviará una notificación a la URL configurada previamente. Esta URL recibirá un mensaje JSON mediante una petición HTTP POST con los campos que se describen a continuación:

Campo

Descripción

invoice_id

Identificador de la factura enviado en la solicitud

serie

Serie de la factura

folio

Folio de la factura

transaction_id

Identificador de transacción de Openpay ligado a la factura

creation_date

Fecha de solicitud

issue_date

Fecha de emisión de la factura

uuid

UUID de la factura

receiver_rfc

RFC del receptor de la factura

total

Total de la factura

subtotal

Subtotal de la factura

status

PENDING, OK, ERROR

fiscal_status

ACTIVE, CANCELLED

cancellation_date

Fecha de cancelación de la factura en caso que este cancelada

public_xml_link

Liga para descarga del xml de la factura

public_pdf_link

Liga para descarga del pdf de la factura

link_expiration_date

Expiración de las ligas de descarga, una vez expiradas los xml / pdf pueden ser descargados desde el dashboard

message

Detalle del status de la factura

Ejemplo de notificación enviada:

   {
        "type":"invoice.created",
        "event_date":"2016-04-25T12:14:58-05:00",
        "invoice_data":{
            "invoice_id":"order1234",
            "transaction_id":"trgbokypja3hrza3k7mp",
            "creation_date":"2016-04-25T12:14:52-05:00",
            "issue_date":"2016-04-25T00:14:54-05:00",
            "uuid":"9E837DCC-9D91-413B-B6EA-ECDBC1AA17A1",
            "receiver_rfc":"NIET7511116SA",
            "total":580,
            "subtotal":500,
            "status":"ok",
            "fiscal_status":"active",
            "public_xml_link":"https://cfdi-repository.s3.amazonaws.com/TEST/OPE130906HN4/AAD990814BP7/201604/NIAM7511116SA-9E837DCC-9D91-413B-B6EA-ECDBC1AA17A1.xml?Signature=qiDHA7Zvq6lUQ8FjUS1avCwHxaE%3D&AWSAccessKeyId=AKIAIB52WRJT34BDPATQ&Expires=1461863698",
            "public_pdf_link":"https://cfdi-repository.s3.amazonaws.com/TEST/OPE130906HN4/AAD990814BP7/201604/NIAM7511116SA-9E837DCC-9D91-413B-B6EA-ECDBC1AA17A1.pdf?Signature=ToETRkAP1FGxx78IoI8rULOvBdo%3D&AWSAccessKeyId=AKIAIB52WRJT34BDPATQ&Expires=1461863698",
            "link_expiration_date":"2016-04-28T12:14:58-05:00",
            "message":"Cfdi successfully generated"
        }
    }