API para Consulta de Saldo en Servicio de Timbrado

Reachcore ha creado un API REST para la consulta de saldos empleados en el servicio web de Timbre:

Contenido

¿Qué necesito?

  • Tener activado el servicio de Timbre en tu cuenta Reachcore.
  • 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 cómo generar el API Key, consulta el siguiente artículo: Generar API Key para Web Services.

API de Consulta de Saldos de Timbre

En este recurso se podrá consultar el saldo de todos los RFC registrados en tu cuenta, o la información específica de uno. Para ello, se debe enviar al API REST lo siguiente:

Ambiente URL
Piloto https://oat.reachcore.com/api/rest/Timbre/saldos
Producción https://go.reachcore.com/api/rest/Timbre/saldos


Todas las solicitudes se deberán hacer por el canal de comunicación seguro (https). Las conexiones realizadas por http serán rechazadas

Verbo HTTP: POST

Encabezado HTTP

Parámetro Valor Uso Descripción
RCApiKey API Key Requerido Autenticación al servicio por medio del API Key generado en la plataforma de Reachcore.
Content-Type application/json Requerido El API Rest solo procesa estructuras JSON, por la cual se debe declarar.

Cuerpo

Solo se acepta la estructura de un JSON en el cuerpo de la solicitud

Atributo Uso Descripción
MesConsulta Requerido Establece el mes y año de la consulta para generar el estado de cuenta. Fecha en formato yyyy-mm.
RFCConsulta Opcional RFC del cual se desea obtener el estado de cuenta de saldos. En caso de no proporcionar este parámetro, se regresa información de todos los RFC registrados para timbrar en la cuenta.

Ejemplo de solicitud consulta de saldo de los RFC registrados en la Cuenta

{
  "MesConsulta" : "2019-01"
}

Ejemplo de solicitud consulta de saldo por RFC específico

{ 
  "MesConsulta" : "2019-12",
  "RFCConsulta" : "A&D061009TY8" 
}

Códigos de respuesta

Como respuestá del servicio REST, obtendrá un código indicando el resultado de la operación. Todas las repuestás son en formato JSON (application/json)

Código HTTP Código error Significado Descripción
200 - OK La consulta se realizó correctamente.
400 400-001 Bad Request MesConsulta se encuentra en un formato inválido.
400 400-002 Bad Request El RFC proporcionado no pertenece a los RFC registrados en la cuenta a la que pertenece el API KEY.
401 - Unauthorized El API Key no es válido.
404 - Not found La URL no existe.
500 - Internal Server Error Error de la plataforma Reachcore


Ejemplo de respuesta a una consulta de saldo de los RFC registrados en la Cuenta

{
  "TipoConsumo" : "Postpago",
  "FechaActual" : "2019-11-19T13:53:41"
  "Registrados" : 0,
  "Autorizados" : 0,
  "GeneraronTimbre" : 0,
  "Transacciones" : 2,
  "Detalle" : [
    {
      "RFC" : "A&D061009TY8",
      "Fecha" : "2019-11-02T00:00:00",
      "TipoMovimiento" : "Consumo de timbre",
      "Monto" : 1
    },
    {
      "RFC" : "AAA010101AAA",
      "Fecha" : "2019-11-03T00:00:00",
      "TipoMovimiento" : "Consumo de timbre",
      "Monto" : 1
    }
  ]
}

Ejemplo de respuesta a una consulta de saldo por RFC específico

{
  "TipoConsumo" : "Postpago",
  "FechaActual" : "2019-11-19T13:55:49"
  "Registrados" : 0,
  "Autorizados" : 0,
  "GeneraronTimbre" : 0,
  "Transacciones" : 1,
  "Detalle" : [
    {
      "RFC" : "A&D061009TY8",
      "Fecha" : "2019-11-02T00:00:00",
      "TipoMovimiento" : "Consumo de timbre",
      "Monto" : 1
    }
  ]
}

Ejemplo de respuesta que indica un error en la petición

{
  "errors": [
    {
      "Code": "400-001",
      "Message": "'MesConsulta' se encuentra en un formato inválido."
    }
  ]
}


Donde:

