EVO · API Externa

Documentação da API

Consulta de vendas (com cobranças e notas fiscais), clientes, ARPs e credenciamento. Cada credencial acessa apenas as rotas liberadas para ela.

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

Autenticação

A API é somente leitura (apenas GET). Envie a chave da credencial no header Authorization, no formato Bearer:

Authorization: Bearer evo_key

Acessos. Cada credencial tem as rotas liberadas individualmente (coluna Acesso abaixo). Rota não liberada responde 403. GET /api/v1/me lista os acessos da sua credencial.

Endpoints

Método	Caminho	Acesso	Descrição
GET	`/api/v1/me`	—	Identifica a credencial autenticada e os acessos liberados (teste de conexão).
GET	`/api/v1/vendas`	vendas:read	Lista vendas, agregadas por venda (inclui número/série/chave/status/DANFE das notas).
GET	`/api/v1/vendas/:id_venda`	vendas:read	Detalhe de uma venda pelo código.
GET	`/api/v1/vendas/:id_venda/notas-fiscais`	notas_fiscais:read	Notas fiscais da venda com o XML completo.
GET	`/api/v1/clientes`	clientes:read · só EVO	Lista clientes.
GET	`/api/v1/clientes/:id_cliente`	clientes:read · só EVO	Detalhe de um cliente.
GET	`/api/v1/arps`	arps:read · só EVO	Lista ARPs.
GET	`/api/v1/arps/:id_cliente`	arps:read · só EVO	Detalhe de um ARP.
GET	`/api/v1/credenciamento`	credenciamento:read	Lista ingressos credenciáveis e status de check-in.
GET	`/api/v1/credenciamento/:id_ingresso_item`	credenciamento:read	Detalhe de um ingresso.

Vendas

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.
`notas_fiscais`	array	Notas fiscais (NF-e) da venda, sem o XML — use /vendas/:id_venda/notas-fiscais para o XML.
`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.

`notas_fiscais[]`

Cada item é uma NF-e da venda. Uma venda pode ter várias: uma por cobrança/ciclo, por recebedor e por tipo (Venda ou Devolução). Produtora vê só as notas emitidas por ela.

Atributo	Tipo	Descrição
`id_nota`	uuid	Identificador da nota.
`numero`	integer	Número da NF-e. null quando não autorizada.
`serie`	string	Série da NF-e.
`chave`	string	Chave de acesso (44 dígitos).
`status`	string	EMITIDA, CANCELADA, REJEITADA, ERRO, PENDENTE, SUBSTITUIDA, NAO_EMITIR…
`tipo_nf`	string	Venda ou Devolução.
`ids_cobranca`	integer[]	Cobranças (id_cobranca) cobertas pela nota.
`ciclo`	integer	Ciclo da assinatura, quando recorrência.
`danfe_url`	string	Link do PDF do DANFE (temporário, gerado pelo emissor).
`data_emissao`	datetime	Data de emissão.
`criada_em`	datetime	Data de registro da nota.
`xml`	string	Somente em /vendas/:id_venda/notas-fiscais. XML autorizado (nfeProc). null quando não autorizada.

`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
        }
      ],
      "notas_fiscais": [
        {
          "id_nota": "731fb46f-b46d-41e5-8d31-2fe2797cf78d",
          "numero": 26227,
          "serie": "3",
          "chave": "53260957823240000103550030000262271204298636",
          "status": "EMITIDA",
          "tipo_nf": "Venda",
          "ids_cobranca": [27651],
          "ciclo": null,
          "danfe_url": "https://…/NFe5326…-nfe.pdf",
          "data_emissao": "2026-06-06T00:05:40",
          "criada_em": "2026-06-06T00:05:31"
        }
      ],
      "venda": { "criada_em": "2026-06-06T00:03:12", "concluida": true },
      "recebedores": [
        { "nome": "PRODUTORA EXEMPLO LTDA", "valor": 91.18, "percentual": 94 }
      ]
    }
  ]
}

Clientes

GET /api/v1/clientes — Cadastro de clientes. Exclusivo de credencial EVO, escopo clientes:read. Para as compras do cliente, use /vendas?cpf=.

Parâmetros

Parâmetro	Tipo	Descrição
`cpf`	string	Lookup pelo CPF (só dígitos).
`email`	string	Lookup pelo e-mail.
`telefone`	string	Contém no WhatsApp (só dígitos).
`nome`	string	Contém no nome ou sobrenome.
`data_inicio, data_fim`	string	YYYY-MM-DD, sobre a data do cadastro.
`page, page_size`	integer	Paginação (page_size máx. 100, default 50).

