Autenticación

Para autenticarte con la API de T1pagos, debes utilizar una API Key. Esta clave debe incluirse en el encabezado de todas las solicitudes HTTP que realices a la API.

Nota: En la nueva versión de la plataforma T1pagos, se ha migrado del sistema de Bearer Token a API Key para simplificar la autenticación.

Encabezados de Autenticación

Incluye tu API Key en el encabezado de cada solicitud:

X-API-Key: tu_api_key_aqui

Ambientes

T1pagos proporciona dos ambientes para el desarrollo e implementación de tu integración:

Ambiente URL Base Descripción
Sandbox https://api.sandbox.t1pagos.com/v2 Ambiente de pruebas para desarrollo e integración. Utiliza tarjetas de prueba y no realiza cargos reales.
Producción https://api.t1pagos.com/v2 Ambiente de producción para transacciones reales.
Importante: Nunca compartas tu API Key de producción. Mantenla segura y no la incluyas en código del lado del cliente.

Cargos con Tarjeta

Objetivo

Aceptar pagos con tarjeta con T1pagos es un proceso de 3 pasos con acciones del lado del cliente (front-end) y del servidor (back-end):

  1. Device fingerprint - En tu sitio web, que está siendo ejecutado en el navegador del cliente, se inserta un archivo de javascript que envía a la herramienta de prevención de fraude la información del dispositivo del cliente y este le regresa al navegador un identificador único del dispositivo llamado device_fingerprint.
  2. Tokenización - Cuando tu cliente da clic en Pagar, tu sitio deberá enviar a T1pagos la información de la tarjeta de tu cliente y este le regresará un token único de la tarjeta. Después tu sitio deberá enviar a tu servidor el token, device_fingerprint y todos los datos del pedido.
  3. Cargo - Tu servidor deberá hacer un request al API de T1pagos para crear un cargo y complementar el pago.

La tokenización asegura que la información sensible de la tarjeta nunca toque tu servidor, lo que te permite minimizar el alcance de una certificación PCI Compliance.

Proceso de Cargo a Tarjeta

Diagrama de proceso de cargo
  1. Front end Comercio, a través de un Javascript, envía datos del navegador a Herramienta de Prevención de Fraude (opcional)
  2. Herramienta de Prevención de Fraude envía Device fingerprint generado
  3. Front end Comercio envía datos de tarjeta a T1pagos
  4. T1pagos regresa un token
  5. Front end Comercio envía datos de pedido a Back end comercio
  6. Back end de Comercio solicita creación de cargo enviando datos del pedido a T1pagos
  7. T1pagos evalúa y procesa la transacción al switch correspondiente y envía respuesta final a Back end Comercio

Tokenización

El envío de datos de la tarjeta se realizará haciendo una petición al método POST /tarjeta.

POST /v2/tarjeta

Request:

{
  "nombre": "NOMBRE DEL TITULAR",
  "pan": "4242424242424242",
  "expiracion_mes": "03",
  "expiracion_anio": "27",
  "cvv2": "123",
  "default": true
  }

Response:

{
  "status": "success",
  "data": {
    "tarjeta": {
      "cliente_id": "ba3e968d-95d0-4a4d-928b-808a58ffbb55",
      "default": true,
      "nombre": "NOMBRE DEL TITULAR",
      "iin": "424242",
      "terminacion": "4242",
      "pan": "424242******4242",
      "marca": "visa",
      "expiracion_mes": "03",
      "expiracion_anio": "27",
      "token": "5c4a7103-d35f-4136-98be-6210d57b0ca3",
      "actualizacion": "2025-03-25T15:52:11-05:00",
      "creacion": "2025-03-25T15:52:11-05:00"
      }
  },
  "http_code": 200,
  "datetime": "2025-03-25T15:52:11-05:00",
  "timestamp": 1711400531
  }

Crear un Cargo

Para generar un cargo, tu servidor debe hacer una petición al API de T1pagos usando el método POST /cargo.

POST /v2/cargo

Request:

{
  "monto": "10",
  "descripcion": "Cargo de prueba",
  "pedido": {
    "device_fingerprint": "5834125431628311477"
    },
  "metodo_pago": "tarjeta",
  "tarjeta": {
    "token": "5c4a7103-d35f-4136-98be-6210d57b0ca3"
    }
}

