# API Reference

{% hint style="success" %}
Únete a nuestro [*<mark style="color:blue;">espacio de Slack</mark>*](https://join.slack.com/t/preauth-soporte/shared_invite/zt-18pzujyy8-F6cZBsHmZ_5OZFd16fnnWw) y te ayudaremos con tus dudas
{% endhint %}

### Autenticación

Para tener acceso a los servicios es necesario haber obtenido el api-token para ser usado como cabecera en cada petición. Para más información, puedes revisar como obtener el api-token en la guía de [Primeros pasos](/primeros-pasos.md#2-verifica-que-tengas-tu-api-token).

Cuando obtengas tu api-token, es necesario que lo envíes en la cabecera **"x-auth-token"** en cada petición que quieras hacer.

### Servicios

## Crear orden

<mark style="color:green;">`POST`</mark> `https://api.preauth.io/v1/order`

Servicio para crear una orden, con el id de la orden luego podrás realizar la retención utilizando el [Widget](/widget.md)&#x20;

#### Headers

| Name                                           | Type   | Description |
| ---------------------------------------------- | ------ | ----------- |
| x-auth-token<mark style="color:red;">\*</mark> | String | Api token   |

#### Request Body

| Name                                          | Type    | Description                                                                                                                                          |
| --------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| country<mark style="color:red;">\*</mark>     | String  | [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (Ej: PE, CL, MX)                            |
| currency<mark style="color:red;">\*</mark>    | String  | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) (Ej: PEN, CLP, MXN)                                                                  |
| amount<mark style="color:red;">\*</mark>      | Integer | Monto en la mínima denominación. Ejemplo: Dólares en centavos (para US$100, enviar 100000) y pesos chilenos en entero (para CLP$100, enviar 100)     |
| reference<mark style="color:red;">\*</mark>   | String  | Referencia del comercio                                                                                                                              |
| limit\_date<mark style="color:red;">\*</mark> | String  | Fecha límite de la orden (YYYY-mm-dd)                                                                                                                |
| meta.client.phone                             | String  | Formato[ E.123](https://en.wikipedia.org/wiki/E.123#Example_formats)                                                                                 |
| meta.client.documentType                      | String  | Tipo de documento                                                                                                                                    |
| meta.client.document                          | String  | Alfanumérico del documento                                                                                                                           |
| meta.client.email                             | String  | RFC 5322                                                                                                                                             |
| meta.product.title                            | String  | Nombre del producto/servicio                                                                                                                         |
| meta.billing.address                          | String  | Dirección del cliente                                                                                                                                |
| meta.billing.city                             | String  | Ciudad del cliente                                                                                                                                   |
| meta.billing.region                           | String  | Región del cliente                                                                                                                                   |
| meta.billing.country                          | String  | País del cliente                                                                                                                                     |
| meta.client.name                              | Stng    | Nombre del cliente                                                                                                                                   |
| card\_id                                      | Integer | Id de tarjeta previamente almacenada (asociada a otra orden). Puede hacer que el servicio dure más debido a que intenta generar una preautorización. |

{% tabs %}
{% tab title="200: OK Modelo Order" %}

```json
{
  "id": "4085-whOdSyS2FkGmm4j9feJNeMh0SjQDgLa5xAUENBkajsfQK",
  "reference": "order_00001",
  "currency": "PEN",
  "country": "PE",
  "limit_date": "2022-10-10",
  "amount": 15000,
  "status": "created",
  "pending_amount": 15000,
  "captured_amount": 0,
  "meta": {},
  "card_id": null,
  "created_at": "2021-10-15 20:31:07",
  "updated_at": "2021-10-15 20:35:28"
}
```

{% endtab %}

{% tab title="200: OK Modelo Order con card\_id" %}

```json
{
  "id": "4085-whOdSyS2FkGmm4j9feJNeMh0SjQDgLa5xAUENBkajsfQK",
  "reference": "order_00001",
  "currency": "PEN",
  "country": "PE",
  "limit_date": "2022-10-10",
  "amount": 15000,
  "status": "in_progress",
  "pending_amount": 15000,
  "captured_amount": 0,
  "meta": {},
  "card_id": 1025,
  "created_at": "2021-10-15 20:31:07",
  "updated_at": "2021-10-15 20:35:28"
}
```

{% endtab %}
{% endtabs %}

## Obtener orden

<mark style="color:blue;">`GET`</mark> `https://api.preauth.io/v1/order/{id}`

Obtienes el objeto orden actualizado. Importante utilizarlo luego de recibir la confirmación de que se realizó la retención para verificar que la orden se encuentra en `in_progress`

#### Query Parameters

| Name                                 | Type   | Description    |
| ------------------------------------ | ------ | -------------- |
| id<mark style="color:red;">\*</mark> | String | Id de la orden |

#### Headers

| Name                                           | Type   | Description |
| ---------------------------------------------- | ------ | ----------- |
| x-auth-token<mark style="color:red;">\*</mark> | String | Api token   |

{% tabs %}
{% tab title="200: OK Modelo Order" %}

```javascript
{
  "id": "4085-whOdSyS2FkGmm4j9feJNeMh0SjQDgLa5xAUENBkajsfQK",
  "reference": "order_00001",
  "currency": "PEN",
  "country": "PE",
  "limit_date": "2022-10-10",
  "amount": 15000,
  "status": "in_progress",
  "pending_amount": 15000,
  "captured_amount": 0,
  "meta": {},
  "card_id": 1025,
  "created_at": "2021-10-15 20:31:07",
  "updated_at": "2021-10-15 20:35:28"
}
```

{% endtab %}
{% endtabs %}

## Actualizar orden

<mark style="color:purple;">`PATCH`</mark> `https://api.preauth.io/v1/order/{id}`

Modifica el monto o la fecha límite de una orden creada. Solo cuando esté en `created` o `in_progress`

#### Query Parameters

| Name                                 | Type   | Description    |
| ------------------------------------ | ------ | -------------- |
| id<mark style="color:red;">\*</mark> | String | Id de la orden |

#### Headers

| Name                                           | Type   | Description |
| ---------------------------------------------- | ------ | ----------- |
| x-auth-token<mark style="color:red;">\*</mark> | String | Api token   |

#### Request Body

| Name                                          | Type    | Description                                                                                   |
| --------------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| amount<mark style="color:red;">\*</mark>      | Integer | Monto en centavos, solo puede ser menor a order.pending\_amount                               |
| limit\_date<mark style="color:red;">\*</mark> | String  | Fecha límite de la orden, se puede editar según la fecha de expiración de la tarjeta asociada |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
  "status": "OK"
}
```

{% endtab %}
{% endtabs %}

## Cancelar orden

<mark style="color:red;">`DELETE`</mark> `https://api.preauth.io/v1/order/{id}`

Devolverá el dinero retenido y la orden cambiará de estado a `canceled`.&#x20;

¡Importante!, una vez cancelada una orden no puede cambiar a otro estado, tendrás que crear una nueva orden desde cero.

#### Query Parameters

| Name                                 | Type   | Description    |
| ------------------------------------ | ------ | -------------- |
| id<mark style="color:red;">\*</mark> | String | Id de la orden |

#### Headers

| Name                                           | Type   | Description |
| ---------------------------------------------- | ------ | ----------- |
| x-auth-token<mark style="color:red;">\*</mark> | String | Api token   |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
  "status": "OK"
}
```

{% endtab %}
{% endtabs %}

## Capturar orden

<mark style="color:green;">`POST`</mark> `https://api.preauth.io/v1/order/{id}/capture`

Cobra todo o parte del dinero retenido, adicionalmente nos indicas si el monto sobrante quieres seguir reteniéndolo o lo liberarás. Ej: si tienes reservado $1000 y cobras $100, ¿qué quieres hacer con los $900 sobrantes? puedes seguir bloqueándolos o liberarlos, dependiendo del caso de uso que tengas.

#### Query Parameters

| Name                                 | Type   | Description    |
| ------------------------------------ | ------ | -------------- |
| id<mark style="color:red;">\*</mark> | String | Id de la orden |

#### Headers

| Name                                           | Type   | Description |
| ---------------------------------------------- | ------ | ----------- |
| x-auth-token<mark style="color:red;">\*</mark> | String | Api token   |

#### Request Body

| Name                                          | Type    | Description                                                             |
| --------------------------------------------- | ------- | ----------------------------------------------------------------------- |
| amount<mark style="color:red;">\*</mark>      | Integer | Monto en centavos, solo puede ser menor o igual a order.pending\_amount |
| keep\_alive<mark style="color:red;">\*</mark> | Boolean | Flag para preautorizar el monto restante                                |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
  "status": "OK"
}
```

{% endtab %}
{% endtabs %}

## Hacer prueba de vida

<mark style="color:green;">`POST`</mark> `https://api.preauth.io/v1/order/{id}/liveness`

