Generic Operations

Brazil

Overview

Carat Portal has a REST interface for performing generic operations. These operations are exclusive to certain authorizers and do not follow the standardized flows used by the other services.

In this REST interface, each operation code may require additional data to work as expected. Some operations require an authenticity token, which must be generated for each call of the generic operation. For more details on each generic operation, use the specific routing documentation.

For nomenclatures such as Bin, Software Express, Carat and e-Sitef, see the glossary in the portal.

Communication

To make a generic service REST web service request, use the following Carat Portal base URLs:

Environment	Base URL
Production	`https://<urlpostmanprod>/e-sitef/api`
Homologation	`https://<urlpostman>/e-sitef/api`

What you will need

An application capable of receiving POST HTTPS calls
Active registration in the Carat Portal environment with the URL for the authenticity POST

Flow

Generic operations have two flows that depend on whether the authenticity token is required for execution.

sequenceDiagram
    participant MERCHANT
    participant CARAT
    MERCHANT->>+CARAT: 1. Request token generation
    CARAT-->>MERCHANT: 2. Return authenticity token
    MERCHANT->>+CARAT: 3. Execute generic operation
    CARAT-->>-MERCHANT: 4. Return operation result

Flow description

Merchant requests the generation of a token for generic operations.
Carat Portal generates an authenticity token internally.
The generated authenticity token is sent to the store via POST to the authenticity URL. The merchant must keep this token.
The merchant uses the generated authenticity token to perform a generic operation.
Carat Portal validates and inactivates the authenticity token before performing the requested operation.
Carat Portal performs the generic operation and obtains the results of the operation.
Carat Portal returns the result of the requested operation.

Obs: Some generic operations do not need the authenticity token. In that case, steps 1, 2 and 3 are not necessary.

Authenticity token creation

_{Source: https://dev.softwareexpress.com.br/en/docs/e-sitef/generic-operation-rest-token}

This service is used to generate the authenticity token required by some generic operations.

Call details

Feature: /v1/genericoperations
HTTP Method: POST
Request format: JSON
Response format: JSON

Header parameters

Parameter	Description	Type (Size)	Mandatory
`merchant_id`	Store code on Carat Portal. The production and certification codes will be different.	`AN (≤ 15)`	Yes
`merchant_key`	Store authentication key on Carat Portal. The production and certification keys will be different.	`AN (≤ 80)`	Yes
`Content-Type`	Use `application/json` value.	`AN (= 15)`	Yes

Request parameter

Parameter	Description	Type (Size)	Mandatory
`operation`	Identifying number of the operation to be called.	`N (≤ 3)`	Yes
`parameters`	Set of properties that must be sent to perform the operation specified in `operation`.	`AN (≤ 20)`	Yes

Descriptive table of `parameters`

Each operation has a set of parameters. Below are the parameters with common characteristics for all operations:

Parameter	Description	Type (Size)	Mandatory
`token`	Authenticity token generated by Carat Portal.	`AN (= 66)`	Conditional per operation
`authorizer_id`	Authorization code on Carat Portal.	`AN (≤ 3)`	Yes
`terminal_id`	Numeric value that represents a logical terminal in SiTef. A logic terminal number cannot be used at the same time for two different requests.	`AN (= 8)`	Yes
`merchant_usn`	NSU of in-store operation.	`N (≤ 12)`	Yes
`operator_code`	Operator code.	`N (= 2)`	No
`supervisor_code`	Supervisor code.	`N (= 5)`	No
`subfunction`	Subfunction of the operation. The value of this field must be consistent with the operation.	`N (= 2)`	Yes

Answer

The answer depends on each operation and will be specified in the documentation of each authorizer/routing.