Response:

{
  "status": "success",
  "data": {
    "cargo": {
      "id": "ce6fa69d-a2ab-471a-b2a9-9ed18f3241b7",
      "monto": "200.0000",
      "tipo": "cargo",
      "orden_id": 0,
      "cliente_id": "ba3e968d-95d0-4a4d-928b-808a58ffbb55",
      "estatus": "completada",
      "codigo": "approved",
      "descripcion": "La transacción ha sido aprobada",
      "prueba": true,
      "tarjeta": {
        "creacion": "2025-03-25T15:56:45-05:00",
        "nombre": "NOMBRE DE CLIENTE",
        "expiracion_mes": "03"
        "expiracion_anio": "27"
        "token": "5c4a7103-d35f-4136-98be-6210d57b0ca3",
        "iin": "424242"
        "marca": "visa",
        "terminacion": "4242"
        }
    }
  },
  "http_code": 200,
  "datetime": "2025-03-25T15:56:45-05:00",
  "timestamp": 1711400805
  }

Campos Requeridos

Campo Descripción
monto Monto a cobrar. Debe ser un número entre 1 y 999999999999999.
descripcion Descripción breve del cargo.
metodo_pago Método de pago, debe ser 'tarjeta'.
tarjeta.token Token de la tarjeta obtenido en el proceso de tokenización.
pedido.device_fingerprint Identificador único del dispositivo generado por la herramienta de prevención de fraude.

Campos Opcionales

Campo Descripción
orden_id ID de la orden en tu sistema.
pedido.id_externo ID externo del pedido.
pedido.total_articulos Número total de artículos en el pedido.
pedido.monto_articulos Monto total de los artículos.
pedido.total_monto Monto total del pedido.
pedido.creacion Fecha de creación del pedido.
pedido.articulos Array de artículos en el pedido.
cliente Información del cliente.
PlanPagos Detalles sobre el plan de pagos.

Gestionar Clientes y Tarjetas

T1pagos permite guardar tarjetas para futuros cargos, lo que mejora la experiencia del usuario al no tener que ingresar los datos de su tarjeta en cada compra.

Crear Cliente

Antes de guardar una tarjeta, es necesario crear un cliente en el sistema.

POST /v2/cliente

Request:

{
  "nombre": "Juan",
  "apellido_paterno": "Pérez",
  "apellido_materno": "García",
  "email": "juan.perez@ejemplo.com",
  "telefono": {
    "tipo": "celular",
    "codigo_pais": "+52",
    "codigo_area": "55",
    "numero": "12345678"
  }
}

Response:

{
  "status": "success",
  "data": {
    "cliente": {
      "id": "ba3e968d-95d0-4a4d-928b-808a58ffbb55",
      "nombre": "Juan",
      "apellido_paterno": "Pérez",
      "apellido_materno": "García",
      "email": "juan.perez@ejemplo.com",
      "estado": "activo",
      "telefono": {
        "tipo": "celular",
        "codigo_pais": "+52",
        "codigo_area": "55",
        "numero": "12345678"
      },
      "creacion": "2025-03-25T16:00:10-05:00",
      "actualizacion": "2025-03-25T16:00:10-05:00"
    }
  },
  "http_code": 200,
  "datetime": "2025-03-25T16:00:10-05:00",
  "timestamp": 1711401010
}

Guardar Tarjeta de Cliente

Una vez que tienes un cliente creado, puedes guardar sus tarjetas para futuros cargos.

POST /v2/cliente/{cliente_id}/tarjeta

Request:

{
  "token": "5c4a7103-d35f-4136-98be-6210d57b0ca3",
  "default": true
}

Response:

{
  "status": "success",
  "data": {
    "tarjeta": {
      "cliente_id": "ba3e968d-95d0-4a4d-928b-808a58ffbb55",
      "default": true,
      "nombre": "NOMBRE DEL TITULAR",
      "iin": "424242",
      "terminacion": "4242",
      "pan": "424242******4242",
      "marca": "visa",
      "expiracion_mes": "03",
      "expiracion_anio": "27",
      "token": "5c4a7103-d35f-4136-98be-6210d57b0ca3",
      "actualizacion": "2025-03-25T16:02:30-05:00",
      "creacion": "2025-03-25T16:02:30-05:00"
    }
  },
  "http_code": 200,
  "datetime": "2025-03-25T16:02:30-05:00",
  "timestamp": 1711401150
}