Realiza una prueba de vida a la tarjeta asociada a la orden. Esto te sirve para saber si la tarjeta está activa en el momento y poder tomar acción en caso no se encuentre activa.

Solo se puede hacer una prueba de vida por día. Si se requiere hacer más de una prueba de vida es necesario enviar el parámetro "force" en true.

#### Query Parameters

| Name                                 | Type   | Description    |
| ------------------------------------ | ------ | -------------- |
| id<mark style="color:red;">\*</mark> | String | Id de la orden |

#### Headers

| Name                                           | Type   | Description |
| ---------------------------------------------- | ------ | ----------- |
| x-auth-token<mark style="color:red;">\*</mark> | String | Api token   |

#### Request Body

| Name  | Type    | Description          |
| ----- | ------- | -------------------- |
| force | Boolean | Por defecto es false |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
  "status": "OK"
}
```

{% endtab %}
{% endtabs %}

### Modelos

#### Order

<table><thead><tr><th width="204.4464285714286">Attributo</th><th>Tipo</th><th width="197.33333333333331">Descripción</th><th>Ejemplo</th></tr></thead><tbody><tr><td>id</td><td>Text</td><td>Identificador de la orden</td><td>4085-whOdSyS2FkGmm4j9feJNeMh0SjQDgLa5xAUENBkajsfQK</td></tr><tr><td>reference</td><td>Text</td><td>Referencia del comercio</td><td>order_0001</td></tr><tr><td>currency</td><td>Text</td><td>ISO 4217</td><td>PEN</td></tr><tr><td>country</td><td>Text</td><td>ISO 3166-1 alpha-2</td><td>PE</td></tr><tr><td>limit_date</td><td>Text</td><td>Fecha límite, pasada esta fecha se liberará el valor del pending_amount</td><td>2022-10-10</td></tr><tr><td>amount</td><td>Integer</td><td>Monto en centavos</td><td>15000</td></tr><tr><td>status</td><td>OrderStatus</td><td>Ver OrderStatus</td><td>created</td></tr><tr><td>pending_amount</td><td>Integer</td><td>Monto en centavos de lo que debe mantenerse preautorizado</td><td>15000</td></tr><tr><td>capture_amount</td><td>Integer</td><td>Monto en centavos de lo que se ha ido capturando</td><td>0</td></tr><tr><td>card_id</td><td>Integer</td><td>Referencia a tarjeta almacenada. Es posible usarla para crear una nueva orden.</td><td>1025</td></tr><tr><td>meta</td><td>Object</td><td>Parámetro en donde se puede enviar data adicional.</td><td><pre class="language-json"><code class="lang-json">{
  "email": "example@preauth.io",
  "name": "Pedro"
}
</code></pre></td></tr><tr><td>created_at</td><td>Text</td><td>Fecha de creación de la orden</td><td>2021-10-15 20:31:07</td></tr><tr><td>update_at</td><td>Text</td><td>Última fecha de actualización de la orden</td><td>2021-10-15 20:35:28</td></tr></tbody></table>

#### OrderStatus

<table><thead><tr><th width="220.84721916142615">Attributo</th><th>Descripción</th></tr></thead><tbody><tr><td>created</td><td>Cuando la orden ha sido creada y aún no tiene un medio de pago asociado.</td></tr><tr><td>in_progress</td><td>Cuando la orden ya cuenta con una tarjeta asociada.</td></tr><tr><td>canceled</td><td>Cuando el comercio solicitó la cancelación.</td></tr><tr><td>finished</td><td>Cuando la fecha límite ya pasó.</td></tr><tr><td>desynchronized</td><td>Cuando la tarjeta asociada a la orden no puede ser preautorizada nuevamente.</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.preauth.io/api-rest.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.