Electronic Invoice

Operation

Openpay's electronic invoice generation API is part of the functionalities offered by the platform to complement the user's purchase process.

The generation process is performed asynchronously, the trade sends the generation request to Openpay so that the request is validated and the generation process is triggered and the result of the validation will be responded to once the process is launched Generation Openpay will notify the commerce through notification (webhook) the final result of the generation.

Funcionamineto generacion factura electrónica

Requirements

Testing Environment

  1. Send the merchant_id of the Test account of Openpay

Production Environment

  1. Send the merchant_id of the productive account of Openpay
  2. Send the tax information of the issuer of the CFDI
  3. Send the CSD (Digital Seal Certificate): private, public key and password granted by the SAT for the issuance of CFDI
  4. Send the logo of the trade that will be placed in the printed representation of the CFDI (PDF)

Note: This information must be sent only to your account executive

Configuration

Once the information described in the previous point has been received, the invoice API will be enabled in the account and the URL where you wish to receive the notifications of the CFDI generation can be configured. See section "Notifications" in this document.

To set the URL, go to: Settings -> Webhooks -> Add and select "Customize Events" and notifications of Invoices created and failed as shown in the following image:

Funcionamineto generacion factura electrónica

Note: The "Invoices" events section will only be available until your Openpay account has activated the Invoice API.

Endpoints

Invoice services are available within the Openpay API and require the same authentication of the other services. For more information about authentication, see: https://www.openpay.mx/en/docs/api/?#authentication

Endpoints for invoice:

Action

URL

Método

Invoice Generation

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

POST

List CFDI

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

GET

Retrieve CFDI

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

GET

Cancel Invoice

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

DELETE

Environments

  • Tests: Production:
  • Production https://api.openpay.mx

Example:

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

Generation of CFDI

For the generation of CFDI it is necessary to send a Generation of CFDI ObjectThe fields of this object must be sent in a JSON message by making an HTTP POST request to the URL: https://{enviroment}/v1/{merchant_id}/invoices/v33

Object List

Example of request:

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

Generation request response

Field

Description

invoice_id

Identifier of the invoice sent in the request

request_id

POST

date

POST

status

POST

fiscal_status

POST

message

POST

Example of request:

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

Listing CFDI

To obtan a list of the generated CFDI, all you have to do is send an HTTP GET request to the API URL. This will retrieve a list of the latest generated invoices for the merchant, arranged by creation date in descending order.

The API allows the merchant to use the parameters limit and offset to list the genetared CFDI, but it is recommended to use these parameters in combination with the creation parameter. creation.

Parameters allowed in the request

Field

Description

creation

List the CFDI with creation date of a given day. YYYY-MM-DD.

creation[gte]

List the CFDI with creation date greater or equal to a given day. YYYY-MM-DD.

creation[lte]

List the CFDI with creation date less or equal to a given day. YYYY-MM-DD.

id

Search CFDI by invoice_id

limit

The maximum number of results to retrieve. The default is 10, and the maximum allowed value is 500.

offset

The number of initial CFDI to ignore. Used together with limit to obtain more results.

Fields of the response objects returned in the list

Field

Description

invoice_id

Identifier of the invoice sent in the request

creation_date

Date when the generation request was received

issue_date

Date when the CFDI was stamped

uuid

UUID of the CFDI

certificate_number

Number of Certificate used

receiver_rfc

Receiver RFC

total

Total amount received in the generation request

subtotal

Subtotal received in the generation request

status

PENDING,OK,ERROR

fiscal_status

ACTIVE, CANCELLED

Example:

 

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

 

Retrieving a CFDI

To retrieve the information for a single CFDI, append the UUID to the GET request sent to the API URL. This will retrieve the data for a single CFDI, optionally retrieving the URL for the PDF and XML.

Parameters allowed in the request

Field

Description

getUrls

If sent with value true, retrieves the download URL for the PDF and XML. These URL have an expiration date, so they must be used immediately.

CFDI Response

Field

Description

invoice_id

Identifier of the invoice sent in the request

creation_date

Date when the generation request was received

issue_date

Date when the CFDI was stamped

uuid

UUID of the CFDI

certificate_number

Number of Certificate used

receiver_rfc

Receiver RFC

total

Total amount received in the generation request

subtotal

Subtotal received in the generation request

status

PENDING,OK,ERROR

fiscal_status

ACTIVE, CANCELLED

public_xml_link

Download URL for the XML. Will only be returned if getUrls was sent true.

public_pdf_link

Download URL for the PDF. Will only be returned if getUrls was sent true.

link_expiration_date

Expiration date for both URL. Will only be returned if getUrls was sent true.

Example:

 

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

 

Canceling CFDI

To cancel a CFDI, all you have to do is make an HTTP DELETE request to the cancellation API URL using the UUID of the generated invoice.

Example:

 

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

 

Notifications

Once Openpay generates the CFDI, a notification will be sent to the previously configured URL. This URL will receive a JSON message through an HTTP POST request with the fields described below:

Field

Description

invoice_id

Identifier of the invoice sent in the request

serie

Invoice series

folio

Folio of the invoice

transaction_id

Openpay transaction identifier linked to the invoice

creation_date

Application date

issue_date

Issue date of the invoice

uuid

UUID of the invoice

receiver_rfc

RFC of the invoice recipient

total

Total invoice

subtotal

Subtotal of the invoice

status

PENDING, OK, ERROR

fiscal_status

ACTIVE, CANCELLED

cancellation_date

Date of cancellation of the invoice in case it is canceled

public_xml_link

Link to download the XML of the invoice

public_pdf_link

Link to download the PDF of the invoice

link_expiration_date

Expiration of the download leagues, once expired the xml / pdf can be downloaded from the dashboard

message

Detalle del status de la factura

Notification example sent:

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