Atributo Descripción
TipoConsumo Tipo de consumo que tiene la cuenta: Prepago, o Postpago
FechaActual Timestamp en formato yyyy-mm-ddThh:MM:ss en el que se atiende la petición
Registrados Cantidad de RFC Registrados en la cuenta a la que pertenece el APIKEY
Autorizados Cantidad de RFC Autorizados para timbrar en plataforma Reachcore de la cuenta a la que pertenece el APIKEY
GeneraronTimbre Cantidad de RFC que generaron al menos una transacción exitosa de timbrado en la cuenta a la que pertenece el APIKEY
Transacciones Cantidad total de todos los timbres de todos los RFC autorizados que se generaron de manera exitosa en el periodo especificado en la cuenta a la que pertenece el APIKEY
Detalle Detalle de las transacciones en el periodo del RFC Especificado. Se compone de los siguientes elementos:
  • RFC: RFC consultado.
  • Fecha: Fecha en que se realizó un movimiento en la cuenta.
  • TipoMovimiento: Tipo de movimiento registrado en la cuenta.
  • Monto: Cantidad de operaciones del TipoMovimiento en la Fecha para el RFC.

Descarga de reporte de consumo en formato PDF o CSV

En este recurso se podrá consultar el reporte de consumo en formato PDF o CSV (el cual puede ser interpretado por Excel). Las ligas para descargar estos reportes son las siguientes:

Para formato PDF:

Ambiente URL
Piloto https://oat.reachcore.com/api/rest/Timbre/saldos/pdf
Producción https://go.reachcore.com/api/rest/Timbre/saldos/pdf


Todas las solicitudes se deberán hacer por el canal de comunicación seguro (https). Las conexiones realizadas por http serán rechazadas

Para formato CSV:

Ambiente URL
Piloto https://oat.reachcore.com/api/rest/Timbre/saldos/csv
Producción https://go.reachcore.com/api/rest/Timbre/saldos/csv


Todas las solicitudes se deberán hacer por el canal de comunicación seguro (https). Las conexiones realizadas por http serán rechazadas

En ambos URL para la petición de descarga del reporte debe contener los siguientes parámetros:

Verbo HTTP: POST

Encabezado HTTP

Parámetro Valor Uso Descripción
RCApiKey API Key Requerido Autenticación al servicio por medio del API Key generado en la plataforma de Reachcore.
Content-Type application/json Requerido El API Rest solo procesa estructuras JSON, por la cual se debe declarar.

Cuerpo

Solo se acepta la estructura de un JSON en el cuerpo de la solicitud

Atributo Uso Descripción
MesConsulta Requerido Establece el mes y año de la consulta para generar el estado de cuenta. Fecha en formato yyyy-mm.

Ejemplo de solicitud consulta de reporte

{
  "MesConsulta" : "2019-10"
}

Códigos de respuesta

Como respuestá del servicio REST, obtendrá un código indicando el resultado de la operación. Todas las repuestás son en formato JSON (application/json)

Código HTTP Código error Significado Descripción
200 - OK La consulta se realizó correctamente.
400 400-001 Bad Request MesConsulta se encuentra en un formato inválido.
400 400-002 Bad Request No es necesario mandar el RFCConsulta.
400 400-003 Bad Request El formato (formatoSolicitado) no está soportado
401 - Unauthorized El API Key no es válido.
404 - Not found La URL no existe.
500 - Internal Server Error Error de la plataforma Reachcore


Ejemplo de respuesta de la descarga de un reporte (CSV o PDF)

Si se puede generar el archivo con el reporte, el código HTTP será 200 y se responderá con un attachment con el reporte solicitado. Para un reporte en CSV, el contenido del attachment es el siguiente:


Cuenta,TipoConsumo,FechaInicioConsulta,FechaFinConsulta,FechaActual
Pruebas,Postpago,2019-10-01T00:00:00,2019-10-31T00:00:00,2019-11-20T16:57:53

Estado de los RFC
Registrados,0
Autorizados,1
Generaron Timbre,1

Transacciones
Consumo de todos los RFC:,3

RFC,Fecha,Tipo movimiento,Monto
AAA010101AAA ,10/17/2019 12:00:00 AM,Consumo de timbre,3

Ejemplo de respuesta que indica un error en la petición

{
  "errors": [
    {
      "Code": "400-002",
      "Message": "No es necesario mandar el 'RFCConsulta'"
    }
  ]
}


Para mayor información o aclaración de dudas relacionadas con está guía, por favor envía un correo a MEX-soporte@sovos.com


Regresar