API Token

Índice

• API Token
  • Índice
  • Obtener el API Token
  • Autenticación con Bearer Token
  • Identificador de la tienda (S-ID)
    • Cómo obtener el S-ID
  • Consultas a la API
    • Métodos CRUD
    • Ejemplos con cURL
  • Limiter en la API
    • Límites por tipo de solicitud
    • Headers de respuesta
      • Ejemplo de headers
  • Ejemplos de uso de la API
    • PHP
    • JavaScript
    • Java
    • Go
    • CSharp
  • Conclusión

---

Obtener el API Token

Para interactuar con la API de TurpialAPP, primero necesitas obtener tu API Token. Para ello:

1. Inicia sesión en el sistema.
2. Ve a Integraciones en el menú principal.
3. Dentro de Integraciones, encontrarás el API Token que se necesita para autenticarte en las peticiones a la API.

Para consultar todos los enpoint disponibles puede verlo en nuestra API Reference

---

Autenticación con Bearer Token

Las solicitudes a la API de TurpialAPP deben incluir un API Token para la autenticación. Este token se puede enviar de dos formas:

• En el header de la solicitud: Usando la autenticación Bearer.

  Ejemplo de header: Authorization: Bearer API_TOKEN

• En la URL: En lugar de enviarlo en el header, también se puede enviar el token en la URL del cuerpo de la solicitud.

Ejemplo de URL: https://api.turpial.app/invoices?access_token=API_TOKEN

Ambas formas son válidas, pero se recomienda utilizar el header Bearer por motivos de seguridad.

---

Identificador de la tienda (S-ID)

Algunos endpoints de la API requieren un identificador único de la tienda, conocido como S-ID. Este identificador debe incluirse en el header de la solicitud como X-Store-Uuid.

Cómo obtener el S-ID

1. Dirígete a Turpial Dashboard.
2. En el menú "Mis Tiendas y Almacenes", verás una lista de las tiendas asociadas a tu cuenta.
3. Encuentra la tienda que deseas utilizar y haz clic en el ícono de portapapeles al lado del S-ID para copiar el identificador completo.
4. El S-ID tiene el siguiente formato: 00000000-0000-0000-0000-000000000000 (un UUID).

• En el header de la solicitud: Este S-ID debe ser enviado en el header de la solicitud como sigue:

X-Store-Uuid: 00000000-0000-0000-0000-000000000000

• En la URL: En lugar de enviarlo en el header, también se puede enviar el S-ID en la URL del cuerpo de la solicitud.

Ejemplo de URL: https://api.turpial.app/invoices?access_token=API_TOKEN&store_uuid=00000000-0000-0000-0000-000000000000

Ambas formas son válidas, pero se recomienda utilizar el header por motivos de seguridad.

Asegúrate de utilizar el S-ID correcto al realizar las solicitudes a la API que requieren este identificador.

---

Consultas a la API

La API de TurpialAPP utiliza tecnología API REST, que es un conjunto de convenciones y principios para la comunicación entre sistemas mediante HTTP. Esta tecnología es ampliamente utilizada por su simplicidad y flexibilidad. En REST, los recursos se identifican mediante URLs y las operaciones se realizan utilizando los métodos HTTP estándar.

Métodos CRUD

• GET: Obtener datos del servidor.
• POST: Crear nuevos recursos.
• PUT: Actualizar recursos existentes.
• DELETE: Eliminar recursos.

Ejemplos con cURL

• GET (Obtener datos)

curl -X GET "https://api.turpial.app/ENDPOINT" -H "Authorization: Bearer <API_TOKEN>"

• POST (Crear un recurso)

curl -X POST "https://api.turpial.app/ENDPOINT" -H "Authorization: Bearer <API_TOKEN>" -d '{ ... }'

• PUT (Actualizar un recurso)

curl -X PUT "https://api.turpial.app/ENDPOINT/123" -H "Authorization: Bearer <API_TOKEN>" -d '{ ... }'

• DELETE (Eliminar un recurso)

curl -X DELETE "https://api.turpial.app/ENDPOINT/123" -H "Authorization: Bearer <API_TOKEN>"

Limiter en la API

La API de Turpial aplica un sistema de límites para gestionar la cantidad de solicitudes permitidas por token en un período de tiempo determinado. Este mecanismo asegura un uso justo y eficiente de los recursos del sistema.

Límites por tipo de solicitud

• POST: Máximo de 10 solicitudes por minuto.
• GET: Máximo de 50 solicitudes por minuto.
• Otros métodos: Máximo de 20 solicitudes por minuto.

Headers de respuesta

Cada respuesta de la API incluye información en los headers para indicar cuántas solicitudes puedes realizar antes de alcanzar el límite:

