# kartesim supplier protocol

kartesim buys SMS codes from SIM farms over the standard supplier protocol most
farms already speak. You answer our calls for stock and numbers, push us the
SMS, and earn your price for every code that arrives.

Web version, with the live country and service codes: https://www.kartesim.com/docs/suppliers

## How a sale goes

1. Every minute we ask your server what it has (`GET_COUNT`).
2. When a buyer needs a number and your price is at or under our cap, we ask you for one (`GET_NUMBER`).
3. You send every SMS that number gets to our push address.
4. We close the order (`FINISH_ACTIVATION`): status 3 means a code arrived and we owe you your price.

## Join

Apply at https://www.kartesim.com/become-a-supplier with your account. After
we approve, the same login opens your supplier portal
(https://www.kartesim.com/supplier/connection), where you set your endpoint
address and the key we send with every call, and copy your push key.
Your endpoint must be a public https address that answers within 8 seconds.

## Connection test

One run from the portal; nothing is sold during it:

1. We send `GET_COUNT`; you need at least one country and service we know.
2. We send `GET_NUMBER` for your best-stocked pair.
3. Within 15 minutes, push us an SMS on that number containing the 6-digit code the portal shows.
4. We send `FINISH_ACTIVATION` with status `5` (nothing owed) and expect `SUCCESS`.

When the run passes, we switch you on.

## Calls we send to your endpoint

`POST <your endpoint>`, JSON body, always with `key` (the key you set in the
portal). Answer HTTP 200 with JSON.

### GET_COUNT (every minute)

```json
{ "action": "GET_COUNT", "key": "your-endpoint-key" }
```

```json
{ "status": "SUCCESS", "countMap": { "england": { "any": { "wa": { "SMS": 12 }, "tg": { "SMS": 4 } } } } }
```

Operators are added up. Countries and services we do not know are ignored.

### GET_NUMBER

```json
{ "action": "GET_NUMBER", "key": "your-endpoint-key", "country": "england", "service": "wa",
  "operator": "any", "sum": 0.12, "currency": 840, "exceptionPhoneSet": [] }
```

`sum` is what we pay you in USD if a code arrives. Never give a number listed
in `exceptionPhoneSet`.

```json
{ "status": "SUCCESS", "number": 447700900123, "activationId": 123456 }
```

or `{ "status": "NO_NUMBERS" }`.

### FINISH_ACTIVATION

```json
{ "action": "FINISH_ACTIVATION", "key": "your-endpoint-key", "activationId": 123456, "status": 3 }
```

- `3`: sold. A code arrived and we owe you `sum`.
- `5`: cancelled or expired with no code. Nothing is owed.
- `1`: we could not use the number (already used for this service, for example). Nothing is owed.

Answer `{ "status": "SUCCESS" }`.

## SMS push

For every SMS on a number we took:

```bash
curl -X POST https://www.kartesim.com/api/supply/sms \
  -H "Content-Type: application/json" \
  -d '{"key":"your-push-key","phone":447700900123,"phoneFrom":"WhatsApp","text":"Your code is 123-456","smsId":"sms-98765"}'
```

We answer `{ "status": "SUCCESS" }`. On any other answer, try again. Send
`smsId` so a retry is never counted twice.

## Price API

`POST https://www.kartesim.com/api/supply/prices` with your push key:

```json
{ "key": "your-push-key", "action": "GET_PRICES" }
{ "key": "your-push-key", "action": "SET_PRICE", "country": "england", "service": "wa", "price": 0.12 }
```

`"price": null` goes back to the default; `"enabled": false` stops selling a
pair. You can also set prices on the Prices page of your portal.

## Money

- You earn your price for each order where a code arrived (status 3).
- New earnings are held for 3 days in case a sale is disputed.
- Withdraw in USDT (TRC20) from 50 USD, with a small fee per payout (shown in
  your portal). You can also move earnings to your buyer wallet for free.
- We only send an order when your price is at or under our cap. Farms whose
  codes rarely arrive get fewer orders until they improve.

Questions: support@kartesim.com