EVO · API Externa

Vendas — Documentação da API

Consulta das vendas, agregadas por venda, com os pagamentos detalhados por cobrança. Todos os valores agregados consideram apenas as cobranças pagas.

GET https://api.metodoevo.com.br/api/v1

Autenticação

A API é somente leitura (apenas GET) e retorna um objeto por venda. Envie a chave da credencial no header Authorization, no formato Bearer:

Authorization: Bearer evo_key

Endpoints

Método	Caminho	Descrição
GET	`/api/v1/me`	Identifica a credencial autenticada (teste de conexão).
GET	`/api/v1/vendas`	Lista vendas, agregadas por venda.
GET	`/api/v1/vendas/:id_venda`	Detalhe de uma venda pelo código.

Parâmetros de consulta

Query string de GET /api/v1/vendas. Todos opcionais.

Parâmetro	Tipo	Descrição
`data_inicio, data_fim`	string	YYYY-MM-DD, sobre a data da venda. Default: últimos 30 dias. Janela máxima: 366 dias.
`status`	string	Contém no status da venda (ex.: pago, aguardando, estornado).
`evento`	string	Contém no nome do evento.
`recorrencia`	boolean	true ou false.
`id_venda`	integer	Lookup exato pelo código da venda.
`cpf`	string	Lookup pelo CPF do cliente (só dígitos).
`email`	string	Lookup pelo e-mail do cliente.
`telefone`	string	Lookup pelo telefone / WhatsApp do cliente (só dígitos).
`page, page_size`	integer	Paginação (page_size máx. 100, default 50).

Lookups & período. Ao usar um lookup (id_venda, cpf, email, telefone) sem data explícita, a janela de data é ignorada e a busca cobre todo o histórico. Passar data_inicio/data_fim volta a restringir o período.

Envelope da resposta

Atributo	Tipo	Descrição
`success`	boolean	Indica se a requisição foi bem-sucedida.
`data`	array	Lista de objetos venda.
`page`	integer	Página atual.
`page_size`	integer	Tamanho da página (máx. 100).
`has_more`	boolean	Indica se há mais páginas. Pagine até false.
`periodo`	object · null	Janela de datas aplicada (data_inicio/data_fim). null quando um lookup ignora a janela.

Campos da resposta

`Objeto venda`

Cada item de data é um objeto venda.

Atributo	Tipo	Descrição
`id_venda`	integer	Código da venda.
`status`	string	Status da venda (ex.: PAGO, AGUARDANDO PAGAMENTO, ESTORNADO).
`recorrencia`	boolean	Indica se a venda é uma assinatura (recorrência).
`evento`	object	Dados do evento.
`produto`	object	Dados do produto.
`cliente`	object	Dados do cliente.
`valores`	object	Valores financeiros (soma das cobranças pagas).
`cobrancas`	array	Cobranças individuais da venda, em ordem cronológica.
`venda`	object	Metadados da venda.
`recebedores`	array	Recebedores do split. Produtora recebe só a própria fatia.

`evento`

Objeto evento.

Atributo	Tipo	Descrição
`nome`	string	Nome do evento.

`produto`

Objeto produto.

Atributo	Tipo	Descrição
`descricao`	string	Descrição do(s) produto(s) da venda; vários unidos por " \| ".

`cliente`

Objeto cliente.

Atributo	Tipo	Descrição
`nome`	string	Nome do cliente.
`email`	string	E-mail do cliente.
`whatsapp`	string	Telefone / WhatsApp do cliente (só dígitos).
`cpf`	string	CPF do cliente (só dígitos).

`valores`

Todos os valores somam apenas as cobranças pagas da venda.

Atributo	Tipo	Descrição
`moeda`	string	Moeda dos valores (ex.: BRL).
`valor_venda`	number	Valor total da venda (preço do produto).
`valor_pago`	number	Total pago (soma das cobranças pagas), com juros.
`valor_sem_juros`	number	Valor base sem juros (soma das cobranças pagas).

