Consulta de Comprobantes Fiscales
Consulta un listado de todos tus comprobantes timbrados y cancelados en Reachcore, tanto CFDI como Retenciones, para una fecha específica.
Contenido
- Características generales
- ¿Qué necesito?
- Ubicación del servicio
- Autenticación
- Operaciones
- Resúmen diario de comprobantes
- Descarga de reportes
Características Generales
Este servicio permite consultar la relación de todos los comprobantes Timbrados y Cancelados en Reachcore, y consiste en los siguientes tipos de reportes:
- Listado de los CFDIs Timbrados en un día.
- Listado de los CFDIs Cancelados en un día.
- Listado de los comprobantes de Retenciones Timbrados en un día.
- Listado de los comprobantes de Retenciones Cancelados en un día.
¿Qué necesito?
Para poder hacer uso del servicio se necesita lo siguiente:
- Tener activo en tu cuenta Reachcore el servicio de Consulta de Reportes de Comprobantes por día. Para mayor información acerca de los costos y planes de servicio envía un correo a MEX-soporte@sovos.com.
- Generar un API Key en tu cuenta Reachcore, ya que se usa para autenticar la solicitud en el API Rest. El API Key debe corresponder al ambiente en el que se realiza la solicitud. Para referencia de como generar el API Key, consulta el siguiente artículo: Generar API Key para Web Services.
- Aplicación para realizar solicitudes HTTP a través de internet sobre conexión segura (SSL).
Ubicación del servicio
El API REST se localiza en las siguientes URLs para cada uno de los ambientes:
| Ambiente | URL |
|---|---|
| Piloto | https://oat.reachcore.com/api/rest/comprobantes |
| Producción | https://go.reachcore.com/api/rest/comprobantes |
Autenticación
Para realizar la autenticación con el servicio API REST, es requerido incluir en el encabezado de la solicitud HTTP el parámetro RCApiKey, indicando el valor del API Key que fue generado en la plataforma de Reachcore.
| Encabezado HTTP | Valor | Uso | Descripción |
|---|---|---|---|
RCApiKey |
API Key secreto | Requerido | Autenticación al servicio por medio del API Key generado en la plataforma de Reachcore. |
Operaciones
| Acción | Método | Descripción |
|---|---|---|
| Resumen diario | /resumen/{fecha} |
Devuelve un documento formato JSON con la lista de reportes que están disponibles para la fecha solicitada. Este resumen contienen las ligas de cada uno de los reportes individuales, así como el número de comprobantes que contiene cada uno de ellos. |
| Reporte de CFDIs Timbrados | /cfdi/timbrados/{fecha} |
Descarga del archivo de reporte de CFDIs timbrados en la fecha solicitada. |
| Reporte de CFDIs Cancelados | /cfdi/cancelados/{fecha} |
Descarga del archivo de reporte de CFDIs cancelados en la fecha solicitada. |
| Reporte de Retenciones Timbrados | /retenciones/timbrados/{fecha} |
Descarga del archivo de reporte de Comprobantes de Retenciones timbrados en la fecha solicitada. |
| Reporte de Retenciones Cancelados | /retenciones/cancelados/{fecha} |
Descarga del archivo de reporte de Comprobantes de Retenciones cancelados en la fecha solicitada. |
A continuación se describe el uso de cada una de estas operaciones.
Consulta del resumen diario
Solicitud
Para obtener el resumen diario de comprobantes, se debe hacer una solicitud HTTP GET a la siguiente URL, especificando la fecha en formato aaaa-mm-dd y proporcionando en el encabezado de la solicitud HTTP el parámetro RCApiKey, indicando el valor del API Key que fue generado en la plataforma de Reachcore.
{api-endpoint}/comprobantes/resumen/{fecha}
Por ejemplo, para ambiente piloto y fecha de 7 de julio de 2016:
https://oat.reachcore.com/api/rest/comprobantes/resumen/2016-07-07
Respuesta
La respuesta de éxito de esta operación siempre tendrá las siguientes características:
- Código de resultado
HTTP 200 OK - Encabezado
Content-Typecon valorapplication/json; charset=utf-8 - Cuerpo será un documento
JSONcon la siguiente estructura.
{
"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"
}
]
}Esta respuesta contiene un arreglo items en donde cada elemento describe un tipo distinto de reporte. La estructura de estos elementos del arreglo es:
| Propiedad | Tipo | Descripción |
|---|---|---|
| type | string | Tipo de comprobante para este reporte. Será siempre uno de los valores CFDI o Retenciones |
| operation | string | Operación para este reporte. Será siempre uno de los valores Cancelacion o Timbre |
| available | bool | true.- cuando el reporte está disponible. false.- cuando el reporte no se pueda descargar, ya sea porque es una fecha en futuro, o bien porque en la fecha especificada no se había activado todavía este servicio en tu cuenta de Reachcore. |
| count | int | Número de comprobantes contenidos en este reporte. Puede ser cero si durante la fecha especificada no realizaste transacciones de este tipo en tu cuenta de Reachcore. Esta propiedad count existirá solo si la propiedad available es true. |
| url | string | Liga para la descarga del archivo de reporte. NOTA: esta liga es autenticada (requiere ser invocada con el encabezado RCAPiKey). Esta url existirá solo si la propiedad available es true. |
Respuesta de error
Si la operación no devuelve un código de resultado HTTP 200 OK significa que el resumen diario no pudo ser entregado. En este caso la respuesta tendrá Content-Type con valor application/json; charset=utf-8, y el cuerpo de la respuesta será un documento JSON con el siguiente formato:
{
"errors": [
{
"Codigo": "302",
"Mensaje": "El archivo para la fecha 2016-07-08 no ha sido generado aún."
}
]
}En la siguiente tabla se presentan los diferentes escenarios de error.
| HTTP Status Code | Codigo | Mensaje |
|---|---|---|
| 404 Not Found | <N/A> | La URL especificada no es un recurso válido (ej. fecha inválida) |
| 401 Unauthorized | 100 | API Key Requerida |
| 401 Unauthorized | 101 | API Key no válida |
| 401 Unauthorized | 102 | API Key no tiene privilegios suficientes |
| 500 Internal Server Error | 999 | Solicitud no pudo ser procesada. Favor de reportar con el área de Soporte de Reachcore |
Descarga de reportes
Una vez consultado el resumen para descubrir los reportes que están disponibles para la fecha especificada, cada reporte podrá ser descargado a través de su URL especificando la fecha en formato aaaa-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}`
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
Solicitud
Cualquier de estas URLs deberá se accedida con un método HTTP GET y proporcionando en el encabezado HTTP de autenticación con API KEY RCAPiKey.
Respuesta
Todos los métodos de descaga de comprobantes devuelven un archivo formato zip binario con las siguientes características:
- En el encabezado
Content-Typede la respuesta seráapplication/zip - En el encabezado
Content-Dispositionespecifica que la respuesta es un archivo y su nombre, ejemplo:attachment; filename=CFDITimbre_2016-07-07.zip. - Dentro del archivo zip siempre existirá un solo archivo de texto con la siguiente convención de nombre:
{Tipo de Comprobante}{Operacion}_{fecha}.txtejemplo:CFDITimbre_2016-07-07.txty el contenido descrito en la siguiente sección.
Respuesta de error
Si la operación no devuelve un código de resultado HTTP 200 OK significa que reporte no pudo ser entregado. En este caso la respuesta tendrá Content-Type con valor application/json; charset=utf-8, y el cuerpo de la respuesta será un documento JSON con el siguiente formato:
{
"errors": [
{
"Codigo": "302",
"Mensaje": "Reporte no disponible. Reporte no ha sido generado aún."
}
]
}En la siguiente tabla se presentan los diferentes escenarios de error.
| HTTP Status Code | CodigoError | MensajeError |
|---|---|---|
| 404 Not Found | <N/A> | La URL especificada no es un recurso válido (ej. fecha inválida) |
| 401 Unauthorized | 100 | API Key Requerida |
| 401 Unauthorized | 101 | API Key no válida |
| 401 Unauthorized | 102 | API Key no tiene privilegios suficientes |
| 404 Not Found | 301 | Reporte no disponible. Demasiado viejo. |
| 404 Not Found | 302 | Reporte no disponible. Reporte no ha sido generado aún. |
| 500 Internal Server Error | 999 | Solicitud no pudo ser procesada. Favor de reportar con el área de Soporte de Reachcore |
Archivo de reporte
Los archivos de reporte descargados son archivos con las siguientes características:
- Archivo de texto plano
- Encoding UTF-8
- Saltos de línea formato Windows (CR+LF)
- Contenido en formato CSV (Comma Separated Values) sin encabezados.
- Cada línea del archivo representa un comprobante y siempre están ordenados por fecha de operación ascendente (fecha de timbrado o fecha de cancelación, según corresponda).
Las columnas dependen del tipo de comprobante y tipo de operación.
Columnas del reporte de Timbre de CFDI:
| Posición | Columna | Descripción |
|---|---|---|
| 1 | FolioFiscal | Folio fiscal (UUID) del comprobante. |
| 2 | FechaTimbrado | Fecha de timbrado en formato ISO 8601 aaaa-mm-ddThh:mm:ss. Hora oficial del Centro de México. |
| 3 | FechaEmision | Fecha de emisión del comprobante exactamente como aparece en el CFDI (generalmente aaaa-mm-ddThh:mm:ss). |
| 4 | RFCEmisor | El RFC del emisor del comprobante. |
| 5 | RFCReceptor | El RFC del receptor del comprobante. |
| 6 | Serie | La serie del comprobante. Puede ser vacío ya que es un campo opcional del CFDI. |
| 7 | Folio | El folio del comprobante. Puede ser vacío ya que es un campo opcional del CFDI. |
| 8 | RazonSocialReceptor | La razón social del receptor. Útil para identificar comprobantes donde el receptor tiene el RFC genérico extranjero XEXX010101000. Este valor siempre aparecerá entre comillas dobles ("). |
Ejemplo de una línea de este archivo:
85BB589A-C0BD-4FD8-A06F-17AFB4A3D236, 2013-01-10T21:00:13, 2013-01-09T13:42:36, AAA010101AAA, XXX010101XXX, A, 01, "Razón Social Receptor"Columnas del reporte de Timbre de Retenciones:
| Posición | Columna | Descripción |
|---|---|---|
| 1 | FolioFiscal | Folio fiscal (UUID) del comprobante. |
| 2 | FechaTimbrado | Fecha de timbrado en formato ISO 8601 aaaa-mm-ddThh:mm:ss. Hora oficial del Centro de México. |
| 3 | FechaEmision | Fecha de emisión del comprobante exactamente como aparece en el comprobante (generalmente aaaa-mm-ddThh:mm:ss-06:00). |
| 4 | RFCEmisor | El RFC del emisor del comprobante. |
| 5 | RFCReceptor | El RFC del receptor del comprobante. |
| 6 | RazonSocialReceptor | La razón social del receptor. Útil para identificar comprobantes donde el receptor tiene el RFC genérico extranjero XEXX010101000. Este valor siempre aparecerá entre comillas dobles ("). |
Ejemplo de una línea de este archivo:
FD0EE4C2-8AF4-44E2-A98B-4A6CDF19ECA0, 2013-01-10T11:00:13, 2013-01-09T13:45:36, AAA010101AAA, XXX010101XXX, "Razón Social Receptor"Columnas de los reportes de Cancelación de CFDI y Cancelación de Retenciones:
| Posición | Columna | Descripción |
|---|---|---|
| 1 | FolioFiscal | Folio fiscal (UUID) del comprobante. |
| 2 | RFCEmisor | El RFC del emisor del comprobante. |
| 3 | FechaCancelacion | Fecha de cancelación en formato ISO 8601 aaaa-mm-ddThh:mm:ss. Esta es la fecha que el SAT registra como fecha oficial de la operación en el acuse de cancelación. Hora oficial del Centro de México. |
Ejemplo de una línea de este archivo:
1619752C-D6D2-4447-942B-60E5A5EB3AB6, AAA010101AAA, 2013-01-09T13:45:36Regresar