Vendas

Depois que o dinheiro entra, três coisas interessam: quem comprou, o que foi vendido e o que precisa voltar. O domínio de vendas cobre as três em 6 operações.

Os exemplos usam $TOKEN. Veja Primeiros passos se ainda não tiver um.

1. Cadastre o cliente

O cadastro é por documento: mandar o mesmo CPF de novo atualiza o cliente existente em vez de duplicá-lo.

curl -s -X POST https://api.ephra.io/v1/customers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mariana Ribeiro Alves",
    "document": "390.533.447-05",
    "email": "mariana.alves@exemplo.com.br",
    "phone": "+5521998877665",
    "mailMarketing": true,
    "address": {
      "street": "Rua Visconde de Pirajá",
      "streetNumber": "414",
      "complement": "sala 1108",
      "neighborhood": "Ipanema",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "zipCode": "22410-002"
    }
  }'

{
  "success": true,
  "data": {
    "id": "cmtxysj1i0000owg1gz61pago",
    "name": "Mariana Ribeiro Alves",
    "email": "mariana.alves@empresadela.com.br",
    "phone": "+5521998877665",
    "document": "39053344705",
    "documentType": "CPF",
    "instagram": null,
    "birthDate": null,
    "mailMarketing": true,
    "taxFree": false,
    "tags": ["lancamento-setembro"],
    "notes": "Pediu nota com o CNPJ dela a partir da próxima compra.",
    "address": null,
    "createdAt": "2026-09-12T05:48:39.654Z",
    "updatedAt": "2026-09-12T05:48:48.041Z"
  }
}

Três coisas a notar:

O document volta sem pontuação. Mande com ou sem — a API normaliza.
documentType é deduzido do tamanho: 11 dígitos viram CPF, 14 viram CNPJ.
O campo é o streetNumber, não number. Mandar number reprova com 422 address.streetNumber: Required.

2. Ache um cliente

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

search procura em nome, e-mail e documento ao mesmo tempo, então serve tanto para o time de suporte quanto para uma busca por CPF.

3. Atualize o que mudou

PUT aqui é parcial: mande só os campos que mudaram.

curl -s -X PUT https://api.ephra.io/v1/customers/cmtxysj1i0000owg1gz61pago \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "mariana.alves@empresadela.com.br",
    "phone": "+5521997766554",
    "tags": ["lancamento-setembro", "cliente-recorrente", "nota-cnpj"]
  }'

{
  "success": true,
  "data": {
    "id": "cmtxysj1i0000owg1gz61pago",
    "name": "Mariana Ribeiro Alves",
    "email": "mariana.alves@empresadela.com.br",
    "phone": "+5521997766554",
    "document": "39053344705",
    "documentType": "CPF",
    "mailMarketing": true,
    "taxFree": false,
    "tags": ["lancamento-setembro", "cliente-recorrente", "nota-cnpj"],
    "notes": "Pediu nota com o CNPJ dela a partir da próxima compra.",
    "address": {
      "street": "Rua Visconde de Pirajá",
      "streetNumber": "414",
      "complement": "sala 1108",
      "neighborhood": "Ipanema",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "zipCode": "22410-002"
    },
    "createdAt": "2026-09-12T05:48:39.654Z",
    "updatedAt": "2026-09-12T06:27:58.195Z"
  }
}

tags substitui a lista inteira — não acrescenta. Leia antes se quiser preservar as existentes.

4. Exporte o relatório de vendas

A exportação devolve o CSV dentro do JSON, pronto para gravar em disco.

curl -s -X POST https://api.ephra.io/v1/transactions/export \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paid",
    "startDate": "2026-08-01T00:00:00.000Z",
    "endDate": "2026-08-31T23:59:59.000Z"
  }'

{
  "success": true,
  "data": {
    "filename": "vendas-2026-09-12.csv",
    "contentType": "text/csv; charset=utf-8",
    "rowsExported": 0,
    "filtersDescription": "Período: 2026-08-01T00:00:00.000Z até 2026-08-31T23:59:59.000Z · Status: paid",
    "content": "﻿ID,Data da criação,Data do pagamento,Produto,Nome,E-mail,Telefone,CPF/CNPJ,Método,Status,Data da solicitação de reembolso,Data da execução do reembolso,Motivo de recusa,Total líquido,Total bruto"
  }
}

São 15 colunas fixas. O content começa com BOM UTF-8 () de propósito: sem ele o Excel brasileiro abre “Tráfego” como “TrÃ¡fego”.

curl -s -X POST https://api.ephra.io/v1/transactions/export \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"status":"paid","startDate":"2026-08-01T00:00:00.000Z","endDate":"2026-08-31T23:59:59.000Z"}' \
  | jq -r '.data.content' > vendas-agosto.csv

rowsExported diz quantas linhas de dados vieram, sem contar o cabeçalho. 0 significa que o filtro não achou nada — não que a exportação falhou.

5. Estorne uma venda

O estorno é irreversível e devolve o dinheiro ao comprador. A reason fica no histórico e aparece para o time de suporte.

curl -s -X POST https://api.ephra.io/v1/transactions/cmtxyt3780001eag1tol64iwm/refund \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Comprador desistiu dentro do prazo de garantia de 7 dias."}'

Só uma venda paga pode ser estornada. Qualquer outro estado responde 400 dizendo em que estado a venda está:

{
  "success": false,
  "message": "Apenas transações com status 'paid' podem ser reembolsadas. Status atual: pending"
}

Esta rota estorna direto, sem passar pelo fluxo de aprovação. Quando o pedido vem do comprador pelo formulário da Ephra, ele nasce como uma solicitação e você decide — veja Reembolsos. Use POST /v1/transactions/{transactionId}/refund quando a decisão já foi tomada fora da Ephra.

Onde está a listagem de vendas?

O domínio de vendas não tem um GET /v1/sales. Para consultar transações uma a uma ou em página, use a superfície transacional, que já existe e continua suportada:

GET /v1/transactions — lista com filtros.
GET /v1/transactions/{transactionId} — uma venda com cliente, itens e dados do Pix.

Essas duas rotas são anteriores à API do vendedor e não usam o envelope pagination desta documentação: respondem totalRows. Veja Paginação, filtros e erros.

Todas as operações do domínio

Clientes

Listar, cadastrar, consultar e atualizar.

Exportar vendas

CSV de 15 colunas, filtrado por período e status.

Estornar uma venda

Devolve o dinheiro de uma venda paga.

Reembolsos

O fluxo com aprovação, quando o pedido parte do comprador.

Integração

API do vendedor

Cobranças

Assinaturas

Ajuda

1. Cadastre o cliente

2. Ache um cliente

3. Atualize o que mudou

4. Exporte o relatório de vendas

5. Estorne uma venda

Onde está a listagem de vendas?

Todas as operações do domínio

Clientes

Exportar vendas

Estornar uma venda

Reembolsos

​1. Cadastre o cliente

​2. Ache um cliente

​3. Atualize o que mudou

​4. Exporte o relatório de vendas

​5. Estorne uma venda

​Onde está a listagem de vendas?

​Todas as operações do domínio

Clientes

Exportar vendas

Estornar uma venda

Reembolsos

1. Cadastre o cliente

2. Ache um cliente

3. Atualize o que mudou

4. Exporte o relatório de vendas

5. Estorne uma venda

Onde está a listagem de vendas?

Todas as operações do domínio