Primeiros passos

Em cinco minutos você sai de uma conta Ephra vazia para uma chamada autenticada respondendo 200. São três passos: criar a chave no painel, trocá-la por um token e usar o token.

O que você vai precisar

Uma conta de vendedor na Ephra, com acesso ao painel em app.ephra.io.
curl e jq no terminal (qualquer cliente HTTP serve — os exemplos usam curl).

A URL base de produção é https://api.ephra.io. Não existe ambiente de sandbox público: as chamadas atingem a sua empresa de verdade. Comece por rotas de leitura (GET).

Passo 1 — Crie a chave de API

Abra o painel

Entre em app.ephra.io e vá em Dashboard › Chaves de API (/dashboard/api-keys).

Gere a chave

Clique em Nova chave, dê um nome que identifique o sistema que vai usá-la (por exemplo, ERP da loja) e confirme.

Guarde o par de credenciais

A tela mostra dois valores: o público (api_token) e o secreto (api_secret).

O valor secreto aparece uma única vez. Copie-o para um cofre de segredos antes de fechar a tela. Se perder, revogue a chave e gere outra.

Exporte os dois no seu terminal para os próximos passos:

export EPHRA_KEY="cmtxzjidu0000isg1f7pzbisr"
export EPHRA_SECRET="992a7d55bccbf39adfe6bec6259297a9..."

Você pode conferir as chaves ativas da empresa pela própria API, em GET /v1/api-keys. A resposta traz o publicKey, se a chave está active e quando foi criada — o segredo nunca volta.

Passo 2 — Troque a chave por um token

A chave de API não autentica as rotas /v1/* diretamente. Ela serve para uma coisa só: pedir um token em POST /auth, usando HTTP Basic — o valor público como usuário, o secreto como senha.

curl -s -X POST https://api.ephra.io/auth \
  -u "$EPHRA_KEY:$EPHRA_SECRET"

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 60000
}

Guarde o token numa variável:

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

O token dura 60 segundos em produção. O campo expiresIn vem em milissegundos: 60000. Não guarde o token em cache por horas nem o distribua entre processos — peça um novo sempre que for iniciar uma sequência de chamadas, e refaça o POST /auth quando receber 401.

O motivo de o token ser tão curto é o mesmo de qualquer credencial de portador: quem tiver o token tem a empresa. Um minuto de janela transforma um vazamento em quase nada. A chave de API, essa sim, é de longo prazo — e por isso nunca sai do seu servidor.

Passo 3 — Faça a primeira chamada

Com o token na mão, qualquer rota /v1/* aceita o header Authorization: Bearer. Comece pelo saldo, que é leitura pura:

curl -s https://api.ephra.io/v1/balance \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "data": {
    "available": 83470,
    "receivable": 0,
    "reserved": 0
  }
}

Os três campos são inteiros em centavos: available é o que dá para sacar agora, receivable o que ainda vai liberar e reserved o que está retido. 83470 é R$ 834,70. Dinheiro nunca aparece como ponto flutuante nesta API. Agora liste os seus produtos:

curl -s "https://api.ephra.io/v1/products?page=1&pageSize=2" \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "data": [
    {
      "id": "cmtxxggxb0000vyg19j6v7qja",
      "name": "Curso de Tráfego Pago",
      "description": "Do primeiro anúncio ao primeiro real faturado.",
      "status": "approved",
      "categoryId": 1,
      "price": 49900,
      "productType": "digital",
      "billingType": "one_time",
      "deliveryType": "link",
      "imageUrl": null,
      "salesPage": "https://exemplo.com.br/trafego-pago",
      "productorName": null,
      "supportEmail": "suporte@exemplo.com.br",
      "supportPhone": null,
      "refundPeriodDays": 7,
      "createdAt": "2026-09-12T05:11:17.451Z",
      "updatedAt": "2026-09-12T05:51:19.286Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 2, "total": 6, "totalPages": 3 }
}

É esse o formato de toda lista da API do vendedor: success, data e pagination. Veja Paginação, filtros e erros.

Quando o `401` aparecer

Token inválido ou expirado

{ "success": false, "message": "Token inválido ou expirado" }

Passou dos 60 segundos, ou a sessão daquele login foi encerrada. Refaça o POST /auth e repita a chamada. Vale escrever isso uma vez no seu cliente HTTP: em 401, reautentique e tente de novo, no máximo uma vez.

Credenciais inválidas no POST /auth

São duas respostas 401 diferentes, e elas dizem coisas diferentes:

{ "success": false, "message": "Credenciais inválidas." }

O valor público existe, mas o secreto não confere — quase sempre é um segredo truncado na cópia.

{ "success": false, "message": "API key não encontrada" }

O valor público não existe, ou a chave foi revogada no painel. Gere outra em Dashboard › Chaves de API; revogar não é reversível.

Esqueceu o Basic no POST /auth

POST /auth não tem corpo. As credenciais vão no header Authorization: Basic, que o -u do curl monta para você. Mandar um JSON com a chave dentro não autentica nada.

Para onde ir agora

Paginação, filtros e erros

O envelope de lista, os parâmetros page/pageSize e o formato de erro que toda rota compartilha.

Catálogo

Crie um produto, uma oferta e um cupom pela API.

Servidor MCP

Dê a API inteira para um agente de IA operar em linguagem natural.

Cobranças

Gere um PIX ou uma cobrança no cartão.

​O que você vai precisar

​Passo 1 — Crie a chave de API

​Passo 2 — Troque a chave por um token

​Passo 3 — Faça a primeira chamada

​Quando o 401 aparecer

​Para onde ir agora

Paginação, filtros e erros

Catálogo

Servidor MCP

Cobranças

O que você vai precisar

Passo 1 — Crie a chave de API

Passo 2 — Troque a chave por um token

Passo 3 — Faça a primeira chamada

Quando o `401` aparecer

Para onde ir agora