Modify the balance of an RFC in the stamping service API

Sovos Mexico has created a REST API that allows you to increase or decrease the balance of a given RFC registered in your account for the stamping web service:

Content

Requirements
Service location
Modify the balance for a RFC
- HTTP response codes for Modify balance operation
E-mail notifications configuration
- HTTP response code for e-mail notification operation

Requirements

Have stamping service enabled in your Sovos Mexico account.
Generate an API Key for your Sovos Mexico account. This is used to authenticate the request to the REST API. The API Key must correspond to the environment in which the request is made. For reference on how to generate the API Key, see the following article: Generate API Key for Webservices (Spanish only).

Service location

In this API you can affect (increase or decrease) the balance of each of the RFCs registered in your Sovos Mexico account. To do this, the following information must be sent to the REST API:

Environment	URL
UAT	https://oat.reachcore.com/api/rest/timbre/asignacion/saldo
Production	https://go.reachcore.com/api/rest/timbre/asignacion/saldo

All requests must be sent through the secure communication channel (https). Connections made by http will be rejected.

Modify the balance for a RFC

HTTP: POST

HTTP Header

Parameter	Value	Usage	Description
`RCApiKey`	API Key	Required	Authentication to the service through the API Key generated in the Sovos Mexico platform.
`Content-Type`	`application/json`	Required	The REST API only processes JSON structures therefore this header must be included.

Body

Only a JSON structure is accepted in the request body

Atribute	Type	Description	Validations on the attribute
RFC	String	RFC to which you want to modify its balance	The RFC must be valid (according to the structure of an RFC specified in Anexo 20). The RFC must be registered in the account (either for issuance or stamping).
Incrementar	Integer	Amount of balance to increase	Only integer values are allowed. The value specified in this parameter must be greater than zero and less than or equal to the balance to assign.
Decrementar	Integer	Amount of balance to decrease	Only integer values are allowed. The value specified in this parameter cannot be negative and cannot be greater than the current balance for the specified RFC.

Note

The attributes incrementar and decrementar should not be specified at the same time.

Example of request to increase balance

{
  "rfc" : "XAXX0101010000",
  "incrementar" : 1
}

Example of response

{
    "result": "El saldo fue afectado exitosamente.",
    "rfc": "XAXX0101010000",
    "saldo_disponible_rfc": "7",
    "saldo_por_asignar": "3"
}

HTTP response codes

HTTP code	Error Subcode de error	Meaning	Description
200	--	OK	RFC balance was successfully affected.
400	400-001	Bad request	Only one operation must be specified: 'incrementar' or 'decrementar'.
400	400-002	Bad request	You cannot allocate more transactions than the ones you have allocated in your account.
400	400-003	Bad request	Transactions with negative numbers cannot be modified.
401	--	Unauthorized	Invalid API Key is invalid.
404	--	Not found	The specified URL does not exist.
412	412-001	Precondition failed	Sovos Mexico account does not have stamping service enabled.
412	412-002	Precondition failed	The provided RFC does not exist in your Sovos Mexico account.
500	--	Internal server error	Sovos Mexico platform error.

E-mail notifications configuration

Description

This API method allows you to specify a transaction limit per RFC so that when the balance of that RFC reaches that limit, an email is sent to the specified addresses.

Environment	URL
UAT	https://oat.reachcore.com/api/rest/timbre/asignacion/AlertaSaldo
Production	https://go.reachcore.com/api/rest/timbre/asignacion/AlertaSaldo

All requests must be made through the secure communication channel (https). Connections made by http will be rejected

HTTP Header

Parameter	Value	Usage	Description
`RCApiKey`	API Key	Required	Authentication to the service through the API Key generated in the Sovos Mexico platform.
`Content-Type`	`application/json`	Required	The REST API only processes JSON structures therefore this header must be included.

Body

Only a JSON structure is accepted in the request body.

Atribute	Type	Description	Validations on the attribute
RFC	String	RFC to which you want to add the notification	The RFC must be valid (according to the structure of an RFC specified in Anexo 20). The RFC must be registered in the account (either for issuance or stamping).
Limite	Integer	Number of transactions from which a notification will be sent	Must be a positive integer.
Correo	String	Email address or addresses (separated by commas) to which a notification of balance reaching a 'limit' will be sent	It is verified that the email address provided is in a valid format.
Apagar	Boolean	Flag that allows you to turn off a balance limit notification	Allowed values: { `"true"`, `"false" }.

If the Apagar attribute has a value of false or is not sent in the request, the Limite and Correos fields are required.

Example of Request

{
  "RFC" : "XAXX010101000",
  "Apagar": "false",
  "Limite" : "10",
  "Correos" : [
  		"abdul.alhazred@mail.com",
  		"howard.lovecraft@mail.com]
}

Example of Response


{
	"result": "El límite para notificación de correo del RFC XAXX010101000 fue afectado exitosamente."
}

HTTP Response codes

HTTP code	Error Subcode de error	Meaning	Description
200	--	OK	RFC mail notification limit for RFC 'SpecifiedRFC' has been successfully defined.
400	400-001	Bad request	Cannot add notifications with negative numbers.
400	400-002	Bad request	Specified RFC does not have a valid structure.
400	400-003	Bad request	The email address 'address@invalid' does not appear to be a valid email address.
400	400-004	Bad request	Only a numeric value should be specified in: 'limite'.
400	400-005	Bad request	Only a boolean value should be specified in: 'apagar': `true` or `false`.
400	400-006	Bad request	The 'limite' attribute is required.
400	400-007	Bad request	The 'correos' attribute is required.
401	--	Unauthorized	The API Key is invalid.
404	--	Not Found	The specified URL does not exist.
412	412-001	Precondition Failed	Sovos Mexico account is not configured for stamping.
412	412-002	Precondition Failed	The provided RFC does not exist in your Sovos Mexico account.
412	412-003	Precondition Failed	You have not specified an RFC to which to enable notifications.
500	--	Internal Server Error	Sovos Mexico platform error.

For more information or any doubt related to this guide, please send an email to MEX-soporte@sovos.com

Regresar