# Documentação

> Receba cada rodada em JSON segundos depois de fechar na mesa, com histórico e estatísticas prontos, e monte o seu bot, site ou painel sem copiar resultado à mão. Para quem está no Brasil, em Portugal, em Angola ou em qualquer lugar.

Aqui fica o que vale para todas as APIs, como autenticação, teste, limites e erros, e cada API tem a própria página com os endpoints, os parâmetros e o significado de cada campo da resposta.

Source: https://lynxmetrics.com/docs

## APIs

Escolha a API para ver como ela responde. Todas ficam em `https://api.lynxmetrics.com/v1/` seguido do slug da API, e as respostas vêm dentro de `data`, com datas em UTC.

### Cassino ao vivo

- [Bac Bo Live](https://lynxmetrics.com/docs/bacbo-live.md): `/v1/bacbo-live`, No Bac Bo Live, Player e Banker jogam dois dados cada. Resultados, dados e multiplicadores de empate.
- [Lightning Baccarat](https://lynxmetrics.com/docs/lightning-baccarat.md): `/v1/lightning-baccarat`, Rodadas da mesa Lightning Baccarat da Evolution: cartas do Player e do Banker, pontuação, quem ganhou, pares e naturais. Sem os multiplicadores do Lightning.
- [Baccarat 1](https://lynxmetrics.com/docs/baccarat-1.md): `/v1/baccarat-1`, Rodadas da mesa Baccarat 1 da Pragmatic Play: cartas do Player e do Banker, pontuação, quem ganhou, pares e naturais.

## Autenticação

Cada chave vale para uma API só e começa com `sk-lynx`, por isso crie no painel uma chave para cada API que usar e envie no cabeçalho `x-api-key`, trocando `{api}` pelo slug dela. Uma chave de uma API chamando outra recebe `key_wrong_api`. No painel cada chave aparece mascarada, com um botão para copiar quando quiser e outro para rotacionar, que troca a chave por uma nova e faz a antiga parar de responder em instantes.

```bash
curl https://api.lynxmetrics.com/v1/{api}/latest \
  -H "x-api-key: SUA_CHAVE"
```

## Catálogo

`GET /v1/apis` é aberto, sem chave, e lista as APIs com categoria, status, os planos de cada uma com preço e limites e as regras do teste em `trial`, e você pode filtrar com `?category=`.

```json
GET /v1/apis

{
  "data": [
    {
      "slug": "bacbo-live",
      "name": "Bac Bo Live",
      "category": "live-casino",
      "provider": "Evolution",
      "status": "live",
      "description": "No Bac Bo Live, Player e Banker jogam dois dados cada. Resultados, dados e multiplicadores de empate.",
      "plans": [
        {
          "id": "pro",
          "priceCents": 2190,
          "currency": "BRL",
          "maxResults": 250,
          "maxStatsSample": 250,
          "historyDays": 7,
          "requestsPerMinute": 60,
          "maxStreams": 1
        },
        {
          "id": "business",
          "priceCents": 4990,
          "currency": "BRL",
          "maxResults": 1000,
          "maxStatsSample": 1000,
          "historyDays": null,
          "requestsPerMinute": 400,
          "maxStreams": 5
        }
      ],
      "trial": {
        "plan": "pro",
        "durationMinutes": 120,
        "cooldownHours": 24,
        "requiresVerifiedEmail": true,
        "startsOnFirstRequest": true
      }
    }
  ],
  "categories": ["live-casino"]
}
```

## Tempo real

Há três jeitos de receber cada rodada, do mais rápido para o mais simples. Os três entregam o mesmo objeto, então dá para começar pelo mais simples e trocar depois sem mexer no resto do código.

1. O `/stream` de cada API: uma conexão aberta que recebe a rodada no instante em que ela fecha. Só a abertura conta no limite por minuto. É o recomendado para quem roda o dia inteiro.
2. O `/latest?wait=20`: um pedido comum que só responde quando a próxima rodada fecha, ou depois de 20 segundos. É uma requisição por rodada, sem manter conexão aberta, e serve para qualquer linguagem que faça um GET.
3. O `/latest` consultado de tempos em tempos: funciona, mas cada consulta conta no limite por minuto e a rodada chega com o atraso do seu intervalo. Mande o `ETag` em `if-none-match` para receber `304` quando nada mudou.

O código pronto de cada um, em Python, Node.js e PHP, está na documentação de cada API, na seção Exemplos de código. Para saber se uma mesa está entregando rodadas agora, veja a [página de status](https://lynxmetrics.com/status).

## Teste e assinatura

Cada assinatura é uma API com um identificador fixo como `coral-7k2m`, e o teste também. Com o e-mail confirmado, você cria no painel o teste de cada API, que fica numa API de teste e dá uma chave que funciona por `trial.durationMinutes` minutos com os limites de `trial.plan` e depois responde `trial_expired`. Esses minutos começam a contar na primeira chamada da chave, não na hora em que você a criou, então ela espera sem vencer até você integrar. O próximo teste da mesma API fica disponível `trial.cooldownHours` horas depois do fim do anterior, com o mesmo identificador e uma chave nova, e quem já assina aquela API não precisa de teste. Ao assinar a API do teste, ela vira paga com o mesmo identificador e o mesmo uso, e a chave de teste passa a ser uma chave normal do plano, sem prazo, então a integração não muda. Você pode assinar a mesma API quantas vezes quiser, cada assinatura com o seu nome, o seu plano, as suas chaves, o seu limite por minuto e o seu uso, e cada chave funciona enquanto a assinatura dela estiver ativa. Depois que ela é encerrada, as chaves respondem `subscription_required`, e com o pagamento pendente elas seguem por 3 dias enquanto o Stripe tenta cobrar de novo e depois respondem `payment_pending` até o pagamento entrar.

## Limites

Os limites vêm do plano da assinatura a que a chave pertence, ou do plano do teste enquanto a chave de teste vale: o máximo de `limit`, o tamanho de `sample` e até quantos dias para trás `before` pode ir. Um valor acima do máximo é reduzido ao máximo, o uso é contado por assinatura e os números de cada plano estão na documentação de cada API. Cada plano também tem um limite de requisições por minuto, que vale para cada assinatura somando todas as chaves dela, então quem assina a mesma API duas vezes tem dois limites separados, e o teste usa o limite do plano dele. Você pode fazer uma rajada de até esse número de uma vez, e o saldo volta aos poucos ao longo do minuto. Toda resposta de uma chave aceita traz `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset`, que diz em quantos segundos o saldo volta inteiro; os erros que vêm antes do limite, como chave inválida, API errada e assinatura encerrada, não trazem esses cabeçalhos, e quem passa do limite recebe 429 `rate_limited` com `Retry-After`, que diz quantos segundos esperar.

## Erros

Cada erro traz um código que nunca muda e uma mensagem no idioma da sua conta.

```json
{
  "error": {
    "code": "key_wrong_api",
    "message": "Esta chave é de outra API."
  }
}
```

| code | HTTP |  |
| --- | --- | --- |
| `bad_request` | 400 | Um parâmetro veio em formato inválido, como uma data de before que não é ISO 8601. |
| `unauthorized` | 401 | Chave ausente, inválida ou revogada. |
| `key_wrong_api` | 403 | A chave é de outra API. |
| `trial_expired` | 403 | A chave de teste passou do prazo, então assine a API do teste no painel e a mesma chave volta a funcionar. |
| `subscription_required` | 403 | A assinatura a que a chave pertence não está ativa. |
| `payment_pending` | 402 | O pagamento da assinatura a que a chave pertence está pendente há mais de 3 dias. |
| `plan_limit` | 403 | O pedido passa do que o seu plano nesta API permite, como um histórico mais antigo. |
| `not_found` | 404 | Essa API não existe ou ainda não está online. |
| `route_not_found` | 404 | Esse endereço não existe. |
| `rate_limited` | 429 | Foram pedidos demais em pouco tempo, então espere os segundos de Retry-After e tente de novo. |
| `too_many_streams` | 429 | A API está com todas as conexões do /stream ocupadas agora, então tente de novo em instantes. Passar do número de conexões do seu plano não dá este erro: a conexão mais antiga da chave é encerrada e a nova entra no lugar. |
| `internal_error` | 500 | Erro inesperado do nosso lado. |
| `upstream_error` | 502 | Não conseguimos ler os dados agora, tente de novo em instantes. |
| `timeout` | 504 | O pedido levou mais de 10 segundos, tente de novo em instantes. |