Listar Tarjetas de un Cliente

Puedes obtener todas las tarjetas guardadas de un cliente.

GET /v2/cliente/{cliente_id}/tarjeta

Response:

{
  "status": "success",
  "data": {
    "tarjetas": [
      {
        "cliente_id": "ba3e968d-95d0-4a4d-928b-808a58ffbb55",
        "default": true,
        "nombre": "NOMBRE DE TITULAR",
        "iin": "424242",
        "terminacion": "4242",
        "pan": "424242******4242",
        "marca": "visa",
        "expiracion_mes": "03",
        "expiracion_anio": "27",
        "token": "5c4a7103-d35f-4136-98be-6210d57b0ca3",
        "actualizacion": "2025-03-25T16:02:30-05:00",
        "creacion": "2025-03-25T16:02:30-05:00"
      }
    ]
  },
  "http_code": 200,
  "datetime": "2025-03-25T16:03:45-05:00",
  "timestamp": 1711401225
}

Ejemplos de Integración

A continuación se presentan ejemplos de integración con la API de T1pagos en diferentes lenguajes de programación.

Ejemplo de integración con Java

Este ejemplo muestra cómo realizar un cargo a tarjeta utilizando Java y la biblioteca OkHttp: 

import com.google.gson.Gson;
import com.google.gson.JsonObject;
import okhttp3.*;
import java.io.IOException;

public class T1PagosExample {
    private static final String API_URL = "https://api.sandbox.t1pagos.com/v2";
    private static final String API_KEY = "tu_api_key_aqui";
    
