Ventas: +52 (55) 1328 4035    ventas@openpay.mx
|
Soporte: +52 (55) 5022 0404    soporte@openpay.mx

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 Id de petición generado por Openpay
date Fecha en que se solicito la generación
status PENDING, OK, ERROR
fiscal_status ACTIVE, CANCELLED
message Description del status

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"
        }
    }

Inicio

Guías

  • Pagos con tarjeta
  • Pagos en tiendas (Paynet)
  • Pagos con códigos QR
  • Pagos con Bancos
  • Otros

    • Referencia

    Plugins

    FAQs

    Legal