• X-RateLimit-Post-Remaining: Número de solicitudes POST restantes en el período actual.
• X-RateLimit-Get-Remaining: Número de solicitudes GET restantes en el período actual.
• X-RateLimit-Other-Remaining: Número de solicitudes de otros métodos restantes en el período actual.

Ejemplo de headers

HTTP/1.1 200 OK
X-RateLimit-Post-Remaining: 7
X-RateLimit-Get-Remaining: 45
X-RateLimit-Other-Remaining: 15

Ejemplos de uso de la API

PHP

<?php
$api_token = 'tu_api_token_aqui';
$s_id = '00000000-0000-0000-0000-000000000000';
$api_url = 'https://api.turpial.app/invoices';

// Inicializar cURL
$ch = curl_init($api_url);

// Configurar los parámetros de la solicitud
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer $api_token",
    "X-Store-Uuid: Bearer $s_id"
]);

// Ejecutar la solicitud y obtener la respuesta
$response = curl_exec($ch);

// Verificar errores
if(curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}

curl_close($ch);

// Procesar la respuesta
echo $response;

JavaScript

const apiToken = 'tu_api_token_aqui';
const storeId = '00000000-0000-0000-0000-000000000000';
const apiUrl = 'https://api.turpial.app/invoices';

fetch(apiUrl, {
    method: 'GET',
    headers: {
        'Authorization': `Bearer ${apiToken}`,
        'X-Store-Uuid': storeId
    }
})
.then(response => response.json())
.then(data => {
    console.log(data);
})
.catch(error => {
    console.error('Error:', error);
});

Java

import java.net.HttpURLConnection;
import java.net.URL;
import java.io.InputStreamReader;
import java.io.BufferedReader;

public class TurpialAPI {
    public static void main(String[] args) {
        try {
            String apiToken = "tu_api_token_aqui";
            String storeId = "00000000-0000-0000-0000-000000000000";
            String apiUrl = "https://api.turpial.app/invoices";

            URL url = new URL(apiUrl);
            HttpURLConnection connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("GET");
            connection.setRequestProperty("Authorization", "Bearer " + apiToken);
            connection.setRequestProperty("X-Store-Uuid", storeId);
            
            BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
            String inputLine;
            StringBuffer response = new StringBuffer();
            
            while ((inputLine = in.readLine()) != null) {
                response.append(inputLine);
            }
            in.close();

            System.out.println(response.toString());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Go

package main

import (
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() {
	apiToken := "tu_api_token_aqui"
	storeId := "00000000-0000-0000-0000-000000000000"
	apiUrl := "https://api.turpial.app/invoices"

	// Crear una solicitud GET
	req, err := http.NewRequest("GET", apiUrl, nil)
	if err != nil {
		fmt.Println(err)
		return
	}

	// Agregar el encabezado de autorización
	req.Header.Add("Authorization", "Bearer "+apiToken)
	req.Header.Add("X-Store-Uuid", storeId)

	// Hacer la solicitud
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()

	// Leer la respuesta
	body, _ := ioutil.ReadAll(resp.Body)
	fmt.Println(string(body))
}

CSharp

using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        // URL de la API
        string url = "https://api.turpial.app/invoices";

        // API Token
        string apiToken = "TU_API_TOKEN_AQUÍ";  // Reemplaza con tu API Token

        // S-ID (Identificador de la tienda)
        string storeId = "00000000-0000-0000-0000-000000000000";  // Reemplaza con tu S-ID

        // Crea un cliente HTTP
        using (HttpClient client = new HttpClient())
        {
            // Agrega el header Authorization con Bearer Token
            client.DefaultRequestHeaders.Add("Authorization", "Bearer " + apiToken);

            // Agrega el header X-Store-Uuid con el S-ID
            client.DefaultRequestHeaders.Add("X-Store-Uuid", storeId);

            // Realiza la solicitud GET
            HttpResponseMessage response = await client.GetAsync(url);

            // Verifica si la solicitud fue exitosa
            if (response.IsSuccessStatusCode)
            {
                string responseData = await response.Content.ReadAsStringAsync();
                Console.WriteLine("Respuesta exitosa: ");
                Console.WriteLine(responseData);
            }
            else
            {
                Console.WriteLine("Error: " + response.StatusCode);
            }
        }
    }
}

Conclusión

La API de TurpialAPP permite interactuar con el sistema de forma sencilla y segura. Asegúrate de obtener tu API Token desde el menú de Integraciones y utilizarlo para autenticar tus peticiones. Los ejemplos anteriores te permitirán hacer consultas a la API utilizando diferentes lenguajes de programación.

Si tienes dudas o necesitas más información sobre cómo utilizar la API, no dudes en contactarnos.