Documentación para integración con servicios Sovos
Inicio

Consultation of Receipt's reports for day

You can consult a list of all of your stamping receipts and canceled in Sovos (as a PAC), either CFDI or retenciones, on a specific date.

Content

General Features

Using this service, you can consult the relation of every receipt Stamping and Canceled in Sovos (as a PAC). It is integrated by the following type of reports:

  • List of the CFDIs stamped on a single day.
  • List of the CFDIs canceled on a single day.
  • List of the Retenciones stamped on a single day.
  • List of the Retenciones canceled on a single day.

What do I need?

  • To have configured and active the service for Consultation of Receipt’s reports for day. For more information about the costs and service plans, please send an email to MEX-soporte@sovos.com
  • To generate an API key on your Sovos Mexico account, this is an identifier that authenticates the user on the platform's webservices. To generate an API key, please check this article: Generating an API Key for web services (Spanish only).
  • To use an application to perform HTTP requests on the internet through a safe connection (SSL).

Service Location

The URLs for each of the environments are:

Environment URL
UAT https://oat.reachcore.com/api/rest/comprobantes
Production https://go.reachcore.com/api/rest/comprobantes

Authentication

To perform the authentication with the REST API service, it is required to include the parameter RCApiKey in the header of the HTTP request, indicating the API Key value that was generated in the Sovos Mexico platform.

HTTP Header Value Use Description
RCApiKey Secret API Key Required Service authentication through the API Key generated in the Sovos Mexico platform

Operations

Action Method Description
Daily Summary /resumen/{fecha} This returns a document on JSON format with the list of available reports for the requested date. This summary contains the links to each report and the number of receipts inside each of them.
Report of Stamped CFDIs /cfdi/timbrados/{fecha} Downloads the stamping CFDIs report file on the requested date.
Report of Canceled CFDIs /cfdi/cancelados/{fecha} Downloads the canceled CFDIs report on the requested date.
Report of Stamped Retenciones /retenciones/timbrados/{fecha} Downloads the report of stamped Retenciones on the requested date.
Report of Canceled Retenciones /retenciones/cancelados/{fecha} Downloads the report of canceled Retenciones on the requested date.

Next, you can find a description of each of these procedures.

Consultation of daily summary

Request

To obtain the daily summary of receipts, you must perform an HTTP GET request to the following URL, specify the date in format yyyy-mm-dd, and add the RCApiKey header with the value of the API Key you got in the Sovos Mexico platform. 

{api-endpoint}/comprobantes/resumen/{fecha}

E.g., test environment dated July 7 of 2016 

https://oat.reachcore.com/api/rest/comprobantes/resumen/2016-07-07

Response

A successful response will have the following features:

  • Result Code HTTP 200 OK
  • Header Content-Type with value application/json; charset=utf-8
  • Body will be a JSON structure with the following structure:
{
  "date": "2016-07-07",
  "items": [
    {
      "type": "CFDI",
      "operation": "Timbre",
      "available": true,
      "count": 1234,
      "url": "https://oat.reachcore.com/api/rest/comprobantes/CFDI/timbrados/2016-07-07"
    },
    {
      "type": "CFDI",
      "operation": "Cancelacion",
      "available": true,
      "count": 1234,
      "url": "https://oat.reachcore.com/api/rest/comprobantes/CFDI/cancelados/2016-07-07"
    },
    {
      "type": "Retenciones",
      "operation": "Timbre",
      "available": true,
      "count": 1234,
      "url": "https://oat.reachcore.com/api/rest/comprobantes/Retenciones/timbrados/2016-07-07"
    },
    {
      "type": "Retenciones",
      "operation": "Cancelacion",
      "available": true,
      "count": 1234,
      "url": "https://oat.reachcore.com/api/rest/comprobantes/Retenciones/cancelados/2016-07-07"
    }
  ]
}

This response has an array of items where each element describes a different type of report. The structure of the arrangement elements is:

Property Type Description
type string Type of receipt for this report. It will always be one of the values CFDI or Retenciones.
operation string Procedure for this report. It will always be one of the values Cancelacion or Timbre.
available bool
  • true – when the report is available
  • false – when the report can’t be downloaded, whether it has a future date, or because on the specified date you didn’t have this service active in your Sovos Mexico account.
count int The number of items on this report. It can be zero if during the specified date you didn’t perform this type of procedure in your Sovos Mexico account. The count property will exist only if the available property is true.
url string Link to download the file report. NOTE: this link is authenticated (requires to be used with the header RCAPIKey). This url will exist only if the available property is true.

Error response

If the procedure does not return a result code of HTTP 200 OK, it means that the daily summary couldn’t be delivered. In this case, the response will have a Content-Type with value application/json; charset=utf-8, and the body of the response will be a JSON structure with the following format: 

{
  "errors": [
    {
      "Codigo": "302",
      "Mensaje": "El archivo para la fecha 2016-07-08 no ha sido generado aún."
    }
  ]
}

The following table shows the different error scenarios.

HTTP Status Code Code Message
404 Not Found <N/A> The specified URL is not a valid (e.g., due invalid date)
401 Unauthorized 100 The API Key is required
401 Unauthorized 101 The API Key is not valid
401 Unauthorized 102 The API Key doesn’t have this service enabled
500 Internal Server Error 999 The request couldn’t be processed. Please report it to Sovos Support.