    public static void main(String[] args) {
        try {
            // 1. Tokenizar tarjeta
            String cardToken = tokenizeCard(
                "NOMBRE DEL TITULAR",
                "4242424242424242",
                "03",
                "27",
                "123"
            );
            
            // 2. Crear cargo con el token
            createCharge(cardToken, "10", "Cargo de prueba", "5834125431628311477");
            
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
    
    private static String tokenizeCard(String name, String cardNumber, String expiryMonth, 
                                      String expiryYear, String cvv) throws IOException {
        OkHttpClient client = new OkHttpClient();
        
        // Crear objeto JSON para la solicitud
        JsonObject cardData = new JsonObject();
        cardData.addProperty("nombre", name);
        cardData.addProperty("pan", cardNumber);
        cardData.addProperty("expiracion_mes", expiryMonth);
        cardData.addProperty("expiracion_anio", expiryYear);
        cardData.addProperty("cvv2", cvv);
        cardData.addProperty("default", true);
        
        // Configurar la solicitud
        RequestBody body = RequestBody.create(
            MediaType.parse("application/json"), new Gson().toJson(cardData));
            
        Request request = new Request.Builder()
            .url(API_URL + "/tarjeta")
            .addHeader("X-API-Key", API_KEY)
            .post(body)
            .build();
            
        // Ejecutar la solicitud
        try (Response response = client.newCall(request).execute()) {
            if (!response.isSuccessful()) {
                throw new IOException("Error inesperado: " + response.code());
            }
            
            // Procesar la respuesta
            String responseBody = response.body().string();
            JsonObject jsonResponse = new Gson().fromJson(responseBody, JsonObject.class);
            
            // Extraer el token de la tarjeta
            return jsonResponse.getAsJsonObject("data")
                              .getAsJsonObject("tarjeta")
                              .get("token").getAsString();
        }
    }
    
    private static void createCharge(String cardToken, String amount, String description, 
                                    String deviceFingerprint) throws IOException {
        OkHttpClient client = new OkHttpClient();
        
        // Crear objeto JSON para la solicitud
        JsonObject chargeData = new JsonObject();
        chargeData.addProperty("monto", amount);
        chargeData.addProperty("descripcion", description);
        chargeData.addProperty("metodo_pago", "tarjeta");
        
        // Añadir información del pedido
        JsonObject orderInfo = new JsonObject();
        orderInfo.addProperty("device_fingerprint", deviceFingerprint);
        chargeData.add("pedido", orderInfo);
        
        // Añadir información de la tarjeta
        JsonObject cardInfo = new JsonObject();
        cardInfo.addProperty("token", cardToken);
        chargeData.add("tarjeta", cardInfo);
        
        // Configurar la solicitud
        RequestBody body = RequestBody.create(
            MediaType.parse("application/json"), new Gson().toJson(chargeData));
            
        Request request = new Request.Builder()
            .url(API_URL + "/cargo")
            .addHeader("X-API-Key", API_KEY)
            .post(body)
            .build();
            
        // Ejecutar la solicitud
        try (Response response = client.newCall(request).execute()) {
            String responseBody = response.body().string();
            System.out.println("Respuesta del cargo: " + responseBody);
            
            // Procesar la respuesta según tus necesidades
            JsonObject jsonResponse = new Gson().fromJson(responseBody, JsonObject.class);
            String status = jsonResponse.get("status").getAsString();
            
            if ("success".equals(status)) {
                JsonObject chargeInfo = jsonResponse.getAsJsonObject("data")
                                                   .getAsJsonObject("cargo");
                String chargeStatus = chargeInfo.get("estatus").getAsString();
                
                if ("completada".equals(chargeStatus)) {
                    System.out.println("¡Cargo completado con éxito!");
                } else {
                    System.out.println("El cargo fue procesado pero no completado: " + 
                                      chargeInfo.get("descripcion").getAsString());
                }
            } else {
                System.out.println("Error al procesar el cargo: " + 
                                  jsonResponse.getAsJsonObject("error").get("message").getAsString());
            }
        }
    }
}

Ejemplo de integración con Go

Este ejemplo muestra cómo realizar un cargo a tarjeta utilizando Go: 

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io/ioutil"
	"net/http"
)

const (
	apiURL = "https://api.sandbox.t1pagos.com/v2"
	apiKey = "tu_api_key_aqui"
)

// Estructuras para la tokenización de tarjeta
type CardTokenRequest struct {
	Nombre        string `json:"nombre"`
	Pan           string `json:"pan"`
	ExpiracionMes string `json:"expiracion_mes"`
	ExpiracionAnio string `json:"expiracion_anio"`
	Cvv2          string `json:"cvv2"`
	Default       bool   `json:"default"`
}

type CardTokenResponse struct {
	Status    string `json:"status"`
	Data      struct {
		Tarjeta struct {
			Token string `json:"token"`
		} `json:"tarjeta"`
	} `json:"data"`
}

// Estructuras para la creación de cargo
type ChargeRequest struct {
	Monto       string `json:"monto"`
	Descripcion string `json:"descripcion"`
	Pedido      struct {
		DeviceFingerprint string `json:"device_fingerprint"`
	} `json:"pedido"`
	MetodoPago string `json:"metodo_pago"`
	Tarjeta    struct {
		Token string `json:"token"`
	} `json:"tarjeta"`
}

type ChargeResponse struct {
	Status string `json:"status"`
	Data   struct {
		Cargo struct {
			ID         string `json:"id"`
			Estatus    string `json:"estatus"`
			Codigo     string `json:"codigo"`
			Descripcion string `json:"descripcion"`
		} `json:"cargo"`
	} `json:"data"`
}

func main() {
	// 1. Tokenizar tarjeta
	cardToken, err := tokenizeCard("NOMBRE DEL TITULAR", "4242424242424242", "03", "27", "123")
	if err != nil {
		fmt.Printf("Error al tokenizar tarjeta: %v\n", err)
		return
	}
	
	fmt.Printf("Tarjeta tokenizada con éxito. Token: %s\n", cardToken)
	
	// 2. Crear cargo con el token
	err = createCharge(cardToken, "10", "Cargo de prueba", "5834125431628311477")
	if err != nil {
		fmt.Printf("Error al crear cargo: %v\n", err)
		return
	}
}

func tokenizeCard(name, cardNumber, expiryMonth, expiryYear, cvv string) (string, error) {
	// Preparar datos de la solicitud
	cardData := CardTokenRequest{
		Nombre:        name,
		Pan:           cardNumber,
		ExpiracionMes: expiryMonth,
		ExpiracionAnio: expiryYear,
		Cvv2:          cvv,
		Default:       true,
	}
	
	// Convertir a JSON
	jsonData, err := json.Marshal(cardData)
	if err != nil {
		return "", err
	}
	
	// Crear solicitud HTTP
	req, err := http.NewRequest("POST", apiURL+"/tarjeta", bytes.NewBuffer(jsonData))
	if err != nil {
		return "", err
	}
	
	// Añadir encabezados
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-API-Key", apiKey)
	
	// Enviar solicitud
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		return "", err
	}
	defer resp.Body.Close()
	
