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 ----==----APP, 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 ----==----APP 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 ----==---- 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 ----==----APP 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 ----==---- 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 ----==----API {
    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 ----==----APP 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.