`cobrancas[]`

Cada item é uma cobrança da venda (ordem cronológica). Assinatura inclui os ciclos futuros (Pendente); tentativas de checkout não pagas ficam fora. parcelas_cartao e ciclo/ciclos são mutuamente exclusivos (depende de recorrencia).

Atributo	Tipo	Descrição
`id_cobranca`	integer	Código da cobrança.
`status`	string	Status da cobrança (ex.: Pago, Pendente, Estornado).
`forma_pagamento`	string	Forma de pagamento da cobrança (Pix, Cartão de Crédito, Boleto...).
`valor`	number	Valor da cobrança, COM juros quando parcelada.
`valor_sem_juros`	number	Valor base da cobrança, sem juros.
`valor_pago`	number	Valor efetivamente pago (0 quando não paga).
`parcelas_cartao`	integer	Só quando recorrencia = false. Parcelamento no cartão (1 cobrança em N× na fatura). null quando a forma não é cartão (Pix, Boleto...).
`ciclo, ciclos`	integer	Só quando recorrencia = true. Ciclo desta cobrança e total de ciclos (ex.: 3 de 18).
`data_pagamento`	datetime	Data real do pagamento. null quando não paga.
`data_vencimento`	date	Vencimento da cobrança (ciclos de assinatura). null quando não se aplica.

`venda`

Objeto venda (metadados).

Atributo	Tipo	Descrição
`criada_em`	datetime	Data de criação da venda.
`concluida`	boolean	Indica se a venda foi concluída (quitada).

`recebedores[]`

Cada item é um recebedor do split. Produtora vê só a própria fatia.

Atributo	Tipo	Descrição
`nome`	string	Nome do recebedor (nome fantasia da produtora).
`valor`	number	Valor recebido (soma das cobranças pagas).
`percentual`	number	Percentual do recebedor no split (%, 2 casas) — calculado sobre o valor sem juros.

Exemplo de resposta

{
  "success": true,
  "page": 1,
  "page_size": 50,
  "has_more": false,
  "periodo": { "data_inicio": "2026-06-01", "data_fim": "2026-06-30" },
  "data": [
    {
      "id_venda": 17705,
      "status": "PAGO",
      "recorrencia": false,
      "evento": { "nome": "CURSO MENTALIDADE DE CURA | 2026" },
      "produto": { "descricao": "CURSO MENTALIDADE DE CURA • INGRESSO DUPLO" },
      "cliente": {
        "nome": "NOME DO CLIENTE",
        "email": "cliente@dominio.com",
        "whatsapp": "34991946492",
        "cpf": "35157313691"
      },
      "valores": {
        "moeda": "BRL",
        "valor_venda": 97,
        "valor_pago": 104.9,
        "valor_sem_juros": 97
      },
      "cobrancas": [
        {
          "id_cobranca": 27651,
          "status": "Pago",
          "forma_pagamento": "Cartão de Crédito",
          "valor": 104.9,
          "valor_sem_juros": 97,
          "valor_pago": 104.9,
          "parcelas_cartao": 3,
          "data_pagamento": "2026-06-06T00:03:12",
          "data_vencimento": null
        }
      ],
      "venda": { "criada_em": "2026-06-06T00:03:12", "concluida": true },
      "recebedores": [
        { "nome": "PRODUTORA EXEMPLO LTDA", "valor": 91.18, "percentual": 94 }
      ]
    }
  ]
}

Erros

Código	Descrição
`401`	Credencial ausente, inválida, revogada, desativada ou expirada.
`400`	Parâmetro inválido (mensagem em statusMessage).
`404`	Venda inexistente ou fora do escopo da credencial.
`429`	Limite de 120 requisições por minuto excedido (aguarde o header Retry-After).

Limites

120 requisições por minuto por credencial. Ao exceder, a API responde 429 com o header Retry-After — aguarde o tempo indicado antes de repetir a requisição.