Início rápido

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.

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 antes de escrever.

Crie a chave de API

No painel, abra Integrações › Chaves de API (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 — Integrações › Chaves de API

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

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.

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

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.

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

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();

import os, requests

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

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

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.

Faça a primeira chamada

O mesmo token vale nas duas APIs da Ephra (veja Qual API usar). Comece pelo cadastro da sua empresa, que é leitura pura:

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

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

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

{
  "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.

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.

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"
  }'

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();

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:

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"]}'

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();

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

Token inválido ou expirado

{
  "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.

Credenciais inválidas no POST /auth

{
  "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.

{
  "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.

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

Liberar acesso depois da venda

O fluxo que toda integração de infoproduto precisa.

Sincronizar vendas

Leve as vendas para o seu ERP ou planilha.

Tratar reembolso

Receba o pedido e aprove ou recuse pela API.

Servidor MCP

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

Visão geral

Comece aqui

Conceitos

Guias

Webhooks

MCP

Ajuda

Início rápido

Quando o `401` aparecer

Para onde ir agora

Liberar acesso depois da venda

Sincronizar vendas

Tratar reembolso

Servidor MCP

​Quando o 401 aparecer

​Para onde ir agora

Liberar acesso depois da venda

Sincronizar vendas

Tratar reembolso

Servidor MCP

Quando o `401` aparecer

Para onde ir agora