# Integración — Búsqueda de documentos (sistema legacy)

Guía para que el **sistema legacy** consuma la misma búsqueda de documentos que
`GET /api/document/search`, con la misma autenticación interna que el bridge de
webhooks.

---

## Datos de conexión

| Campo | Valor |
|-------|-------|
| **Método** | `GET` |
| **URL** | `https://TU_DOMINIO/internal/document/search` |
| **Header obligatorio** | `X-Internal-Token: <token secreto>` |

> El token es el mismo que el de webhooks (`INTERNAL_WEBHOOK_TOKEN`).
> **No** se genera un token por compañía: un único token sirve para todas. La
> compañía se identifica con el query param `companyId`.

---

## Query parameters

| Campo | Tipo | Obligatorio | Notas |
|-------|------|-------------|-------|
| `companyId` | int | Sí | Id de la compañía |
| `searchBy` | string | Sí | Ver valores permitidos abajo |
| `pattern` | string | No | Texto a buscar |
| `limit` | int | No | Default `20` |
| `cursor` | string | No | Cursor de paginación |
| `direction` | string | No | `next` (default) o `prev` |
| `agency` | int | No | Filtro por agencia |
| `fromDate` | string | No | Fecha inicio (formato de la compañía) |
| `toDate` | string | No | Fecha fin (formato de la compañía) |

### Valores de `searchBy`

| Valor | Busca en |
|-------|----------|
| `packageTracking` | Tracking de paquete (receipt) |
| `packageDescription` | Descripción de paquete |
| `packageNumber` | Número de paquete |
| `warehouseReceiptNumber` | Número de recepción de almacén |
| `shipmentNumber` | Número de guía / shipment |
| `invoiceNumber` | Número de factura |
| `customerInfo` | Información de cliente |

La respuesta (shape y paginación por cursor) es la misma que
`GET /api/document/search`.

---

## Ejemplo (curl)

```bash
curl -G "https://TU_DOMINIO/internal/document/search" \
  -H "X-Internal-Token: $TOKEN" \
  --data-urlencode "companyId=13" \
  --data-urlencode "searchBy=customerInfo" \
  --data-urlencode "pattern=maria" \
  --data-urlencode "limit=10" \
  --data-urlencode "cursor="
```

### Respuesta 200 (ejemplo)

Corresponde al curl de arriba (`searchBy=customerInfo`, `pattern=maria`).
Cada elemento de `data` es un cliente; el tipo de objeto cambia según `searchBy`
(paquetes, warehouse, guías, facturas o clientes).

```json
{
  "data": [
    {
      "id": 8841,
      "name": "Maria",
      "lastname": "Gonzalez",
      "fullName": "Maria Gonzalez",
      "initials": "MG",
      "number": "10452",
      "email": "maria.gonzalez@example.com",
      "active": true,
      "agent": {
        "id": 12,
        "name": "Carlos",
        "lastname": "Perez",
        "email": "carlos.perez@example.com",
        "address": "Calle 1",
        "phone": "555-1000",
        "mobile": "555-2000",
        "zip": "33101",
        "docid": "V-12345678",
        "city": {
          "id": 101,
          "name": "Miami",
          "latitude": 25.7617,
          "longitude": -80.1918,
          "code": "MIA",
          "longFormat": "Miami, Florida (United States)",
          "active": true,
          "state": {
            "id": 10,
            "name": "Florida",
            "code": "FL",
            "country": {
              "id": 1,
              "name": "United States",
              "code": "US"
            }
          }
        },
        "creationdate": "2024-01-15T10:00:00+00:00",
        "contact": null,
        "website": null,
        "limitcustomer": false,
        "active": true,
        "deleted": false
      },
      "agency": {
        "id": 3,
        "name": "Miami Warehouse",
        "email": "miami@example.com",
        "isMaster": true,
        "phone": "555-0100",
        "manager": "Ana Ruiz",
        "city": {
          "id": 101,
          "name": "Miami",
          "latitude": 25.7617,
          "longitude": -80.1918,
          "code": "MIA",
          "longFormat": "Miami, Florida (United States)",
          "active": true,
          "state": {
            "id": 10,
            "name": "Florida",
            "code": "FL",
            "country": {
              "id": 1,
              "name": "United States",
              "code": "US"
            }
          }
        },
        "creationDate": "01/01/2023 12:00:00 PM"
      },
      "creationdate": "03/12/2025 09:30:00 AM",
      "customerType": {
        "id": 1,
        "name": "Person",
        "description": "Individual customer"
      },
      "adrdefault": {
        "id": 550,
        "name": "Maria",
        "lastname": "Gonzalez",
        "fullName": "Maria Gonzalez",
        "address": "1200 Brickell Ave",
        "phone": "555-3000",
        "mobilCode": "+1",
        "mobile": "555-4000",
        "email": "maria.gonzalez@example.com",
        "barrio": null,
        "zip": "33131",
        "docType": "ID",
        "docid": "A1234567",
        "city": {
          "id": 101,
          "name": "Miami",
          "latitude": 25.7617,
          "longitude": -80.1918,
          "code": "MIA",
          "longFormat": "Miami, Florida (United States)",
          "active": true,
          "state": {
            "id": 10,
            "name": "Florida",
            "code": "FL",
            "country": {
              "id": 1,
              "name": "United States",
              "code": "US"
            }
          }
        },
        "zoomCityCode": null,
        "emailAddresses": ["maria.gonzalez@example.com"],
        "default": true,
        "fullAddress": "1200 Brickell Ave, Miami, FL 33131",
        "latitude": 25.7617,
        "longitude": -80.1918
      },
      "groupTariff": {
        "id": 2,
        "name": "Retail",
        "type": "CUSTOMER",
        "creationdate": "01/01/2024 08:00:00 AM",
        "active": true,
        "isDefault": false,
        "tariffsgroup": []
      },
      "location": {
        "id": 8,
        "code": "A-01",
        "description": "Shelf A-01",
        "type": "SHELF",
        "agency": {
          "id": 3,
          "name": "Miami Warehouse",
          "email": "miami@example.com",
          "isMaster": true,
          "phone": "555-0100",
          "manager": "Ana Ruiz",
          "city": null,
          "creationDate": "01/01/2023 12:00:00 PM"
        },
        "creationdate": "01/06/2024",
        "active": true
      },
      "emailAddresses": ["maria.gonzalez@example.com"],
      "poboxId": 220,
      "poboxNumber": "POBOX-10452",
      "documentId": "V-87654321"
    }
  ],
  "pagination": {
    "cursor": null,
    "hasNext": false,
    "hasPrevious": false,
    "itemsPerPage": 10
  }
}
```

---

## Errores

| Código | Causa |
|--------|-------|
| **401** | `X-Internal-Token` ausente o incorrecto |
| **400** | Validación (`companyId`, `searchBy`, fechas, etc.) |