# Company Lookup API

Look up a French company's public information by its SIRET or SIREN number (via INSEE).

---

## Endpoint

```
GET /api/admin/company-lookup
```

## Authentication

- **Method:** Bearer token (Sanctum)
- **Required role:** `superadministrator`
- **Rate limit:** 30 requests per minute

## Query Parameters

Provide **exactly one** of the following (they are mutually exclusive):

| Parameter | Type   | Description                          | Example            |
|-----------|--------|--------------------------------------|--------------------|
| `siret`   | string | 14-digit SIRET number                | `35600000049837`   |
| `siren`   | string | 9-digit SIREN number                 | `356000000`        |

## Responses

### 200 OK - Company found

```json
{
  "status": true,
  "message": "Company info retrieved.",
  "data": {
    "name": "LA POSTE",
    "siren": "356000000",
    "siret": "35600000049837",
    "address": "9 RUE DU COLONEL PIERRE AVIA",
    "postal_code": "75015",
    "city": "PARIS"
  }
}
```

| Field         | Type           | Description                                      |
|---------------|----------------|--------------------------------------------------|
| `name`        | string         | Legal name of the company                        |
| `siren`       | string         | 9-digit SIREN (always present)                   |
| `siret`       | string \| null | 14-digit SIRET (null if lookup was done by SIREN)|
| `address`     | string         | Street address                                   |
| `postal_code` | string         | Postal code                                      |
| `city`        | string         | City name                                        |

### 404 Not Found - Company does not exist

```json
{
  "status": false,
  "message": "Company not found."
}
```

### 422 Unprocessable Entity - Validation error

Returned when the identifier is missing, malformed, or invalid.

```json
{
  "status": false,
  "message": "The given data was invalid.",
  "errors": {
    "siret": [
      "SIRET must contain only digits."
    ]
  }
}
```

Possible validation messages:

| Field   | Error                                              | Cause                        |
|---------|----------------------------------------------------|------------------------------|
| `siret` | SIRET must contain only digits.                    | Non-numeric characters       |
| `siret` | SIRET must be exactly 14 digits (X provided).      | Wrong length                 |
| `siret` | The provided SIRET is invalid.                     | Luhn checksum failure        |
| `siren` | SIREN must contain only digits.                    | Non-numeric characters       |
| `siren` | SIREN must be exactly 9 digits (X provided).       | Wrong length                 |
| `siren` | The provided SIREN is invalid.                     | Luhn checksum failure        |
| both    | The siret field is required when siren is not present. | Neither field provided    |
| both    | The siret field prohibits siren from being present.    | Both fields provided     |

### 503 Service Unavailable - Upstream service down

```json
{
  "status": false,
  "message": "Company lookup service is temporarily unavailable."
}
```

This is a transient error. The client should retry after a short delay.

### 401 Unauthorized

Returned if the bearer token is missing or invalid.

### 403 Forbidden

Returned if the authenticated user does not have the `superadministrator` role.

### 429 Too Many Requests

Returned if the rate limit (30 req/min) is exceeded.

---

## Example Requests

### Lookup by SIRET

```bash
curl -X GET "https://{host}/api/admin/company-lookup?siret=35600000049837" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
```

### Lookup by SIREN

```bash
curl -X GET "https://{host}/api/admin/company-lookup?siren=356000000" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
```

---

## Notes

- Results are cached server-side. Subsequent lookups for the same identifier return faster.
- The `siret` field in the response will be `null` when the lookup was performed by SIREN (since a SIREN maps to the legal entity, not a specific establishment).
- Both SIRET and SIREN are validated using the Luhn algorithm before hitting the upstream service.