	// Leer respuesta
	body, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		return "", err
	}
	
	// Verificar código de estado
	if resp.StatusCode != http.StatusOK {
		return "", fmt.Errorf("error en la solicitud: %s", body)
	}
	
	// Procesar respuesta
	var tokenResponse CardTokenResponse
	err = json.Unmarshal(body, &tokenResponse)
	if err != nil {
		return "", err
	}
	
	// Verificar estado de la respuesta
	if tokenResponse.Status != "success" {
		return "", fmt.Errorf("error al tokenizar tarjeta: %s", body)
	}
	
	return tokenResponse.Data.Tarjeta.Token, nil
}

func createCharge(cardToken, amount, description, deviceFingerprint string) error {
	// Preparar datos de la solicitud
	chargeData := ChargeRequest{
		Monto:       amount,
		Descripcion: description,
		MetodoPago:  "tarjeta",
	}
	chargeData.Pedido.DeviceFingerprint = deviceFingerprint
	chargeData.Tarjeta.Token = cardToken
	
	// Convertir a JSON
	jsonData, err := json.Marshal(chargeData)
	if err != nil {
		return err
	}
	
	// Crear solicitud HTTP
	req, err := http.NewRequest("POST", apiURL+"/cargo", bytes.NewBuffer(jsonData))
	if err != nil {
		return err
	}
	
	// Añadir encabezados
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-API-Key", apiKey)
	
	// Enviar solicitud
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		return err
	}
	defer resp.Body.Close()
	
	// Leer respuesta
	body, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		return err
	}
	
	// Procesar respuesta
	var chargeResponse ChargeResponse
	err = json.Unmarshal(body, &chargeResponse)
	if err != nil {
		return err
	}
	
	// Verificar estado de la respuesta
	if chargeResponse.Status != "success" {
		return fmt.Errorf("error al crear cargo: %s", body)
	}
	
	// Verificar estado del cargo
	fmt.Printf("Cargo procesado. Estado: %s\n", chargeResponse.Data.Cargo.Estatus)
	if chargeResponse.Data.Cargo.Estatus == "completada" {
		fmt.Println("¡Cargo completado con éxito!")
	} else {
		fmt.Printf("El cargo no se completó: %s\n", chargeResponse.Data.Cargo.Descripcion)
	}
	
	return nil
}

Ejemplo de integración con Python

Este ejemplo muestra cómo realizar un cargo a tarjeta utilizando Python y la biblioteca requests: 

import requests
import json

# Configuración
API_URL = "https://api.sandbox.t1pagos.com/v2"
API_KEY = "tu_api_key_aqui"

def tokenize_card(name, card_number, expiry_month, expiry_year, cvv):
    """
    Tokeniza una tarjeta y devuelve el token generado.
    """
    # Preparar datos de la solicitud
    card_data = {
        "nombre": name,
        "pan": card_number,
        "expiracion_mes": expiry_month,
        "expiracion_anio": expiry_year,
        "cvv2": cvv,
        "default": True
    }
    
    # Configurar encabezados
    headers = {
        "Content-Type": "application/json",
        "X-API-Key": API_KEY
    }
    
    # Realizar la solicitud
    response = requests.post(
        f"{API_URL}/tarjeta",
        headers=headers,
        json=card_data
    )
    
    # Verificar respuesta
    if response.status_code != 200:
        raise Exception(f"Error al tokenizar tarjeta: {response.text}")
    
    # Procesar respuesta
    response_data = response.json()
    if response_data["status"] != "success":
        raise Exception(f"Error en la respuesta: {response_data}")
    
    # Extraer token
    return response_data["data"]["tarjeta"]["token"]