`Objeto cliente`

Atributo	Tipo	Descrição
`id_cliente`	uuid	Identificador do cliente (use em /clientes/:id_cliente).
`codigo`	integer	Código numérico do cadastro.
`nome, sobrenome`	string	Nome e sobrenome.
`email`	string	E-mail.
`cpf`	string	CPF (só dígitos).
`whatsapp`	string	Telefone / WhatsApp.
`country_code`	string	DDI do telefone.
`data_nascimento`	date	Data de nascimento.
`estrangeiro`	boolean	Cadastro de estrangeiro.
`ativo`	boolean	Cadastro ativo.
`endereco`	object	logradouro, numero, complemento, bairro, cidade, uf, cep, pais.
`criado_em`	datetime	Data do cadastro.
`atualizado_em`	date	Última atualização do cadastro.
`arp`	boolean	Indica se o cliente é ARP.

ARPs

GET /api/v1/arps — Cadastro de ARPs. Exclusivo de credencial EVO, escopo arps:read.

Parâmetros

Parâmetro	Tipo	Descrição
`cpf`	string	Lookup pelo CPF (só dígitos).
`email`	string	Lookup pelo e-mail.
`telefone`	string	Contém no WhatsApp (só dígitos).
`nome`	string	Contém no nome ou sobrenome.
`data_inicio, data_fim`	string	YYYY-MM-DD, sobre a data do cadastro.
`local`	string	Contém no local do ARP.
`adimplente`	boolean	true ou false.
`evo_avante`	boolean	Participa do EVO Avante (true ou false).
`page, page_size`	integer	Paginação (page_size máx. 100, default 50).

`Objeto arp`

Atributo	Tipo	Descrição
`id_cliente`	uuid	Identificador do cliente (use em /clientes/:id_cliente).
`codigo`	integer	Código numérico do cadastro.
`nome, sobrenome`	string	Nome e sobrenome.
`email`	string	E-mail.
`cpf`	string	CPF (só dígitos).
`whatsapp`	string	Telefone / WhatsApp.
`country_code`	string	DDI do telefone.
`data_nascimento`	date	Data de nascimento.
`estrangeiro`	boolean	Cadastro de estrangeiro.
`ativo`	boolean	Cadastro ativo.
`endereco`	object	logradouro, numero, complemento, bairro, cidade, uf, cep, pais.
`criado_em`	datetime	Data do cadastro.
`atualizado_em`	date	Última atualização do cadastro.
`local`	string	Local do ARP.
`produto`	string	Produto do ARP.
`origem`	string	Origem do cadastro de ARP.
`ano`	string	Ano do ARP.
`adimplente`	boolean	Situação de adimplência.
`evo_avante`	boolean	Participa do EVO Avante.

Credenciamento

GET /api/v1/credenciamento — Ingressos credenciáveis (vendas pagas e origens gratuitas; exclui cancelados/estornados) e status de check-in. Escopo credenciamento:read. Produtora vê só ingressos dos próprios eventos. Obrigatório informar id_evento, cpf ou email.

Parâmetros

Parâmetro	Tipo	Descrição
`id_evento`	integer	Código do evento.
`cpf`	string	Lookup pelo CPF do participante (só dígitos).
`email`	string	Lookup pelo e-mail do participante.
`status`	string	Contém no status do ingresso (ex.: USADO, ATIVO).
`origem`	string	Contém na origem (Venda, Cortesia, Generosidade, Indicação, Entrada Antecipada, Inscrição).
`checkin`	boolean	true = já fez check-in; false = ainda não.
`checkin_inicio, checkin_fim`	string	YYYY-MM-DD, sobre a data do check-in.
`page, page_size`	integer	Paginação (page_size máx. 100, default 50).

`Objeto credenciamento`

Atributo	Tipo	Descrição
`id_ingresso_item`	integer	Código do ingresso emitido (use em /credenciamento/:id_ingresso_item).
`participante`	object	id_cliente, nome, email, cpf, whatsapp.
`evento`	object	id, nome, cidade, endereco, data, ativo.
`ingresso`	object	id_ingresso, nome, status, origem, cortesia_gerada_por, criado_em.
`checkin`	object	realizado (boolean) e data do check-in.
`transferencia`	object	transferido_para, transferido_de, data, tem_historico, tem_troca_evento.

Erros

Código	Descrição
`401`	Credencial ausente, inválida, revogada, desativada ou expirada.
`400`	Parâmetro inválido (mensagem em statusMessage).
`403`	Credencial sem acesso à rota (escopo não liberado) ou rota exclusiva de credencial EVO.
`404`	Registro 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.