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.
Requirements
Testing Environment
- Send the merchant_id of the Test account of Openpay
Production Environment
- Send the merchant_id of the productive account of Openpay
- Send the tax information of the issuer of the CFDI
- Send the CSD (Digital Seal Certificate): private, public key and password granted by the SAT for the issuance of CFDI
- 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:
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 | Method |
---|---|---|
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: https://sandbox-api.openpay.mx
- 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 Object. The 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
- DoctoRelacionado Object
- Concept Object
- Tax Object
- Receiver Object
- Related Object
- CFDI Related Object
- Complements Object
- Complement Airlines Object
- Charge Airlines Object
- Complement Payment Object
- Complement Donee Object
Request example:
Generation request response
Field | Description |
---|---|
invoice_id | Identifier of the invoice sent in the request |
request_id | Request ID generated by Openpay |
date | Date on which the generation was requested |
status | PENDING, OK, ERROR |
fiscal_status | ACTIVE, CANCELLED |
message | Status description |
Request example:
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.
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 | Invoice ID received in the generation 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:
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 | Invoice ID received in the generation 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:
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:
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 | Detail of the status of the invoice |
Notification example sent: