Communication Format

Overview

This document outlines how to securely and consistently interact with the API. It includes authentication, protocol requirements, request structure, and expected response formats.

Authentication & Protocol

All API communication is handled over HTTPS using secure HTTP POST requests.
Each client is issued a unique API key during onboarding, which must be included in the request headers to ensure authentication.

Security Requirements

• All communication must use TLS 1.2 or higher.
• Older TLS versions (1.0, 1.1) are deprecated and must not be used.

API Endpoint

Base URL:
https://pos-api.fidelizacion.app

Request Structure

All requests must include a UTF-8 encoded JSON body and be sent via POST to a versioned API endpoint.

Format:

https://pos-api.fidelizacion.app/v1/{apiCall}

URL Components

Component	Description
API server host	Base domain of the API
Versioned path	API version and specific call
Parameters	Optional query parameters

Request Headers

Header	Type	Required	Description
Content-Type	string	Yes	Always set to application/json
x-api-key	string	Yes	Client API key for authentication
x-branch-id	string	Yes	Identifier for the business branch
x-pos-id	string	Yes	Identifier for the POS terminal making the request
x-source-type	string	Yes	Origin of transaction (e.g., POS, Website, Kiosk)
x-source-name	string	Yes	Name of the integration or source system

Response Format

The API returns a JSON response object with a status field indicating success or failure.
In case of failure, an error object is included with details.

Error Response Fields

Field	Type	Description
code	string	Unique error identifier
message	string	Description of the issue
path	string	Location in the request that failed

Example Error Response

{
  "status": "error",
  "error": {
    "code": "4001012",
    "message": "Member not found",
    "path": "body.member.phoneNumber"
  }
}