# Consulta externa

El servicio de consulta externa puede tener dos tipos de integración: código de convenio propio o referencia con prefijo (prefijo + identificación).

La integración con convenio propio es posible sólo con la red de recaudo efecty. Y la integración de referencia con prefijo debe de seguir el formato prefijo + número y garantizar una longitud mínima para ser considerada de ​9 dígitos y​ una máxima de ​16 dígitos​. Queda a disposición de cada comercio decidir cómo rellenar los dígitos faltantes, pero se recomienda utilizar el número 0, por ejemplo: 326000034567

El servicio de consulta externa, permite que el comercio sea quien tenga el control de la orden a recaudar y el medio de pago que se utilizará para realizar el pago. 

<div align="left"><img src="https://1874222255-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MNsmrOb2q0SiO670iPn%2F-MNsmwbMANrsyTlS8qJp%2F-MNsoNc-DKopdmjZ0Dpf%2FCaptura%20de%20Pantalla%202020-12-06%20a%20la(s)%2011.10.10%20a.%C2%A0m..png?alt=media&#x26;token=b7812c34-cbf9-4d95-b2c6-493f86db2e3b" alt=""></div>

{% tabs fullWidth="false" %}
{% tab title="Request" %}

| Campo            | Requerido | Tipo         | Longitud | Descripción                                                                                                                      |
| ---------------- | --------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| reference        | Si        | Numérico     | 16       | Número de referencia proporcionado por el usuario                                                                                |
| netname          | Si        | Alfanumérico | 40       | Nombre del medio de recaudo                                                                                                      |
| currency         | Si        | Numérico     | 1        | Moneda asociada al monto de la orden de compra ([Monedas](https://docs.payvalida.com/api-cashin-plus/codigos-de-pais-y-monedas)) |
| timestamp\_start | Si        | Numérico     | 10       | Tiempo de inicio de la transacción en formato Unix Timestamp (Segundos) UTC                                                      |
| checksum         | si        | Alfanumérico | 512      | Cadena de comprobación SHA512(reference + currency + netname + timestamp\_start +  FIXED\_HASH)                                  |
| {% endtab %}     |           |              |          |                                                                                                                                  |

{% tab title="Request (ejemplo)" %}

```go
curl --location --request POST '<Endpoint de cada comercio>' \
--header 'Content-Type: application/json' \
--data-raw '{
 "reference":"123456789",
 "netname":"VIA",
 "currency":1,
 "timestamp_start":1581370328, 
 "checksum":"71ff0ca3ffa49f0d13c7de5c661c6f8fddcab38004a195718e3d89d330005ee 34623959e93893cc2ff5f451b89b43dcc514c5767a2415066578adecbd4ef8242"
 }'
 

```

{% endtab %}

{% tab title="Response" %}

<table data-header-hidden data-full-width="false"><thead><tr><th>Campo</th><th>Requerido    </th><th>Estructura</th><th>Tipo</th><th>Longitud</th><th>Descripción                        </th></tr></thead><tbody><tr><td>Campo</td><td>Requerido    </td><td>Estructura</td><td>Tipo</td><td>Longitud</td><td>Descripción                        </td></tr><tr><td>CODE</td><td>       si</td><td>-</td><td>Alfanumérico</td><td>       4</td><td>Código de respuesta de errores "0000" para respuesta OK</td></tr><tr><td>TEXT</td><td>       si</td><td>-</td><td>Alfanumérico</td><td>       2</td><td>Descripción de respuesta "OK" para ejecución correcta. </td></tr><tr><td>DATA</td><td>       si</td><td>-</td><td>estructura</td><td>       -</td><td>Estructura json que contiene los datos de respuesta</td></tr><tr><td>order</td><td>       si</td><td>DATA</td><td>Alfanumérico</td><td>    200</td><td>Número de orden registrada en el sistema del comercio debe ser única. A este campo se le realiza una validación por expresión regular (<strong>^[a-zA-Z0-9_-]{1,200}$</strong>)</td></tr><tr><td>amount</td><td>       si</td><td>DATA</td><td>Alfanumérico</td><td>      20</td><td>Monto de la orden. Enviar 0 para que el usuario pueda pagar lo que desee (monto abierto)</td></tr><tr><td>description</td><td>       si</td><td>DATA</td><td>Alfanumérico</td><td>      40</td><td>Descripción corta de la orden. A este campo se le realiza una validación por expresión regular (<strong>^[\w -]+$</strong>)</td></tr><tr><td>email</td><td>       si</td><td>DATA</td><td>Alfanumérico</td><td>      100</td><td>Correo electrónico del usuario</td></tr><tr><td>timestamp_end</td><td>       si</td><td>DATA</td><td>Alfanumérico</td><td>       10</td><td>Tiempo de finalización de la transacción en formato Unix Timestamp (Segundos) UTC</td></tr><tr><td>min</td><td>     no*</td><td>DATA</td><td>Alfanumérico</td><td>      20</td><td>Monto mínimo a pagar, default 0. * Obligatorio si el monto es 0 (monto abierto).</td></tr><tr><td>max</td><td>     no*</td><td>DATA</td><td>Alfanumérico</td><td>       20</td><td>Monto máximo a pagar, default 999999999. * Obligatorio si el monto es 0 (monto abierto).</td></tr><tr><td>checksum</td><td>       si</td><td>DATA</td><td>Alfanumérico</td><td>      512</td><td>Cadena de comprobación, calculada con SHA512(Revisar apartado de Checksum para conocer como realizar el cálculo correcto)</td></tr></tbody></table>
{% endtab %}

{% tab title="Response (ejemplo)" %}

```
{
  "CODE":"0000", 
  "TEXT":"OK", 
  "DATA":{
     "order":"123456789",
     "amount":"0", 
     "description":"Orden de compra", 
     "email":"example@example.com", 
     "timestamp_end":"1581370646",
     "min":"0",
     "max":"10000", 
     “checksum”:”c07f779252b735c67df2c1945b68ca93f72100ece73dac778964aca...”
  }  
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Los montos mix y max son obligatorios si el monto es 0 (monto abierto).
{% endhint %}

{% hint style="info" %}
Es de suma importancia garantizar un tiempo de respuesta del servicio menor a 5 segundos, de lo contrario, nuestro sistema cerrará la conexión.
{% endhint %}

{% hint style="danger" %}
Es potestad de cada comercio realizar la validación del medio de recaudo, es decir, de rechazar o no la petición de detalles de la orden de compra de acuerdo al medio que se envía.
{% endhint %}

## Checksum

Si los montos min y max  no son enviados, el checksum se calcula sin tener estos campos en cuenta. Los dos escenarios para el cálculo de checksum son:&#x20;

Sin límites: order + amount + timestamp\_end + FIXED\_HASH                                                   &#x20;

Con límites: order + amount + min + max + timestamp\_end + FIXED\_HASH