Reports Download

You can download each report through a URL specifying the date in format yyyy-mm-dd


    `{api-endpoint}/comprobantes/cfdi/timbrados/{fecha}`
    `{api-endpoint}/comprobantes/cfdi/cancelados/{fecha}`
    `{api-endpoint}/comprobantes/retenciones/timbrados/{fecha}`
    `{api-endpoint}/comprobantes/retenciones/cancelados/{fecha}`

e.g., test environment dated on July 7 of 2016 Por ejemplo, para ambiente piloto y fecha de 7 de julio de 2016:


    https://oat.reachcore.com/api/rest/comprobantes/cfdi/timbrados/2016-07-07
    https://oat.reachcore.com/api/rest/comprobantes/cfdi/cancelados/2016-07-07
    https://oat.reachcore.com/api/rest/comprobantes/retenciones/timbrados/2016-07-07
    https://oat.reachcore.com/api/rest/comprobantes/retenciones/cancelados/2016-07-07

Request

You must enter the URLs using an HTTP GET method and provide the HTTP header with API Key authentication RCApiKey.

Response

All the downloading methods for receipts return a zip binary format file with the following features:

  • The response header Content-Type will be application/zip
  • The header Content-Disposition specifies that the response is a file and its name, e.g.: attachment; filename=CFDITimbre_2016-07-07.zip.
  • In the zip file there will always be a single text file with the following name convention: {Receipt type}{Operation}_{date}.txt e.g.;: CFDITimbre_2016-07-07.txt and the body of the response will be a JSON document with the following format: 
{
  "errors": [
    {
      "Codigo": "302",
      "Mensaje": "Reporte no disponible. Reporte no ha sido generado aún."
    }
  ]
}

The following table shows the different error scenarios:

HTTP Status Code Error Code Error Message
404 Not Found <N/A> The specified URL is not a valid resource (e.g., invalid date)
401 Unauthorized 100 The API Key is required
401 Unauthorized 101 The API Key is not valid
401 Unauthorized 102 The API Key doesn’t have this service enabled
404 Not Found 301 The report is not available. It is too old.
404 Not Found 302 The report is not available. It has not been generated yet.
500 Internal Server Error 999 The requisition couldn’t be processed. Please report with Sovos Support.

Report File

The report files are downloaded with the following features:

  • Flat text file
  • UTF-8 Encoding
  • New Line breaks in Windows format (CR+LF)
  • Content in CSV format (comma separated values) with no headers
  • Each line of the file represents a receipt, and they will always be ordered by upward date (stamping date or cancelation date)

The columns depend on the type of receipt and type of procedure.

Columns of the CFDI Stamping report:

Position Column Description
1 FolioFiscal Fiscal folio (UUID) of the receipt.
2 FechaTimbrado Stamping date on ISO-8601 format yyyy-mm-ddThh:mm:ss official hour from Mexico’s city.
3 FechaEmision Issuance date of the receipt as it appears in the CFDI (generally yyyy-mm-ddThh:mm:ss).
4 RFCEmisor The issuer’s RFC.
5 RFCReceptor The Recipient’s RFC.
6 Serie The receipt’s serie. It can be empty because it’s an optional field of the CFDI.
7 Folio The receipt’s folio. It can be empty because it’s an optional field of the CFDI.
8 RazonSocialReceptor The Recipient’s name. This is useful to identify receipts where the Recipient has the generic foreign RFC XEXX010101000. This value will always appear in double quotations (").

Example of a line from this file: 

85BB589A-C0BD-4FD8-A06F-17AFB4A3D236, 2013-01-10T21:00:13, 2013-01-09T13:42:36, AAA010101AAA, XXX010101XXX, A, 01, "Razón Social del Receptor"

Columns of the Retenciones Stamping Report:

Position Column Description
1 FolioFiscal Fiscal folio (UUID) of the receipt.
2 FechaTimbrado Stamping date on ISO-8601 format yyyy-mm-ddThh:mm:ss official hour from Mexico’s city.
3 FechaEmision Issuance date of the receipt as it appears in the CFDI (generally aaaa-mm-ddThh:mm:ss-06:00).
4 RFCEmisor The Issuer’s RFC.
5 RFCReceptor The Recipient’s RFC.
6 RazonSocialReceptor The receiver’s company name. this is useful to identify receipts where the Recipient has the generic foreign RFC XEXX010101000. This value will always appear in double quotations (").

Example of a line from this file:

FD0EE4C2-8AF4-44E2-A98B-4A6CDF19ECA0, 2013-01-10T11:00:13, 2013-01-09T13:45:36, AAA010101AAA, XXX010101XXX, "Razón Social Receptor"

Columns of the CFDI Cancelation and Retention Cancelation Reports:

Position Column Description
1 FolioFiscal Fiscal folio (UUID) of the receipt.
2 RFCEmisor The issuer’s RFC.
3 FechaCancelacion Cancelation date in ISO-8601 format yyyy-mm-ddThh:mm:ss. This is the date the SAT registers as the official procedure date in the cancelation receipt. Official hour from Mexico City.

Example of a line from this report:

1619752C-D6D2-4447-942B-60E5A5EB3AB6, AAA010101AAA, 2013-01-09T13:45:36

Regresar