> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ephra.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Início rápido

> Crie uma chave de API, troque por um token, faça a primeira chamada e receba um webhook de teste em menos de 10 minutos.

Em quatro passos você sai de uma conta Ephra sem integração para uma chamada respondendo `200` e um webhook de teste chegando no seu servidor.

> [!NOTE]
>
> A URL base é `https://api.ephra.io`. Não existe sandbox: as chamadas atingem a sua empresa de verdade. Comece por rotas de leitura (`GET`) e veja [Como testar](https://docs.ephra.io/comece-aqui/como-testar.md) antes de escrever.

**1. Crie a chave de API**

No painel, abra **Integrações › Chaves de API** ([app.ephra.io/painel/chaves-api](https://app.ephra.io/painel/chaves-api)), clique em **Nova chave** e dê um nome que identifique o sistema, como `ERP da loja`.

![Tela Integrações › Chaves de API](https://mintcdn.com/ephraio-2770e271/j9pHfIg8y1UXAJx2/images/guias/chaves-api.png?fit=max\&auto=format\&n=j9pHfIg8y1UXAJx2\&q=85\&s=3e0836d3f9bdf20e2544d57ffaaa2d26)

Integrações › Chaves de API

A tela mostra dois valores: o **público** e o **secreto**.

> [!WARNING]
>
> O valor secreto aparece **uma única vez**. Copie para um cofre de segredos antes de fechar a tela. Se perder, revogue a chave e gere outra.

```bash theme={"system"}
export EPHRA_KEY="cmtxzjidu0000isg1f7pzbisr"
export EPHRA_SECRET="992a7d55bccbf39adfe6bec6259297a9..."
```

**2. Troque a chave por um token**

A chave serve só para pedir um token em `POST /auth`, com **HTTP Basic**: o valor público como usuário e o secreto como senha. A rota não tem corpo.

```bash cURL theme={"system"}
export TOKEN=$(curl -s -X POST https://api.ephra.io/auth \
  -u "$EPHRA_KEY:$EPHRA_SECRET" | jq -r .token)
```

```javascript Node theme={"system"}
const basic = Buffer.from(`${process.env.EPHRA_KEY}:${process.env.EPHRA_SECRET}`).toString("base64");
const res = await fetch("https://api.ephra.io/auth", {
  method: "POST",
  headers: { Authorization: `Basic ${basic}` },
});
const { token } = await res.json();
```

```python Python theme={"system"}
import os, requests

res = requests.post(
    "https://api.ephra.io/auth",
    auth=(os.environ["EPHRA_KEY"], os.environ["EPHRA_SECRET"]),
)
token = res.json()["token"]
```

```json theme={"system"}
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 60000
}
```

> [!WARNING]
>
> **O token dura 60 segundos.** `expiresIn` vem em milissegundos. Peça um token novo ao iniciar cada sequência de chamadas e refaça o `POST /auth` quando receber `401`.

**3. Faça a primeira chamada**

O mesmo token vale nas duas APIs da Ephra (veja [Qual API usar](https://docs.ephra.io/comece-aqui/qual-api-usar.md)). Comece pelo cadastro da sua empresa, que é leitura pura:

```bash cURL theme={"system"}
curl -s https://api.ephra.io/v1/company \
  -H "Authorization: Bearer $TOKEN"
```

```javascript Node theme={"system"}
const res = await fetch("https://api.ephra.io/v1/company", {
  headers: { Authorization: `Bearer ${token}` },
});
const { data } = await res.json();
```

```python Python theme={"system"}
res = requests.get(
    "https://api.ephra.io/v1/company",
    headers={"Authorization": f"Bearer {token}"},
)
data = res.json()["data"]
```

```json theme={"system"}
{
  "success": true,
  "data": {
    "id": "cmtxx1uar0001hlg1u3ajbj6o",
    "name": "Doce Ofício Confeitaria Digital LTDA",
    "status": "active",
    "isBlocked": false
  }
}
```

`status: "active"` com `isBlocked: false` é a combinação que vende.

**4. Receba um webhook de teste**

Cadastre o endpoint que vai receber os eventos. A Ephra testa a URL com um `POST` na hora do cadastro, então ela já precisa responder `2xx`. Durante o desenvolvimento, um túnel como o ngrok resolve.

```bash cURL theme={"system"}
curl -s -X POST https://api.ephra.io/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seusite.com/webhooks/ephra",
    "events": ["transaction_paid", "release_access"],
    "name": "Minha integração"
  }'
```

```javascript Node theme={"system"}
const res = await fetch("https://api.ephra.io/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "url": "https://seusite.com/webhooks/ephra",
    "events": [
      "transaction_paid",
      "release_access"
    ],
    "name": "Minha integração"
  }),
});
const json = await res.json();
```

```python Python theme={"system"}
import requests

res = requests.post(
    "https://api.ephra.io/v1/webhooks",
    headers={
        "Authorization": f"Bearer {token}",
    },
    json={
        "url": "https://seusite.com/webhooks/ephra",
        "events": [
            "transaction_paid",
            "release_access"
        ],
        "name": "Minha integração"
    },
)
data = res.json()
```

Com o `data.id` da resposta, dispare um evento de teste:

```bash cURL theme={"system"}
curl -s -X POST https://api.ephra.io/v1/webhooks/31/test \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"events": ["transaction_paid"]}'
```

```javascript Node theme={"system"}
const res = await fetch("https://api.ephra.io/v1/webhooks/31/test", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "events": [
      "transaction_paid"
    ]
  }),
});
const json = await res.json();
```

```python Python theme={"system"}
import requests

res = requests.post(
    "https://api.ephra.io/v1/webhooks/31/test",
    headers={
        "Authorization": f"Bearer {token}",
    },
    json={
        "events": [
            "transaction_paid"
        ]
    },
)
data = res.json()
```

O seu endpoint recebe um `transaction_paid` completo, com `scope: "test"`. Descarte eventos de teste antes de liberar qualquer pedido.

## Quando o `401` aparecer

> [accordion] Token inválido ou expirado
>
> ```json theme={"system"}
> {
>   "success": false,
>   "message": "Token inválido ou expirado"
> }
> ```
>
> Passou dos 60 segundos ou a sessão foi encerrada. Refaça o `POST /auth` e repita a chamada, no máximo uma vez.

> [accordion] Credenciais inválidas no POST /auth
>
> ```json theme={"system"}
> {
>   "success": false,
>   "message": "Credenciais inválidas."
> }
> ```
>
> O valor público existe, mas o secreto não confere. Quase sempre é um segredo cortado na cópia.
>
> ```json theme={"system"}
> {
>   "success": false,
>   "message": "API key não encontrada"
> }
> ```
>
> O valor público não existe ou a chave foi revogada. Gere outra em **Integrações › Chaves de API**.

> [accordion] Mandou a chave no corpo
>
> `POST /auth` não tem corpo. As credenciais vão no header `Authorization: Basic`, que o `-u` do `curl` monta para você.

## Para onde ir agora

> [card] [Liberar acesso depois da venda](https://docs.ephra.io/receitas/liberar-acesso.md)
>
> O fluxo que toda integração de infoproduto precisa.

> [card] [Sincronizar vendas](https://docs.ephra.io/receitas/sincronizar-vendas.md)
>
> Leve as vendas para o seu ERP ou planilha.

> [card] [Tratar reembolso](https://docs.ephra.io/receitas/tratar-reembolso.md)
>
> Receba o pedido e aprove ou recuse pela API.

> [card] [Servidor MCP](https://docs.ephra.io/guias/mcp.md)
>
> Dê a API inteira para um agente de IA operar.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.