# Conexión a ERP

<!-- Fuente: https://docs.efipay.co/documentation-erp -->

- [Recauda ERP](#recauda)
  - [Recauda Información](#information)
  - [Recauda Opciones Avanzadas](#information)

Con recauda erp podrás proporcionar un endpoint de tipo get por el cual consultaremos la información de pagos que desees realizar a un cliente a partir de un número de identificación, de tal manera que cada vez que tu cliente ingrese al portal de recaudo e ingrese su número de identificación, nosotros consultaremos el endpoint proporcionado y poder mostrarle los pagos pendientes.
 
---

## Documentación de la Estructura de Datos

| Método | Uri | Query Params |
| -- | -- | -- |
| Get| https://your.domain.com/... | id_number |

## ejemplo
```http
Get https://your.domain.com/get-recaudas?id_number=12345678
```

Al realizar el consumo del api, se espera el body en formato json y con un array de objetos "payments".

Nota: Se recomienda llevar seguimiento de los recauda pendientes enviados para no volver a enviarlos y así hacer mas rápida la consulta.

## Estructura del body

El body es un objeto con un único campo `payments`, un array donde cada elemento
es un recaudo. Cada recaudo tiene dos objetos: `recauda_information` (el cobro) y
`advanced_options` (opcional, todo lo demás).

| Campo | Tipo | Descripción |
| - | - | - |
| `payments` | array, requerido | Array de objetos con los recauda a ser consultados |
| `payments[].recauda_information` | object, requerido | Información del cobro de cada recauda |
| `payments[].advanced_options` | object, opcional | Opciones adicionales del cobro |

### `recauda_information`

| Campo | Tipo | Descripción |
| - | - | - |
| `description` | string, requerido, min:4, max:191 | Descripción de la recaudación |
| `amount` | string, requerido, min:4, max:191 | Monto de la recaudación |
| `currency_type` | string, requerido, enum: `COP`, `USD`, `EUR` | Tipo de moneda del monto |
| `id_number` | string numérico, min_dígitos:5 | Número de identificación del cliente |
| `payer_name` | string, requerido, min:5, max:191 | Nombre del pagador |
| `ref_payment` | string, requerido, único | Referencia de pago. Debe ser único: es lo que usamos para no duplicar los recauda |
| `expiration_date` | fecha `yyyy-mm-dd`, opcional | Fecha de expiración, informativa para el cliente. Se sigue mostrando y se permite pagar aunque ya esté vencida |
| `advance` | object, opcional | Indica si el recaudo permite adelantos |
| `advance.type` | string, enum: `Valor Minimo`, `Porcentaje Minimo` | Tipo de adelanto |
| `advance.value` | número, requerido | Monto mínimo permitido para el adelanto |
| `metadata` | array, opcional | Data adicional que el comercio requiera |

### `advanced_options`

| Campo | Tipo | Descripción |
| - | - | - |
| `picture` | string, opcional, max:250 | Imagen relacionada |
| `limit_date` | fecha `Y-m-d`, opcional, igual o mayor a hoy | Fecha límite para pagar. Solo se muestra y se permite el pago si la fecha es mayor a la fecha de consulta del recaudo |
| `references` | array, opcional, max:3 | Contenedor de las referencias |
| `references[]` | string, requerido, max:50 | Referencias a agregar |
| `result_urls` | object, opcional | Contenedor para las url de respuesta |
| `result_urls.webhook` | string url, requerido | Url para recibir actualizaciones vía webhook |
| `delivery_service` | object, opcional | Indica si tiene servicio a domicilio |
| `delivery_service.type` | enum: `Gratis`, `Con Valor`, requerido | Tipo de entrega |
| `delivery_service.value` | decimal:2 | Valor de la entrega |
| `request_address_delivery` | bool, opcional | Indica si se solicita la dirección de entrega |
| `discount` | object, opcional | Indica si se aplica algún descuento al pago |
| `discount.before_on` | fecha `Y-m-d`, igual o posterior a hoy | Fecha máxima para aplicar el descuento |
| `discount.type` | enum: `Porcentaje`, `Valor` | Tipo de descuento a aplicar |
| `discount.value` | decimal:2 | Valor del descuento a aplicar |
| `cash_expired_period` | integer, nullable, min:1, max:60 | Customiza el tiempo de expiración de un cupón en efectivo. Requiere `cash_expired_interval`. Solo aplica al pago de una factura |
| `cash_expired_interval` | enum: `minute`, `hour`, `day`, `week`, `month`, `year`, nullable | Unidad del tiempo de expiración del cupón en efectivo. Requiere `cash_expired_period`. Solo aplica al pago de una factura |
| `has_comments` | bool, requerido | Indica si permite comentarios |
| `comments_label` | string, opcional, max:100 | Personaliza el campo para adicionar comentarios |

---

#### Ejemplo de body esperado

---

```json
{
    "payments": [
        {
            "recauda_information": {
                "description": "prueba fill out all",
                "amount": 20000,
                "selected_taxes": null,
                "currency_type": "COP",
                "id_number": "12345678",
                "payer_name": "efipay",
                "ref_payment": "1234567",
                "advance": {
                    "type": "Valor Minimo",
                    "value": 5000
                },
                "metadata": {
                    "data": "Your additional data here"
                }
            },
            "advanced_options": {
                "picture": "https://efipay.co/images/logo.svg",
                "limit_date": "2025-03-15",
                "references": [
                    "123456",
                    "323432",
                    "6546456"
                ],
                "result_urls": {
                    "webhook": "https://webhook-test.com/310b715b9704556033c7fe260915cdfd"
                },
                "delivery_service": {
                    "type": "Con Valor",
                    "value": 5000
                },
                "has_comments": false,
                "comments_label": "Deja tus comentarios"
            }
        },
        {
            "recauda_information": {
                "description": "prueba fill out recauda only",
                "amount": 20000,
                "selected_taxes": null,
                "currency_type": "COP",
                "id_number": "12345678",
                "payer_name": "efipay",
                "ref_payment": "7654321",
                "advance": {
                    "type": "Valor Minimo",
                    "value": 5000
                }
            },
            "advanced_options": null
        },
        {
            "recauda_information": {
                "description": "prueba fill out errors",
                "amount": 20000,
                "selected_taxes": null,
                "currency_type": "COP",
                "id_number": "12345678",
                "payer_name": "efipay",
                "ref_payment": "7654322",
                "advance": {
                    "type": "Valor Minimo",
                    "value": 5000
                }
            },
            "advanced_options": null
        }
    ]
}
```

#### Ejemplo webhook
El webhook se usará para notificar la trx creada y el valor abonado.

La respuesta se compone de la transacción, con el monto pagado y el estado de la transacción.
Adicionalmente el checkout tiene información importante sobre la información del recauda configurado, y el abono realizado.

Ten en cuenta que el monto de la trx puede no corresponder al del recauda configurado, ya que en una sola transacción se pueden pagar diferentes facturas de recauda.

Para identificar la trx puedes basarte en la referencia de pago que puedes ubicar `checkout.payment_referenceable.ref_payment`

Si la transacción se encuentra Aprobada puedes agregar el monto abonado en esta transacción el cual lo ubicas en `checkout.paid_advance.amount_paid`

---

Ejemplo del body:

---

```json
{
  "transaction": {
    "transaction_id": 758,
    "amount": 100000,
    "currency_type": "COP",
    "value_cop": 100000,
    "payment_method": "pse",
    "payment_method_source": "BANCO BANK",
    "trazability_id": "UGdRx2g4AH",
    "authorization_code": "UGdRx2g4AH",
    "reference_1": "example@email.com",
    "reference_2": "1772557680767",
    "reference_3": "Recauda : 2referencias a pagar",
    "transaction_details": {
      "name": "dsfasd fas",
      "user_type": "person",
      "identification_type": "CedulaDeCiudadania",
      "identification_number": "424342432",
      "email": "example@email.com",
      "country": "+57",
      "phone": "3001234567",
      "address": "address",
      "bank": "BANCO BANK",
      "status_message": "Test mock"
    },
    "status": "Aprobada",
    "url_response": "https://efipay-sag.test/Checkout/Transaction/019cb4ab-c080-72fa-b029-19841fe1d7c7/Response",
    "approved_at": "2026-03-03T17:08:54.285461Z",
    "production": true,
    "created_at": "2026-03-03 12:08:00",
    "customer_payer": {
      "id": "9d549c89-5633-439c-ba42-f2f275d21636",
      "name": "dsfasd fas",
      "email": "example@email.com",
      "identification_type": "CC",
      "id_number": "123456789",
      "dialling_code": "+57",
      "cellphone": "3001234567",
      "country": "COL",
      "zip_code": "0000",
      "state": "Bogotá",
      "city": "Bogota",
      "address_2": "Apto",
      "address_1": "Calle 32 32",
      "created_at": "2024-10-25 04:41:30",
      "updated_at": "2026-03-03 12:08:54"
    },
    "currency_rate_conversion": {
      "id": 3,
      "usd_to_cop": 4192.65,
      "eur_to_cop": 4692.573296,
      "trm_for_cop": 1,
      "active": 1,
      "created_at": "2025-05-15T09:24:57.000000Z",
      "updated_at": "2025-05-15T09:24:57.000000Z",
      "deleted_at": null
    },
    "description": "Test mock"
  },
  "checkout": {
    "id": "019cb4aa-27ac-7079-bade-b21dcc0fcb72",
    "payment_referenceable_type": "App\\Models\\CollectionTools\\Recauda\\Recauda",
    "payment_referenceable_id": "019cb4a9-a206-7375-a57a-1a2305cf0dd4",
    "payment_gateway_id": "019cb4a9-a224-708a-9c9b-90718973fb3d",
    "delivery_address_id": null,
    "commerce_id": 1,
    "office_id": 1,
    "comments": null,
    "total_advance": 0,
    "paid_at": null,
    "ongoing_transaction": 0,
    "customer_payer_id": "9d549c89-5633-439c-ba42-f2f275d21636",
    "created_at": "2026-03-03 12:06:16",
    "updated_at": "2026-03-03 12:08:54",
    "total_pending": 50000,
    "pivot": {
      "transaction_id": "019cb4ab-c080-72fa-b029-19841fe1d7c7",
      "checkout_gateway_id": "019cb4aa-27ac-7079-bade-b21dcc0fcb72"
    },
    "payment_gateway": {
      "id": "019cb4a9-a224-708a-9c9b-90718973fb3d",
      "gatewayable_type": "App\\Models\\CollectionTools\\Recauda\\Recauda",
      "gatewayable_id": "019cb4a9-a206-7375-a57a-1a2305cf0dd4",
      "advanced_option_id": "019cb4a9-a21d-7241-8684-0c08b1cfcf49",
      "created_user_id": 11,
      "updated_user_id": 11,
      "office_id": 1,
      "commerce_id": 1,
      "massive_upload_id": null,
      "url": "https://efipay-sag.test/Checkout/Recauda/1/c4ca4238a0b923820dcc509a6f75849b",
      "full_payment_at": "2026-03-03 12:08:54",
      "active": 1,
      "production": 1,
      "expired_at": null,
      "checkout_template_id": null,
      "created_at": "2026-03-03 12:05:41",
      "updated_at": "2026-03-03 12:08:54",
      "deleted_at": null,
      "sub_total": 50000,
      "amount_without_tax": 50000,
      "tax_amount": null,
      "total": 50000,
      "total_cop": 50000,
      "tool_name": "Recauda",
      "purchase_detail": {},
      "advanced_option": {},
      "gatewayable": {}
    },
    "payment_referenceable": {
      "id": "019cb4a9-a206-7375-a57a-1a2305cf0dd4",
      "description": "Prueba 1",
      "amount": 50000,
      "tax": null,
      "currency_type": {
        "name": "Peso Colombiano",
        "symbol": "$",
        "abbreviation": "COP"
      },
      "id_number": "12345679",
      "payer_name": "Efipay prueba",
      "advance_type": null,
      "advance_value": null,
      "metadata": null,
      "ref_payment": null,
      "expiration_date": null,
      "email": null,
      "cellphone": null,
      "created_at": "2026-03-03 12:05:41",
      "updated_at": "2026-03-03 12:05:41",
      "deleted_at": null,
      "total": 50000,
      "include_tax": false,
      "has_advance": false,
      "advance": {
        "type": null,
        "value": null
      },
      "url_bill": null,
      "tax_amount": 0
    },
    "paid_advance": {
      "id": "019cb4aa-284c-702e-b311-1c76e7382a61",
      "description": "Prueba 1",
      "amount_paid": 50000,
      "amount_currency": {
        "name": "Peso Colombiano",
        "symbol": "$",
        "abbreviation": "COP"
      },
      "exchange_paid": 50000,
      "exchange_currency": "COP",
      "tool_paid": true,
      "checkout_gateway_id": "019cb4aa-27ac-7079-bade-b21dcc0fcb72",
      "transaction_id": "019cb4aa-27e0-7080-85a2-4c4ad71fcdcf",
      "created_at": "2026-03-03 12:06:16",
      "updated_at": "2026-03-03 12:06:16",
      "deleted_at": null
    },
    "answer_form": null
  }
}
```

### Consulta de una factura recauda
`GET /api/v1/payment/recauda`

Envía **uno de los dos** identificadores; si no envías ninguno, la petición se rechaza.

| Nombre del campo | Descripción | Reglas |
| - | - | - |
| payment_gateway_id | Id del cobro generado para la factura | `['required_without:ref_payment', 'nullable', 'string', 'uuid']` |
| ref_payment | La referencia que le asignaste a la factura | `['required_without:payment_gateway_id', 'nullable', 'string', 'max:191']` |

`GET /api/v1/payment/recauda`

Cuerpo de ejemplo:

```json
{
    "ref_payment": "FACT-00123"
  }
```

```bash
curl -X GET \
'/api/v1/payment/recauda?ref_payment=FACT-00123' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json"
```

:::danger
No existe una factura con ese id o esa referencia en tu comercio
:::

Código de respuesta: 404

```json
{
    "message": "Recauda or payment gateway not found."
}
```

**Respuesta exitosa:**

```json
{
    "payment_gateway": {
        "id": "019cb4aa-f88c-7217-8a64-bc8bb0491cc1",
        "tool_name": "Recauda",
        "active": 1,
        "production": 1,
        "full_payment_at": "2026-03-03 12:08:54",
        "url": "https://efipay-sag.test/Checkout/Recauda/1/c4ca4238a0b923820dcc509a6f75849b",
        "created_at": "2026-03-03 12:07:09",
        "updated_at": "2026-03-03 12:08:54"
    },
    "recauda": {
        "id": "019cb4aa-f87a-70a1-a98f-ce9e1fe90dbb",
        "description": "prueba 2",
        "amount": 50000,
        "tax": null,
        "currency_type": {
            "name": "Peso Colombiano",
            "symbol": "$",
            "abbreviation": "COP"
        },
        "id_number": "123456789",
        "payer_name": "efipay",
        "ref_payment": "100",
        "expiration_date": null,
        "total": 50000,
        "include_tax": false,
        "has_advance": false,
        "created_at": "2026-03-03 12:07:09",
        "updated_at": "2026-03-03 12:07:09",
        "metadata": null
    },
    "summary": {
        "amount": 50000,
        "amount_cop": 50000,
        "amount_paid": 50000,
        "totalmente_pagado": "2026-03-03 12:08:54"
    },
    "checkout_gateway": {
        "id": "019cb4ab-c066-71d8-a5dd-1b8c0cb5328a",
        "total_advance": 50000,
        "total_pending": 0,
        "paid_at": "2026-03-03 12:08:54",
        "ongoing_transaction": 0,
        "comments": null,
        "created_at": "2026-03-03 12:08:00",
        "updated_at": "2026-03-03 12:08:54",
        "transactions": [
            {
                "transaction_id": 758,
                "amount": 100000,
                "currency_type": "COP",
                "value_cop": 100000,
                "payment_method": "pse",
                "payment_method_source": "BANCO CAJA SOCIAL",
                "trazability_id": "UGdRx2g4AH",
                "authorization_code": "UGdRx2g4AH",
                "reference_1": "example@email.com",
                "reference_2": "1772557680767",
                "reference_3": "Recauda : 2referencias a pagar",
                "transaction_details": {
                    "name": "dsfasd fas",
                    "user_type": "person",
                    "identification_type": "CedulaDeCiudadania",
                    "identification_number": "123456789",
                    "email": "exmaple@email.com",
                    "country": "+57",
                    "phone": "3001234567",
                    "address": "Calle 32 # 465 - 14",
                    "bank": "BANCO CAJA SOCIAL",
                    "status_message": "Test mock"
                },
                "status": "Aprobada",
                "url_response": "https://efipay-sag.test/Checkout/Transaction/019cb4ab-c080-72fa-b029-19841fe1d7c7/Response",
                "approved_at": "2026-03-03 12:08:54",
                "production": true,
                "created_at": "2026-03-03 12:08:00",
                "customer_payer": {
                    "id": "9d549c89-5633-439c-ba42-f2f275d21636",
                    "name": "dsfasd fas",
                    "email": "example@email.com",
                    "identification_type": "CC",
                    "id_number": "123456789",
                    "dialling_code": "+57",
                    "cellphone": "3001234567",
                    "country": "COL",
                    "zip_code": "0000",
                    "state": "Bogotá",
                    "city": "Bogota",
                    "address_2": "Apto",
                    "address_1": "Calle 32 32",
                    "created_at": "2024-10-25 04:41:30",
                    "updated_at": "2026-03-03 12:08:54"
                },
                "currency_rate_conversion": {
                    "id": 3,
                    "usd_to_cop": 4192.65,
                    "eur_to_cop": 4692.573296,
                    "trm_for_cop": 1,
                    "active": 1,
                    "created_at": "2025-05-15T09:24:57.000000Z",
                    "updated_at": "2025-05-15T09:24:57.000000Z",
                    "deleted_at": null
                },
                "description": "Test mock"
            }
        ]
    }
}
```

Posibles errores:
404: not found