# Start a consent

`POST /businesses/{bid}/ita/connect`

Requires the `businesses` scope.

Returns an address for the business's OWNER to open. Live, it is the רשות המסים consent page: he signs in there with his own credentials and authorizes BillOS to request allocation numbers for his business. In the sandbox it is a simulated consent page and nothing reaches the authority.

Afterwards his browser lands on `returnUrl` with `ita` (`connected`, `denied` or `error`), `business`, your `state`, and on a failure `reason`. Treat that query as a hint and confirm with `GET /businesses/{bid}/ita` or the `ita.connected` webhook.

`returnUrl` is not registered ahead: it must be https (http to localhost in the sandbox), carry no credentials or fragment, and not already use the names BillOS adds. Owner only; the business must be approved and not paused.

## Path parameters

| Name | Type | | Description |
|---|---|---|---|
| `bid` | string | **required** | Business id, from `POST /businesses`. |

## Body

| Field | Type | | Description |
|---|---|---|---|
| `returnUrl` | string | **required** | Where the owner lands after the consent. Up to 512 characters. |
| `state` | string |  | Your own value, echoed back on `returnUrl`. Printable ASCII, no spaces, up to 128 characters. Use it to tie the return to your user's session. |
| `link` | boolean |  | True for an address to SEND the owner (by email or WhatsApp), good for 24 hours. Default: 15 minutes, for a user who is in front of your screen now. |

## Response

`201`: `{ "ok": true, … }`

| Field | Type | | Description |
|---|---|---|---|
| `ok` | boolean | **required** |  |
| `url` | string | **required** | The address the owner opens. |
| `expiresAt` | string | **required** | After this the address no longer works: start a new one. |
| `sandbox` | boolean | **required** |  |

Errors: `400`, `401`, `403`, `404`, `429`, `503`. Every failure answers `{ "error", "reason", "hint", "param", "doc_url", "retryable", "request_id" }`: branch on `reason`, and read `hint` for what to change (https://docs.billos.co.il/errors.md).

## Examples

### cURL

```bash
curl -X POST "$BASE/businesses/$BID/ita/connect" \
  -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "returnUrl": "string"
  }'
```
### Node

```node
const res = await fetch(`${BASE}/businesses/${BID}/ita/connect`, {
  method: 'POST',
  headers: {
    'X-Api-Key': KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "returnUrl": "string"
  }),
})
const data = await res.json()
if (!data.ok) throw new Error(data.reason)
```
### Python

```python
import requests
res = requests.post(
    f"{BASE}/businesses/{BID}/ita/connect",
    headers={"X-Api-Key": KEY},
    json={
      "returnUrl": "string"
    },
)
data = res.json()
```