# Introducción

Usar el API de Persat es muy sencillo. Si usaste un **API REST** alguna vez, vas a sentirte como en casa. Si no, en esta guía vas a encontrar todo lo necesario para hacerlo.

Para comunicarnos con la API, debemos hacer un pedido a la URL base, seguido de la versión (en este caso v1), seguido del **namespace** correspondiente, es decir, el nombre del recurso al cual deseamos acceder. Los namespaces están en inglés, pero es muy sencillo reconocerlos. Por ejemplo, si necesitamos leer información de los clientes, entonces el namespace será `clients` y la URL completa será algo como:

```
https://api.persat.com.ar/v1/clients
```

## Métodos REST

Para leer o escribir información a través del API debemos hacer pedidos HTTP. Como las convenciones de REST indican, los métodos utilizados son los siguientes:

| Método     | URL               | Efecto                            |
| ---------- | ----------------- | --------------------------------- |
| **GET**    | `/[namespace]`    | Obtener un listado de elementos   |
| **GET**    | `/[namespace]/id` | Obtener el detalle de un elemento |
| **POST**   | `/[namespace]`    | Crear un nuevo elemento           |
| **PUT**    | `/[namespace]/id` | Modificar un elemento             |
| **DELETE** | `/[namespace]/id` | Eliminar un elemento              |

## Content type

El header Content-Type indica el formato que estamos utilizando en el contenido de un pedido POST o PUT. El único`Content-Type` que soporta la API por el momento es `application/json`

{% hint style="info" %}
Si indicamos un Content-Type no soportado, recibiremos un error 415 UNSUPPORTED\_MEDIA\_TYPE . En caso que el formato utilizado en el contenido no pueda ser interpretado correctamente, el error será 400 BAD\_REQUEST Api key
{% endhint %}

Para que nuestro pedido sea aceptado por el API, debemos enviar un **api key** válido que nos identifica como usuarios de la cuenta sobre la que queremos trabajar. Podés consultar cómo obtener un api key en la sección [autenticación](https://docs.api.persat.com.ar/como-usar-la-api/autenticacion).

En el siguiente ejemplo, mostramos como obtener los datos de un cliente particular con número de cliente "CL-0044", suponiendo además que nuestra api key es `YOUR_API_KEY`

```
curl --location --request GET "https://api.persat.com.ar/v1/clients/CL-0044" \
  --header "Authorization: Bearer YOUR_API_KEY"
```