def create_charge(card_token, amount, description, device_fingerprint):
    """
    Crea un cargo utilizando un token de tarjeta.
    """
    # Preparar datos de la solicitud
    charge_data = {
        "monto": amount,
        "descripcion": description,
        "pedido": {
            "device_fingerprint": device_fingerprint
        },
        "metodo_pago": "tarjeta",
        "tarjeta": {
            "token": card_token
        }
    }
    
    # Configurar encabezados
    headers = {
        "Content-Type": "application/json",
        "X-API-Key": API_KEY
    }
    
    # Realizar la solicitud
    response = requests.post(
        f"{API_URL}/cargo",
        headers=headers,
        json=charge_data
    )
    
    # Procesar respuesta
    response_data = response.json()
    print(f"Respuesta del cargo: {json.dumps(response_data, indent=2)}")
    
    # Verificar estado de la respuesta
    if response_data["status"] != "success":
        print(f"Error al procesar el cargo: {response_data.get('error', {}).get('message', 'Error desconocido')}")
        return False
    
    # Verificar estado del cargo
    charge_status = response_data["data"]["cargo"]["estatus"]
    if charge_status == "completada":
        print("¡Cargo completado con éxito!")
        return True
    else:
        print(f"El cargo no se completó: {response_data['data']['cargo']['descripcion']}")
        return False

def main():
    try:
        # 1. Tokenizar tarjeta
        print("Tokenizando tarjeta...")
        card_token = tokenize_card(
            "NOMBRE DEL TITULAR",
            "4242424242424242",
            "03",
            "27",
            "123"
        )
        print(f"Tarjeta tokenizada con éxito. Token: {card_token}")
        
        # 2. Crear cargo con el token
        print("Creando cargo...")
        success = create_charge(
            card_token,
            "10",
            "Cargo de prueba",
            "5834125431628311477"
        )
        
        if success:
            print("Proceso de cargo completado correctamente.")
        else:
            print("El proceso de cargo no se completó correctamente.")
            
    except Exception as e:
        print(f"Error durante el proceso: {e}")

if __name__ == "__main__":
    main()

Webhooks

En el sistema T1pagos algunos procesos son ejecutados de manera automática, como es el caso de los cobros de las suscripciones. Para poder mantener sincronizados los sistemas, podrá configurarse un endpoint para recibir notificaciones de algunos eventos como nuevos cargos, renovación de suscripciones y otros.

El registro se realiza desde el sistema Admin, podrá incluirse más de un endpoint y canalizar las notificaciones a cada nueva ruta.

Eventos Disponibles

Método Tipo de Evento Id Descripción
Cargo Exitoso cargo.exitoso Indicará cuando fue realizado un cargo exitoso
Cargo Fallido cargo.fallido Indicará cuando fue realizado un cargo fallido o rechazado
Cargo Cancelado cargo.cancelado Indicará cuando un cargo haya sido cancelado
Cargo Reembolsado cargo.reembolsado Indicará cuando un cargo haya sido reembolsado
Suscripción Creada suscripcion.creada Indicará la creación de una nueva suscripción, el evento no notificará el cobro de una suscripción
Suscripción Actualizada suscripcion.actualizada Se ejecuta cuando se realiza una actualización a una suscripción.
Suscripción Cancelada suscripcion.cancelada Se ejecuta cuando se ejecuta el comando "cancelar" de una suscripción.
Suscripción Pago.exitoso suscripcion.pago.exitoso Se ejecuta cuando se realiza el cobro de una suscripción de manera exitosa
Suscripción Pago.fallido suscripcion.pago.fallido Se ejecuta cuando se realiza el cobro de una suscripción de manera fallida

Seguridad en Recepción de Eventos

En la configuración de recepción de eventos podrá habilitarse un usuario y contraseña que deberá de validar el sistema al recibir cada evento. El esquema, conocido como autenticación básica, permite añadir una capa de seguridad adicional.

Consulta de Eventos

Si el sistema que recibe las notificaciones presenta algún contratiempo, o se busca confirmar las operaciones realizadas, podrá hacerse uso del método GET /notificacion para consultar un listado de eventos que han sido creados y enviados.

GET /v2/notificacion

Response:

{
  "status": "success",
  "http_code": 200,
  "datetime": "2025-03-25T16:30:35-05:00",
  "timestamp": 1711402835,
  "data": {
    "eventos": {
      "data": [
        {
          "id": "string",
          "creacion": "2025-03-25T16:30:35-05:00",
          "tipo": "evento",
          "tipo_evento": "cargo.exitoso",
          "prueba": true,
          "estatus": "entregado",
          "fecha_entrega": "2025-03-25T16:30:35-05:00",
          "codigo_http": 200,
          "mensaje_http": "OK",
          "total_intentos": 1,
          "data": {
            "cargo": {
              "id": "string",
              "monto": 100,
              "autorizacion_id": "string",
              "tipo": "cargo",
              "fecha": "2025-03-25T16:30:35-05:00",
              "orden_id": "string",
              "cliente_id": "string",
              "estatus": "completada",
              "codigo": "string",
              "descripcion": "string",
              "tarjeta": {
                "token": "string",
                "pan": "string",
                "terminacion": 0,
                "nombre": "string",
                "expiracion_mes": 0,
                "expiracion_anio": 0,
                "iin": 0,
                "marca": "visa",
                "cliente_id": "string",
                "default": true
              }
            }
          }
        }
      ],
      "registros_por_pagina": 5,
      "pagina_actual": 1,
      "desde": 1,
      "hasta": 1,
      "total": 1,
      "total_pagina": 1,
      "ultima_pagina": 1
    }
  }
}

Respuestas y Errores

El modelo de respuesta del API agrupa los errores en categorías, adoptando el modelo de respuestas HTTP como códigos de cada grupo. Se adoptan sólo una serie de códigos HTTP para reflejar el resultado de la operación, además, las respuestas incluyen descripción de los errores y en algunos casos el detalle del origen del error en el campo data.

Las respuestas que sean ejecutadas de manera correcta, regresarán un código HTTP 200.

Códigos de Error HTTP

Código Tipo Campo Data Descripción
400 Parámetros Presente La solicitud contiene sintaxis errónea o un parámetro incorrecto, deberá corregirse antes de realizar una nueva petición
401 Autenticación N/A El método de autenticación proporcionado no es válido
403 Autenticación N/A El método de autenticación no cuenta con permisos suficientes
404 General N/A No se ha encontrado el recurso solicitado
405 Sistema N/A Se ha hecho una solicitud a un método no soportado
409 Parámetros N/A Se ha realizado una solicitud que entra en conflicto con un recurso existente
412 Precondición N/A Una o más condiciones no se han cumplido por lo que no se puede procesar la petición
429 Sistema N/A Se han realizado demasiadas peticiones
500 Sistema N/A Ha ocurrido un error en el servidor

Formato de Respuestas

En general, todas las respuestas del API incluyen un wrapper en las respuestas, el concepto detrás del wrapper es permitir una rápida interpretación de la ejecución de la petición realizada, más no del resultado, el resultado estará contenido en el campo data, algunas peticiones también podrán incluir un objeto error en el cuerpo del mensaje.

Ejemplo de Respuesta Exitosa:

{
  "status": "success",
  "data": {},
  "http_code": 200,
  "datetime": "2025-03-25T16:35:21-05:00",
  "timestamp": 1711403121
}

Ejemplo de Error:

{
  "status": "error",
  "error": {
    "code": 429,
    "type": "Sistema",
    "message": "Ha excedido la tasa máxima de peticiones"
  },
  "http_code": 429,
  "datetime": "2025-03-25T16:36:49-05:00",
  "timestamp": 1711403209
}

Ejemplo de Error con Detalle:

{
  "status": "fail",
  "error": {
    "code": 400,
    "type": "Parámetros",
    "message": "Error en parámetros de entrada."
  },
  "http_code": 400,
  "datetime": "2025-03-25T16:38:33-05:00",
  "timestamp": 1711403313,
  "data": {
    "errors": {
      "email": [
        "El campo email no corresponde con una dirección de e-mail válida."
      ]
    }
  }
}

Valores de Status

  • success - Indicará que la petición fue al API fue procesada correctamente. El detalle de la operación solicitada se encontrará en el campo data.
  • fail - Indicará que hubo un error con los valores enviados en la petición o no se cumplió con una precondición, por ejemplo no se incluyó un campo obligatorio.
  • error - Indicará que ha ocurrido un error al procesar la petición, por ejemplo, que ha sucedido una excepción al procesar la operación.